--- title: Create a REST web service activity description: Use this procedure to create a custom REST web service Orchestration activity.The ServiceNow activity designer allows you to map parameter values in a REST test payload to variables in the Outputs stage automatically.You use execution parameters to create the input process script in the Pre Processing form of the activity designer.These are instructions for creating JavaScript arrays using REST execution parameters.Use these parameters to create a post-processing script.Use the input variables you created to configure the command that Orchestration executes on the REST endpoint. locale: en-US canonical_url: https://www.servicenow.com/docs/r/australia/servicenow-platform/orchestration/t\_CreateARESTWebServiceActivity.html release: australia product: Orchestration classification: orchestration topic_type: task last_updated: "2026-03-12" reading_time_minutes: 13 breadcrumb: [Orchestration custom activity templates, Orchestration activity designer, Classic Orchestration, ServiceNow AI Platform Additional Capabilities, Extend ServiceNow AI Platform capabilities] --- # Create a REST web service activity Use this procedure to create a custom REST web service Orchestration activity. ## Before you begin Role required: web\_service\_admin, activity\_admin, activity\_creator ## About this task To create and use a REST web service workflow activity: - Create a [Create a REST message](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/api-reference/web-services/t_ConfiguringARESTMessage.md) if an appropriate one is not already configured. - Assign the web\_service\_admin role to any user who must create or edit a custom REST activity. - Determine an application, or [Application scope](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/application-development/c_ApplicationScope.md), for this activity. - Determine the [Create a REST message](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/api-reference/web-services/t_ConfiguringARESTMessage.md) to use for the activity. Use this value to override the endpoint configured in the REST message. - Optionally, create [basic authentication credentials](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/platform-security/r_BasicAuthCredentialsForm.md). Use this value to override the credentials configured in the SOAP message. ## Procedure 1. Create a [custom activity](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/integrate-applications/create-custom-activities.md). This action creates a custom activity using a template. 2. After setting up [general properties](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/servicenow-platform/orchestration/General-Flds-Templates.md) and [creating input variables](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/servicenow-platform/orchestration/CreateInputVariables.md), configure the REST web service Execution Command.
**[Map the input variables](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/servicenow-platform/orchestration/CreateInputVariables.md)** Use the variables you created to configure the command that Orchestration executes.
**REST message** Name of an existing REST message to use in this activity.
**REST message function** REST message function to use for this activity.
**Endpoint** Endpoint URL for the REST web service this activity uses. Enter an endpoint in this field to override the endpoint configured in the REST message. Click the lock to open the input field.
**Variable substitutions** Name-value pairs to pass to the REST endpoint. You can create these parameters manually, or drag input variables into the parameter fields, and then assign a value. Parameters defined in the REST message that use **$\{\}** can be assigned data from this activity template. Use the **Additional attribute** column to configure the system to not escape the text. By default the text sent to the REST message is escaped. If the users have provided variables using [Variable substitution in outbound REST messages](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/api-reference/web-services/c_VariableSubstitutionREST.md) in the REST message, then the **Name** column is automatically populated.
**Additional Headers** Additional HTTP header parameters for the REST message selected. You can also use these values to override parameters inherited from the REST message.
**Additional Query Parameters** Additional query parameters for the REST message selected. You can also use these values to override parameters inherited from the REST message.
**Use MID Server** Check box that determines if a MID Server should be used to invoke the REST web service.**Note:** If the REST web service message function defines a MID Server, that MID Server is used instead of the one selected here.
**Required MID Server capabilities** MID Server with the appropriate [MID Server capabilities](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown) for connecting to the REST endpoint. By default, the system selects a MID Server with REST capabilities. This field is available when the **Use MID Server** check box is selected.
**Timeout** Allowed duration of the REST web service request before it times out, in seconds. The default is **10**.
**Authentication** Determines what type of authentication is required for the endpoint. The options are:- **Use existing credentials in REST message**: Uses credential definitions from the REST message definition. - **Override with Basic Authentication credentials**: Uses [Enable basic authentication for outbound SOAP](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/api-reference/web-services/t_BasicAuthentication.md) credentials to override the credentials in the REST message definition. Basic authentication credentials must be provisioned before they are available for selection. - **Override with Certificate Authentication credentials**: Uses a certificate, such as a private key, to override the credentials in the REST message definition. - **Override with Both Basic and Certificate Authentication credentials**: Uses both basic authentication and certificate authentication to override the credentials in the REST message definition. - **Override with OAuth Authentication credentials**: Uses [OAuth 2.0](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/platform-security/c_OAuthApplications.md) credentials to override the credentials in the REST message definition. The REST message selected for this activity must have its [OAuth 2.0 tutorial - create a REST message](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/api-reference/web-services/t_OAuthDemoCreateRESTMessage.md) set to **OAuth 2.0** and its [OAuth profiles and scopes](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/api-reference/web-services/c_OAuthProviderAndScope.md) configured appropriately.
**Credentials** Required REST endpoint basic authentication credentials. This field is available when **Override with Basic Authentication credentials** is selected in the **Authentication** field. Only basic authentication credentials appear in the selection list, which includes credentials stored on the instance and credential IDs from an external storage system. If you are using credentials stored in a CyberArk safe, you can override the default safe defined in the MID Server configuration file. See [Configure the MID Server for CyberArk](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/platform-security/c_CyberArkIntegrationConfiguration.md) for details. Add the name of a different safe as a prefix to the credential ID, separated by a colon. For example, **newsafe:orch-test-f5**.
**Protocol Profile** Certificate authentication to use. This field is available when the selections in the **Authentication** are either **Override with Certificate Authentication credentials** or **Override with Both Basic and Certificate Authentication credentials**.
**OAuth profile** Profile for the OAuth provider for this REST message. See [Specify an OAuth profile](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/api-reference/web-services/t_SpecifyAnOAuthProfile.md) for more information.
**Note:** You can map parameter values in a test payload to variables in the **Outputs** tab automatically. See [automap output variables](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/servicenow-platform/orchestration/automap-output-variable-inputs.md). ## What to do next Finish creating your Rest web service activity by [creating output variables](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/servicenow-platform/orchestration/t_CreateAnOutputVariable.md), [creating a parsing rule](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/servicenow-platform/orchestration/t_CreateAParsingRule.md), or [Conditions](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/integrate-applications/conditions.md). Refer to the [create custom activities](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/servicenow-platform/orchestration/create-custom-activities.md) topic to know your template options. **Parent Topic:**[Orchestration custom activity templates](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/servicenow-platform/orchestration/c_ActivityDesignerComponents.md) ## Auto-map REST activity output variables The ServiceNow activity designer allows you to map parameter values in a REST test payload to variables in the **Outputs** stage automatically. ### Before you begin Role required: web\_service\_admin, activity\_admin, activity\_creator ### About this task **Note:** You can test input variables from any stage in the activity designer if you have provided enough information for Orchestration to contact the endpoint and return data. Typically, the **Execution Command** stage is the point at which your inputs are ready for testing. ### Procedure 1. In the activity designer, proceed to the **Execution Command** stage. 2. Define an appropriate MID Server, if requested. The test fails if the MID Server cannot be found or if it cannot connect to the target. 3. Click **Test Activity** to test the input parameters. If you added actual values for the parameters and fields, the system runs those values against the specified target and returns the resulting payload. If you mapped input variables to fields and parameters, the system displays a dialog box for assigning test values to those variables. 4. Provide test values, if requested, and click **OK** to display the payload. The entire payload appears in the **Raw Output** tab of the Response form. \[Omitted image "AutoMappingButtons.png"\] Alt text: Auto-mapping controls 5. Select one of these auto-mapping options. - **Auto-Map to Local**: Directly maps values to a local variable for use within the activity. - **Auto-Map to Output**: Directly maps values to the output variable to pass to other activities in the workflow. Auto-mapping to an output variable creates an array of objects, each of which contains the column names from the query result. ## REST template execution parameters You use execution parameters to create the input process script in the **Pre Processing** form of the activity designer. For descriptions of the REST web service command fields, see [Configure the REST execution command](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/servicenow-platform/orchestration/t_CreateARESTWebServiceActivity.md). **Note:** You must use the `executionParam.` prefix with all variables in this table.
Name Variable Type Usage
Web service message web\_service\_message Reference The sys\_id of the corresponding web service message.
Web service message function web\_service\_message\_function Reference The sys\_id of the REST message function.
Web service endpoint web\_service\_endpoint String URL of the REST endpoint.
Parameters parameters Array of JavaScript objects Array of JavaScript objects, expressed with the `executionParam.` prefix. For instructions on creating arrays using this parameter see [Create a JavaScript array in a REST template](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/servicenow-platform/orchestration/t_CreateARESTWebServiceActivity.md).
Use mid server use\_mid\_server Boolean Selects whether or not to use the MID Server. A value of **true** uses the MID Server, and a value of **false** does not use the MID Server.
MidCapabilities midCapabilities String \(comma separated\) List of references to required MID Server capabilities.
Time out time-out String Allowable time out duration, expressed in seconds.
ValueCapabilities valueCapabilities Array of hashmap Capability values used to select the MID Server. For more information, see [MID Server capabilities](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown). Use this example to customize the MID Server selection if there are additional capabilities that are assigned by value:``` var valueCapability = {'NEW_MID_CAPABIILTY':'NEW_MID_CAPABILITY_VALUE'}; executionParam.valueCapabilities.push(valueCapability); ```
Auth Type auth-type Boolean Type of credentials to use. The choices are:- basic\_auth\_pick\_credentials - use\_existing\_credentials
Credentials credentials Reference Contains the credentials to use for this REST message when the **auth\_type** selected is **basic\_auth\_pick\_credentials**.
## Create a JavaScript array in a REST template These are instructions for creating JavaScript arrays using REST execution parameters. ### Before you begin Role required: web\_service\_admin, activity\_admin, activity\_creator ### About this task To add more name-value pairs to the parameter's array, append the values to the existing array. ### Procedure 1. Create a JavaScript object with the following syntax, and add it to the `executionParam.parameter` array: ``` var newParameter = {"name":"parameterName","value":"parameterValue","additional_attribute":"none"}; executionParam.parameters.push(newParameter); ``` By adding the new parameter JavaScript object to the array, you ensure that any elements already available in the array are not impacted. 2. Make sure to set the value in the **Additional attribute** column in the **REST message parameters** input field to **Do not escape text**. In this case, the system does not escape the value specified for the **value** attribute. An example of this is: ``` var newParameter = {"name":"parameterName","value":"parameterValue","additional_attribute":"do_not_escape_text"}; executionParam.parameters.push(newParameter); ``` **Note:** If the value for the **additional\_attribute** field is **None**, then the system escapes the value specified by the **value** attribute. In the first example, `parameterValue` is escaped. ## REST template post-processing parameters Use these parameters to create a post-processing script. |Name|Variable|Type|Usage| |----|--------|----|-----| |Status code|status\_code|Integer|Contains the status code returned from the REST web service.| |Header|header|Hashmap of JavaScript object|Hashmap of key value pairs associated with the header values passed into the web service. You can access each value with `executionResult.header[keyName]`.| |Body|body|String|Contains a string value representing the output from the REST message| |Error|error|String|Returns the error string from the REST web service, unless there are no errors, in which case it returns**null**.| ## Configure the REST execution command Use the input variables you created to configure the command that Orchestration executes on the REST endpoint. ### Before you begin Create the input variables you need in the **Inputs** form before you can advance to the **Execution Command** stage. Role required: web\_service\_admin, activity\_admin, activity\_creator **Note:** You can test the REST connection between the MID Server and the endpoint without having to run the acvitity in a workflow context. For details, see [test template outputs](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/servicenow-platform/orchestration/CreateInputVariables.md). ### Procedure 1. Drag variables from the list of inputs and drop them into command fields. The system formats the variable in the proper syntax for the command. \[Omitted image "RESTExecutionCommand.png"\] Alt text: REST execution command 2. Complete the fields shown in the table.
Field Description
Input Input variable builder. [Create input variables](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/servicenow-platform/orchestration/CreateInputVariables.md) to map to available fields.
REST message Name of an existing REST message to use in this activity. Users must have the web\_service\_admin role to configure this field.
REST message function REST message function to use for this activity. Users must have the web\_service\_admin role to configure this field.
Endpoint Endpoint URL for the REST web service this activity uses. Enter an endpoint in this field to override the endpoint configured in the REST message. Click the lock to open the input field.
Variable substitutions Name-value pairs to pass to the REST endpoint. You can create these parameters manually, or drag and drop input variables into the parameter fields, and then assign a value. Parameters defined in the REST message that use **$\{\}** can be assigned data from this activity template. Use the **Additional attribute** column to configure the system to not escape the text. By default the text sent to the REST message is escaped. The **Name** column is automatically populated if the users have provided variables using [Variable substitution in outbound REST messages](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/api-reference/web-services/c_VariableSubstitutionREST.md) in the REST message.
Additional Headers Additional HTTP header parameters for the REST message selected. You can also use these values to override parameters inherited from the REST message.
Additional Query Parameters Additional query parameters for the REST message selected. You can also use these values to override parameters inherited from the REST message.
Use MID Server Check box that determines if a MID Server should be used to invoke the REST web service.**Note:** If the REST web service message function defines a MID Server, that MID Server is used instead of the one selected here.
Required MID Server capabilities MID Server with the appropriate [MID Server capabilities](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown) for connecting to the REST endpoint. By default, the system selects a MID Server with REST capabilities. This field is available when the **Use MID Server** check box is selected.
Timeout Allowed duration of the REST web service request before it times out, in seconds. The default is **10**.
Authentication Determines what type of authentication is required for the endpoint. The options are:- **Use existing credentials in REST message**: Uses credential definitions from the REST message definition. - **Override with Basic Authentication credentials**: Uses [Enable basic authentication for outbound SOAP](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/api-reference/web-services/t_BasicAuthentication.md) credentials to override the credentials in the REST message definition. Basic authentication credentials must be provisioned before they are available for selection. - **Override with Certificate Authentication credentials**: Uses a certificate, such as a private key, to override the credentials in the REST message definition. - **Override with Both Basic and Certificate Authentication credentials**: Uses both basic authentication and certificate authentication to override the credentials in the REST message definition. - **Override with OAuth Authentication credentials**: Uses [OAuth 2.0](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/platform-security/c_OAuthApplications.md) credentials to override the credentials in the REST message definition. The REST message selected for this activity must have its [OAuth 2.0 tutorial - create a REST message](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/api-reference/web-services/t_OAuthDemoCreateRESTMessage.md) set to **OAuth 2.0** and its [OAuth profiles and scopes](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/api-reference/web-services/c_OAuthProviderAndScope.md) configured appropriately.
Credentials Required REST endpoint basic authentication credentials. This field is available when **Override with Basic Authentication credentials** is selected in the **Authentication** field. Only basic authentication credentials appear in the selection list, which includes credentials stored on the instance and credential IDs from an external storage system. If you are using credentials stored in a CyberArk safe, you can override the [Configure the MID Server for CyberArk](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/platform-security/t_ConfigureTheMIDServerForCyberArk.md) defined in the MID Server configuration file by adding the name of a different safe as a prefix to the credential ID, separated by a colon. For example, **newsafe:orch-test-f5**.
Protocol Profile Certificate authentication to use. This field is available when the selections in the **Authentication** field is either **Override with Certificate Authentication credentials** or **Override with Both Basic and Certificate Authentication credentials**.
OAuth profile Profile for the OAuth provider for this REST message. See [Specify an OAuth profile](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/api-reference/web-services/t_SpecifyAnOAuthProfile.md) for more information.
3. Click **Save**. 4. Click **Continue** to advance to the **Outputs** stage.