Dataforms: Workspace Building Blocks

Dataform Configuration 

The Dataform Properties form presents the fields in groups. The first step is to configure the general properties such as name, type, field, group, and description.

To customize your dataform:

1. Use the following image and field descriptions as a guide.
   • Dataform Name: The name of the dataform that is displayed within the application such as in lists where you select a dataform.
   • Dataform Type: Select the type: Standard, Organization, or Contact.
   • Dataform Group: Use grouping to organize dataforms into tiles on the Workspace Landing page. You can use the group as a search parameter when modifying a dataform or adding a new dataform to a workspace.
   • Description: Provide a brief description of the dataform and its purpose.
     
     
     
     
     
     
2. After you configure this first section, click Apply.

  After you Apply changes, then you will see the Table Name and Default Field fields. 

• Table Name: Displays the generated table name that is stored in the database. This can be useful for reporting. You cannot edit this field.
• Default Field: When you associate one dataform with another through linked fields, the default attribute is displayed in the select list. It is a best practice to make the default attribute field of the form Required, so any linked forms will have something to display.

Action Center

The next step is to secure the form, add and configure fields, and add and configure tabs. These actions are performed in the Action Center pane (on the right side of the screen).

To continue with the configuration:

1. In the Action Center, select Secured, Fields, or Tabbed Forms.
   
   
   
   
2. Use the following field descriptions to guide you through the configuration.
   • Secured : Secures the form and generates a security entity for the field in the format of gen_TableName. For more details about using security entities in Role security, review Organization and Workspace Security Configuration.
   • Fields: This is where you add and configure fields for this dataform (see Fields Configuration).
   • Tabbed Forms: This is where you add and configure tabs for any foreign key related child forms of this dataform. (Child forms have a Parent form field that uses this dataform as the Parent Form. See Adding Tabbed dataforms.) 
3.  Apply your changes as you navigate the various panels for Secured, Fields, and Tabbed Forms.

Actions and Developer Settings

The next step is to configure the actions for your dataform. The following fields are in the Actions and Developer Settings of Dataform Properties.

To further customize your dataform:

1. On the Dataform Properties form, locate the Actions area, where you will find an array of checkboxes.
2. Use the following field descriptions to guide you through the configuration.

• Can Have Multiple: Single vs. Multiform. Dataforms come in two basic flavors:
• The Single form (such as the Client Master) has a one-to-one relationship with the Workspace. This is great for recording specifics about an individual or client where there is only ever one item, and if it changes you need to update it.
• The Multiform (such as locations) has a one-to-many relationship with the workspace. This is great for recording multiple instances of something, such as physical locations for a client, or paycheck records for an employee.
• Search On Load: Multiforms present as a list of records, whether this list is populated automatically when you land on the dataform or have to click Search to populate the list is a function of search on load.
• Secure Attachments: Secures attachments for this dataform.
• Show on Landing Page: Indicates the dataform will be available at the bottom of the various types of Landing pages in our Next application under dataform search. Leave this unchecked if you only want to display the form in Next as a tabbed or linked dataform.
• Exclude from BI: Checking this box removes the dataform from the list of available tables in the Datasources section of Business Intelligence, effectively hiding the dataform from reporting.
• BI Name: If completed, the "friendly name" stored in this field will display in Business Intelligence reporting.
• Time Category: On creation of a time tracking record from this dataform, the category field of the record defaults to the selected value.

Developer Settings

• Time Category Function: This option requires custom development and allows you to override the default Time Tracking Category.
• Icon CSS Class: This field defines the type of icon that will be displayed for this form on the workspace landing page.
• Include Activities in Notifications: Specifies if Activities (CRM Notes) are included in dataform notifications.

Features

Next, customize the Features areas.

To further customize your dataform:

1. On the Dataform Properties form, locate the Features area, where you will find an array of checkboxes.
2. Use the following field descriptions to guide you through the configuration.

• Enable Tasks: Adds the My Tasks action item to the dataform . Tasks added from this dataform are linked to this dataform.
• Enable Attachments: Adds the Attachment Action Item to the dataform, providing the ability to attach files to the dataform.
• Enable Subscribers: Adds the Subscribers Action Item to the dataform, which allows you to automatically notify system users via email of changes to the form.
• Enable Subscription Emails: This field sets which notification system is used when producing dataform subscription emails. If checked, a core system notification is produced when the record is changed. If checked and a published Email Template has been configured for this dataform, that template is used. If unchecked and no template exists, subscription emails are not sent.
• Enable Activities: Determines whether Activities may be attached to and displayed on this dataform.
• Enable Time Tracking: Adds the Time Tracker action item  to the dataform. Time tracked from this icon is linked to this dataform.
• Enable WFC Cloning: Used by Workflow Channels to determine whether dataforms are available as "Triggered Forms" during workflow dataform cloning.
• Enabled Triggering: Used by Workflow Channels to determine whether dataforms are available as "Triggering Forms" during the initial channel configuration.

