AX2195

How triggers work

Each file group can have one or more defined triggers, to trigger the automatic execution of Scheduler jobs after data has been saved from a plan file in the file group.

Each trigger in a file group has a defined event name. This event name is what links the trigger to the Scheduler jobs to be run. Additionally, triggers can use the following optional settings:

  • One or more variables can be defined for the trigger. These variables can be used in the Scheduler job to impact the job execution in some way. The variables can be linked to a column in the plan code table, or they can have a defined value.

  • Notification address settings can be defined for the file group. You can have a default email address for the file group and/or you can use a column in the plan code table that contains email addresses per plan code. The information passed to the triggered Scheduler job will be grouped by these addresses (meaning one job per unique address), so that you can use the {NotificationAddress} variable to send notifications.

Trigger events are triggered by any action that causes data to be saved from a plan file. For example, the triggering action could be a user who manually opens a plan file and then saves it, or a Process Plan Files utility that uses the save-to-database option. The event is only triggered if the save-to-database process results in a change to the database—if no data is changed in a particular plan file, then no trigger-related action occurs for that plan file.

If data is changed as a result of the save-to-database process, then the plan code for the associated plan file is added to a trigger queue. If the file group has multiple triggers, each trigger will be evaluated for that plan code.

If the plan file was saved independently, then the trigger queue is evaluated immediately. For each trigger in the queue, Axiom Software checks to see if any Scheduler jobs exist that contain an event handler with the same name as the trigger event. If any matching jobs are found, they are added to the Scheduler queue to be eligible for immediate processing (pending available Scheduler threads and any higher-priority jobs already in the queue). If no matching jobs are found, then no action is taken, and no error occurs. In both cases, the plan code / trigger combination is cleared from the trigger queue.

If the plan file was saved as part of a Process Plan Files utility, then the changed plan codes are still added to the trigger queue, but the trigger queue is not evaluated until the entire Process Plan Files utility is finished. Once the utility is complete, the trigger queue is evaluated, but in this case the plan code / trigger combinations are first grouped by notification addresses. This ensures that each unique notification address for the file group has its own Scheduler job, so that the {NotificationAddress} variable can be used to send notifications once the process is complete.

Example

Twenty plan codes are added to the trigger queue as a result of a Process Plan Files utility:

  • If the notification address settings are not used, or if only the default address is used, then all twenty plan codes are evaluated as a single group. For each Scheduler job that matches the trigger event, one instance of that job is added to the Scheduler queue. All twenty codes will be considered for the evaluation of variables in that Scheduler job.

  • If a table column is used for the notification address settings, and the twenty plan codes are associated with five unique email addresses, then the twenty codes are grouped into five different groups. For each Scheduler job that matches the trigger event, five instances of that job are added to the Scheduler queue. In each job, only the codes associated with that unique email address will be considered for the evaluation of variables in that Scheduler job.

The Scheduler job added to the Scheduler queue as a result of the trigger event can perform any Scheduler task. For example, it could be used to process a report, or to run an import, or to process plan files in a different, dependent file group. If the trigger event has defined variables, those variable values are available to the Scheduler job to impact the job processing.

Example

The trigger event has a variable named Region, which uses the DEPT.Region column. For each plan code in the trigger queue associated with this Scheduler job, the plan code's region is passed to the job, and is used wherever the variable {Region} is used in the job settings. If multiple plan codes result in multiple region values, then the list of regions is passed as a comma-delimited list.

If the Scheduler job was used to perform a Process Plan Files task on a different file group, it could be set up to use a filter such as DEPT.Region IN ({Region}). This would resolve to a filter value such as DEPT.Region IN ('North','South'), if the plan codes in the trigger queue which caused this Scheduler job to be triggered belonged to the North and South regions.

To prevent duplicate trigger processing, the following checks occur:

  • If data is saved from a plan file, and the associated plan code / trigger combination is already in the trigger queue waiting to be evaluated, then it is not added to the queue again.
  • When the trigger queue is evaluated and a matching Scheduler job is found, if an instance of that job is already in the Scheduler queue, then it is not added to the Scheduler queue again. The relevant passed values (variable values and notification address) are considered to help determine if a job instance is a duplicate.