Applying JSONata functions to transform your data

When you edit a target field in a flow, you can add a transformation function to customize the value of a source field that is to be passed to the target application.

How to use JSONata

IBM® App Connect provides JSONata functions that you can use to transform the data that you pass through your flow. The following points demonstrate how to use JSONata when you configure your flows.

The syntax of the functions is JSONata, a lightweight query and transformation language. For example, JSONata string functions are shown in the table JSONata string functions. Learn more about JSONata functions at http://jsonata.org.
You can insert functions into a target field by several techniques (after selecting the target field):
- Select a source field that you have already inserted into the target field, and then select Apply a function from the context menu; select a function from the list provided.
- Select the Insert function icon (fx), then select a function to insert into the target field, and then insert source fields into the function.
- Type the JSONata expression directly.
In the target field, a function is represented with curly brackets; for example:
Figure 1. Email mapping before applying a JSONata function
The previous example, after applying the substringBefore function, changes to become:
You can edit a JSONata expression to apply more complex functions, including the use of regular expressions; for example:
```
{{$substringBefore($substringAfter(name, "Name: "), ", Email:")}}
```
adds John Smith to the target field if the source field contains ... Name: John Smith, Email: ....

If a JSONata expression is not valid, an error message is displayed; for example:


JSONata expression: ?{{$uppercase(Department)}
       Use '}}' to end an expression

If you want to test out your JSONata expression before adding it in App Connect, you can use the JSONata Exerciser provided at http://jsonata.org.

If you want to fetch/retrieve/map the value of a specific property, you can use JSONata expressions. For example, see the following response for a Resolve resource URI operation:

{
    "response": [
      {
        "dcterms:identifier": "howFound.literal.l1",
        "prefixes": {
          "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
          "owl": "http://www.w3.org/2002/07/owl#",
          "dcterms": "http://purl.org/dc/terms/"
        },
        "dcterms:title": "Unknown",
        "owl:sameAs": {
          "rdf:resource": "http://jazz.net/ns/sse#HowFoundUnknown"
        },
        "rdf:type": [
          {
            "rdf:resource": "https://jazz.net/sandbox01-ccm/oslc/enumerations/_QnfWUHnuEeyeRfvzsMQn7Q/howFound"
          },
          {
            "rdf:resource": "http://jazz.net/xmlns/prod/jazz/rtc/cm/1.0/Literal"
          }
        ],
        "rdf:about": "https://jazz.net/sandbox01-ccm/oslc/enumerations/_QnfWUHnuEeyeRfvzsMQn7Q/howFound/howFound.literal.l1"
      }
    ]
  }

From this response, if you want to fetch, retrieve, or map the value of specific property in the next node, you can use these JSONata expressions:

If the key name is a normal key name (without namespace):

{{$IBMEngineeringWorkflowManagementGeturiresolver.response[0].prefixes.owl}}

If the key name is with a namespace (that is, namespace:propName) in its name (for example, dcterms:identifier):
```
{{$IBMEngineeringWorkflowManagementGeturiresolver.response[0]."dcterms:identifier"}}
```

JSONata string functions

The following table lists some of the available transform functions for string values, describes the purpose of each transform function, and gives an example.

Table 1. JSONata string functions
Function	Description
contains (field)	Returns `true` if `str` is matched by `pattern`, otherwise it returns `false`.	The `pattern` parameter can either be a string or a regular expression (regex). For example: `$contains("abracadabra", "bra") => true $contains("abracadabra", /a.a/) => true $contains("abracadabra", /ar.a/) => false`
length (field)	Returns the number of characters in the source field.	You can get the number of characters in a name. For example: `{{$length(Last Name)}}` adds `3` to the target field if the source field contains `Doe`.
lowercase (field)	Convert the source field to lower case.	You can convert a name to lower case. For example: `{{$lowercase(Last Name)}}` adds `doe` to the target field if the source field contains `Doe`.
replace (field, pattern, replacement [, limit])	Finds occurrences of `pattern` within the source field and replaces them with `replacement`. The `pattern` parameter can either be a string or a regular expression (regex). The `replacement` parameter can either be a string or a function. The optional limit parameter, is a number that specifies the maximum number of replacements to make before stopping. For more details and examples, see the JSONata documentation	For example: `{{$replace(Name, "Jane", "Ms")}}` adds `Ms Doe` to the target field if the source field, Name, contains `Jane Doe`. `{{$replace(Name, /(\w+)\s(\w+)/, "$2, $1")}}` adds `Doe, Jane` to the target field if the source field, Name, contains `Jane Doe`.
substring (field, start[, length])	Add the substring of a source field that starts at position start (zero-offset). If length is specified, then the substring will contain the maximum length characters. If start is negative then it indicates the number of characters from the end of the source field.	You can extract the first 3 characters of a name. For example: `{{$substring(Name, 0, 3)}}` adds `Jan` to the target field if the source field, Name, contains `Jane Doe`.
substringAfter (field, "`string`")	Add the part of a source field that occurs after a given string of characters.	You can extract the mail domain from an email address, by using '@' as the delimiting character. For example: `{{$substringAfter(Email, "@")}}` adds `email.com` to the target field if the source field, Email, contains `Jane Doe@email.com`.
substringBefore (field, "`string`")	Add the part of a source field that occurs before a given string of characters	You can extract the name from an email address, by using '@' as the delimiting character. For example: `{{$substringBefore(Email, "@")}}` adds `Jane Doe` to the target field if the source field, Email, contains `Jane Doe@email.com`.
trim (field)	Normalizes and trims all whitespace characters in the source field by applying the following steps: All tabs, carriage returns, and line feeds are replaced with spaces. Contiguous sequences of spaces are reduced to a single space. Trailing and leading spaces are removed.	You can trim a string field. For example: `{{$trim(Description)}}` adds `Hello World` to the target field if the source field, Description, contains `Hello \n World` .
uppercase (field)	Convert the source field to upper case.	You can convert a name to upper case. For example: `{{$uppercase(Last Name)}}` adds `DOE` to the target field if the source field, Last Name, contains `Doe`.