Conventional triggers are executed in their own processes. For example, a Perl trigger starts the Perl interpreter, which runs the script, and subsequently the interpreter terminates. In contrast, in-process triggers, which are also called BSF triggers because they use the Bean Scripting Framework, are run inside the web server process. The advantage to this is less overhead and potentially better performance. Additionally, BSF triggers have access to the Trigger API, as opposed to the Perl API.
Conventional triggers are started by calling the executable to run the script file.
For example:
perl my_trigger.js arg1 arg2
The executable required to run the script must be available. Perl is available by default, but other commands must either be in your path or be installed in the triggers directory. Successful commands must return "0" (zero).
Most triggers access the Perl API. See the Perl API Help for details.
An in-process trigger is declared by using bsf in place of the executable name.
For example:
bsf my_trigger.js arg1 arg2
The file extension of a BSF script (.js for JavaScript, .py for Python) determines which scripting language is used to execute the script.
Scripts can get an object from the bsf global object by calling bsf.lookupBean (object name). The syntax varies depending on the exact scripting language.
Object | Description |
---|---|
Event | Contains details about the particular trigger event that is firing. Notably, it contains a token for the current user and the admin user. This token can be used to interact with the API and the CR or task ID that is being modified. While there are some shared properties for all triggers, most trigger types have their own event object with at least some unique properties on each. For more details, see the trigger API documentation. |
args | An array of the arguments passed to the script, for example, arguments defined in the lifecycle. However, some scripting languages have their own method of getting command-line arguments, but that should not be used by triggers. |
log | A way to write messages to the event.log file. For more details, see the trigger API documentation. |
api | API for triggers to interact with Rational® Change. For example, to look up CR attributes or to create associated tasks. For more details, see the trigger API documentation. |
Call event.stopTransition(msg), which prevents a transition from proceeding if it is in progress and shows the given message to the user if appropriate.
event.fail(errorMsg), which displays the error message to the user if possible, or in the event.log, for example, during an asynchronous trigger. When called during a pre-transition, fail hides the transition link or prevents the transition from proceeding, which is like calling event.stopTransition.