Create a custom command in ServiceNow CLI
Manage your custom application from the command line by creating custom commands in the ServiceNow CLI.
Before you begin
Role required: admin
About this task
A ServiceNow CLI command maps to a scripted REST endpoint in the End Point [sn_cli_metadata_end_point] table. You can define a scripted REST endpoint to perform a function in your custom application, or use any existing REST endpoint. Then map a CLI command to execute the REST call.
Procedure
Make a REST endpoint available to a ServiceNow CLI command.
Navigate to Command Line Interface (CLI) > End Points.
Select New and complete the form.
Field Description Resource Path Required. Path to the endpoint on the instance to map a command to. Can be the path to an inbound REST API, or a scripted REST API. For example, api/now/table/{table}/{sysid}. For more information, see Available REST APIs and Scripted REST APIs.HTTP Method Required. HTTP method to use when the user runs the associated command. Application Read-only application scope for the endpoint.
Create a command group.
Alternatively, you can add your new command to an existing command group.
Navigate to Command Line Interface (CLI) > Command Groups.
Select New and complete the form.
Field Description Name Required. Name of the command group. Parent Group Parent command group. Reference Group Command group to reference. For example, you can create a new command group as an alias for an existing command group. When the user calls a referenced command using the new command group, the original command executes. This enables you to create a command group specific to your custom application that includes both new and existing commands. Short Description Required. Short description for the command group. Description Description of the command group used as help text when the user runs the --helpcommand on the command group.Application Read-only application scope for the command group. Active When selected, the command group is active.
Create a command.
Navigate to Command Line Interface (CLI) > Commands.
Select New and complete the form.
| Field | Description |
|---|---|
| Name | Required. Name of the command. |
| Command Group | Required. Command group that the command is a part of. |
| Reference Command | Command to reference. For example, you can create a new command as an alias for an existing command. When the user calls the new command, the original command executes. This enables you to create a command specific to your custom application that executes existing functionality.Note: A command cannot reference a command that references another command, or reference a descendant command, an ancestor command, or a callback command. |
| API Endpoint | Required. API call to execute when the user runs the command. |
| Short Description | Required. Short description of the command. |
| Application | Read-only application scope for the command. |
| Active | When selected, the command is active. |
| Is Callback Command | When true, designates the command as a callback command. Select this option to hide the command from the CLI client and prevent users from calling it from the command line. Use this field with the Callback section of a primary command. The callback command executes when the primary command is complete. |
| Help Text | |
| Description | Description of the command used as help text when the user runs the `--help` command. |
| Examples | Examples of the command used as help text when the user runs the `--help` command. |
| Expressions | |
| Success Expression | Expression used to evaluate the response from the server and determine if the command succeeded. For example, `result.code = 1`. |
| Failure Expression | Expression used to evaluate the response from the server and determine if the command failed. |
| Messages | |
| Success Message | Message displayed on the CLI client when the command is successful. |
| Progress Message | Message displayed on the CLI client when the command is in progress. |
| Failure Message | Message displayed on the CLI client when the command fails. |
| Callback | |
| Callback Expression | Expression used to determine whether to execute the callback command. For example, you can write an expression that checks on a long-running process. If the expression produces a certain result, the callback executes. |
| Callback Command | Command to execute when the Callback Expression is satisfied. Must be a command with the Is Callback Command field selected. |
| Callback Interval | The interval between callback command executions. Unit: Milliseconds Default: 1,000 |
| Max Retries | Maximum number of times the callback command executes. Default: 10 |
3. In the Command Arguments related lists, create any command arguments needed for the command.
Create a command argument to allow users to set options when running a command.
| Field | Description |
|---|---|
| Name | Required. Name of the command argument, for example `data`. |
| Short Name | Short dame of the command argument, for example `d`. |
| Data Type | Required. Type of data expected for the command argument. Options include:- String: Allows users to enter a string as input. - Integer: Allows users to enter a number as input. - Boolean: Allows users to enter true or false as input. - File Input: Allows users to upload a file as input. Map this argument to a Body Parameter Type in the API Endpoint Arguments related list in the next step. Users can pass plain text, YAML, JSON, or another file type accepted by the REST API. When the user submits a YAML file, the CLI client converts to file to JSON format by default. Use the Skip Pre-processing field to disable this behavior. - Password: Allows users to securely enter a password as input. Note: For File Input data types, the file size limit is 10 MB by default. However, you change this limit using the glide.rest.scripted.max_inbound_content_length_mb system property. |
| Skip Pre-processing | Set this flag to prevent the CLI client from converting YAML files into JSON format before sending them in the request. When Data Type is set to File Input and the user submits a YAML file, the CLI client converts the file to JSON before executing the command by default.Note: Only applies when Data Type is set to File Input. |
| Default Value | Default value to use when the user does not pass a value. |
| Short Description | Required. Short description of the command argument. Used as help text when the user runs the `--help` command. |
| Application | Read-only application scope for the argument. |
| Command | Required. Command that the argument applies to. |
| Mandatory | When selected, the user must provide a value for the argument when running the associated command. |
| Prompt | Prompt to request information from the user. The CLI prompts for information when the user does not include a required argument in a command. |
| Visibility Expression | Expression used to determine whether the CLI should prompt for the argument. Typically used to display an argument based on the value provided to a previous argument. |
| Order | Order in which to prompt for the argument. |
4. In the API Endpoint Arguments related lists, create any API endpoint arguments needed for the command.
Map command arguments from the Command Arguments related list to parameters in your REST endpoint.
| Field | Description |
|---|---|
| Name | Required. Name of the argument. |
| Value | Required. The value from the command that you want to pass to the REST endpoint. You can pass a static value, or an expression such as `{flags.table}`. Use the `flags` global variable to access the command arguments. |
| Parameter Type | Required. The type of parameter in the REST endpoint that you want to pass the Value to. For example, if you select Body, the CLI passes the value of the Value field to the REST endpoint body. Options include:- Body - Header - Path - Query |
| Application | Read-only application scope for the argument. |
| Command | Required. Command that the argument applies to. |
5. In the Return Values related lists, create any return values needed for the command.
Create return values to only return certain keys from the response.
|Field|Description|
|-----|-----------|
|Path Expression|Required. Expression representing the path to the key that you want to return.|
|Alias|Variable name to assign the return value to.|
|Application|Read-only application scope for the command.|
|Command|Required. Command that the return value applies to.|
Result
When the user runs the ServiceNow CLI command, the system executes the associated REST API call and returns the result to the ServiceNow CLI.
Parent Topic:ServiceNow CLI