×

IDMWORKS Blog

REST Calls from ServiceNow Workflow


servicenow-icon.png

Introduction

The following guide will walk you through all of the steps necessary to create a series of REST activities in a custom ServiceNow workflow. We’ll be using JSONPlaceholder as a REST API for the examples. This is a simple public JSON API that supports all of the various HTTP verbs and mocks the results.

One of the endpoints supplied by the REST API is for managing hypothetical blog posts. The general workflow we’ll be creating is this:

  1. Request a list of posts
    • Store the ID of the first post
  2. Request a single post matching the stored ID
    • Store the Title and Body of the resulting post
  3. Create a new post using the stored Title and Body
    • Store the ID of the created post
  4. Log the stored ID of the created post

Let’s get started.

Create a Workflow

  1. Login to your ServiceNow dashboard
  2. If necessary, click Toggle Navigator to display the Navigator pane
  3. In the Type filter text field type ‘workflow’
  4. Click Workflow Editor
  5. Click New
  6. Enter a Name
  7. For Table specify Global
  8. Click Submit

Add an Activity

  1. Expand the Utilities folder on the right-hand-side of the Workflow Editor
  2. Click and drag a REST Message activity to the design surface
  3. Name the activity Get Posts
  4. Click the Magnifying Glass  next to REST Message
    • Since we do not have a predefined REST Message we’ll need to create one
  5. Click the New button in the REST Messages window
  6. Name the REST Message Placeholder Posts
  7. For the REST endpoint specify http://jsonplaceholder.typicode.com/posts
  8. Under REST Message Headers add a single row with a Name of content-type and a Value of application/json
  9. Click Submit
    • This will create the new REST Message and assign it to the Activity
  10. Click the Magnifying Glass  next to REST Message Function
  11. Click get
    • Note that this function and others were created automatically by ServiceNow when we submitted our new REST Message definition – more on that under Exploring the REST Message
  12. Click Submit

You should now have a new REST Message Activity on the design surface titled Get Posts.

Define the Workflow

  1. Click the transition line (the arrow indicating workflow) where it connects to the End activity – a blue box should appear
  2. Drag the transition to connect to the Get Posts REST Message activity instead of the End activity
  3. Click the yellow Success box and drag a new transition from the Get Posts REST Message to the End activity
  4. Repeat step #3 for the yellow box next to Failure

Verify the Workflow

  1. Click the green Play  button in the header of the workflow
  2. Click the Submit button on the Start Workflow window
    • The Workflow started window should indicate State: Finished and the blue line should trace through the Success path(s)
  3. Return to the ServiceNow dashboard in a separate browser window or tab (this should still be open from the first section)
  4. Under the Workflow section in the Navigator pane, click History
    • You should see new entries for your workflow – sort by the Ended column if necessary
  5. Click the name of your workflow under the Context column
  6. Click the Workflow Log tab to view a detailed log of the workflow
  7. Click the Show Workflow link to view the workflow as executed
    • You can hover over each activity to view details
  8. Click the Show Timeline link to view a timeline for the workflow
    • Note that this view is especially useful as you can double-click activities to verify each JSON response
  9. Finally return to the Workflow Editor

Exploring the REST Message

When creating the Get Posts activity we had to define a REST Message that represents the various actions we want to accomplish with our endpoint. Note that this REST Message is now re-usable on other ServiceNow workflows.

Let’s explore the details of the REST Message (a separate concept / object from the REST Message activity) that we created above.

  1. Double-click the Get Posts activity
  2. Click the Info Icon  to the right of the Magnifying Glass  next to REST Message

A New REST Message window will be displayed with the details of the REST Message.

A REST Message defined within ServiceNow has three primary components:

  1. An endpoint URL
  2. A set of headers
  3. A set of functions

The set of functions correspond to the various HTTP verbs, e.g. DELETE, GET, POST, and PUT. Note that creating a new REST Message automatically created four of these functions for us.

These REST Message Functions are themselves complex objects and you can view their details – and test the REST endpoint – by clicking the Info Icon  next to the function name.

To illustrate, click the Info Icon  next to get. Then, under Related Links, click Test.

You should see a Response with 100 blog post entries:

Click the [X] button in the upper-right of the REST Message dialog to close the Window.

Advanced Workflow

Retrieve a Post by ID

The next thing we need to do to satisfy our workflow goals is capture the ID of the first blog post returned by our Get Posts activity.

To do this, double-click the Get Posts activity and specify the following Javascript code for the Sensor Script:

