Administration Guide

Creating Integrations

To create an Integration, follow the instructions below.

Integrations run PowerShell commands, from lightweight "cmdlets" to PowerShell scripts and external programs. This gives you a powerful tool for launching any external commands, scripts, and apps directly from Alloy Navigator Express.

Depending on the task you want an external command to perform, it can run on a client computer, i.e. on the computer from which the workflow action is initiated, or on the server computer, i.e. the computer hosting the Automation Server.

Typically, client commands perform interactive tasks that show something to the user who run them. For example, they can return ping replies or open a remote desktop session.

Server commands typically perform non-interactive, background jobs. Background jobs run commands that take long time to be completed. When finished, jobs do not display their results, but save them somewhere, and you can retrieve them when needed.

NOTE: Client commands can be launched only from the Web App, Desktop App, and the Self Service Portal. Server commands can be launched from anywhere.

 

To configure an Integration:

  1. Go to Customization > [Module] > [Object Class] > Workflow > Integrations section and click New. The [Object Class] Integration [ID] window opens.

    TIP: To base a new Integration on an existing one, select the source Integration and click Copy Item.

  2. In the Name field, type in the Integration name. This name will be displayed to the user in the Action Bar and the Actions menu. Optionally, specify a description.

  3. Keep the Enabled check box selected. Otherwise, the Integration will not be available.

  4. Under Run command on, choose where to run the command: on the client or on the server.

  5. Under Run, enter a command or script for the PowerShell to run, just like you would enter it in your Windows PowerShell console. This can be a PowerShell cmdlet, a combination of cmdlets, a script, or any external program.

    ABOUT LAUNCHING EXTERNAL PROGRAMS:

    In order to launch external programs, PowerShell must know where their executables reside. The best practice is to add paths to their directories to the PATH environment variable. This will help PowerShell find the programs without giving it the full paths. Some standard programs, such as Ping or Remote Desktop, can be run just by typing the name of their executable because their directory path (C:\Windows\System32) exists in the Windows search path by default.

    An alternative method is specifying full paths to programs explicitly. If a path contains spaces, enclose the path with double quotation marks ("), and add an ampersand character (&) before the first quotation mark. The ampersand tells PowerShell to treat the string expression in quotes as a command to be executed. Note that the "full path" method requires that the path is the same on all computers from which the Integration is initiated.

    To enter a dynamic parameter, such as the name or IP address of the client computer, click Insert Placeholder and use the Select Placeholder dialog box to insert a placeholder. At runtime, all placeholders will be replaced by the actual data.

    INFO: For details, see Inserting Placeholders.

    IMPORTANT: Add double quotation marks (") around placeholders, so all placeholders in your command are enclosed in quotes. For example: "%[DBF Field1]%" or "%[DBF Field1]%%[DBF Field2]%%[DBF Field3]%".

    IMPORTANT: The version of PowerShell on computers where the command will run must match the version of your PowerShell script or command, or be higher. The screenshot above shows an example for PowerShell version 5, which comes preinstalled on Windows 10 and Windows Server 2016.

    INFO: For additional information, see Microsoft PowerShell documentation at https://docs.microsoft.com/powershell/.

  6. For client commands: If you want the user to review the output information in the PowerShell window, select the Display PowerShell window check box.

  7. For server commands: Specify the timeout period (in minutes) after which the Automation Server will finish inactive background jobs.

    TIP: If you want the job to run with no timeout, enter 0 (zero).

  8. Click OK.

NOTE: To run External Command operations, the PowerShell executable file (powershell.exe) must exist in the folder specified in the PATH environment variable on the computer where the operations run, i.e. on the client or on the server.

INFO: For information on Integrations, see Integrations.