Triggers
Level: Expert
Keywords: business, trigger, cron, event
The result: defining a trigger for events and periodic actions
Triggers provide the possibility to respond to various events in the application on the business server side, or to ensure some periodic actions. There are three types of triggers. The Event trigger responds to various events that occur in the system. Cron and Periodic seem to be similar, but they have a major difference in what time they are triggered.
Cron​
The following example shows a cron trigger that is invoked every day at 2 a.m on the 15th day of the month. The attribute cronExpression is very similar to crontab in Unix and has this meaning s m h d m y. For example, 0/5 in the minutes field indicates every 5 minutes. But 2 in the hours field means at 2 a.m every day.
Another attribute with name authoredBy means under which user the following actions will be called. Writes only the username.
Optional attribute inherits determines whether this defined cron will be inherited into child entities. Default value is true, the next option is none.
{
"triggers": {
"synchronizeEmployee" : {
"type" : "cron",
"cronExpression" : "0 0 2 0/5 * *",
"authoredBy" : "superuser",
"actions" : [
"collectStats"
],
"inherits": "none"
}
}
}
If you have some actions that are computationally intensive and take a very long time and are called very quickly in a row, then use a trigger of the periodic type. The cron type is not suitable in this case as it can cause server congestion.
More details about Cron Trigger configurations can be found in Lighthouse Software / Application server / Business server / Configuration / Triggers / Cron trigger
Event processing​
TODO::::
- context.attributes.lastTriggerAt
- context.attributes.currentTriggerAt
Periodic​
The periodic trigger ensures that the next trigger is called only after the end of the current call. Attribute periodic is time in milliseconds.
The optional attribute fixedRate ensures that the next trigger is called after the current call has ended and the defined period time has elapsed. Default value is false.
Next optional initDelay attribute defines the time that elapses before actions are called. It is also in milliseconds and the default is 0.
{
"triggers": {
"importChanges" : {
"type" : "periodic",
"period" : 30000, // in millis
"fixedRate" : true,
"initialDelay" : 10,
"authoredBy" : "superuser",
"actions" : [
"importChanges"
],
"inherits": "none"
}
}
}
More details about Periodic Trigger configurations can be found in Lighthouse Software / Application server / Business server / Configuration / Triggers / Periodic trigger
Event processing​
Event​
Each event that will be captured by this trigger contains several labels. These describe for example, which event it is, how it was created, which entity was created and what attributes were changed. It also informs about the creation of the association. If we enumerate a list of attributes, then such event must have all the labels specified by us. Mandatory attribute include (of type array) is used to list labels, that should invoke the trigger when they occur in the event. The opposite is true for exclude attribut, in which case the event must not have any of the listed labels.
Attribute async allows the following actions to be invoked asynchronously. In the event where an error occurs in the following actions, or if an error message is published, it will not affect the actions already performed. Default Value is false.
The attribute autoIncludeType defines whether the current featureType (e.g. ft_boDefect) should be automatically added to the labels (include). Default value is true.
The following example shows a trigger that responds to creation of association between two entities.
{
"triggers": {
"defectAssetAssocCreated" : {
"type": "event",
"eventType": "entityAssociationCreated",
"include": [
"as_defect_asset"
],
"actions": [
"defectAssetAssocCreatedAction"
]
}
}
}
{
"triggers": {
"attachmentEvent": {
"type": "event",
"autoIncludeType": false,
"include": [
"entity",
"attachment"
],
"actions": [
"attachmentEvent"
]
}
}
}
There are several types of event:
- entityCreated: When the entity is created.
- entityCreatedComposite: When entity is created and all codelists and references attributes are filled.
- entityUpdated:
- entityDeleted: When entity is deleted. Recommended with the option
"async": true - entityWillBeDeleted: Before the entity will be deleted. However, associations are already removed at this point due to system cleanup processes (e.g., AssociationListener), so references might no longer be available.
- entityRestored
- entityAssociationCreated
- entityAssociationDeleted
- entityAssociationUpdated
- entityAttributeUpdated
- entityStateUpdated
- entityActionTriggered
- cutomEventFired
More details about Event Trigger configurations can be found in Lighthouse Software / Application server / Business server / Configuration / Triggers / Event trigger
Invoking custom event​
In cases when we want to invoke our own event, we use the method from scriptingAPI api.business().prepareFireEvent(). We choose the value for the eventType attribute. We can add some custom attributes and labels. All these values are then available in the script, where the trigger is processed.
api.business()
.prepareFireEvent(context)
.entityType("ft_boConstruction") // required by entityEvent
.entityId("330599133626798023742267269600") // can be dervied from context
.entityEvent() // adds entityType and entityId as event attribute. Also adds entity and entityType label
.eventType("interfaceExchange")
.addUserAttribute() // add authenticated user as event attribute
.addAttribute("responseCode", "CODE-12345")
.addLabel("customLabel")
.addLabel("CODE-12345")
.fire();
Event processing​
When processing a trigger, typically using a script, we have a lot of information about the event. This information is in the context.variables. For simplicity, only type will be here further used to reference context.attributes.type.
In general, we have type, where the value is eg. eventCreated. It is a value from json trigger definition where name is eventType.
Especially for cron or periodic triggers, there are lastTriggerAt and currentTriggerAt variables available, where is the information in timestamp (time in milliseconds).
For events that are triggered over an instance of the entity, we have available entityType and entityId. Similarly, for operations on associations, where we have startEntityType, startEntityId, endEntityType and endEntityId.
When it comes to updating attributes, these individual attributes are listed in field updatedAttributes (as simple array). Old and new values are available as objects in field attributesChange (the each object has two attribute oldValue and newValue).
The folowing example shows the structure of the available information.
attributes: {
"type" : "entityAttributeUpdated",
"entityType" : "ft_defBoDefect",
"entityId" : "30332597",
"updatedAttributes" : [ "at_defBoDefect__note" ],
"labels" : [ "ft_defBoDefect", "attribute", "updated", "entity", "at_defBoDefect__note" ],
"attributesChange" : {
"at_defBoDefect__note" : {
"newValue" : "new note",
"oldValue" : null
}
}
}