External Process Connector

This topic provides details of the Alemba® External Process Connector, including:

• The name of the .NET assembly file

• The connection methodology

• Use case scenarios

• Architectural and functional details that ensure the running of the use case through the Outbound Action task in the Workflow Platform

For compatibility and version support details, refer to the ASM Connector Matrix.

Overview

This connector:

• Sends values from a request, task, or a linked entity, to an external process.

• Receives values from the executable and passes them to the request or task.

You should familiarize yourself with the information in Installing Connectors before installing any connectors, and read the Integration topics for more information on how to configure them.

Use Case Scenario

Purpose	External processes are 3rd-party executables such as Powershell and Ping, and perform a functions that cannot performed natively by ASM.
Role	The role of this connector is to pass parameters from the Outbound Action task to the External Process and receive return parameters.
Example	As part of a virtual machine creation, ping an IP address entered into the request submission form to confirm the environment is running before continuing with the request. The IP address is passed by the Outbound Action task in the request to the Ping external process, and returns the latency value to the mapped field in the request or task.

Connector Description

The table below provides a description of the Alemba® External Process Connector.

Information fields	Name
Connector	External Process <-> ASM Core workflow
Assembly	Alemba®.Conenctor.ExternalProcess.dll
Configuration File	Alemba®.Connector.ExternalProcess.xml (default)
Configuration GUI	Alemba®.Connector.ExternalProcess.Config.exe
Connection Methodology	not applicable

Connection Parameters

The connection parameters for this connector are contained within an XML file on the application server where is installed. This file must be mapped to the connector Source.

Connection parameters	Description
Configuration File	The file path and name of the XML file which contains the connection details and parameters for the connector. Required.

Connector Requirements

Ensure that all security requirements are met for the external process to be run. When executing processes on a server other than the ASM server, ensure the executable is accessible through the firewall.

Installation

No install is required for this connector. Upon ASM Core install, this connector is visible in the Integration module, ready to be configured.

Additional Information

This connector does not include any Federated CMDB population functionality.

Connector Operation

Overview

To make the Alemba® External Process Connector work, you must:

1. Configure the XML file using the configuration GUI on the ASM server

2. Configure ASM with a Source for the Alemba® External Process Connector

3. Configure ASM Outbound Action tasks

Configure the XML file

An executable has been provided to assist in the configuration of the Alemba®.Connector.ExternalProcess.xml file, where all the connection parameters, mappable fields, and other details for the external process are defined.

Multiple versions of this XML file can be created by copying the file and giving it a different name. There are no requirements for the file name.

1. Run the configuration GUI

   • Log onto the ASM web server, if you're not already logged on

   • Navigate to the ASM root folder

   • C:\Program Files\Alemba\ASM\

   • Run Alemba®.Connector.ExternalProcess.Config.exe

   • The Alemba® External Process Connector Configuration window opens

   • Toward the top of the window, above the Process field, is shown the XML file which will be affected by any changes that are saved.

   • On first-time configuration, the GUI opens with a simple external process (Ping) already configured to provide an example showing how to configure the tool.

2. Change to a different XML file if this is not the file you want to modify:

3. Once the correct XML file is selected, complete the details:

All examples below use the Ping external process.