Adding Dataform Tabs 

Create the tabbed dataform(s) in Dataform Administration, ensuring that you include a Parent Form datatype field, configured to point at the Parent form where you would like the tab to appear.

To add dataform tabs:

1. Go to System Admin  > Advanced > Dataform Admin.
   The Dataform Admin list is displayed.
2. Search for the Parent Dataform and click  Form Properties.
   The Dataform Properties form is displayed.
3. In the Action Center, click Tabbed Forms.
   The Tabbed Forms list is displayed.
4. Click Add.
   The Tabbed Form dialog opens.
   
   
5. In the Dataform list, select the tab dataform.
6. Provide a Display Order (this is the order in which the tabs will appear at the top of the dataform). The display order is numeric.
7. Click Ok.

To add fields for storing information that you want to track:

1. Go to System Admin  > Advanced > Dataform Admin.
   The Dataform Admin list is displayed.
2. From the list, select an entry and click Edit or click  (Jump).
   The Dataform Properties form opens.
3. In the Action Center, click Fields.
   The Fields list of the dataform is displayed. From here you can Open, Delete, and Add (New) fields.
4. Click  (New).
   The New Field form opens.
   
   
   
5. Use the following field descriptions to continue the configuration. 
6. Click Apply when you are done.
   • Element Type: Determines the type of data you will store in this field. In the example, we selected the Lookup (core) datatype, but ClientSpace has a full array of different datatypes. The most commonly used datatypes can be found in the section Configuring your Dataform - Datatypes. For an in-depth look at the Lookup datatype used in our example, see Adding Or Configuring Lookups.
   • Field Set: Outlines that hold and organize other fields. No actual SQL field is created and no data can be stored in a fieldset.
   • Field Label: The field label is displayed on the dataform. By default, the underlying field name is set to the field name with any spaces or special characters removed. Click on the field name to open the field properties page.
   • Field Name: The name of the field that is created on the SQL table. By default, the field label is stripped of its spaces and special characters and used as the Field Name. The field name can be overridden as needed and can be set to anything that is accepted by SQL Server as a valid field name. Duplicate field names are not accepted. Field labels are often duplicated in developing large dataforms. As duplicate fields are created, you must modify the field name to make it unique in order to save the field. After the field is saved the first time, the field name CANNOT be changed. Carefully map out your field naming standards before creating dataforms. ClientSpace utilizes a standard naming convention when naming a field based on the datatype of the field. It is a recommended best practice to utilize these same conventions in your own field names. To discover the best practice for your field type read Dataform Field Naming Standards.
   • Row: The row property determines the vertical ordering of fields and fieldsets. Fields that are within a fieldset are ordered within that field set. Though the sort uses a standard numeric order, it is recommended that rows are initially set in increments of ten. This allows for re-ordering fields or adding fields between rows without re-ordering the entire form.
   • Column: The column property is hardcoded to dictate a two-column format. Technically, you are able to select the same row and column for more than one field and they will align alphabetically. This will generally cause problems in the presentation of the dataform to the user.
   • Field Behavior 
     • ReadOnly: This field cannot be edited. Normally these fields are set automatically by business logic.
     • Required: This property can only be set from within the field properties page. When selected, the field must be completed for the dataform to be saved. **This function is overridden if the field is contained in a hidden field set.** 
   • Length: Defines the maximum length of the field entry. This property is valid for text and integer data types.
   • Comment: The text in Comment provides contextual help for dataform users. When comments are added to any dataform field, the info bubble next to the field label is enabled and on hover, the info bubble displays the comment text in a popup.
   • Quick Search: Selecting a value in this dropdown adds the field to the Quick Search on multi from searches. Available options (quick search types) include Starts With, Equals, Contains (% search).
   • Form Searchable: Is this one of the Search parameters available in a multiform list? This property can be set from the form list page or from within the field property page.
   • Secured: Secures the field and generates a security entity for the field in the format of gen_TableName_FieldName. For more in-depth documentation about using security entities in Role security, review ClientSpace Organization and Workspace Security Configuration.
   • Active: Determines if the field appears on the dataform. De-Activating a field is preferential to deleting it because deleting the field removes it from the underlying SQL table and erases the data. When you de-activate or hide a field, you retain the data for later use.
   • Hidden: This property is only available for Field Sets. When selected, the field and its children are hidden when a dataform record is viewed.
   • Index this field: Marks the field for addition to the SQL table index; you can make searches based on this field faster.
   • Audit this field: Marks the field auditable and is configured in System Admin > Advanced > Tables.
   • Cloneable: Marks the field as configurable when this dataform is created by Workflow and Email templates.
   • Triggerable: Marks the field as available for use as a Triggering Field or as one of the Triggering Conditions when configuring Workflow Channels and Email Templates. When a field is marked as Triggerable, it displays in the field list on Email Templates and Workflow Channels.
   • Allow Dataform Notification: If selected, this field is included in a dataform notification when dataform subscribers are emailed. Updated fields appear in bold in this email. 

Available field actions

When viewing the list of dataform fields, note the available actions:

Action	Action label	Description
	Open	Opens the field properties for the highlighted field.
	Delete	Deletes the highlighted field.  For system fields, the Delete action is not available and displays as disabled. System fields can be easily identified because their field names do not begin with z_.
	New	Adds a new field.
	Save	Saves changes to the dataform fields list.

Deleting a dataform field

A few situations can exist that prevent a field from being deleted:

1. The field is a system field.
2. Other system configurations depend on the field.

For system fields, the Delete action is not available and displays as disabled. System fields can be easily identified since their field names do not begin with z_.

Dataform fields that are referenced by system functions, e.g., rules, links, or field display conditions, cannot be deleted until their dependencies are removed. If you try to delete a field that has a dependency, an error message is displayed in the delete dialog: "This field is used by the following System functions and cannot be deleted while these dependencies are in place: System Function". From the delete dialog, you can open the dependency.

After you Save the configuration, you can then view the form from Admin Workspace.

1. Go to System Admin  > Administrative Data > <groupname>.

   Where <groupname> matches the Dataform Group value you selected during the initial Dataform Properties add process.

2. Alternatively, click Admin Workspace from your modules bar (if you added to your modules bar).

3. In Admin Workspace, open the group, and within the group open the form.

4. Click Add.

   The form is displayed.

The following images illustrate:

• Dataform field mapping during the Add process

• The completed form, viewable through Admin Workspace

Dataform rules include Biz Logic, Hard Errors, and Soft Errors. These rules can trigger events, ensure that data does not become corrupt (i.e., no duplicate SSN and FEIN), and manage the requirements of a workflow, along with any number of custom functions.

• Business Logic Rules are rules that compare fields, perform calculations, change values of fields, validate values, etc.
• Hard Errors are hard and fast requirements that must be met before the action can be completed. These are most commonly used to require data be entered prior to a certain step in the process but without making it a hard requirement to save the current dataform.
• Soft Errors are used as reminders and warnings. These can be configured as custom and complex warnings or they can be simple warnings to remind someone to complete a specific field.

Step-by-step guide

To provide an example of Business Rules configuration we will look at Configuring a SetField rule.

 Business Rules can be configured on the Client Processing Team dataform so when a Service Team is selected it will auto-populate the Client Team's various roles. To do this a Global Admin needs to configure a rule for each role that needs to be auto-filled. See the following figure for an example of how to configure this rule. This rule will set the Implementation Specialist when the "Blue Jay" Service Team is selected.

1. Go to System Admin  > Advanced > Manage Rules.
   The Custom Logic Rules list is displayed.
2. To add a business rule, click Add.
   The Rule Details form opens.

• Dataform: This is the dataform where this rule will be executed when the dataform is saved.
• Method:  Choose '_SetFieldValue'
• Rule Title:  Provide an abbreviated explanation of what this rule will due, for example, "Set Implementation Specialist For Blue Jay Team".
• RuleType:  ClientSpace controls this field automatically.
• Description:  Provide a more thorough explanation of what this rule is to accomplish.
• Primary Trigger Field:  Select the field that is going to cause the change.  In this example, 'Service Team (fkServiceTeamID)' represents the Service Team field on this dataform.
  Primary Trigger Value:  Type the value of what is stored in the database for the Trigger Field.  In this example '8' is the value that is stored in the system to represent the 'Green Team'.
  Secondary Trigger Field: Select an additional trigger condition that must be met if necessary.
  Secondary Trigger Value: Set the secondary trigger value.

