Adding Run Executable automation rule actions

The Run Executable automation rule action runs a script or compiled program if the rule passes. For example, you can create scripts to check changes made in items and send item information to an external reporting system. You can add this action to before save triggers, after save triggers, and escalation rules.

To run an executable from an automation rule, the executable must be located on the Helix ALM Server computer. The administrator also needs to make sure the executable has appropriate directory access permissions and the same run privileges as the server. If Helix ALM cannot find the executable, an error is returned to Helix ALM and the action does not run.

If you add a trigger to run a Unix shell script, make sure the file has execute permissions for the root user. The shebang line (e.g., #! /bin/sh) tells the operating system which application to use to run the script. Helix ALM cannot run the script without this line.

Adding to before save triggers

Before save triggers can run server scripts that perform additional checks. Executables that run for before save triggers must return a value that tells the server if items can be saved. A return value of 0 indicates the items should be saved. Any other return value indicates the items should not be saved. If a value other than 0 is returned, any messages output by the executable (output to stdout) are sent back to Helix ALM with the error. This error is truncated to 1024 characters.

Following are examples of how to return a value from an executable run by a trigger.

  • C program—Specify the value in the return() statement in the main() routine. You can also use a parameter in the exit statement.
  • Windows/DOS batch file—Set the ERRORLEVEL value.
  • Windows application—Use the CWinApp::ExitInstance() function.

Adding to after save triggers and escalation rules

After save triggers and escalation rules can run server scripts that perform additional actions based on saved items. Executables that run for after save triggers and escalation rules do not require a return value and run immediately when the rule passes.

You can use environment variables to retrieve data about the item that caused rules to run and pass the data back to the executable. See Environment variables.

1. Select Run executable from the Action list in the Add Rule Action dialog box when you are configuring an automation rule.

2. Enter the full path to the Executable location.

The location must be the relative or absolute path to the executable on the Helix ALM Server. Multiple files and arguments are not supported.

3. Click OK to add the action.

You can configure timeout limits and the maximum number of simultaneous processes that can run for executables in the Helix ALM Registry Utility. See the registry utility documentation for information about editing automation rules options.