Process	The user-defined name of the process. Multiple processes can be configured within a single XML file. Each process appears as a list item in the Action field of the Outbound Action task.
Active	Select the checkbox to make the process selectable in the Action field of the Outbound Action tasks.
Add	Creates a new blank process within the XML file. Presents a popup box to enter the new Process Name.
Clone	Creates a clone of the currently selected process under a new name within the XML file. Presents a popup box to enter the new Process Name.
Remove	Deletes the currently selected process from the XML file.
Rename	Presents a popup box to enter a new name for the currently selected process.
Description	Enter a description to help identify the purpose of the selected process and configuration.
File Path	The file path of the process to be executed. Processes that can be called from anywhere on the server, such as Ping, do not require the path to be included. Other processes require the full file path. To execute Ping, enter Ping. To execute paint.net enter C:\Program Files\paint.net\PaintDotNet.exe
Arguments	Define the input parameters for the process. Parameters can be values or fields mapped from the Outbound Action task. Fields must be enclosed by {{ }}, must exist as rows in the Input Fields section, and must be mapped to ASM fields in the Outbound Action task in order for a value to be passed in. Enter {{IP Address}} to ping the IP address entered into the workflow. Enter 192.168.1.1 to always ping 192.168.1.1 whenever the process is executed.
User Name	Enter the user name under which to run the process. If this field is blank, the process will run using the service account configured for the ASM Services.
Password	Enter the password for the supplied user name.
Input Fields	Create a row for each input field to be mapped to a field in ASM Core. Input fields created here appear as selectable Action Fields in the Outgoing tab of the Outbound Action task. These input fields can be used in the Arguments if enclosed by {{ }}. Name Enter a name for the field. This name appears in the Outbound Action Task as a selectable Action Field, and is also used in the Arguments when defining variable parameters. Type Use the drop down to select the field type, such as Text, Integer, or Blob. Format Enter a format if DateTime was selected as the Type. If blank, will default to the server format. dd/MM/yyyy Test Value Enter a value to be used when testing the configuration for this process returns the desired results. This value is used only when Test Process is pressed. An input field configured as shown: is used in Arguments this way: appears in the Outbound Action task here:
Name	Enter a name for the field. This name appears in the Outbound Action Task as a selectable Action Field, and is also used in the Arguments when defining variable parameters.
Type	Use the drop down to select the field type, such as Text, Integer, or Blob.
Format	Enter a format if DateTime was selected as the Type. If blank, will default to the server format. dd/MM/yyyy
Test Value	Enter a value to be used when testing the configuration for this process returns the desired results. This value is used only when Test Process is pressed.
Output Pattern	Define a formula, based on Regular Expression parsing, to extract the required parameters from the output of the external process and make them available to be mapped to the ASM workflow. In the formula, replace the output parameter with a field defined in the Output Fields section and enclosed it in < >. The output from Ping is: Minimum = 288ms, Maximum = 289ms, Average = 288ms Therefore the Output Pattern would be defined as: Minimum = (?<timeMin>\d+)ms, Maximum = (?<timeMax>\d+)ms, Average = (?<timeAvg>\d+)ms ... where the Output Fields section contains a row with the Name value of timeMin.
Error Pattern	Same as for the Output Pattern, but used instead of the Output Pattern when the external process returns an error message. Define a formula, based on Regular Expression parsing, to extract the required parameters from the error output of the external process and make them available to be mapped to the ASM workflow. In the formula, replace the output parameter with a field defined in the Output Fields section and enclosed it in < >.
Failure Codes	Define the exit codes from the external process to trigger the failure/rejection path in the ASM workflow. Multiple error codes can be entered, separated by a comma.
Time Limit (ms)	Set a time limit for the process to complete. If a process takes longer to complete than the specified time limit, it fails.
Output Fields	Create a row for each output field to be mapped to a field in ASM Core. Output fields created here appear as selectable Action Fields in the Incoming tab of the Outbound Action task. These output fields can be used in the Output Pattern and/or Error Pattern if enclosed by < >. Name Enter a name for the field. This name appears in the Outbound Action Task as a selectable Action Field, and is also used in the Output Pattern or Error Pattern when defining parameters. An output field defined with the Name timeMin can be used in the Output Pattern as follows: Minimum = (?<timeMin>\d+)ms Type Use the drop down to select the field type, such as Text, Integer, or Blob. Format Enter a format of DateTime was selected as the Type. If blank, will default to the server format. Leave this field blank if Date/Time was not selected as the Type. dd/MM/yyyy Output fields configured as shown: are used in the Output Pattern this way: appear in the Outbound Action task here: Output fields that are not used in either the Output Pattern or Error Pattern will return no values to the ASM task.
Name	Enter a name for the field. This name appears in the Outbound Action Task as a selectable Action Field, and is also used in the Output Pattern or Error Pattern when defining parameters. An output field defined with the Name timeMin can be used in the Output Pattern as follows: Minimum = (?<timeMin>\d+)ms
Type	Use the drop down to select the field type, such as Text, Integer, or Blob.
Format	Enter a format of DateTime was selected as the Type. If blank, will default to the server format. Leave this field blank if Date/Time was not selected as the Type. dd/MM/yyyy

