Integrating a REST Web Service That Returns JSON Data

Last Updated: 05/02/2018 Introduced in Version: 2.0

Overview

The Decisions portal can integrate with web services that return JSON formatted data.

The steps for retrieving and using the JSON data are as follows:

  1. Integrate the service within the Decisions portal
  2. Create a flow to make the service call and handle the results
  3. Generate a data type to deserialize the JSON data so it is usable and introduce that type into the flow

In this example, a web service that retrieves weather is integrated with the Decisions portal. An XML data type is generated against the web service’s return data structure, and a flow is created to make the service call and handle the results.

Integrating the Web Service

Log in to the portal (with an administrator account) and navigate to System > Designers > Integrations > External Services.

Click on Add REST Service Integration. In the Service Name field, enter the name of the web service , and in the Service URL field, paste in the URL. Most likely, the URL will contain variables to pass in; those will be moved to a new field after the following settings are established.

16

 

Change the Service Input Method field value to Post, since information will be passed in to the service. Upon selecting Post, the Service Content Type field appears; select Json from this list.

17

 

Next, populate the Data To Send field with the data to pass in. From the URL, cut the list of parameters, which starts after the question mark (?) in the URL. Paste that string into the Data to Send field and remove the question mark that starts the string. In this example, there are three values to pass in: the city, number of days (num_of_days), and the key.

WebService2

To make the values dynamic, it is necessary to remove the values and replace them with tokens representing the data, enclosed within this type of bracket: {}. In this example, the Data to send field parameters list should look like:

q={CityName}&format=json&num_of_days={NumberOfDays}&key={KeyValue}

WebService3

Now that the data to send is formatted, the last step is to put that string into the service URL. Type a “q” at the end of the string in the Service URL field. Copy the formatted string in the Data to Send field and paste it at the end of the string in the Service URL field:

JSONsettings2

 Click OK.

Using the Web Service Call in a Flow

Next, create a new flow that will make the call to the weather web service and ingest the return data. From the Designer Folder, click Create Flow. Name the new flow and click OK.

18

 

From the Flow Designer start-up window, expand the Integrations > All Integrations > Rest Service category, and select the Weather Service component. Click Add to add it to the workspace. 

 

19

Notice the three input fields; the values established here will populate the query string passed in to the service. For simplicity, hard-coded values will be used in this example (however, a more valid example is using a form to pass in values, giving a user the ability to provide input). The values are San Francisco, 5 (for number of days), and an authorization key given to the account used to run the service when we registered online to use the service.

The output of this web service call will be a string of serialized JSON data.

JSONReturnData

In order to use the data returned in a more meaningful way, it is necessary to create a data structure for the data.

Save and close the flow.

Create Data Structure From JSON

From the Designer Folder, click on Create Datatypes > Create Types from Json.

21

 

In this example, we have a file that contains the structure of the JSON data returned. It is also possible to simply paste in that structure when creating the data type. Enter a name for the service in the JSON Structure Name field, and either upload a file for the structure or paste in the data structure. In the list of recognized data types from the structure, select the desired types.

JSONDataStructure

Click OK. The data structure is generated for the JSON data, as well as components for deserializing and serializing that data. Next, is is necessary to introduce the Deserialization step into the flow to break down the JSON string into meaningful, usable data.

From the Designer Projects folder, open the flow that contains the weather service step.

Deserialize JSON Data

From the Toolbox, expand the Integrations > JSON Structures category. Notice the category for the structure just created; expand this category.

 

Drag and drop the Deserialize Weather component following the Weather Service 1 component. Connect the Done path of the Weather Service 1 component to the Deserialize Weather component. Connect the Done path out of the Deserialize Weather component to the End component, and do the same with the Error path.

Click on the Deserialize Weather component, and in the Properties panel, change the Input > String to Deserialize mapping type to Select Value. Click on the Path field browse button, and select the Done string and click OK. This is the output from the Weather Service 1 component.

Click on the End step. From its Actions menu, select View Step Data. Notice now that the deserialized output is available:

Additional Resources