Using the JSON parser to parse a JSON string into a JSON object

You can use the JSON parser to convert data from a string that is written in JSON format into a JSON object that represents the string. The JSON parser generates a schema, with keys that are included in the list of fields that are available for mapping into later nodes in the flow.

When you create event-driven or API flows in IBM® App Connect, you typically use the response or output from an event, action, or toolbox node as input in a subsequent action by mapping the fields. In certain cases where data is returned by using JavaScript Object Notation (JSON), the data is provided as a string written in JSON format. To map this data in a subsequent action, you must first use App Connect's built-in JSON parser to convert the data into a JSON object that represents the string.

The schema that the JSON parser generates is formatted as a standard set of comma-separated key and value pairs that are surrounded by curly braces {}. The keys are defined as strings, and their values can be one of the following valid JSON data types: string, number, object, array, Boolean, or null. When these keys are generated, tthey are included in the list of fields that are available for mapping when you click Insert a mapping Insert a mapping icon in a subsequent action.

Defining the data to be parsed and generating a valid JSON schema

You can use the JSON parser to parse JSON strings from various applications. However, a typical use case uses an HTTP invoke action to make a GET, POST, PUT, PATCH, DELETE, or HEAD request that returns a response from an HTTP endpoint.

The following example depicts an HTTP invoke action within a multi-node flow. Here, a GET call is being made to an HTTP Client Testing Service at http://httpbin.org.

Figure 1. Sample field entries for an HTTP invoke action
Sample field entries for an HTTP invoke action

To make the response headers and response body available for mapping in a subsequent action, you must insert a JSON parser node before you add the action. You can then use the node to define the data that you want to parse, and to generate valid JSON schema. You can insert and configure the node by following these steps:

  1. Click the (+), go to the Toolbox tab, and then click JSON parser.
    Figure 2. Selecting the JSON parser from the Toolbox tab
    Selecting the JSON parser from the Toolbox tab
  2. Use the JSON Input field to specify which data from the previous action or event must be parsed.
    JSON Input field
    You can complete the JSON Input field in the following ways.
    • You can map to fields that are shown in the list of available inputs by clicking Insert a mapping Insert a mapping icon.
      Figure 3. JSON Input entry that shows a mapped field
      JSON Input entry showing a mapped field
    • You can combine text with mapped fields.
      Figure 4. JSON Input entry that shows a combination of text and mapped fields
      JSON Input entry showing a combination of text and mapped fields
      Figure 5. JSON Input entry that shows another combination of text and mapped fields
      JSON Input entry showing another combination of text and mapped fields
    • When resolved, the entry in the JSON Input field must produce valid JSON. To prevent runtime errors, any mapped field that you include from a preceding event or action must have a value that transforms into valid input. Based on the data type of the mapped field, you might also need to enclose it in double quotation marks or curly braces {}.
      • If the Response body for a previous HTTP action was returned in JSON format as {"name":"Bob", "age":"99"}, a JSON Input entry of {"responseBody": Response body} resolves to the following valid JSON: {"responseBody": {"name":"Bob", "age":"99″}}
      • If the Response body for a previous HTTP action was returned in plain text as Blob, a JSON Input entry of {"responseBody": Response body} produces invalid JSON: {"responseBody": Blob}

        To make the JSON valid, the JSON Input entry must be specified as {"responseBody": "Response body"} – that is, Response body must be enclosed in double quotation marks. The JSON is considered valid even if no response was returned because the JSON Input entry resolves to {"responseBody": ""}.

      • If you leave the Request headers (JSON format) field for a previous HTTP action blank, a JSON Input entry of Request headers (JSON format) will resolve to an empty value.
      • If you leave the Request headers (JSON format) field for a previous HTTP action blank, a JSON Input entry of {"headers": Request headers (JSON format)} will produce invalid JSON: {"headers":}

        To make the JSON valid, the JSON Input entry must be specified as {"headers": {Request headers (JSON format)}} – that is, Request headers (JSON format) must be enclosed in curly braces.

  3. Expand the Output Schema section and use the Example JSON field to specify sample JSON that you expect to be returned (and which should be converted to a JSON object). The following example shows sample JSON from a GET call to the HTTP Client Testing Service mentioned earlier (http://httpbin.org/get).
    Figure 6. Example JSON field
    Example JSON field
    You can configure the Example JSON field in the following ways.
    • You can copy a sample response that is returned by a web server or API call, for example, and paste it into this field.
    • You can enter a JSON string directly into this field. For example {"name":"Bob","age":"99″}
    • The Example JSON field accepts a maximum of 16,000 characters. This facility is provided for smaller API responses only because schema generation can be resource intensive and result in performance issues. For larger responses, external tools are available that you can use for schema generation if needed. When the schema is generated, you can paste it directly into the JSON schema field (shown in the next step).
  4. To convert the "Example JSON" into a JSON object, click Generate schema. You can see the result in the JSON schema field.
    Figure 7. Flow with a JSON Parser node: generated JSON schema
    Flow with a JSON Parser node: generated JSON schema
    Tip: You can alternatively bypass the schema generation step and enter a valid schema directly into the JSON schema field.

When you add another target application and corresponding action to the flow, you can see the keys in the JSON schema as fields that you can map to.

Examples

Event-driven flow with a JSON Parser node

Create an event-driven flow that uses the JSON parser to convert the response from an HTTP call for subsequent use in a flow

Learn how to create an event-driven flow that parses the response from an HTTP endpoint so that some of the data can be inserted into an email to recipients. See Using the JSON parser to convert the response from an HTTP call for subsequent use in a flow.