To create an Integration, follow the instructions below.
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.
In order to allow for seamless integration, Alloy Navigator Express uses Alloy Integration Launcher. This small program must be installed on the computer where the workflow action containing your external command is initiated from. The installation scenario depends on where the action is initiated from:
Web users install the launcher when needed. The Web App and Self Service Portal prompt their users to instal the launcher when they run such an action for the first time.
Desktop users get the launcher installed automatically, along with their desktop applications.
To configure an
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.
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.
Keep the Enabled check box selected. Otherwise, the Integration will not be available.
Under Run command on, choose where to run the command: on the client or on the server.
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
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]%%[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/.
For client commands: If you want the user to review the output information in the PowerShell window, select the Display PowerShell window check box.
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).
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.