Automation Studio CLI Commands

This section defines Automation Studio CLI operations, lists the options for each operation, and provides best practices and examples.
ra55
This section defines Automation Studio CLI operations, lists the options for each operation, and provides best practices and examples.
Use the -h, --help option with any operation to view a list of all available options for the operation. All examples in this section use the sample application presented in CLI Best Practices.
The following operations let you manage your applications through Automation Studio:
  • export-application
  • get-job-status
  • stop-job
  • run-process
Each of these operations has morel options used to complete the CLI operations.
To enhance security, we recommend that you use the RA_HOME\scripts\encrypt_password utility to encrypt any passwords you enter in CLI commands.
export-application
This operation lets you export one or all applications without launching the UIs.
  • -a,--app-name <arg>
    (Optional) List of application names to be exported. Format as: {app_name1, app_name2,...}. If no applications are specified, then all applications are exported.
  • -f,--file-path <arg>
    Specifies the path of the file that the export creates.
  • -p,--password <arg>
    Specifies the password for the user name you enter in the -u option.
  • -u,--user <arg>
    Specifies a
    Release Automation (Nolio)
    user name that lets you connect to the application.
C:\CA\RelAutoCLI>nolio.cmd export-application --app-name {ParamsTest} --file-path c:\test\ParamsTest --user superuser --password <password> executing export-application Export finished successfully. Export location [c:\test\ParamsTest.dat]
get-job-status
This operation lets you view the status of a job:
  • -i,--job-id <arg>
    Specifies the unique job (executed process) ID.
  • -p,--password <arg>
    Specifies the password for the user name you enter in the -u option.
  • -u,--user <arg>
    Specifies a
    Release Automation (Nolio)
    user name that lets you connect to the application.
C:\CA\RelAutoCLI>nolio.cmd get-job-status --job-id 65556 --user superuser --password <password>
stop-job
This operation lets you stop a running job:
  • -i,--job-id <arg>
    Specifies the unique job (executed process) ID.
  • -p,--password <arg>
    Specifies the password for the user name you enter in the -u option.
  • -u,--user <arg>
    Specifies a
    Release Automation (Nolio)
    user name that lets you connect to the application.
C:\CA\RelAutoCLI>nolio.cmd stop-job --job-id 65557 --user superuser --password <password>
run-process
This operation lets you run an application process:
  • -a,--app <arg>
    Specifies the application name on which the operation occurs.
  • -b,--tag <arg>
    (Optional) Specifies the name of the process tag to run. If none is given, the latest published version is used.
  • -c,--conf-file <arg>
    (Optional) Specifies the path to the configuration file that contains detailed parameters for the CLI to run. Add link
  • -e,--env <arg>
    Specifies the environment name on which the operation occurs.
  • -f,--flow <arg>
    Specifies the name of the process to run.
  • -j,--job-name <arg>
    (Optional) Specifies a display name for the executed job.
  • -n,–async
    (Optional) Runs the process asynchronously. Do not wait until execution terminates.
  • -p,--password <arg>
    Specifies the password for the user name you enter in the -u option.
  • -r,--params <arg>
    (Optional) Specifies a list of parameters to set. Format as {param1, val1, param2, val2…}
  • -s,--servers <arg>
    (Optional) Specifies a list of servers on which to run the process. Format as {server1, server2, server3…}. If no servers are selected, then the process is executed on all servers in the relevant server type.
  • -t,--timeout <arg>
    (Optional) Specifies the time-out for the execution in seconds.
  • -u,--user <arg>
    Specifies a
    Release Automation (Nolio)
    user name that lets you connect to the application.
  • -x,--keep-job
    (Optional) Keeps the process run active if it is paused due to failure. Requires manual intervention.
C:\CA\RelAutoCLI>nolio.cmd run-process --app ParamsTest --env TestEnv --flow TestInit --job-name from-CLI --servers {<hostname>} --user superuser --password <password>
The following example passes the parameters defined for the sample application:
C:\CA\RelAutoCLI>nolio.cmd run-process --app ParamsTest --env TestEnv --flow TestInit --job-name from-CLI --servers {<hostname>} --params {firstValue,1230493,<hostname>/secValue,433434,<hostname>/TestComp/thirdValue, 45602} --user superuser --password <password>
The sample application defined in CLI Best Practices, has three User Input parameters at different levels. Note that only User Input parameters can be passed.
Here is a short summary of the parameter levels, their formats, and the examples from above:
  • Application Level
    A user input value associated with the application.
    Format:
    <parameter name>, <value>
    Example:
    firstValue,1230493
  • Server Type Level
    A user input value associated with the server type. Must include the agent where this process is running.
    Format:
    <server name>/<parameter name>, <value>
    Example:
    <hostname>/secValue,4333434
  • Component Level
    A user input value associated with a component. Must include the agent where this process is running.
    Format:
    <server name>/<component name>/<parameter name>, 12323
    Example:
    <hostname>/TestComp/thirdValue,45602
