IMIconnect Developer Hub

Welcome to the IMIconnect developer hub. You'll find all the resources to help you get started with IMIconnect quickly. We are here to support you if you get stuck. Let's jump right in!

Get Started

Flow: DataParser

The DataParser node is used to extract and load required key values into session data variables or translate data into a custom message with multiple replacement parameters from a large data set. The data is imported during flow execution, hence the actual data supplied can be dynamic. Data parser can be configured to perform basic data checks such as data type and if all the mandatory fields are present.

PROPERTIES


The node specific configuration is accessed by double-clicking on the node. The key values to be extracted / translated from the input data set and the corresponding output is configured using these settings.

Configuration Settings

Field
Description

Load data from

The session variable from which the input data is to be fetched.

Input data format

Specifies the input data format. The following formats are supported:

  • XML
  • JSON

Parser type

Extract - Extracts the configured keys, referenced by their key paths from the input data. Multiple key-values can be extracted and stored in user configured session variables set as output variable.
Translate - Transforms data into structured constructs / templates with multiple replacement parameters extract from the input data.

Name

The name of the node is represented as a string. Enter a new name for the node or continue with the default name.

Extract Settings

Field
Description

Output variable

The session variable into which the value extracted from the data is to be stored.

Reference path

XPath / JSON path reference to the data key that is to be extracted. The reference can be to dot-notated child, a wild card or an array. More on the reference path below.

Validations

Allows specifying if the key referenced in the path is

'Mandatory' for data extraction. Even if a single key among a set of mandatory paths cannot be found in the input data, the parser exits on oninvaliddata edge.

Set default value if the key value is considered optional. In case the path cannot be found or if the key value is null, then the default value is loaded into the output variable and the parser exits on oncomplete edge.

Reference paths:

Data Parser supports following specifications for referencing key-values in the supplied data:

  • Xpath (1.0) - Follows the W3C spec for referencing a key-value in a XML document.
  • JSONPath expressions refer to a JSON structure in the same way as XPath expression. Because JSON structure is usually anonymous and does not necessarily have a root member object, JSONPath assumes the abstract name $ is assigned to the outer level object.

By default the dot-notation is followed, however the bracket-notation is also supported for JSONPath expressions.

Overview of the JSONPath syntax elements along with its XPath counterparts.

XPath
JSONPath
Description

/

$

The root object/element

.

@

The current object/element

/

. or []

Child operator

..

n/a

Parent operator

//

..

Recursive descent. JSONPath borrows this syntax from E4X.

*

*

Wildcard. All objects/elements regardless their names.

@

n/a

Attribute access. JSON structures don't have attributes.

[]

[]

Subscript operator. XPath uses it to iterate over element collections and for predicates. In Javascript and JSON it is the native array operator.

|

[,]

Union operator in XPath results in a combination of node sets. JSONPath allows alternate names or array indices as a set.

n/a

[start:end :step]

Array slice operator borrowed from ES4.

[]

?()

Applies a filter (script) expression.

n/a

()

Script expression, using the underlying script engine.

()

n/a

Grouping in Xpath

XPath and JSONPath examples

Consider the following JSON structure and its equivalent XML document:

<store>
    <book>
        <category>reference</category>
        <author>Nigel Rees</author>
        <title>Sayings of the Century</title>
        <price>8.95</price>
    </book>
    <book>
        <category>fiction</category>
        <author>Evelyn Waugh</author>
        <title>Sword of Honour</title>
        <price>12.99</price>
    </book>
    <book>
        <category>fiction</category>
        <author>Herman Melville</author>
        <title>Moby Dick</title>
        <isbn>0-553-21311-3</isbn>
        <price>8.99</price>
    </book>
    <book>
        <category>fiction</category>
        <author>J. R. R. Tolkien</author>
        <title>The Lord of the Rings</title>
        <isbn>0-395-19395-8</isbn>
        <price>22.99</price>
    </book>
    <bicycle>
        <color>red</color>
        <price>19.95</price>
    </bicycle>
