Creating a Run External Procedure Tasks
A Run External Procedure task can be used to automate any procedure that is part of a workflow. It is used to call and execute an external script. Parameters are passed to the script at runtime
The ability to automatically run an executable once the task is activated allows for an additional level of automation outside of the reach of ASM - for example, a web service could be run to update a user account within another application.
The Run External Procedure Task provides a level of integration through script files, web services, visual basic scripts and other executable files that would otherwise require customization within ASM. Invoking an executable within a workflow process provides the flexibility to make changes not only to other applications but also to networks, networked computers and hardware, websites, configuration information, system setups and more.
Scripts are added to ASM through the Server Console by your system administrator. Users can then specify any of these scripts as the one to be run when a Run External Procedure Task becomes active in a workflow.
The script to be run is selected from a drop-down list within the Run External Procedure Task. Additional parameters can be passed from the Task or Request to the external task in order to fine tune the script. Any parameters defined must be compatible with the script selected. Once the task is activated, the parameters will be appended to the script, the script will be run, the task will complete, and the workflow will progress.
You can create a script for installing software on a particular server, say InstallSoftware.vbs, and add it to the Server Console. When you define the Run External Procedure Task, you will be able to select this script from the Command list. The script requires a parameter that provides the name of the server on which the script needs to install the software. The parameter could be something like “-server //MACHINE01”.
Creating a Run External Procedure Task
The task must be completed automatically for the script execution to occur.
The procedure or command specified on a Run External Procedure task will execute only if the task is closed by the Workflow polling service. If this task is closed using the Complete button on the Task Details window, the message “Completing this Task manually will not run the external command. Do you want to continue?" will be displayed, and the procedure or command will not run.
On the dependency diagram, double-click the Run External Procedure task icon to view the Run External Procedure Task Details window.
Complete the common task fields on this task.
Specify the details of the external procedure to be run.
Command | This list displays all the scripts that are available on your systems. (Scripts are any form of executable files, such as batch files, Visual Basic scripts, and Web services.) Script are added through the Server Console. |
Parameters | This field can be used to pass additional parameters that will be appended to the script when this task is implemented and the script is run. The parameters have to be compatible with the script selected in the Command list. See Passing Field Values to the External Procedure for more details. See Passing Variables to PowerShell to pass variables to a PowerShell script. |
4. Save the task. It will be completed automatically once it is activated as part of a workflow.
Passing Field Values to the External Procedure
You can pass field values from the Request and/or Task to the command, by entering the parameter names from the table into the Parameters field of the Run External Procedure Task Detail window.
For Example: The Request ID needs to be passed to the RunExe.exe executable on the command line, along with constants “xyz” and “aaa,” to allow the Requests to initiate an RBA process as a sub-flow to handle release automation or provisioning. When “xyz [REQUEST_NO] aaa” is entered in the Parameters field, the number of the current Request (163108, for this example) will replace [REQUEST_NO] in the command line of the external procedure task like this: “RunExe.exe xyz 163108 aaa”.
The table below provides the list of standard Request and Task parameters which can be passed in the command line of the executable.
The parameters related to Request and Task must be put between square brackets, as shown.
Field | Output | Parameter |
Request Number | Ref No | [REQUEST_NO] |
Request Title | Text | [REQUEST_TITLE] |
User | Ref No | [REQUESTOR_REF] |
Text | [USER_FULL_NAME] | |
Tel | Text | [TEL] |
Organization | Ref No | [CLIENT_CO_REF] |
Text | [CLIENT_CO_NAME] | |
Location | Ref No | [LOCATION_REF] |
Text | [LOCATION_NAME] | |
Request Type | Text | [REQUEST_TYPE] |
Ref | Text | [REQUEST_REF] |
Priority | Text | [REQUEST_PRIORITY_REF] |
Request Description x | Text | [REQUEST_DESC] |
Task Number | Ref No | [TASK_NO] |
Task Title | Text | [TASK_TITLE] |
Passing Dates and Text Strings
You should confirm the expected format of any dates that you pass to an external procedure to ensure that they are not mistranslated. If, for example, you pass a date in the format ddmmyy, and the external system is expecting a date in the format mmddyy, the date will be misrepresented.
Also, if there are spaces in the original material, the parameter can get split into several parameters. If, for example, you pass date time, it will become two separate fields. You can use this to your advantage if you want to, say, strip out the time that is stored by default in the originating system's date field, but it is something that you need to be aware of.
Likewise, if a name is held as FirstName LastName in the originating system, it will be dismantled into two different parameters. The universal way to keep everything together is to use single quotes outside the square brackets to contain the string.
Request Parameter Examples
Any parameter pertaining to a request apart from those below, must be prefixed with REQUEST:
Request Text/Text Area/Numeric/Checkbox/Date Field
Example | Prefix | Value |
Request Target Date | REQUEST: | TARGET_DATE |
Request Dropdown/List Box/Multi-Select Field
Example | Prefix | Look Up Value in Request | Assigned List |
Risk | REQUEST: | RISK_REF | #CR_REQ_RISK |
Request QD Field
Example | Prefix | Look Up Value in Request | Look Up Table | Value |
User | REQUEST: | REQUESTOR_REF | $AR_PERSON. | DISPLAY |
Organisation | REQUEST: | CLIENT_CO_REF | $AR_CLIENT_COMPANY. | CLIENT_CO_NAME |
Location | REQUEST: | LOCATION_REF | $AR_LOCATIONS. | LOCATION_NAME |
Request QD Linked Field
Example | Prefix | Look Up Value in Request | Look Up Table | Value |
User’s Login ID | REQUEST: | REQUESTOR_REF | $AR_PERSON. | USER_ID |
Org’s Custom String 1 | REQUEST: | CLIENT_CO_REF | $AR_CLIENT_COMPANY. | CUSTOM_STRING_1 |
Location’s Postcode | REQUEST: | LOCATION_REF | $AR_LOCATIONS. | POSTCODE |
Request Custom Extension Text/Text Area/Numeric/Checkbox/Date
Example | Prefix | Value |
Barcode No (Custom Field 500096) | REQUEST: | EXTFLDV_500096 |
Request Custom Extension Dropdown/List Box/Multi-Select
Example | Prefix | Look Up Value in Request | Assigned List |
Leave Type (Custom Field 500108) | REQUEST: | EXTFLDV_500108 | #EXTPROFILE50005 |
Request Custom Extension Single Value QD/Multiple Value QD
Example | Prefix | Look Up Value in Request | Look Up Table | Value |
Business Owner (Custom Field 500076) | REQUEST: | EXTFLDV_500076 | $AR_PERSON. | DISPLAY |
Task Parameter Examples
Task Text/Text Area/Numeric/Checkbox/Date Field
Example | Value |
Task Completion Date | COMPLETION_DATE |
Task Dropdown/List Box/Multi-Select Field
Example | Look Up Value in Task | Look Up Table |
Request Status on Completion | REQ_STATUS | $CR_REQ_STATUS |
Task QD Linked Field
Example | Look Up Value in Request | Look Up Table | Value |
Owned BY | CURRENT_REF | $AR_PERSON. | DISPLAY |
Passing Variables to PowerShell
In the server console on the application server, expand your system name and create the external command in the server console.
In the workflow, add or locate the Run External Procedure task where you can specify the file name and the parameters to be passed.
You can get field names is by going into ASM Designer and opening an email template. Drop the field you are looking for onto the email and it will display its database name and reference. Then just close the email template without saving.
Make sure the parameter names you are passing (in this example one of them is –paramGroupName) is also an accepted parameter in the PowerShell file.