• Execution Pipeline:  Leave this set to Default.

  Execution Order of Precedence

  Within the Rules system, there is a distinct order of precedence that occurs, that being HardError, SoftError, BizLogic. This means that setting a field to a specific value automatically with BizLogic, then validating that field with a Hard Error will never occur in the correct order, as the Hard Error will fire before the BizLogic fills the field. This order of precedence happens irrespective of the execution order placed on the configured rule, so Hard Errors will fire in Execution order least to greatest, then Soft Errors will fire in their order of execution, then the Biz Logic will happen, again in the order of execution set on each rule. 

• Execution Order:  This field controls the order in which rules will execute first. Rules execute from lowest to highest number. It may be necessary to look at other rules already configured on this dataform to determine the order of precedence for executing rules.
• Save Action:  Will this rule be applied on Insert of a new dataform, or on the update of an existing dataform or on both?
• Workspace Template:  Select the Workspace Template(s) to which this rule will apply.
• sFieldName:  Type the technical database name for the field that needs to be set. In this example, 'ImplementationSpecialist' represents the Implementation Specialist field on the Client Team dataform.
• sFieldValue:  Type the value of what should be stored in the database for the Trigger Field. In this example '415' is the value that is stored in the system to represent the 'Adam Harris', the Implementation Specialist.

Note:  You must use a combination of Ad-hoc Reports, the Dataform Specifications Report, Lookup Admin, and or Dataform Admin to find the technical database names and the values stored in the database to represent the value that is seen by the user from the dataform. This rule would also work well in cases where you may want to set the Implementation Specialist to X when the Payroll Specialist is Y.  

To add a dataform to a workspace:

1. Navigate to the Workspace in question. This can be a single administrative workspace, or to have the dataform generated on Workspace creation. Go to System Admin  > Workspace Templates.
   The Workspace Template Search list is displayed.

2. Locate and open the template in question.

3. In Action Center, click Dataforms.

4. Click Add.
   The Add Dataforms dialog opens.

5. Find and Select the dataform.**

6. Click Ok.

The dataform is added to all child workspaces of that template.

Dataforms can also be accessed via custom links in another dataform header. Configuring a header link is detailed in the document Configuring Links. This article discusses the link configuration items to create a Workspace Dataform link.

To add a new link to the dataform:

1. Go to System Admin  > Advanced > Custom Links.
   The Configure Links list is displayed.
2. Click Add.
   The Configure Links Detail form opens.
3. Use the following field descriptions to guide you through adding a new link.
   
   • Location: The name of the dataform on which you want to link to appear.
   • Group: Where in the header the link will appear.
   • Display Value: The text that is displayed in the Action Items area as a clickable link.
   • Display Action: Lists the possible actions for the selected link group. The available actions are based on the selected Group and include items such as running a report or merge. This then creates a HdrAction to fire a business rule or open a system dataform. ***
   • Sort Order: When multiple links are displayed in the header, this determines their order within the link group.
   • Sort/Merge: Select the report or merge to run using the appropriate display action when a Report link is clicked.
   • Target Dataform: The dataform you would like the user to access from this link.
   • Code Value: This is the HrdAction produced when an Action link is clicked.
   • Custom Function: This is the custom function that is called from an Action link.
   • Custom Function Data: This is the data that is passed to a custom function if required.
   • Security Entity: This can be used to hide the link from unauthorized access.
   • URL: Use this field to configure the URL that opens on a URL Display Action. When defining an external URL, include the protocol (http:// or https://) as links. Without the protocol, the link is treated as internal to the application.
   • Confirmation Message: Provide a confirmation message that displays an OK / Cancel dialog box before running the link action. This is most often used with Action Links.
   • Description: A short description of the dataform and how it should be used. This text appears on mouseover of the link.
   • Display this Link when adding: This section can be used to set parameters for when the link should display. For a complete discussion of configuring link display see the document Configuring Links.
   • Pinned Open: When selected, this forces the link to always display in the Action Items area. The link will not collapse when the associated group is collapsed.
   • Condition Expression: This field uses the Labels from any conditions that you added under Add. You can combine multiple triggers into more complex expressions and override the default OR behavior. Conditions that are not included in this field are ignored.
   • Active: By default, configured links are active.
4. After configuring the Dataform Link, remember to Save your changes.