1. To test the Process has been configured correctly, select Test Process

2. To test the Output Pattern has been configured correctly, select Test Pattern

3. Save the configuration details by selecting Save

If the Integration Source is defined, and afterward the configuration in the XML is changed, you must re-save the Source for the connector in the Integration Platform in order for the changes to appear in Outbound Action tasks.

Configuring a Source for External Processes

1. Select ≡ > Admin > Integration.

2. In the Explorer pane, under Integration, select Sources.

3. Select the button on the toolbar. In the pop up window, select Alemba External Process Connector from the drop-down list.

4. In the Integration Source Details window, complete the details.

Name	Type a name for the integration source. Required.
Status	This field is pre-filled with the Active status.
Connector	This field is pre-filled with the Connector type.
Assembly.TypeName	This field is pre-filled based on the selected connector as defined in the Connector DLL, and is read-only.
Configuration File	The file path and name of the XML file which contains the connection details and parameters for the connector. Required.

Save the details.

Configuring Outbound Action Tasks

This connector is designed to be used by Outbound Action tasks in workflows.

The information contained below relates directly, and only, to configuring task fields for the External Process Connector, and assumes a basic working knowledge of tasks in workflow templates.

For general information on configuring Outbound Action tasks, refer to Creating an Outbound Action Task.

In the Mapping Details section of the Outbound Action task, complete the details:

1. Expand the Mapping Details section, if necessary, and select the Source and Action.

Source	Select the Source configured for the External Process connector in the Integration Platform.
Action	Select the process to be run by the Outbound Action Task. Processes are defined in the XML file referenced in the Integration Source details.

1. Select the Outgoing tab to map the fields for outgoing field values from ASM. This allows you to specify how field values from the ASM request or task correlate to the parameters in the external process (defined as Input Fields in the XML file) when this task activates.

2. • Click Add. In the Add Fields window, select the parameters you want to map to fields on the task or parent request. Click OK.

   • On the browse table, click the corresponding cell in the Internal Field column. Then click the field selector button to pick a static value or a field from the task or request.

   • Depending on the field’s data type, additional options can be selected in the field selector, including: field transformations, profile maps, or resolution rules.

   • Add more field mappings if needed.

   • To delete any mapped fields, select the mapping and click Remove. In the warning dialog box, click Yes to remove the field mapping or No to cancel.

   • The Send Notify checkbox does not apply for this connector.

3. Select the Incoming tab to map the incoming values from the external process. This allows you to specify how the values from the external process (defined as Output Fields in the XML file) correlate to fields in ASM when a response is received from the external process.

4. Click Add. In the Add Fields window, select the task or request fields you want to map to parameters in the external process. Click OK.

   • On the browse table, click the corresponding cell in the Action Field column. Then click the field selector button to pick a static value or a parameter from the external process. These fields are defined as Output Patterns in the XML file.

   • Depending on the field’s data type, additional options can be selected in the field selector, including: field transformations, profile maps, or resolution rules.

   • In the Update column, select the conditions for populating the field in ASM. Always always updates the ASM field with the value from the stored procedure. Only When Blank only populates the ASM field with the value of the stored procedure if the field in ASM is blank. This means that an existing value in ASM cannot be overridden.

   • The On Initial Population Only update condition does not apply