Utility Trigger Programs

This section describes the trigger programs that are used by many ENOVIA products, called utility trigger programs. These programs are installed with Business Process Services. For each program, the section lists the purpose of the program, accepted argument inputs, processing details, and returns.

The procedure for specifying the input values is the same for all trigger programs and is described in Modifying Inputs and Execution Sequence for Trigger Programs.

To see which trigger programs are used by an application and to find out which administrative object contains the trigger, see the Administrator Guide for the application. The Administrator Guides also describe the trigger programs that are specific for the application.

Make sure you use the symbolic name for any administrative objects that you specify as an argument input. For example, if you need to specify a relationship for an argument input, use the symbolic name for the relationship and not the standard name (relationship_GBOM instead of GBOM).

Previous Revision Promotion

The trigger program eServicecommonPreviousRevisionPromotion_if.tcl is an action trigger for a promote event. The program promotes to a specified state the previous revision of the object that is being promoted. This ensures that when an object is promoted to a particular state, its previous revision is also promoted. If the program encounters a trigger attached to the state to which the revision is getting promoted, the program presents an error message.

Arguments

Argument Argument Name Description and Inputs

1

sState

The state to which the program should promote the previous revision. The program gets the state names from the policy that governs the object that is being promoted. The program accepts three values for this argument:

next--Indicates the previous revision for the object has to be promoted to its next state regardless of the current state of the object being promoted.

last--Indicates the previous revision has to be promoted to its last state in the lifecycle.

[specific state]--Indicates the revision has to be promoted to that state.

If a null is passed as the input, the program takes the current state of the object being promoted as the state to which the revision should be promoted.

Returns

0 if the previous revision is successfully promoted; otherwise 1 and an error message.

Required Connection Check

This trigger program eServicecommonTrigcRequiredConnection_if.tcl checks to see if an object has specific connections. The following table shows the kinds of information the program can check for.

Does the selected object have any: For example:

Connections with other objects.

Does the object have any relationships?

Connections with other objects in one direction.

Does the object have any relationships in which the object is on the From end?

Connections with other objects through specified relationships.

Does the object have any connections to other objects with the Includes Part relationship.

Relationships with objects of specified types.

Does the object have any connections to a Part object?

You can combine the checks listed above. For example, you can have the program check if the object has a connection in which the object is on the From end of any Supplier Response relationship and in which the connected object is an Initial Quotation type.

Arguments

Argument Argument Name Description and Inputs

1

Direction

The direction(s) the program should search from the selected object to connected objects. The program accepts three values:

from--Search only connections in which the selected object is on the From side of the relationship.

For example, suppose three objects are connected like this:

Object 1 --> Object 2 --> Object 3

If the direction input is "from" and Object 2 is the selected object, then the program only considers the connection between Objects 2 and 3.

to--Search only connections in which the selected object is on the to side of the relationship.

""(blank)--Search all connections, regardless of the direction.

2

RelationList

The relationships the program should check for, formatted as a comma-delimited list of symbolic names for the relationships. For example, to check for the Includes Part and Supplier Response relationships, the input would be: relationship_IncludesPart,relationship_SupplierResponse

3

TypeList

The types the program should check for, formatted as a comma-delimited list of symbolic names for the types. For example, to check for connections with Initial Quotation and Final Quotation objects, the input would be: type_IntitialQuotation,type_FinalQuotation

This table shows how to configure the argument inputs depending on the kind of check you want to perform.

To check for: Use these inputs: Direction RelationList TypeList

Any connection

blank blank blank

Any connection in specified direction

To or From blank blank

Any connection to objects of specified type

To, From, blank blank specified

Any connection of specified relationship

To, From, blank specified blank

Any connection of specified relationship to objects of specified type

To, From, blank specified specified

Returns

0 if at least one specified connection exists. Otherwise the program returns 1 along with an error message indicating no connection was found and giving details of the specified connection.

Required File Check

The program eServicecommonTrigcRequiredFormat_if.tcl can check to see if any files are checked in to the:


  • Selected object
  • Selected object for the default format
  • Selected object for a specified format

Arguments

Argument Argument Name Description and Inputs

1

sSearchKey

Specifies the format(s) to check for. The argument accepts three values:

list

Check formats listed in lFormatPropertyList argument.

default

Check only default format of selected object.

all

Check all the formats supported by selected object.

2

lFormatPropertyList

This argument has meaning only if sSearchKey is set to "list". The argument accepts a list of the symbolic names for of the formats to check for. For example, {format_Word format_generic ?}.

3

bSizeCheck

Checks whether the size of checked in files is 0 bytes. The argument accepts two values:

True

The program checks the size of all the checked files (of the format specified by the sSearchKey argument) and fails if all the checked in files are 0 bytes.

False

The program does not check the file sizes.

Processing

If the input for sSearchKey is: The program:

list

Searches for checked files in all the formats listed in argument 1FormatPropertyList. If any format is not supported by the selected object, the program ignores that format.

default

Searches for checked in files in only the default format for the selected object.

all

Searches for checked in files in all the supported formats of selected object.

Returns

