How Rules are Automated

The trigger management system contains the main components described in this section.

The first component, installed with ENOVIA Business Process Services, is the Trigger Manager (emxTriggerManager). The Trigger Manager accepts input for one argument only. This argument is the name of business objects of a type called eService Trigger Program Parameters, the second component of the trigger management system. Trigger Program Parameters objects represent specific trigger programs and are installed with the ENOVIA products.

eService Trigger Program Parameters objects have attributes that specify the:

• trigger program to run
• inputs to be passed for the trigger program's arguments
• order in which the trigger program should be executed, if other trigger programs of the same kind run for the trigger event
• if the trigger program is a Java program, the name of the method inside the JPO to run

One eService Trigger Program Parameters object must exist for each trigger program that needs to be run for a trigger event. For example, if a trigger event has two check programs and one action program, there must be three Trigger Program Parameters objects.

To ensure the name of each Trigger Program Parameters object is unique and to help you easily identify the different objects, ENOVIA recommends using this naming convention.

[ADMIN OBJECT TYPE][ADMIN OBJECT NAME][TRIGGER EVENT][TYPE OF 
TRIGGER]

Using this convention, the name of a Trigger Program Parameters object indicates the trigger the object is associated with. For example, a Trigger Program Parameters object called "TypePartCreateAction" indicates that the object references an action trigger program that runs when a part is created.

Policy triggers require one more piece of information for the Trigger Program Parameter object name:

[ADMIN OBJECT TYPE][ADMIN OBJECT NAME][STATE NAME][TRIGGER 
EVENT][TYPE OF TRIGGER]

For example, this Trigger Program Parameter is associated with an action trigger program that runs when an object is demoted from the Active state of a Person policy.

Here are some examples of names for Trigger Program Parameters for each administrative object type:

When a trigger event occurs, the Trigger Manager queries for all Trigger Program Parameter objects that have the same name as the input. The query includes all revisions. If more than one trigger program should execute for the same trigger event and the same kind of trigger (Check, Override, Action), the names of the Trigger Program Parameter objects must be the same and the revision must be different. The revision can be a standard number or letter, or it can be a description of the trigger program.

As an example, if two check programs should run when a part is created, there must be two Trigger Program Parameters objects with the name TypePartCreateCheck but with different revisions. Each object has attributes that reference a specific trigger program and set of argument inputs. The objects also have an attribute that specifies which program should run first.

When entering attributes for the eService Trigger Program Parameter object to perform email notifications, the attributes described in this section must be entered with specific values.

Enter the values for these attributes exactly as specified in the following table:

• eService Program Name
• eService Method Name

To define a Notification Object using the eService Trigger Program Parameter Object, the attributes must be defined as described in the following table.

When a trigger event calls the emxTriggerManager program, the program performs the steps described in this section.

1. Make a copy of all of the environment variables.
2. Set a new environment variable called ORIGINAL_INVOCATION with the value from the original INVOCATION variable.

   When a Tcl trigger program is executed through the JPO Trigger Manager, this value gets set to program and you do not want to lose the original INVOCATION value. This means that triggers that rely on the INVOCATION environment variable for program execution should look for the ORIGINAL_INVOCATION environment variable.

3. Query for business objects that meet this criteria:
   
   • Name--Input specified for the emxTriggerManager program. This is the name of the eService Trigger Program Parameters object that represents the trigger program to be run.
   • Type--eService Trigger Program Parameters
   • Revision--* (all)
   • Vault--eService Administration if there is such a vault or * (all) if eService Administration does not exist.
4. Discard all returned objects that are in the Inactive state.
5. Sort the objects in ascending order according to the eService Sequence Number attribute.
6. Loop through each of the objects found and determine if they are Tcl or Java programs.
7. Execute the programs in the specified sequence and include the inputs. Trigger Manager waits for each program to complete successfully before calling the next program. If trigger is a Java program, get the name of the method inside the JPO and invoke it. The method is specified in the eService Method Name attribute for the eService Trigger Program Parameters object. If no method is specified, default to the main (mxMain).

   Or:

   If the trigger is a Tcl program, execute the program using the MQL command class.

8. The program returns zero for success and a nonzero for a failure.

   If, after invoking a JPO trigger, the Trigger Manager gets a return value of 1 and then checks the INVOCATION type. If the INVOCATION is an action (Action Trigger), it throws an exception. For any other type of INVOCATION, the Trigger Manager JPO returns 1 to the invoking environment to indicate failure. Otherwise, a zero is returned to indicate success.

   For each trigger that is completed without error, the Trigger Manager resets all of the environment variables back to their original values, until all trigger(s) are executed successfully.

   If any program returns failure, the Trigger Manager stops execution and returns failure. In the case of a check trigger, failure prevents the event from occurring. In the case of an action trigger, the programs that are called do not return success or failure because actions do not wait for a return code. If a program that is called as an action fails as a result of an error in an MQL command, the event that invoked them will, as expected, be aborted. However, if you want to trap an error in an action program by means other than MQL errors, you can use something like the following:

   If {sString == ""} {
          mql abort transaction
          return
   }
   

The guidelines for running one trigger before or after another trigger are listed in this section.

1. Run Triggers that are expected to fail more often earlier than triggers that are not expected to fail as often. This reduces the amount of time a user waits for triggers that will usually pass because they will only be run after all of the other more likely-to-fail triggers have passed.
2. Run fast Triggers before slow triggers. It is better to get through fast triggers early so if the event must be attempted more than once, the user will not spend as much time waiting for a slow trigger to run more times than necessary.
3. Triggers that perform checks which other triggers (within the same event) depend on must be run first so that those preconditions are satisfied for the later dependent triggers. This reduces redundant checking of subsequent triggers because all preconditions have been met.

Items #1 and #2 above are subjective and require decisions based upon domain knowledge of the process and data to make the proper trade-offs.

Item #3 indicates that triggers installed with the framework and applications should not have their order changed relative to each other unless you know there are no interdependency checks. To determine if there are interdependencies, see the Administrator's Guide for the application.

Trigger programs can come from the main sources listed in this section.

• The trigger programs used by many applications, called utility trigger programs, are installed with ENOVIA Business Process Services and are described in Utility Trigger Programs.
• Programs specific to an ENOVIA product are installed with the application. For information about trigger programs that are specific to an application, refer to the administrator's guide that accompanies the ENOVIA product.
• The Subscription Services Application Library contains many trigger programs.
• You can create your own custom trigger programs.

Do not make changes to the programming for trigger programs that are installed with ENOVIA Business Process Services or ENOVIA products. Handle any adjustments using the argument inputs passed by the eService Trigger Program Parameters object and described in Modifying Inputs Trigger Programs.

Do not change the file names of the trigger programs. The file names for all ENOVIA products programs are prefixed with "eService[name of installed directory]". Do not change this prefix and do not create custom programs using the eService prefix. If you need to modify the name of an ENOVIA product program, clone the program and change the name of the cloned program.