</store>
{
    "store": {
        "book": [{
            "category": "reference",
            "author": "Nigel Rees",
            "title": "Sayings of the Century",
            "price": 8.95
        }, {
            "category": "fiction",
            "author": "Evelyn Waugh",
            "title": "Sword of Honour",
            "price": 12.99
        }, {
            "category": "fiction",
            "author": "Herman Melville",
            "title": "Moby Dick",
            "isbn": "0-553-21311-3",
            "price": 8.99
        }, {
            "category": "fiction",
            "author": "J. R. R. Tolkien",
            "title": "The Lord of the Rings",
            "isbn": "0-395-19395-8",
            "price": 22.99
        }],
        "bicycle": {
            "color": "red",
            "price": 19.95
        }
    }
}

The corresponding reference path syntax for the above:

XPath
JSONPath
Result

/store/book/author

$.store.book[*].author

The authors of all books in the store.

//author

$..author

All authors.

/store/*

$.store.*

All things in the store, which are some books and a red bicycle.

/store//price

$.store..price

The price of everything in the store.

//book[3]

$..book[2]

The third book.

//book[last()]

$..book[-1:]

The last book in order.

//book[position()<3]

$..book[0,1]
$..book[:2]

The first two books.

//book[isbn]

$..book[?(@.isbn)]

Filter all books with isbn number.

//book[price<10]

$..book[?(@.price<10)]

Filter all books cheaper than 10.

//*

$..*

All Elements in XML document. All members of JSON structure.

Translate settings

Field
Description

Output variable

The session variable into which the transformed data is to be stored.

Data translation template

The data parser Apache Velocity Template Language (VTL) to construct data transformation templates by referencing objects.
Refer VTL reference guide for a complete guide on VTL References and directives.
This has been extended to support XML documents.

VTL reference example

Consider the following XML input and the output in different scenarios constructed using VTL:

//JSON input 
{
    "creditCardTx": [{
        "name": "Mark",
        "cardType": "master",
        "amount": "INR 3500.00",
        "merchant": "Nike",
        "date": "29-Feb-2016",
        "time": "04:25:33 PM"
    }, {
        "name": "Sada",
        "cardType": "visa",
        "amount": "INR 5500.00",
        "merchant": "Apple Inc",
        "date": "29-Feb-2016",
        "time": "03:59:23 PM"
    }]
}
//VTL template for converting above JSON into XML

#foreach($user in $creditCardTx)
<creditCardTx>
  <name>$user.name</name>
  <cardType>$user.cardType</cardType>
  <amount>$user.amount</amount>
  <merchant>$user.merchant</merchant>
  <date>$user.date</date>
  <time>$user.time</time>
</creditCardTx>
#end

//Output 
<creditCardTx>
     <name>Mark</name>
     <cardType>master</cardType>
     <amount>INR 3500.00</amount>
     <merchant>Nike</merchant>
     <date>29-Feb-2016</date>
     <time>04:25:33 PM</time>
</creditCardTx>
<creditCardTx>
     <name>Sada</name>
    <cardType>visa</cardType>
    <amount>INR 5500.00</amount>
    <merchant>Apple Inc</merchant>
    <date>29-Feb-2016</date>
    <time>03:59:23 PM</time>
</creditCardTx>
//VTL template for consturcting a mail-merged message  

#foreach($user in $creditCardTx)
   SMS $foreach.count: 
   Hi $user.name,
   $user.amount was spent on your $user.cardType Card on $user.date $user.time at $user.merchant .
#end

//Output
SMS 1: Hi Mark, INR 3500.00 was spent on your master Card on 29-Feb-2016 04:25:33 PM at Nike.
SMS 2: Hi Sada, INR 5500.00 was spent on your visa Card on 29-Feb-2016 03:59:23 PM at Apple Inc.

SESSION DATA


For information on session data, click here .

CUSTOM LOGS


For information on custom logs, click here.

NODE EVENTS


Exit event
Description

oncomplete

Input data is successfully parsed and all the mandatory key paths specified were resolved based, data parser exits on this edge with error code as null.

oninvaliddata

Whenever a key-value marked as mandatory is not found in the input data being parsed, data parser exits on this edge with error code 3003 and description MANDATORY_PARAM_NOT_FOUND.

onerror

Following status codes and descriptions you may encounter using the data parser node:
3001 | VALIDATION_FAIL - Encountered when the parameters are empty
3002 | INVALID_DATA_TYPE - Encountered when an unknown data format is found in the input
3004 | EXCEPTION - Any other exception encountered during run time.

On exit, the error status (if encountered) for a node is available in the session data variable _wferrorstatus and the error description in _wferrordesc.

Flow: DataParser


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.