Configuring Rules and Business Logic

Dataform Business Rules

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.

Click the Parameters label to get detailed explanations of how to configure parameters for many of the business rules, the Trigger Values label works in much the same way.

Business Rule Methods

This article provides a list of methods, a description of the method, and the accompanying parameters.

Clear Field Rules

You can automatically clear a field based on a specific trigger condition.

Method	Description	Parameters
_ClearFieldValue	Clears the value in a specific field on save.	sFieldName (field to be set) sFieldValue (value to be entered in the field)
_ClearTabFieldValue	Clears a field on the sTabTableName dataform on save.	sTabTableName (Dataform Table of Tabbed Dataform) sFieldName (field to be set)

Create Field Rules

Method	Description	Parameters
_CreateCalendarEvent		FieldName Subject Invitees StartTime EndTime MeetingType
_CreateExportTransaction		ExportConfigGUID
_CreateExportTransactionAndData		ExportConfigGUID
_CreateExportTransactionAndDataByUser		ExportUser ExportConfigProc

Required Field Rules

The Required Field business rules enable a dataform field to be completed under certain circumstances.

Method

Description

Parameters

_RequireFieldOnThisForm

Checks for a value in a field on the current form.

sFieldName

_RequireTabField

Checks for a value in a field on a related tab.

sTabTableName
sFieldName

_RequireAdHocField

Checks for a value in a field that resides in a node that is embedded in the dataform XML packet.

For example, there could be an Org node (like on the PEO Client Master), and you want to require the Source field. In that case, the parameters would be:

sFieldPath: Org/crSource
sFieldLabel: Source

sFieldPath
sFieldLabel

Core rules

In addition to the standard required field rules, two CORE rules allow for multiple trigger conditions when requiring fields. Both rules add an additional Trigger field and Trigger value in the parameter area of HE/SE_RequiredFieldEngine rule. Essentially this allows you to have multiple triggers for a required field rule.

Method

Description

Parameters

_SE_RequireFieldOnFormOnTrigger

_HE_RequireFieldOnFormOnTrigger

Soft Error

Hard Error

TriggerTable: must be gen_x or #ThisForm.
- #ThisForm uses live data from the current form PRIOR to the save.
- gen_x evaluates the TriggerField value in the database to determine if TriggerField = TriggerValue
TriggerField: must be a valid field on Trigger Table
TriggerValue: must be a value or #IsEmpty
RequiredTable: must be gen_x or #ThisForm.
- #ThisForm uses live data from the current form PRIOR to the save.
- gen_x evaluate the RequiredField value in the database to determine if RequiredField is populated.
RequiredField: must be a valid field on RequiredTable

Set Field Rules

Sometimes you want to automatically set a field value based on a set of triggering parameters; for this reason, the _SetField rules were created.

The _SetField rules provide several non-specific trigger values:

#IsEmpty - fires the rule if the trigger field on the trigger form has no value
#IsNotEmpty - fires the rule if the trigger field on the trigger form has some value - anything but empty
#IsDirty - fires the rule if the trigger field on the trigger form has any value other than empty and has been changed prior to save
#IsDirtyAndIsEmpty - fires the rule if the trigger field on the trigger form has had its value cleared prior to save
#IsDirtyAndNotEmpty - fires the rule if the trigger field on the trigger form has some value - anything but empty and has been changed prior to save

These options and descriptions have been added to the Context help (click the field label). The TriggerValues of this help are clickable links that fill the trigger field automatically.