Additional Parameter Examples
The following section includes additional examples of how to build parameters into the run-process operation:
Application Parameter
The following example shows a CLI command for running a process with an Application Parameter:
>nolio.cmd run-process -u superuser -p suser -a "Test" -e "Environment for Default Architecture" –f "delay" -r "{Application Parameters/app_param,hello cli}"
The command overrides a parameter set as an Environment parameter as long as User Input is selected.
Two Server Types
The following example shows a CLI command that refers to two server types, similar to the example of the CLI with more than one parameter.
Each parameter is referenced under its server. The servers in this instance are QA_LAB1 and QA_LAB2, which are the names of the Agents:
>nolio.cmd run-process -u superuser -p suser -a "CLI_APP" -e "Environment for CLI arch" -f " CLI_BOOL_PROC" -r "{QA_LAB1/CLI_COMP/cli_bool,true,QA_LAB2/CLI_COMP/cli_bool,false}"
A warning is not given if you run a multiple server type process and you select only one server type to run.
Parameter Under the Default Component Folder
The following example shows a CLI command where the parameter is under the default component folder:
>nolio.cmd run-process -u superuser -p suser -a "Test" -e "Environment for Default Architecture" –f "delay" -r "{QA_LAB2/Default Component/param,hello cli 2}"
Parameter Under a Server Type Folder
The following example shows a CLI command where the parameter is under a server type folder:
>nolio.cmd run-process -u superuser -p suser -a "Test" -e "Environment for Default Architecture" –f "delay" -r "{QA_LAB1/st1p,hello cli 2}" "QA_LAB1" is the agent name; "st1p" is the name of the string parameter that actually sits under a folder called "Server Type 1".
To run the same process on five Agents using the set parameter under Server Type 1, enter the parameter into the CLI five times with each Agent name.
In the example, "hello cli 2" is the value for the string parameter.
Parameter Under a Folder in Application Parameters
The following example shows a CLI command where the target parameter is under a folder in the Application Parameters:
>nolio.cmd run-process -u superuser -p suser -a "Test" -e "Environment for Default Architecture" –f "delay" -r "{Application Parameters/Folder/app_param,hello cli}"
Multiple Parameters
The following example shows a CLI command containing more than one parameter:
Param1,Value1,Param2,Value2:
>nolio.cmd run-process -u superuser -p suser -a "Test" -e "Environment for Default Architecture" -f "delay1" -r "{Application Parameters/intp,7,QA_LAB3/Default Component/param,Hello second param}"
If you provide part of the values for a process with multiple user-input parameters, the process automatically pauses to wait for the omitted parameters. Resume the process by providing the remaining parameters in the UI.
Set a Virtual Name for a Process
When running CLI executions, the triggered process is listed as “Remote Execution": <PROCESSNAME> (<DATE>).
To provide a virtual name for an execution for easier tracking in the UI, use the -j command, as in the following example:
>nolio.cmd run-process -u superuser -p suser -e defaultenv –f p2 -a "test" -j myname
In the UI Administration tab, the Online Audit Report displays the virtual process name in the Run column:
Run a Process with Suspend on Failure Option
All submitted processes proceed to one of the following stages during execution:
  • RUNNING/FINISHED
  • PRE_FAILED
  • FAILED_PAUSED
The few situations in which the process terminates are:
  • The process entered a PRE_FAILED state before the process was created.
  • The process entered a FAILED_PAUSED state while running.
  • The process was paused from the UI and the CLI still shows the state as RUNNING.
If a process was submitted using the '-x' command,
Release Automation (Nolio)
puts the process in a suspended state. You can then:
  • See the FAILED_PAUSE stage in the UI
  • Check the execution result string using the -g command in the CLI
Using the stage or result string information, you can fix the problem and continue the execution by selecting RESUME in the UI.
The following example uses the -x command:
>nolio.cmd run-process -u superuser -p suser -e defaultenv -f p2 -a test –x
Use a Configuration File with Automation Studio
You cannot modify parameters and server dependencies for specific servers executing under multiple server types using the CLI. However, it is possible to do so by using an XML configuration file in the CLI.
The CLI syntax for Automation Studio is:
nolio.cmd run-process -u superuser -p suser -a applicationName -e environmentName -f processName -c cli-file-path
You can place all CLI commands in a configuration file, however, any command set in a configuration file gets overridden by the same command that is also set in the CLI.
Scope of Configuration File Definitions
Parameter and dependency definitions in a configuration file have different effects on subsequent runs:
  • Parameters that are defined in the configuration file are only active for the current CLI execution.
  • Dependencies that are defined in the configuration file are active for the current and future executions, because the
    Release Automation (Nolio)
    database definition is updated with the configuration file value.
  • When the dependencies are defined in the configuration file, the definitions override the database environment values and are active beyond the CLI execution.
  • When the dependencies are not defined in the configuration file, environment values are used.
Configuration File Examples
The following is an example configuration file for Automation Studio:
<nolio> <application name="MyApplication" /> <env name="MyEnvironment" /> <process name="MyProcess" /> <user name="superuser" /> <server-types> <server-type name="Server Type 1"> <server name="127.0.0.1" /> <server name="iceman2" /> </server-type> <server-type name="Server Type 2"> <server name="MyServer"> <dependencies> <dependency server-type="Server Type 1" server="127.0.0.1" /> </dependencies> </server> </server-type> <server-type name="e"> <server name="MyServer"> <dependencies> <dependency server-type="Server Type 2" server="127.0.0.1" /> </dependencies> </server> </server-type> </server-types> <parameters> <app-param> <param name="Application Parameters/a" value="global parameter value"/> </app-param> <server-type name="Server Type 1"> <server name="127.0.0.1"> <param name="f/ui" value="value on ST1" /> </server> </server-type> <server-type name="Server Type 2"> <server name="127.0.0.1"> <param name="f/ui" value="value on ST2" /> </server> </server-type> </parameters> </nolio>
Example of Array Value Syntax
The following is an example of the array value syntax:
<app-param>\ <!—regular parameter--> <param name="Folder_Name/Parameter_Name" value="Global_Parameter_Value" /> <!—array parameter--> <param name="Folder_Name/Array_Parameter_Name2"> <value>Global_Array_Parameter_Value_1</value> <value>Global_Array_Parameter_Value_2</value> <value>Global_Array_Parameter_Value_3</value> </param> </app-param>