The Now Platform® Washington DC release is live. Watch now!

Help
cancel
Showing results for 
Show  only  | Search instead for 
Did you mean: 
Patrick Beauche
ServiceNow Employee
ServiceNow Employee

ServiceNow continues to innovate when it comes to integrating with other tools from the ServiceNow platform.  This blog will focus in that ability to integrate with APIs using Flow Designer and IntegrationHub and explain a migration path for consuming those APIs using Workflow and Orchestration to Flow Designer and IntegrationHub.  This blog will focus on integrating with REST APIs but most of the following stands true for SOAP as well.  For those of you who are reading this and saying, “what the heck is an api?”  I would suggest watching this video by Glitch on YouTube, where the creator explains the power of APIs and how they connect the modern services we consume at home or work every day.  The best part Danielle Thé easily explains this technical topic with Legos, so now my Seven-year-old totally understands how APIs are utilized when he logs into Code.org with his google account.

You have been able to consume REST APIs inside of Workflow for many ServiceNow releases, it started with the ability to utilize a script activity to send outbound REST messages using JavaScript.  After this, workflow activities were created to utilize these REST messages to simplify this process and did not require the use of JavaScript code.  While this no code method of utilizing APIs in workflow was a vast improvement, it had one major downfall, you needed to bounce between the Outbound REST Message table and the Workflow Activity Editor.

While this was is an extremely useable solution it does tend to be time consuming to create your REST message and functions in one tab and then have to go to another tab to utilize one inside a workflow activity.  One of the other downfalls was for accomplishing something that required multiple calls to the same API.  A common example of this would be you POST some authentication credentials and that API returns a token that can be used for the session to make subsequent calls.  This would be a several step process involving creating one activity to POST credentials and obtain a token, you would then need to parse this token from the response body and create a workflow scratchpad variable to store it.  You would then use that variable in the subsequent API call, these activities would have to be strung together within the workflow editor.  At this point writing JavaScript may have been a faster method.  

I recently stumbled upon a problem in my life that the ServiceNow Platform and its ability to integrate with external data sources and it ability to help users build low code / no code applications could help me solve.  I recently took up indoor cycling and am too cheap to purchase a Peloton Bike.  My DIY solution is: a good quality magnetic resistance spin bike, a Bluetooth cadence sensor, a Peloton Digital subscription and, to utilize my smartwatch as a heart rate monitor.  My goal is to integrate with the Various APIs that these devices and services have and to pull my data back into The Now Platform using Integration Hub, so I can store all my workout data in one place.

This first blog post will focus in integrating with the Peloton API.  We will need to connect to that API, retrieve a Key for our session and make a subsequent call to pull in the workout data.  For anyone interested I found this Postman collection and environment file on GitHub that was super helpful in getting started.

 

Step 1:

Create a new action and flow in Flow Designer

find_real_file.png

 

Step 2:

Modify the newly created action.  Create a new rest step and give it a useful name I will call it Auth Step.   This first rest step will allow us to connect to the API and retrieve an API Key and a UserID.  For the purposes of this example we will define the connection information inline.  We will also not use the mid server for this example as the Peloton API is accessible on the open internet.  Please note that if your endpoint is behind your corporate firewall you have the ability to utilize the Mid server.

find_real_file.png

 

Step 3:

Continue modifying the rest API action, we will now need to add the request content.  We will need a content type of text and the data that needs to be sent into the API.  We will parameterize this body content by creating two input variables one for user name and another for password.

find_real_file.png

 find_real_file.png

 

Step 4:

Return back to our Peloton Flow, we will now add our newly created Connect to Peloton and Get Data rest step in our flow.  We can now populate our newly created Inputs, for this example we will code them directly into the flow, but keep in mind you can use the get record action and use data elsewhere in the platform.  We are now ready to test our REST message.

find_real_file.png

Step 5:

We will click on the hyperlink created that will take us to the execution details of the flow.  If we expand the execution details for our REST message.  Look for the section that is called Step Output Data this is the response information from the API.  We will want to ensure that the status code is a 200 indicating success.  We will then open up the response body and copy this output.  Open up a editor that is capable of formatting JSON and paste the output.  There are JSON editors available on line such as http://json.parser.online.fr/ that can be very useful for this. 

find_real_file.png

 find_real_file.png

Step 6:

We will need to parse two important pieces of information out of this response body, the user_id and session_id.  We can now return back to our Connect to Peloton and Get data action and create a new step under the Auth Step.  Under the Utilities select script, lets call it Parse Auth Response.  Create a new input variable called ResponseBody.  Drag the Response Body from the Data Panel into the value column.  We know we need to parse user_id and session_id from the JSON response so let’s create two Output variables for those.  Output variables can be used in subsequent steps.

 find_real_file.png

Step 7:

We are now ready to use JavaScript to parse our response body and grab our user_id and session_id.  Let’s dissect the script below.  First you will notice that I am setting a variable called object and using method called JSON.parse on inputs.ResponceBody.  This is the input from above.  Next we are setting two more variables called outputs.user_id and outputs.session_id.  JSON.parse allows us to perfrom simple dot walking to the values in the JSON payload that we want to retrieve.  We can now save, return back to our Peloton Flow and test.  If our test executes successfully, we should see two Variables under the Step Output Data section under Step 2- Parse Auth Response.  One called session_id and one called user_id they should each contain a runtime value.

(function execute(inputs, outputs) {
var object = JSON.parse(inputs.ResponseBody); //calling JSON.parse on inputs.ResponseBody
outputs.user_id = object.user_id; //setting output.user_id and parsing user_id from JSON inputs.ResponseBody
outputs.session_id = object.session_id;  //setting output.session_id and parsing user_id from inputs.ResponseBody
})(inputs, outputs);

 

Step 8:

Now we are ready to use our User_ID and Session_ID to connect to the API and retrive data.  We will need one additional REST step to achieve this.  Let’s call it Retrieve Data.  We will utilize the same Base URL for the API, but a different resource path.  We will pass our UserID into the resource path utilizing the output variable user_id from the Parse Auth Response step in the Data Panel.  Since we are retrieving data we will use a GET Method.  We are now ready to test one last time.  We will now need to check for that 200 response code under Step 3 – Retrieve Data step, and validate we have data in the Response Body.

find_real_file.png

find_real_file.png

 

This is where this blog post will end, in the next post we will parse this response body and populate a custom table with the Peloton workout data all within Flow Designer and IntegrationHub.  This will be an interesting task as it appears that the Peloton API only returns 20 workouts at a time and uses pagination for subsequent workout information.  I hope you enjoyed reading this and found it informative, if you have any questions please do not hesitate to comment.

5 Comments