Define a Run a Program Action
Use the Run a Program Action to launch any program that can be run from a Windows command line.
For example, add a One-Step Action to a button, link, menu bar, or task pane of an Incident record to run a program to reset a password, page a technician, or ping a server directly from a record.
You can run a program from:
- The machine from which the One-Step Action is run.
- Another machine on the same network.
- A machine on a remote network, using Trusted Agents.
Users running the One-Step Action must have permissions to access the program location and to run the program you specify in any case.
Using a Trusted Agent with this Action may be required for SaaS customers. See Configure One-Step Actions for Trusted Agent.
To define a Run a Program Action for a One-Step Action:
- Open the One-Step Editor.
- Add a Run a Program Action to the Designer Board.
- Define general properties for the Run a Program Action:
Option Description Name Provide a display name for the Action (this is how the Action is identified within the One-Step Action). Filename Provide the fully qualified path and file name of the program you want to run (using text and/or tokens).
If you are running a program on a local machine or an accessible machine on your network, you can select the Ellipses button to navigate to the program location.
If you are configuring the Action to run using a Trusted Agent Group, the Ellipses button is disabled and you must type or paste the fully qualified path and program file name for the remote machine.
Start In If the program or file should start running in a particular directory, then provide the name of that directory (using text and/or tokens), or select the Ellipses button to browse to the directory on your computer. If no directory is specified, the current working directory is used (this is usually the directory from which CSM was launched).
If you are configuring the Action to run using a Trusted Agent Group, the Ellipses button is disabled and you must type or paste the fully qualified path for the remote machine.
- Define command-line arguments: Provide any arguments that must be passed to the program (using text and/or tokens). Tokens are passed to the program as parameters.
- Define how the One-Step Action should interact with the program:
Option Description Wait for Program to End before Continuing Select this check box to have the One-Step Action wait until the program finishes executing before continuing to the next Action. Timeout after X Seconds When the Wait for Program to End before Continuing check box is selected, specify a timeout period in seconds. The program either waits until the program is finished executing or the specified number of seconds has passed. Store Exit Code from Program Select this check box to store the program’s return code for use in future One-Step Actions. A name is provided for the variable that will hold the return code (example: Run program result). The variable is available in the system so you can reuse it. This is not required; however, in most cases, you want to store the program result so that you can do something with it (example: Create a Journal - History record that stores the result).
- Define how the program should run:
Option Description Run In the drop-down, select the size of window (normal, minimized, maximized, or no window) to open the program in. This applies to a command prompt window as well as the executable program. The command prompt window is in the background and is not shown to users. Custom Run Verb Uses a custom run verb. This is an additional parameter that tells the program how to run (if the program requires one). Some common verbs are new, open, edit, and print. Consult the program’s documentation to find out what verbs are available. If the program makes its list of supported verbs available, they are available in the drop-down. Pause after Run The One-Step Action pauses for a few extra seconds after running the program before continuing to the next Action; the User specifies the number of seconds the One-Step Action should pause.
- Define the Annotations for a One-Step Action.
- Select Save.
Configuring the Run a Program Action for Trusted Agents
To configure the Run a Program Action to run on a remote network, follow the steps in Configure One-Step Actions to Run on Trusted Agents.
One-Step Actions that run using Trusted Agents are intended to run unattended. One-Step Actions that require User interaction during execution may fail when they are run using Trusted Agents.