Trigger scripts are run when data is created or updated.
Typical scenarios for trigger scripts include:
- Creating initial data for a node.
- Creating additional nodes.
- Creating permissions.
Unlike traditional database triggers, Metrici trigger scripts run whenever a change transaction is applied, irrespective of whether any changes have actually taken place. Specifically, they run:
- When a node is inserted.
- When a node is updated.
- When a node is deleted.
- When the type of a node is changed.
Trigger scripts are not run when nodes are imported (imported data is presumed to be in its post-trigger state), or after some other system processes. Solutions should not presume that trigger scripts will necessarily have been run on data.
General notes
The scripts are read from the Type Trigger Script (system.TYPE_TRIGGER_SCRIPT) member of the node type. If this does not exist, no error is raised.
The scripts are run using the node owner's authority.
The type of trigger is passed into the trigger script in the 'trigger' attribute. This will be one of:
- insert
- update
- delete
- applyType
- removeType
If the script creates an error, it will be returned as the error of the triggering operation (an apply or change reference, delete errors are discarded). However, it will not undo the triggering operation. Trigger scripts should not return errors under normal circumstances; returning errors should be considered a last resort.
Note: Metrici requires the user performing the action to have execute authority on the node in order to run a trigger script, which means that all users with update authority on the node also require execute authority.
Insert script
The script runs with the new node as the context.
The trigger attribute will be set to "insert".
The nodeVersionReferenceAfter attribute will be set to the node version reference of the new node, which will always be the same as application.getContext().getNodeVersionReference().
Update script
The script runs with the updated node as the context.
The trigger attribute will be set to "update".
The nodeVersionReferenceBefore attribute will be set to the node version reference of the node before the update.
The nodeVersionReferenceAfter attribute will be set to the node version reference of the node after the update.
Delete script
The delete trigger runs before the node is deleted.
It runs with the node as its context.
The trigger attribute will be set to "delete".
The nodeVersionReferenceBefore attribute will be set to the node version reference of the node that will be deleted.
Any errors will be discarded.
Change type
A type change triggers two scripts: a remove type and an apply type.
The remove type script is run from the type before the change.
The apply type script is run from the type after the change.
The apply type script will always run immediately after the remove type script. Application attributes set in the remove type script will be passed to the apply type script.
Both scripts run with the new node as the context.
The nodeVersionReferenceBefore attribute will be set to the node version reference of the node before the type change.
The nodeVersionReferenceAfter attribute will be set to the node version rererence of the node after the type change (which should always be the same).
Remove type
The trigger attribute will be set to "removeType".
Any errors will be passed to the apply type script.
Apply type
The trigger attribute will be set to "applyType".
Custom triggers
It is possible to use the type trigger script to run additional triggers. The following triggers are used by library code and should only be used in the way described.
| init |
Run to initialise a node. init triggers should be re-runnable, i.e. calling init a second time should have no effect. Use the Initialization List type to control the order of initialization. |
Use Trigger Script to apply custom triggers.
Guidelines
Typical use of trigger scripts is to apply package permissions and create nodes within this node.
Code to so this should be modularised, and should run whenever the trigger is "insert" or "applyType". If the actions depend on the data entered into the node, the code should also be run when the trigger is "update".
The code should check for data that is already set up.
Triggers of "delete" and "removeType" are rarely required, since nodes clean up after themselves anyway.
Modify Type Script provides an elegant way of adding triggers to a node type from a field, which can be more convenient than coding multiple triggers into a single Type Trigger Script member.