If bSizeCheck is False and:


  • The program finds a checked in file of the specified format, it returns 0 for success.
  • The program does not find a checked in file of the specified format, it returns 1 along with an MQL message that explains the reason for failure.

If bSizeCheck is True and:


  • The program finds a checked in file of the specified format and the checked in files are not 0 bytes, it returns 0 for success.
  • The program does not find a checked in file of the specified format or the checked in files are all 0 bytes, it returns 1 along with an MQL message that explains the reason for failure.

Check Relative State

The trigger program eServicecommonCheckRelState_if.tcl is a check trigger for a promote event. It searches a specified relationship looking for a specified object type and determines if all of the objects found are at the minimum acceptable state that has been specified.

Arguments

Argument Argument Name Description and Inputs

1

sRelationship

The relationship type to search for. If the argument input is null, the program checks all the relationships in the direction specified for sDirection. If the specified relationship is not assigned to the target object type, the program returns a FAIL.

2

sTargetObject

The object type to search for at the other end of the relationship. If null, the program checks all the objects that can be reached through the relationship specified for sRelationship.

3

sTargetState

The state the target objects should be in. If the specified state is not a valid state defined for the target object, then the program returns a FAIL.

4

sDirection

The direction to search for. The program accepts three values: TO, FROM, BOTH. If null, the program searches in the FROM direction.

5

sComparisonOperator

The operator the program should use for checking the target state. The values are:

LT (Less Than)--The program returns a FAIL if the target object is in a state greater than the target state.

GT (Greater Than)--The program returns a FAIL if the target object is in a state less than the specified state.

EQ (Equal)--The program returns a FAIL if the target object is in a state other than the specified state.

LE (Less Than Or Equal)--The program returns a FAIL if the target object is in a state greater than or equal to the specified state.

GE (Greater Than Or Equal)--The program returns a FAIL if the target object is in a state less than or equal to the specified state.

NE (Not Equal)--The program returns a FAIL if the target object is in the specified state.

If null, the program uses EQ.

6

sObjectRequirement

A flag that specifies whether the object is required or optional. The values are: Required and Optional. If null, the program uses Optional.

Returns

Pass if all objects are in the minimum required state. Otherwise, the program returns fail. The specific conditions for passing and failing depend on the Comparison Operator.

For example, suppose the comparison operator is LT (less than) and the target object has states defined as A, B, and C.

If the target state is: And the current state is: The program returns:

A

A, B, C

fail

B

A

pass

B

B, C

fail

C

A, B

pass

C

C

fail

Now suppose the comparison operator is EQ (equals).

If the target state is: And the current state is: The program returns:

A

A

pass

A

B, C

fail

B

A, C

fail

B

B

pass

C

C

pass

C

A, B

fail

Valid Revision Sequence

The program eServiceValidRevisionChange_if.tcl is a check trigger for a create event. This program ensures the revision sequence is maintained for a business object by not allowing an object to be created if there is an existing object of the same type and name and of any revision.

Arguments

The program accepts no arguments.

Returns

If the program finds no object of the same type and name (with any revision), it returns zero and the object is created. If the program finds an object of the same type and name with any revision, the program returns a non-zero value, prevents the create event, and shows a message telling the user to use Object>New>Revision instead of Object>New>Original.

Relative Float Action

The program eServicecommonRelativeFloatAction_if.tcl is a promote action trigger. When an object is promoted, the program gets the previous revision of the object and floats all the specified relationships in the specified direction.

Arguments

Argument Argument Name Description and Inputs

1

sRel

The relationship to float. Must be the symbolic name (for example, relationship_PartRule).

2

sDirection

The relationship direction to float. Accepts three values: from, to and both.

3

sOperation

A flag that specifies which revision of the object to look for. It accepts two values: PREVIOUS, LATEST

4

sState

If argument 3 is LATEST, this argument should specify the state in which the latest revision should be. It is passed in as the symbolic name for a state (for example, state_Release).

Processing

Suppose there are four versions for an object A: A1, A2, A3 and A4. The trigger gets fired when A4 is promoted to its next state. If the third argument input is LATEST, the trigger program finds the LATEST revision for A that is in the state specified by the fourth argument. If the third argument is PREVIOUS, the program gets the previous revision, which is A3. It then traverses through the relationship specified in argument 1 in the direction specified by argument 2 and gets all the connected objects, then connects them to A4.

Set Originator Attribute

The Java Program Object emxcommonSetOriginator_if is an action program for create and revise events. The program sets the Originator attribute value to the name of the current user. The program looks up the actual Originator attribute name because the customer could change name of the attribute.

When the trigger program runs, it retrieves the necessary environment variables, such as TYPE, NAME, REVISION, VAULT, USER, EVENT, NEWREV, and APPREALUSER. Because creation is often done as the Shadow Agent person, the program checks the environment variable APPREALUSER. If set, it is used instead of USER for setting the originator.

Two eService Trigger Program Parameters objects that call this trigger program are installed with Business Process Services. These objects call the program whenever any type is created or modified. See Automation for All Types.

Arguments

Argument Argument Name Description and Inputs

1

attrName

The symbolic name for the attribute that is to be populated.

Returns

0 for success; non-zero for failure.