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.

1. On the dependency diagram, double-click the Run External Procedure task icon to view the Run External Procedure Task Details window.

2. Complete the common task fields on this task. See Also: Creating a Task

3. 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

1. 
2. In the server console on the application server, expand your system name and create the external command in the server console.

3. 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.