JSON Payload Mapping

This section describes the semantics when mapping JSON payloads. Mappings map segments of JSON data from a source document to a target document. In the context of workflow execution, there are two types of mappings:

  1. Input mappings map workflow instance payload to task payload.
  2. Output mappings map task payload back into workflow instance payload.

Semantics

Payload mapping follows these rules:

  • When no mapping is defined and source payload is available: Success. Source payload is used as target payload.
  • When no mapping is defined and no source payload is available: Success. Target payload remains unchanged.
  • When a mapping is defined and source payload is available: Success. Source payload is merged into target payload.
  • When a mapping is defined and no source payload is available: Failure. A task-related incident is raised.

Note that source payload is only unavailable when a task is completed without payload.

Patterns

Input Mappings

Description Workflow Instance Payload Input Mapping Task Payload
Copy entire payload
{
 "price": 342.99,
 "productId": 41234
}
    
Source: $
Target: $
    
{
 "price": 342.99,
 "productId": 41234
}
    
Move payload into new object
{
 "price": 342.99,
 "productId": 41234
}
    
Source: $
Target: $.orderedItem
    
{
  "orderedItem": {
    "price": 342.99,
    "productId": 41234
  }
}
    
Extract object
{
 "address": {
    "street": "Borrowway 1",
    "postcode": "SO40 9DA",
    "city": "Southampton",
    "country": "UK"
  },
 "name": "Hans Horn"
}
    
Source: $.address
Target: $
    
{
  "street": "Borrowway 1",
  "postcode": "SO40 9DA",
  "city": "Southampton",
  "country": "UK"
}
    
Extract and put into new object
{
 "address": {
    "street": "Borrowway 1",
    "postcode": "SO40 9DA",
    "city": "Southampton",
    "country": "UK"
  },
 "name": "Hans Horn"
}
    
Source: $.address
Target: $.newAddress
    
{
 "newAddress":{
  "street": "Borrowway",
  "postcode": "SO40 9DA",
  "city": "Southampton",
  "country": "UK"
 }
}
    
Extract and put into new objects
{
 "order":
 {
  "customer:{
   "name": "Hans Horst",
   "customerId": 231
  },
  "price": 34.99
 }
}
    
Source: $.order.customer
Target: $.new.details
    
{
 "new":{
   "details": {
     "name": "Hans Horst",
     "customerId": 231
  }
 }
}
    
Extract array and put into new array
{
 "name": "Hans Hols",
 "numbers": [
   "221-3231-31",
   "312-312313",
   "31-21313-1313"
  ],
  "age": 43
{
    
Source: $.numbers
Target: $.contactNrs
    
{
 "contactNrs": [
   "221-3231-31",
   "312-312313",
   "31-21313-1313"
  ]
}
    
Extract single array value and put into new array
{
 "name": "Hans Hols",
 "numbers": [
   "221-3231-31",
   "312-312313",
   "31-21313-1313"
  ],
  "age": 43
{
    
Source: $.numbers[1]
Target: $.contactNrs[0]
    
{
 "contactNrs": [
   "312-312313"
  ]
 }
}
    
Extract single array value and put into property
{
 "name": "Hans Hols",
 "numbers": [
   "221-3231-31",
   "312-312313",
   "31-21313-1313"
  ],
  "age": 43
{
    
Source: $.numbers[1]
Target: $.contactNr
    
{
 "contactNr": "312-312313"
 }
}
    

For more examples see the extract mapping tests.

Output Mapping

Description Task Payload Workflow Instance Payload Output Mapping Result
Replace with entire payload
{
 "sum": 234.97
}
  
{
 "prices": [
   199.99,
   29.99,
   4.99]
}
  
Source: $
Target: $
  
{
 "sum": 234.97
}
  
Merge payload and write into new object
{
 "sum": 234.97
}
  
{
 "prices": [
   199.99,
   29.99,
   4.99]
}
  
Source: $
Target: $.total
  
{
 "prices": [
   199.99,
   29.99,
   4.99],
 "total": {
  "sum": 234.97
 }
}
  
Replace payload with object value
{
 "order":{
  "id": 12,
  "sum": 21.23
 }
}
  
{
 "ordering": true
}
  
Source: $.order
Target: $
  
{
  "id": 12,
  "sum": 21.23
}
  
Merge payload and write into new property
{
 "sum": 234.97
}
  
{
 "prices": [
   199.99,
   29.99,
   4.99]
}
  
Source: $.sum
Target: $.total
  
{
 "prices": [
   199.99,
   29.99,
   4.99],
 "total": 234.97
}
  
Merge payload and write into array
{
 "prices": [
   199.99,
   29.99,
   4.99]
}
  
{
 "orderId": 12
}
  
Source: $.prices
Target: $.prices
  
{
 "orderId": 12,
 "prices": [
   199.99,
   29.99,
   4.99]
}
  
Merge and update array value
{
 "newPrices": [
   199.99,
   99.99,
   4.99]
}
  
{
 "prices": [
   199.99,
   29.99,
   4.99]
}
  
Source: $.newPrices[1]
Target: $.prices[0]
  
{
 "prices": [
   99.99,
   29.99,
   4.99]
}
  
Extract array value and write into payload
{
 "newPrices": [
   199.99,
   99.99,
   4.99]
}
  
{
 "orderId": 12
}
  
Source: $.newPrices[1]
Target: $.price
  
{
 "orderId": 12,
 "price": 99.99
}
  

For more examples see the merge mapping tests.