Sometimes it is essential for an attribute or reference to be populated in one or two specific cases, but is otherwise unnecessary. To account for these cases, the mandatory status of attributes and references on objects moving through a workflow can be enforced via business conditions set on a state or transition.
Mandatory attributes and references configured with a condition will remain mandatory unless that condition returns false, indicating that the condition was not met and the attributes in question are not required when proceeding to the next state in the workflow. Like standard mandatory attributes and references, if conditionally mandatory attributes / references are missing values when attempting to submit an object to the next state, the object is prevented from progressing through the workflow and the user receives a message listing the attributes / references that have missing mandatory values. In Web UI, these conditions can be evaluated on the fly and dynamically reflected as the user works with the data, with a change in mandatory status being reflected on the screen in real time, allowing users to react immediately, without having to submit and receive an error message.
For more information about setting mandatory attributes and references in workflows, refer to the Mandatory Attributes and References in Workflows section of the Workflows documentation here.
For more information about business conditions, refer to the Business Conditions section of the Business Rules documentation here.
Configuring Workflow States / Transitions with Conditionally Mandatory Attributes
A condition can be mapped to an attribute or a group of attributes on either a state or transition in a workflow.
- Navigate to the Mandatory Data tab in the State / Transition Editor.
- Locate the relevant attribute group and/or attribute(s) and click the ellipsis button (
) in the 'Condition' column.
- In the 'Mandatory condition for' editor that displays, specify the condition to use by selecting a global business rule via the 'Business Rule' ellipsis button (). Once the selection is made, close the editor.
Alternatively, you can create a new business condition by clicking the 'Add new Business Condition' link at the bottom of the editor, and then click the Edit Operation button that appears. From the dropdown, select 'Evaluate JavaScript,' then enter the business condition in the JavaScript area.
Important: For use with conditionally mandatory attributes, the business condition should only return 'True' or 'False.' If anything else is returned it will be treated as 'True'.
- Once finished, click Save and close the editor.
- Close the State / Transition Editor and Save the workflow.
Configuring Workflow States / Transitions with Conditionally Mandatory References
Conditionally mandatory references on workflow states and transitions are configured similarly to conditionally mandatory attributes. Conditions can be mapped to all references listed within an attribute group or to individual references.
- Navigate to the Mandatory Data tab in the State / Transition Editor.
- Locate the relevant attribute group and/or reference and click the ellipsis button () in the 'Condition' column.
Note: To apply a condition to all references within an attribute group, the 'Include References' box must first be checked. Also note that the condition will apply to both the attributes and the references in the group, so the condition should be written to take this into consideration.
- In the 'Mandatory condition for' editor that displays, specify the condition to use by selecting a global business rule via the 'Business Rule' ellipsis button (). Once the selection is made, close the editor. (This editor is identical to the one that displays for conditionally mandatory attributes.)
Alternatively, you can create a new business condition by clicking the 'Add new Business Condition' link at the bottom of the editor, and then click the Edit Operation button that appears. From the dropdown, select 'Evaluate JavaScript,' then enter the business condition in the JavaScript area.
Important: For use with conditionally mandatory references, the business condition should only return 'True' or 'False.' If anything else is returned it will be treated as 'True'.
- Once finished, click Save and close the editor.
- Close the State / Transition Editor and Save the workflow.
Conditionally Mandatory Attribute and Reference Handling in Web UI
In Web UI, the mandatory status of attributes and references can be evaluated on the fly as the user works with the data, with any change in mandatory status being reflected on the screen in real time. In order to display these dynamic changes, the attribute values driving the condition must be bound to that condition in the business rule configuration. While the condition driving the mandatory status of an attribute or reference can take more than just attributes into account, if something else is driving the condition, such as a reference, the page will need to be refreshed to update the interface.
Important: The use of business rules to determine mandatory status of an attribute or reference should be done with care, as the performance of the dynamic behavior of the editors could be impacted if highly complex business rules are used.
When viewing a state in a Node Editor, any attributes or references that are currently mandatory are marked with an asterisk. If the condition returns false due to changes in data on the page, these indicators vanish. Additionally, if there are any missing attributes that are currently mandatory, the Submit / Approve button will be locked.
Note: Conditionally mandatory attributes and references that are set in workflow states are marked with an asterisk to end users, while those set on transitions will be highlighted to indicate missing data when the user attempts to submit the object to the next state in the workflow. The user is also notified of the missing data with a message in the Notification Panel.
On Node Lists using Multi-Edit Display Mode, conditionally mandatory attributes and references are indicated by highlighting the cell blue. As with the Node Editor screen, the mandatory status is dynamically evaluated so if the condition returns false, the highlighting disappears.
Example
Note: This example uses conditionally mandatory attributes to describe the functionality, but the behavior is the same for conditionally mandatory references.
The business condition states that if the value of the attribute 'Multiplayer' is 'Yes', the attributes 'Co-op' and 'PvP' are mandatory. Otherwise, 'Co-op' and 'PvP' are not mandatory.
In the image below, the condition is returning true for the Space Adventure Game, so 'Co-op' and 'PvP' are mandatory (and are highlighted blue). Clicking Submit / Approve if either mandatory value is missing will result in an error message listing which mandatory attribute(s) are missing. If both attributes have values they are free to move on to the next state.
In the image below, the condition is returning false for the Space Adventure Game, so 'Co-op' and 'PvP' are not mandatory (and are not highlighted). This object is free to move on to the next state, even if 'Co-op' and 'PvP' do not have values.
In the image below, the condition is returning true, so 'Co-op' and 'PvP' are mandatory (and are marked with asterisks). Since they have values, the Submit / Approve button is enabled.
In the image below, the condition is returning false, so 'Co-op' and 'PvP' are not mandatory (and are not marked with asterisks). Since it does not matter if they have values, the Submit / Approve button is enabled.
In the image below, the condition is returning true, so 'Co-op' and 'PvP' are mandatory (and are marked with asterisks). Since 'Co-op' is missing a value, the Submit / Approve button is disabled.
Conditionally Mandatory Attribute and Reference Handling in Workbench
Support for conditionally mandatory attributes and references is also available in the workbench, though visual indicators are not managed in relation to this. When attempting to submit an object, conditionally mandatory attributes / references are evaluated and an error is presented to the user listing any missing conditionally mandatory attributes / references (in the same manner that standard mandatory attributes / references are reported).
Determining Mandatory Status of an Attribute or Reference
Any attributes / attribute groups and/or references specified under the 'Mandatory Data' tab of a workflow state or transition are considered mandatory if:
- There is no condition set for the attribute / attribute group or reference(s)
- The condition is not applicable for the object type of the object being evaluated
- There is a pre-condition on the rule that is not met and therefore the condition is not evaluated
- The condition fails
- The condition returns 'True'
The only case in which an attribute / attribute group or reference is not considered mandatory is if the condition returns 'False'.
Because the mandatory status of an individual attribute or reference can be determined in a number of different ways, some methods must take priority over others:
- An individual attribute or reference specified on the state / transition takes priority over attributes / references specified as part of a group.
- If an attribute / reference is listed via multiple groups, the group configured with a condition takes priority.
- If an attribute / reference is listed via multiple groups and more than one of those groups is configured with a condition, only the first condition listed is applied.
- If the attribute is explicitly defined as mandatory in Web UI via being set as mandatory on the screen, that setting overrides any conditions that may say otherwise. (This does not apply to references, which cannot be set as anything other than 'visually mandatory' on Web UI screens)