This code uses the ServiceNow JSONParser object to parse the JSON response. We then store the value using the Workflow Scratchpad feature.

Click the Update button.

Now we can use the workingpostid variable elsewhere in our workflow.

Let’s continue with our activities.

  1. Add a new REST Message activity
  2. Name it Get Post
  3. Click the Magnifying Glass  next to REST Message and select Placeholder Posts
  4. Click the Magnifying Glass  next to REST Message Function and select get
  5. Override the endpoint for the REST Message by specifying the following value: http://jsonplaceholder.typicode.com/posts/${workflow.scratchpad.workingpostid}
    • This will allow us to specify a specific blog post ID to retrieve using the ID we stored on the scratchpad using Variable Substitution
  6. Click the Submit button
  7. Repeat the steps found in Define the Workflow so that the success transition lines flow from Begin to Get Posts to Get Post and finally to End
  8. Repeat the steps found in Verify the Workflow to verify that the expanded workflow is functional
    • Specifically, using the View Timeline feature and double-clicking the Get Post activity should show that only a single post was returned

Create a New Post

In order to satisfy our next workflow requirement we must capture the Title and Body of the blog post retrieved in the previous section.

To do this, double-click the Get Post activity and specify the following Javascript code for the Sensor Script:

Note that this code has a couple of extra lines to escape the newline characters found in the blog post Body. Otherwise the following POST operation would result in an HTTP 400 error.

Click the Update button.

Now we can use these scratchpad variables to create the new blog post.

  1. Add a new REST Message activity
  2. Name it Create Post
  3. Click the Magnifying Glass  next to REST Message and select Placeholder Posts
  4. Click the Magnifying Glass  next to REST Message Function and select post

At this point we are very close to achieving our requirements but we have no way to pass our scratchpad variables on to the post function of our Placeholder Posts REST Message. Let’s take care of that.

  1. Click the Info Icon  next to the Magnifying Glass  by the REST Message Function field
  2. On the REST Message Function Parameters tab click the New button
  3. Name the parameter title and click Submit
  4. Repeat the previous step to create body and userId parameters
  5. In the Content field enter the following JSON using Variable Substitution: { "title": "${title}", "body": "${body}", "userId": ${userId} }
  6. Finally, click the Update button in the upper-right of the REST Message Function window to save these new parameters

With these parameters defined we can now enter the following value for the Variables on our activity.

This will pass our two scratchpad variables as parameters to the post REST Message Function and the constant 123 as the userId parameter.

  1. Click the Update button to save changes to the new Create Post activity.
    • Note that if you do not see your new Create Post activity this is a bug in the Workflow Editor. Click the Open button and re-open your workflow to see the new activity.
  2. Repeat the steps found in Define the Workflow so that the success transition lines flow from Begin, to Get Posts, to Get Post, to Create Post, and finally to End
  3. Repeat the steps found in Verify the Workflowto verify that the expanded workflow is functional
    • Specifically, using the View Timeline feature and double-clicking the Create Post activity should show that the proper values were passed in and an ID of 101 was returned:

Log a Success Message

The final step of the workflow goals outlined in the introduction is to log the ID of the blog post we’ve created in the Create Post activity.

To do this, double-click the Create Post activity and specify the following Javascript code for the Sensor Script:

There is nothing new here – we are using the same techniques discussed in previous sections.

Click the Update button and continue to the final workflow activity.

  1. Add a Log Message activity from the Utilities folder to the workflow surface
  2. Specify Log Success for the name
  3. Specify the following for the Message field: CREATED: ${workflow.scratchpad.workingpostid}
  4. Click the Submit button
  5. Repeat the steps found in Define the Workflow so that the Log Success activity falls just before the End activity
  6. Repeat the steps found in Verify the Workflow to verify that the final workflow is functional
    • Specifically, viewing the Workflow Log tab on the History entry should show the following entry: CREATED: 101

Wrapping Up

Our custom workflow is done and satisfies all of the requirements outlined in the introduction. You can now use the workflow Gear menu  to Publish the workflow and schedule it from the ServiceNow dashboard.

For more information, see the following references:

 

Questions, comments or concerns? Feel free to reach out to us below, or email us at IDMWORKS to learn more about how you can protect your organization and customers.

 

Questions, comments or concerns? Feel free to reach out to us below, or email us at IDMWORKS to learn more about how you can protect your organization and customers.

Leave a Reply

Your email address will not be published. Required fields are marked *