Validation scripts are used to validate new or changed data.
There are three forms of validation script:
- Member validation scripts which run whenever a member is changed.
- Member type validation scripts which run whenever a node is changed.
- Node type validation scripts which run whenever a node is changed.
These scripts are applied in the order above. Additionally, if the member type or node type validation scripts modify the data, the member validation scripts for that data may be run again.
Validation scripts follow the same general pattern as other scripts.
- application.getContext() returns the current node as a Script Node Writable Original object. This means that any changes to the node will be permanently stored in the database.
- All the scripts are also passed the context node in application.get("contextNode").
- For member and member type validation scripts, the member type is passed in application.get("contextMemberType").
- For member type validation scripts, the list of members is passed in application.get("contextMemberList").
- For member validation scripts, the member is passed in application.get("contextMember").
- Validation errors are signalled simply by setting a user error, using application.mergeUserError("your message"). System errors will result in system errors in the SetNode service that calls the validation. Member and member type validation errors will be associated with the appropriate member type; type validation errors will only be associated with the node as a whole.
As well as performing validation, validation scripts can modify the data before it is written to the database. Member validation scripts should only modify the member (using member.setValue(), member.setScale() and member.setTarget()). Member type validation and node type validation scripts can perform more complicated modifications. Avoid modifying the same members in both member validation scripts and other scripts (because the other script will interfere with the modifications made by the member validation scripts).
To avoid overhead, member types with a cardinality other than 1 should generally avoid member validation scripts, and validate all the members within a member type validation script.
The member type validation scripts are called in turn. The members for each member type are normalized before the scripts is called; basically, any deletes, inserts and changes of sequence are actioned before the validation is called. However, other member types may not have been normalized. In a member type validation script, it is only safe to access members of other types:
- Where cardinality is 1.
- Or, where the listMembers() method has been used to retrieve the members. (The listMembers() method also normalizes the member lists.)
The node type validation script is only called if the node has passed all other validation.