Retrieve data from applications with Run Process

Using the $PROCESS$ keyword of the Set Fields action, AR System can run an application and set the output of the application in various data fields. You can run only a process that behaves as follows:

• Runs in a console (such as a .bat script or runmacro.exe ), but not in a GUI application.
• Returns 0 if successful. (In this case, stdout is pushed to the field.) If the process returns anything other than 0, stdout displays an error message.

Whether you use an active link, filter, or escalation depends on the purpose of the external application. Active links can execute locally on the client machines or on the server. Filters and escalations execute only on the server.

Retrieving data from another application

When an external application is run on the server, AR System waits for the process to terminate so that it can capture and interpret the output of the process. To avoid situations where AR Systemwaits indefinitely for a process that fails to terminate, a process time-out is built into AR System.

On the AR System Administration: Server Information form, you can configure this time-out for between 1 and 60 seconds.

In a Set Fields definition, the $PROCESS$ keyword indicates that all text that follows is a command. Use the full path name to the executable, and you can pass AR System data field values as parameters. When using active links, remember that they run with the access control of the user, so access to form fields might be limited.

When workflow that performs a Set Fields action is run, the process starts, and the web client waits for it to complete. In UNIX, the process runs in a Bourne shell. The web client reads all returned data, which is processed according to the return status of the process:

• If the return status is zero, the data is used as the new value for the field.
• If the process returns with a status other than zero, the web client assumes the process failed and does not update the field contents. Instead, the output from the process is used as an error message and displayed to the user.

When designing an active link that uses a $PROCESS$ Set Fields action on the client, always consider the variety of client platforms that users will use. The keywords $HARDWARE$ and $OS$ can be used in the Run If the expression for the active link to verify that the client is on an appropriate platform. If the active link is supported on multiple platforms, each platform requires its own active link with appropriate qualifications.

You can run a process on a server by inserting @serverName: before the process name in an active link. For example, $PROCESS$ @ServerA: C:/temp/process.exe. If it is the current server, you can use @@ instead of @serverName.

The following figure shows an example of a Set Fields action for a filter. The action sets the values of two fields by executing a separate utility program for each one, passing the values of existing fields as parameters. If the programs execute correctly that is, return with an exit code of zero, their outputs are assigned to the respective fields.

Defining a Set Fields action using $PROCESS$