Method	Description	Parameters
_SetDateFieldValue	Sets a Date field on the TableName dataform.	sFieldName (field to be set) sFieldValue (value to be entered in the field accepts datetime shortcuts (t,d,w,m,y), such as: t (today), 1w (+1 week)
_SetDateFieldValueFromSourceField		TargetField (field on form to be set) SourceField (field on SourceForm to be inserted) SourceForm (Dataform providing inserted value) OffsetInterval
_SetFieldFromKey	The Field Name of the field (on the Dataform Name dataform) into which the Record ID is inserted if the field is empty. Sets a Text or Integer field to that forms ID. If the field is already filled out, it does not replace the value.	TargetField: The TargetField must be either a Text or Integer Input datatype. Can be used on new or existing records.
_SetFieldFromForm***	Sets a field on the TableName dataform from a field on another dataform. Sets a field on the current single dataform from a field on a different single dataform. Must be in the same workspace. The data types must match. For configuration purposes, TableName is the current (target) dataform. This is to be configured for single dataforms only. Leaving the TriggerField and TriggerValue blank when configuring this rule sets the value on save of trigger dataform. If improperly configured using multi-forms, the data is set from the most recently created form, even if it is inactivated. ***Can only be used on gen_ dataforms that are not Multiforms.	TargetField: field on form to be set SourceField: field on SourceForm to be inserted SourceForm: Dataform providing inserted value AllowEmptyValue: Clears the target field if SourceField is empty. When unchecked, the target field remains unchanged.
_SetFieldOnFormFromForm***	Sets a field on another dataform ( gen_DataformName) from a field on the current dataform (#ThisForm) or from another dataform (gen_DataFormName). Sets a field on a single dataform from a different single dataform in the same workspace. This is triggered by a third, completely different single dataform in the same workspace. The source and target data types must be the same. This is to be configured for single dataforms only. Leaving the TriggerField and TriggerValue blank when configuring this rule sets the value on save of trigger dataform. If improperly configured, when the source dataform is a multi-form, the data is set from the most recent source multiform, even if it is inactive. If the target dataform is a multiform, the data is set on the most recent multiform, even if it is inactive. ***Can only be used on gen_ dataforms that are not Multiforms.	TargetField (field on the form to be set) SourceField (field on SourceForm to be inserted) TargetForm SourceForm (Dataform providing inserted value)
_SetFieldValue	Sets a field on the TableName dataform on save	sFieldName (field to be set) sFieldValue (value to be entered in the field)
_SetFieldValueFromPattern	This rule has the ability to extract the first instance of a value from within a text field using a valid .Net RegEx pattern and set the value of another text field on the same page to this extracted value. Some .Net regex patterns found online begin with the ^ character, which must be removed when configuring this rule. This business rule operates based on the following: The SourceField value is always be treated as text TargetField must be a Text data type TargetField is ALWAYS overwritten with the results of the pattern match SourceField and TargetField must be on the current dataform and cannot be used on tabbed forms. If the pattern match returns no value, the TargetField is cleared.	TargetField: Text datatype SourceField: text Pattern
_SetImportID
_SetTabDateFieldValue	Sets a Date field on the sTabTableName dataform (Tab dataform associated with the triggering dataform)	sTabTableName (Dataform Table of Tabbed Dataform) sFieldName (field to be set) sFieldValue (value to be entered in the field accepts datetime shortcuts (t,d,w,m,y) such as t (today), 1w (+1 week) etc.
_SetTabFieldValue	Sets a field on the sTabTableName dataform on save.	sTabTableName (Dataform Table of Tabbed Dataform) sFieldName (field to be set) sFieldValue (value to be entered in the field).
_SetTabUserField	Sets a user field on the dataform tab that is a from a user field on the parent dataform of the tab. This only works from the Parent form to the Child form.	TabTableName (Dataform Table of Tabbed Dataform) TargetField (field to be set) SourceField Use #CurrentUser to set the target user field to the current logged in user. Use #LoginID (with LoginID replaced by a specific user login ID) to automatically set the target user field to a specific user.)
_SetUserField	Sets a user field on the same dataform.	TargetField: If a non-user field is selected as the TargetField, such as a text field, the importID will be set in the TargetField. SourceField: Use #CurrentUser to set the target user field to the current logged in user. Use #LoginID (with LoginID replaced by a specific user login ID) to automatically set the target user field to a specific user. Leaving the TriggerField and TriggerValue blank when configuring this rule sets the value on save of trigger dataform.

Primary and Secondary Trigger Fields

When configuring business rules, the Primary Trigger Field and Secondary Trigger Field lists include fields that are User datatypes.

Trigger value fields are text fields that support the following configurations:

A single User ID
#IsDirty
#IsEmpty
#IsDirtyAndEmpty
#IsDirtyAndNotEmpty

Primary Trigger

Primary Trigger Field: can specify HdrAction or a field on the current dataform
Primary Trigger Value: the HdrAction value or the field value used for comparison
Compares Primary Trigger Field HdrAction value or the dataform field value with Primary Trigger Value entered
The Primary Trigger Value must have changed for the rule to fire, based on the following criteria:
- If comparing HdrAction value, the HdrAction is assumed changed
- If comparing dataform field values (e.g., luState=MA), the dataform field must have changed
- If #IsEmpty, #IsNotEmpty, dataform field is assumed changed
- If #IsDirty, #IsDirtyAndIsEmpty, #IsDirtyAndNotEmpty, dataform field must have changed
Clicking the label brings up a list of # conditions, which are hyperlinked to set the condition in Primary Trigger Value

Secondary Trigger

Secondary trigger field and value fields are enabled when a primary trigger condition has been set and are optional.

Criteria for secondary trigger conditions are as follows:

Primary Trigger condition must be met. Secondary Trigger acts as an AND with Primary Trigger.
Secondary Trigger Field: can specify HdrAction, a field on the current dataform, or a field from ServerDataProc1 or ServerDataProc2
Secondary Trigger Field: when using Server Data Procs, the format is SDP1.FieldName or SDP2.FieldName
Secondary Trigger Value: the HdrAction value or the dataform/SPD1/SPD2 field value
Compares Secondary Trigger Field HdrAction value or the dataform/ServerDataformProc field value with Secondary Trigger Value entered
The Primary Trigger Value must have changed for the rule to fire, based on the following criteria:
- If comparing HdrAction value, the HdrAction is assumed changed
- If comparing SDP1/SDP2 value, the current value is assumed changed
- If comparing dataform field values (e.g., luState=MA), the current dataform field must have changed
- If #IsEmpty, #IsNotEmpty, current dataform/SPD1/SPD2 field is assumed changed
- If #IsDirty, #IsDirtyAndIsEmpty, #IsDirtyAndNotEmpty, dataform field must have changed
- If #IsDirty, #IsDirtyAndIsEmpty, #IsDirtyAndNotEmpty, previous value is assumed Empty, field must have changed (contains a value)
Clicking the label brings up a list of # conditions, which are hyperlinked to set the condition in Secondary Trigger Value

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.

Go to System Admin > Advanced > Manage Rules.
The Custom Logic Rules list is displayed.
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.

If you need further help with custom rules configuration in your system, create a case for one of our application specialists.

KnowledgeSpace