Calling Approval Server application commands in your application
To support interaction between the and , use a special process—Application-Command. You can run this process from filters, escalations, and active links by using the Run Process action.
The Application-Command process allows the specification of commands to be executed by an application. Whenever an Application-Command process is run, a request is created in the Application Pending form that contains details about the command. The Application Dispatcher retrieves commands from this form and passes them to the approval server for processing. If the Application Dispatcher is not in use, the approval server retrieves commands directly from the Application Pending form.
The Application-Command processes exist on the . If you are performing an operation from an active link, you must use the syntax that indicates that the process should be run as a remote process on the server. For more information, see Defining-Run-Process-actions-to-run-processes-programs-or-commands and Keywords.
The basic command format for an Application-Command process is as follows:
[-e <requestID>] [-t <tag>] [-1 <field1>] [-2 <field2>] [-3 <field3>]
[-o <otherString><255chars>] [-l <otherStringUnlimited>]
The example uses the following conventions:
- Parameters not enclosed in brackets are required.
- Parameters enclosed in square brackets are optional.
- Braces indicate that you must specify only one of the enclosed values.
When an application command is executed from within a Run process of a filter, if the value for the -s parameter is not given, the command automatically takes the value as the form from which the filter was executed. If you want the value of the -s parameter to be blank, you must specify the parameter as follows:
As with all Run Process actions, use quotes around a parameter when its value contains a space, to make sure that it is evaluated correctly.
Application command parameters
The following table describes the parameters and their expected values. The category and command parameters are positional. The other parameters are optional, and can appear in any order after the two positional parameters. If you supply any parameter that is not defined for the command, it is ignored.
Parameter | Description |
|---|---|
category | A character string that identifies which application the command is for; maximum length: 30 characters. For the approval server, this value is always Approval. |
command | A character string that indicates a specific operation to be performed within the category; maximum length: 30 characters. Commands for the approval server are defined in this section. |
-s | formName is the name of a form to which the command is related. |
-e | requestID is the ID of the request to which the command is related. If the request is in a join form, the request ID string consists of the ID of each request separated by a vertical bar, such as: 000000000012344|000000000084934 If no request ID is specified, this value defaults to the current entry ID. |
-t | tag is a description that is specific to the category and command. It might be a further identifier for the operation. For example, for many approval commands, the tag is the name of the approval process. |
-1 | field1, field2, or field3 is the ID of a field or an integer code associated with the category or command. |
-o | otherString<255chars is a string that provides any further information; maximum length: 255 characters. For example, you can provide a list of approvers who are expected to act on this request. |
-l | otherStringUnlimited is a string that provides any further information. For example, you can provide a list of approvers who are expected to act on this request. The approval server does not impose a restriction on this string, but its maximum length might be limited by the database. |
If the operation is performed from a filter or escalation, the -s and -e parameters default to the current form name (as the application form name) and the current request ID (as the application request ID). Therefore, if the default values are sufficient, you can omit these parameters. If the operation is performed from an active link, the cannot determine what the current environment is, and these values must be supplied.
Example of an application command
The following command would start the approval process named MyProcess against the current request: