App Connect includes a JSON parser that can be used to parse the output from an HTTP invoke action or some other application in a flow. If data is returned as a JSON string, the key/value pairs encoded within the string are not recognized as separate entities, so you must use the JSON parser to convert the string into a JSON object to make the data accessible for subsequent use. The following scenario provides an example of how this can be done.
You work for the Electoral Commission Office in the idyllic state of Utopia, a fictional country. In preparation for the upcoming elections, your department has provided a form on the Electoral Commission website, so residents can register to vote online. When each voter registers, you want to send them an email confirming receipt, together with details about their local candidates and a URL reference they can use to obtain up-to-date election information.
We’ll use App Connect to set up this flow, which includes the following prerequisites:
- An App Connect subscription (Free or Personal).
- Free or business accounts for Wufoo and Gmail.
- An online form that voters can use to provide their name and address details. Let’s assume this form is provided as an embedded Wufoo form within the Electoral Commission website.
- Access to a web API with a publicly exposed HTTP endpoint, which returns election data that is relevant to a voter’s postcode.
If not already connected, we’ll also need to connect App Connect to each app in the flow either from the Applications tab on the App Connect Catalog page, or when we add an application to the flow. For Wufoo, we’ll need the Wufoo API key and the subdomain for the Wufoo account (see How to use IBM App Connect with Wufoo for more details). For Gmail, we’ll need the email address and password for the Gmail account.
December 2019 Update: In the tutorial steps, the API key is included as a parameter in the URL that is constructed to call the API. The recommended method for enabling API key authentication is to now add details about the API key parameter, value, and location in the HTTP account connection fields. For more information, see the “What should I consider first?” section in the How to use IBM App Connect with HTTP topic.
Creating the flow:
Let’s create an event-driven flow (named
Send election data to registered voters) that uses Wufoo as the source application with a corresponding New form entry event. In our example, we’ve specified the form that voters will have to submit to trigger the flow. (For information about creating an event-driven flow, see Creating an event-driven flow.)
Now let’s add an HTTP target application that will use a GET method to look up election data on an HTTP endpoint, based on the postcode specified in the submitted form.
- As a prerequisite, we’ve already configured access to this endpoint (by enabling the API and generating an API key), so we’ll now just specify the URL, and append the API key, voter’s address, and election identifier as query parameters.
- We’ll also use the Request headers field to indicate that the content type of the response should be JSON. (After you add the HTTP node to the flow, to display the Request headers field click Edit mappings for the “Request headers” heading.)
Next, we’d like to add a Gmail action to the flow to send an email, which contains some data returned from the HTTP endpoint, to the voter who submitted the form. However, because the response is returned as a string of JSON text, we’ll need to first parse this string into a JSON object in order to be able to map the fields in the Gmail action. Let’s insert a JSON parser node at this point to help us do this. We’ll list the sequence of steps required for clarity:
- Click the (+) to add another application or node to the flow. Then from the Toolbox tab, click JSON parser.
- Click within the JSON Input field, and from the list of available inputs, expand HTTP/Invoke method and select Response body. (Here, we are indicating that we want to parse the response body that is returned by the previous HTTP GET action.)
We can now use the Output Schema fields to model the structure of the JSON schema. We’ll need some sample JSON though of the response, and can quickly obtain this data by calling the API from a browser address bar using a similar URL to the one specified in the HTTP invoke action. For example:
- Expand the Output Schema section and then copy and paste the sample response into the Example JSON field. (It’s worth noting that this field accepts a maximum of 16,000 characters, so the sample JSON obtained might need to be shortened before it’s pasted in. One way of doing this would be to add only one entry of an array/list.)
- Click Generate Schema to convert the sample JSON string into a JSON object. You can see the result in the JSON Schema field.
Finally, let’s add the Gmail action to complete the flow. We’ll use a Create message action and map the recipient’s email address to the one entered in the Wufoo form. We’ll also specify a subject for the email and construct the body of the email using a combination of text strings as well as parsed fields that were generated by the JSON parser.
Tip: For any of the fields in the Gmail action, you should be able to see the set of parsed JSON keys as fields that you can map to. For example:
Here’s an example of the completed Gmail fields:
To start the flow, we’ll open the options menu [⋮] in the banner and click Start flow, and finally click Dashboard to exit the flow. The Dashboard depicts the flow as Running, and listening for the event – a submitted form in Wufoo.
When someone registers to vote using the online form, they should receive a confirmation email with some voter information, as depicted in the following examples: