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 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, for this activity.
• Determine the Create a REST message to use for the activity. Use this value to override the endpoint configured in the REST message.
• Optionally, create basic authentication credentials. Use this value to override the credentials configured in the SOAP message.

Procedure

1. Create a custom activity.

   This action creates a custom activity using a template.

2. After setting up general properties and creating input variables, configure the REST web service Execution Command.

**Note:** You can map parameter values in a test payload to variables in the **Outputs** tab automatically. See [automap output variables](automap-output-variable-inputs.md).

What to do next

Finish creating your Rest web service activity by creating output variables, creating a parsing rule, or Conditions. Refer to the create custom activities topic to know your template options.

Parent Topic:Orchestration custom activity templates

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.

1. 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.

Note: You must use the executionParam. prefix with all variables in this table.

var valueCapability = {'NEW_MID_CAPABIILTY':'NEW_MID_CAPABILITY_VALUE'}; executionParam.valueCapabilities.push(valueCapability);

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.

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.

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.

1. Complete the fields shown in the table.

1. Click Save.

2. Click Continue to advance to the Outputs stage.