{"type":"doc","content":[{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{"minLevel":{"value":"1"},"maxLevel":{"value":"2"},"outline":{"value":"false"},"type":{"value":"list"},"printable":{"value":"false"}},"macroMetadata":{"macroId":{"value":"d23a0e2e-2dfd-4d1f-8d77-e171d6a5abea"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}},"localId":"89b4e190-68c5-41ef-b14e-407bbb7357a4"}},{"type":"heading","attrs":{"level":1},"content":[{"text":"What is JSON Data Mapping?","type":"text"}]},{"type":"paragraph","content":[{"text":"Data Mapping","type":"text","marks":[{"type":"strong"}]},{"text":" in PIPEFORCE means you have two JSON documents: The ","type":"text"},{"text":"source","type":"text","marks":[{"type":"strong"}]},{"text":" and the ","type":"text"},{"text":"target","type":"text","marks":[{"type":"strong"}]},{"text":" and you would like to write ","type":"text"},{"text":"fields","type":"text","marks":[{"type":"strong"}]},{"text":" from the source JSON to the target JSON. This is called ","type":"text"},{"text":"mapping","type":"text","marks":[{"type":"strong"}]},{"text":" since you map from source fields to target fields. For each such field mapping you can define a rule which defines how to map and optionally contains additional instructions in order to prepare the to be mapped data before it gets written to its target location. For example validate it or convert the text to upper case.","type":"text"}]},{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"drawio","parameters":{"macroParams":{"mVer":{"value":"2"},"zoom":{"value":"1"},"simple":{"value":"0"},"inComment":{"value":"0"},"custContentId":{"value":"2547155132"},"pageId":{"value":"2548039682"},"lbox":{"value":"1"},"diagramDisplayName":{"value":"Unbenanntes Diagramm-1690539390278.drawio"},"contentVer":{"value":"5"},"revision":{"value":"5"},"baseUrl":{"value":"https://logabit.atlassian.net/wiki"},"diagramName":{"value":"Unbenanntes Diagramm-1690539390278.drawio"},"pCenter":{"value":"0"},"width":{"value":"800"},"links":{"value":""},"tbstyle":{"value":""},"height":{"value":"330"}},"macroMetadata":{"macroId":{"value":"3dc9dc3a-d0b6-4bde-bb7d-2b5970f99824"},"schemaVersion":{"value":"1"},"placeholder":[{"type":"image","data":{"url":"https://ac.draw.io/connectImage?mVer=2&zoom=1&simple=0&inComment=0&custContentId=2547155132&pageId=2548039682&lbox=1&diagramDisplayName=Unbenanntes+Diagramm-1690539390278.drawio&contentVer=5&revision=5&baseUrl=https%3A%2F%2Flogabit.atlassian.net%2Fwiki&diagramName=Unbenanntes+Diagramm-1690539390278.drawio&pCenter=0&width=800&links=&tbstyle=&height=330"}}],"title":"draw.io Diagram"}},"localId":"03216146-416e-40e4-95bd-555dd19b8bb7"}},{"type":"heading","attrs":{"level":1},"content":[{"text":"Mapping with command ","type":"text"},{"text":"data.mapping","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":"To simplify the mapping, the command ","type":"text"},{"text":"data.mapping","type":"text","marks":[{"type":"link","attrs":{"href":"https://pipeforce.github.io/docs/api/commands#datamapping-v1"}}]},{"text":" can be used.","type":"text"}]},{"type":"paragraph","content":[{"text":"It takes a list of mapping rules and applies them on the source JSON (= input) in order to write data to the target JSON (= output). Also additional expressions can be added to each rule. These expressions are ","type":"text"},{"text":"Pipeline Expressions","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/PA/pages/2543026496"}}]},{"text":" and ","type":"text"},{"text":"Pipeline Expression Utils","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/PA/pages/2542862877"}}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"Let's see an example first:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"yaml"},"content":[{"text":"body: {\n \"firstName\": \"Max \",\n \"lastName\": \"smith\",\n \"age\": 48,\n \"birthDate\": \"01/12/1977\",\n \"hobbies\": [\"hiking\", \"biking\"],\n \"type\": \"customer\"\n }\n\npipeline:\n - data.mapping:\n rules: |\n body.firstName -> person.firstName,\n body.lastName -> person.surname,\n body.age -> person.age,\n body.birthDate -> person.dateOfBirth,\n body.hobbies -> person.hobbies,\n body.type -> person.type","type":"text"}]},{"type":"paragraph","content":[{"text":"This example sets a JSON document in the initial body at the top. Note: This JSON can be loaded from any location instead. ","type":"text"}]},{"type":"paragraph","content":[{"text":"Then it applies the given mapping rules from left to right, and writes by default the result as a new JSON in the body (replacing the initial JSON).","type":"text"}]},{"type":"paragraph","content":[{"text":"As you can see, every mapping rule is placed in a separate line, each ending with a comma, except for the last one.","type":"text"}]},{"type":"paragraph","content":[{"text":"The left part of the mapping rule (left side of the arrow) is the input path (where to read the data from). The right part of the mapping rule (right side of the arrow) is the output path (where to write the data to):","type":"text"}]},{"type":"codeBlock","content":[{"text":"inputPath -> outputPath","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"All mapping rules in ","type":"text"},{"text":"inputPath","type":"text","marks":[{"type":"code"}]},{"text":" are relative to the ","type":"text"},{"text":"context","type":"text","marks":[{"type":"strong"}]},{"text":" given by ","type":"text"},{"text":"input","type":"text","marks":[{"type":"code"}]},{"text":" parameter. By default, this value is the current pipeline message which contains ","type":"text"},{"text":"vars","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"headers","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"body","type":"text","marks":[{"type":"code"}]},{"text":" as root items. So in your mapping, you can access all of them. For example to map from a pipeline variable, you could write a mapping rule like this:","type":"text"},{"type":"hardBreak"},{"text":"vars.myVariable -> target","type":"text","marks":[{"type":"code"}]}]}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"output","type":"text","marks":[{"type":"code"}]},{"text":" parameter points to the location, where the mapping results should be written to. This is by default the body of the pipeline.","type":"text"}]},{"type":"paragraph","content":[{"text":"The final mapping result in the body from the example above will look like this:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"json"},"content":[{"text":"{\n \"person\": {\n \"firstName\": \"Max \",\n \"surname\": \"smith\",\n \"age\": 48,\n \"dateOfBirth\": \"01/12/1977\",\n \"hobbies\": [\n \"hiking\",\n \"biking\"\n ],\n \"type\": \"customer\"\n }\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"As you can see, the applied mapping rules resulted in these changes:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The input field ","type":"text"},{"text":"firstName","type":"text","marks":[{"type":"code"}]},{"text":" was nested inside the new element ","type":"text"},{"text":"person","type":"text","marks":[{"type":"code"}]},{"text":". The field name ","type":"text"},{"text":"firstName","type":"text","marks":[{"type":"code"}]},{"text":" was not changed.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The input field ","type":"text"},{"text":"lastName","type":"text","marks":[{"type":"code"}]},{"text":" was also mapped to the nested element ","type":"text"},{"text":"person","type":"text","marks":[{"type":"code"}]},{"text":". Additionally it was renamed from ","type":"text"},{"text":"firstName","type":"text","marks":[{"type":"code"}]},{"text":" to ","type":"text"},{"text":"surname","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The field ","type":"text"},{"text":"age","type":"text","marks":[{"type":"code"}]},{"text":" was nested inside ","type":"text"},{"text":"person","type":"text","marks":[{"type":"code"}]},{"text":" without any change.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"And the input field ","type":"text"},{"text":"birthDate","type":"text","marks":[{"type":"code"}]},{"text":" was nested inside ","type":"text"},{"text":"person","type":"text","marks":[{"type":"code"}]},{"text":" and renamed to ","type":"text"},{"text":"dateOfBirth","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The field ","type":"text"},{"text":"type","type":"text","marks":[{"type":"code"}]},{"text":" was only nested inside ","type":"text"},{"text":"person","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Using advanced Pipeline Expression in mapping rules","type":"text"}]},{"type":"paragraph","content":[{"text":"Now lets assume we would like to add some functions to the values in parallel to the mapping. You can do so by applying ","type":"text"},{"text":"Pipeline Expressions","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/PA/pages/2543026496"}}]},{"text":" on the input path. For example:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"yaml"},"content":[{"text":"body: {\n \"firstName\": \"Max \",\n \"lastName\": \"smith\",\n \"age\": 48,\n \"birthDate\": \"01/12/1977\",\n \"hobbies\": [\"hiking\", \"biking\"],\n \"type\": \"customer\"\n }\n\npipeline:\n - data.mapping:\n rules: |\n @text.trim(body.firstName) -> person.firstName,\n @text.firstCharUpper(body.lastName) -> person.surname,\n body.age -> person.age,\n body.birthDate -> person.dateOfBirth,\n body.hobbies[0] -> person.primaryHobby,\n @text.upperCase(body.type) -> person.type,\n body.age > 18 -> person.adult,\n \"male\" -> person.gender,\n @data.emptyList() -> person.myList,\n @data.emptyObject() -> person.myObject","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"As you can see, there is no need to wrap each expression inside ","type":"text"},{"text":"${","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"}","type":"text","marks":[{"type":"code"}]},{"text":" since each rule part in the data mapping is automatically treated as a ","type":"text"},{"text":"PE","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/PA/pages/2543026496"}}]},{"text":". This makes it much easier to read the mapping rules.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"The result JSON of this pipeline after execution will look like this:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"json"},"content":[{"text":"{\n \"person\": {\n \"firstName\": \"Max\",\n \"surname\": \"Smith\",\n \"age\": 48,\n \"dateOfBirth\": \"01/12/1977\",\n \"primaryHobby\": \"hiking\",\n \"type\": \"CUSTOMER\",\n \"adult\": true,\n \"gender\": \"male\",\n \"myList\": [],\n \"myObject\": {}\n }\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"As you can see, the nested mapping below ","type":"text"},{"text":"person","type":"text","marks":[{"type":"code"}]},{"text":" was kept. Additionally:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"the field ","type":"text"},{"text":"firstName","type":"text","marks":[{"type":"code"}]},{"text":" was trimmed from whitespaces","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"the field ","type":"text"},{"text":"surname","type":"text","marks":[{"type":"code"}]},{"text":" contain now the first char upper case","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"the first item of the array ","type":"text"},{"text":"hobbies","type":"text","marks":[{"type":"code"}]},{"text":" was selected and set to new element ","type":"text"},{"text":"person.primaryHobby","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"the field ","type":"text"},{"text":"type","type":"text","marks":[{"type":"code"}]},{"text":" was converted to upper case and a new field ","type":"text"},{"text":"person.adult","type":"text","marks":[{"type":"code"}]},{"text":" was added with the result of the expression ","type":"text"},{"text":"age > 18","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"the constant string ","type":"text"},{"text":"male","type":"text","marks":[{"type":"code"}]},{"text":" was set to the new field ","type":"text"},{"text":"person.gender","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"a new, empty list was added in new field ","type":"text"},{"text":"person.myList","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"a new, empty object was added in new field ","type":"text"},{"text":"person.myObject","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"By default the mapping result gets written to the body. If you would like write to a variable instead, you can use the ","type":"text"},{"text":"output","type":"text","marks":[{"type":"code"}]},{"text":" parameter:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"yaml"},"content":[{"text":"vars:\n mappingResult: null\npipeline:\n - data.mapping:\n rules: |\n ...\n output: ${vars.mappingResult}","type":"text"}]},{"type":"paragraph","content":[{"text":"Make sure that the output target was created before.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Contextualize the mapping data","type":"text"}]},{"type":"paragraph","content":[{"text":"By default the input data is provided directly to each mapping rule so it can be very easily accessed like this example shows:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"yaml"},"content":[{"text":"vars:\n data: {\"name\": \"someAttr\", \"value\": \"someValue\"}\n \npipeline:\n - data.mapping: \n input: ${vars.data}\n rules: |\n name -> result.name,\n value -> result.value","type":"text"}]},{"type":"paragraph","content":[{"text":"As you can see, on each mapping rule you can directly access the attributes of the input JSON via ","type":"text"},{"text":"name","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"value","type":"text","marks":[{"type":"code"}]},{"text":" variable.","type":"text"}]},{"type":"paragraph","content":[{"text":"In some situations you need more information on each mapping rule like the result of an inputPath, the current iteration index on case of an iteration and more. In this case, you can set the parameter ","type":"text"},{"text":"contextualize","type":"text","marks":[{"type":"code"}]},{"text":" to ","type":"text"},{"text":"true","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"If ","type":"text"},{"text":"contextualize","type":"text","marks":[{"type":"code"}]},{"text":" is enabled, an mapping context is provided on each mapping rule which gives you read access to these additional attributes:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"vars","type":"text","marks":[{"type":"code"}]},{"text":" = The variables of the pipeline.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"headers","type":"text","marks":[{"type":"code"}]},{"text":" = The headers of the pipeline.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"body","type":"text","marks":[{"type":"code"}]},{"text":" = The current body of the pipeline.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"item","type":"text","marks":[{"type":"code"}]},{"text":" = The current iteration item if this is an iteration mapping. Otherwise returns the current input data.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"index","type":"text","marks":[{"type":"code"}]},{"text":" = The current (0 based) iteration index if this is an iteration mapping. Otherwise returns ","type":"text"},{"text":"-1","type":"text","marks":[{"type":"code"}]},{"text":". ","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"selection","type":"text","marks":[{"type":"code"}]},{"text":" = The current selection result ","type":"text"},{"text":"after","type":"text","marks":[{"type":"underline"},{"type":"strong"}]},{"text":" the ","type":"text"},{"text":"inputPath","type":"text","marks":[{"type":"code"}]},{"text":" expression has been evaluated (= the value from the input to be written to the output). Note: This is only available in ","type":"text"},{"text":"outputPath","type":"text","marks":[{"type":"code"}]},{"text":" (right side).","type":"text"}]}]}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"Note: If ","type":"text"},{"text":"contextualize","type":"text","marks":[{"type":"code"}]},{"text":" is enabled, the current iteration item will be replaced by the context object. In order to still access the current iteration now you have to use the ","type":"text"},{"text":"item.","type":"text","marks":[{"type":"code"}]},{"text":" prefix instead. See the example below.","type":"text"}]}]},{"type":"codeBlock","attrs":{"language":"yaml"},"content":[{"text":"vars:\n data: {\"name\": \"someAttr\", \"value\": \"someValue\"}\n \npipeline:\n - data.mapping: \n input: ${vars.data}\n contextualize: true\n rules: |\n item.name -> result.name,\n item.value -> result.value","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Dynamic Output Path","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"outputPath","type":"text","marks":[{"type":"code"}]},{"text":" (right side of the mapping rule) is usually a fixed path to describe where to write the calculated selection from the inputPath rule to.","type":"text"}]},{"type":"paragraph","content":[{"text":"Sometimes it is required to create this ","type":"text"},{"text":"outputPath","type":"text","marks":[{"type":"code"}]},{"text":" dynamically based on the input data.","type":"text"}]},{"type":"paragraph","content":[{"text":"To do so, you have to set ","type":"text"},{"text":"contextualize: true","type":"text","marks":[{"type":"code"}]},{"text":". This will provide you a mapping context to each mapping rule which contains the current selection. This can be used to create a dynamic output path instead. See this example:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"yaml"},"content":[{"text":"vars:\n data: {\"name\": \"someAttr\", \"value\": \"someValue\"}\n \npipeline:\n - data.mapping: \n contextualize: true\n input: ${vars.data}\n rules: |\n item.value -> ${item.name}","type":"text"}]},{"type":"paragraph","content":[{"text":"As you can see:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Any input data is now accessed using the prefix ","type":"text"},{"text":"item.","type":"text","marks":[{"type":"code"}]},{"text":" This is because if contextualize is set to true, the mapping context is provided which adds multiple tooling variables in order to simplify mapping. Each variable has its own “namespace” to not collide with the input data.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The outputPath now uses a PEL in order to access the mapping context and dynamically set the name for the output attribute.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"The final JSON result is this:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"json"},"content":[{"text":"{\n \"someAttr\": \"someValue\"\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Also see: ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://logabit.atlassian.net/wiki/spaces/PA/pages/2548039682/#Contextualize-the-mapping-data"}},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Conditional mapping rules using if … then …","type":"text"}]},{"type":"paragraph","content":[{"text":"Lets assume you would like to apply a mapping rule only in case a certain condition is true. For example only in case a field in the source data exists or contains a specific value. For this you can define ","type":"text"},{"text":"if .. then .. ","type":"text","marks":[{"type":"code"}]},{"text":"statements as prefix for each rule. For example:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"yaml"},"content":[{"text":"body: {\n \"firstName\": \"Max \",\n \"lastName\": \"smith\",\n \"age\": 48,\n \"birthDate\": \"01/12/1977\",\n \"hobbies\": [\"hiking\", \"biking\"],\n \"type\": \"customer\"\n }\n\npipeline:\n - data.mapping:\n input: ${body}\n rules: |\n if age > 18 then age -> person.adult,\n ...","type":"text"}]},{"type":"paragraph","content":[{"text":"As you can see in this example, the condition expression ","type":"text"},{"text":"body.age > 18","type":"text","marks":[{"type":"code"}]},{"text":" will be executed and only if it returns ","type":"text"},{"text":"true","type":"text","marks":[{"type":"code"}]},{"text":", the field ","type":"text"},{"text":"person.adult","type":"text","marks":[{"type":"code"}]},{"text":" will be created and the value of field ","type":"text"},{"text":"age","type":"text","marks":[{"type":"code"}]},{"text":" will be set there. Otherwise, this mapping rule will be ignored, so there wont be any ","type":"text"},{"text":"person.adult","type":"text","marks":[{"type":"code"}]},{"text":" field created on the target.","type":"text"}]},{"type":"paragraph","content":[{"text":"Here is another example of a conditional mapping rule which checks whether a field on the source data exists and only in this case the mapping rule will be applied:","type":"text"}]},{"type":"codeBlock","content":[{"text":"...\nrules: |\n if ['someField'] then someField -> someTargetField","type":"text"}]},{"type":"paragraph","content":[{"text":"So the syntax of a conditional mapping rule is always:","type":"text"}]},{"type":"codeBlock","content":[{"text":"if CONDITION then MAPPING_RULE","type":"text"}]},{"type":"paragraph","content":[{"text":"CONDITION","type":"text","marks":[{"type":"code"}]},{"text":" is a ","type":"text"},{"text":"Pipeline Expression","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/PA/pages/2543026496"}}]},{"text":". Only if this expression returns:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Not ","type":"text"},{"text":"null","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"true","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"A number >= ","type":"text"},{"text":"0","type":"text","marks":[{"type":"code"}]}]}]}]},{"type":"paragraph","content":[{"text":"then ","type":"text"},{"text":"MAPPING_RULE","type":"text","marks":[{"type":"code"}]},{"text":" will be executed. Otherwise, it will be ignored and no field on target object will be created.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Mapping a List (iterating JSON array)","type":"text"}]},{"type":"paragraph","content":[{"text":"Lets assume you have a JSON array as input and you would like to prepare and write each entry of this array of dynamic length to a target list. This can also be done with the ","type":"text"},{"text":"data.mapping","type":"text","marks":[{"type":"code"}]},{"text":" command by defining the path to the array in the ","type":"text"},{"text":"input","type":"text","marks":[{"type":"code"}]},{"text":" parameter and setting the parameter ","type":"text"},{"text":"iterate","type":"text","marks":[{"type":"code"}]},{"text":" to ","type":"text"},{"text":"true","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"Here is an example:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"yaml"},"content":[{"text":"body: {\"people\": [\n {\n \"firstName\": \"Max \",\n \"lastName\": \"Smith\",\n \"age\": 48,\n \"birthDate\": \"01/12/1977\",\n \"hobbies\": [\"hiking\", \"biking\"],\n \"type\": \"customer\"\n },\n {\n \"firstName\": \"Diana \",\n \"lastName\": \"Serkson\",\n \"age\": 56,\n \"birthDate\": \"01/12/1967\",\n \"hobbies\": [\"reading\", \"swimming\"],\n \"type\": \"employee\"\n }\n ]}\n\npipeline:\n - data.mapping:\n input: ${body.people}\n iterate: true\n rules: |\n @text.upperCase(firstName) -> person.firstName,\n lastName -> person.surname,\n age -> person.age,\n birthDate -> person.dateOfBirth,\n hobbies -> person.hobbies,\n type -> person.type\n","type":"text"}]},{"type":"paragraph","content":[{"text":"As you can see, the ","type":"text"},{"text":"input","type":"text","marks":[{"type":"code"}]},{"text":" parameter points to the ","type":"text"},{"text":"people","type":"text","marks":[{"type":"code"}]},{"text":" array inside the JSON. ","type":"text"}]},{"type":"paragraph","content":[{"text":"The parameter ","type":"text"},{"text":"iterate","type":"text","marks":[{"type":"code"}]},{"text":" is set to ","type":"text"},{"text":"true","type":"text","marks":[{"type":"code"}]},{"text":" in order to iterate over the given JSON array.","type":"text"}]},{"type":"paragraph","content":[{"text":"This initially creates a new array on the output and then creates a new item entry on each iteration step in this list where the target fields will be automatically created if not exists (also recursively).","type":"text"}]},{"type":"paragraph","content":[{"text":"In case the output location is given then the final list will be written to this location. If not defined, the list will be written to the message body by default. ","type":"text"}]},{"type":"paragraph","content":[{"text":"The output in the body from the example above will be this:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"json"},"content":[{"text":"[\n {\n \"person\": {\n \"firstName\": \"MAX \",\n \"surname\": \"Smith\",\n \"age\": 48,\n \"dateOfBirth\": \"01/12/1977\",\n \"hobbies\": [\"hiking\", \"biking\"],\n \"type\": \"customer\"\n }\n },\n {\n \"person\": {\n \"firstName\": \"DIANA \",\n \"surname\": \"Serkson\",\n \"age\": 56,\n \"dateOfBirth\": \"01/12/1967\",\n \"hobbies\": [\"reading\", \"swimming\"],\n \"type\": \"employee\"\n }\n }\n]","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"Hint: In some cases an iteration item should be ignored and not copied to target list in case it is an empty JSON. In such a situation, you can set the parameter ","type":"text"},{"text":"ignoreEmptyItems","type":"text","marks":[{"type":"code"}]},{"text":" to ","type":"text"},{"text":"true","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Iteration Context","type":"text"}]},{"type":"paragraph","content":[{"text":"By default on any iteration loop, the current iteration item from the list will be provided and you can use it to apply mapping rules.","type":"text"}]},{"type":"paragraph","content":[{"text":"In case you need more information on each iteration loop and access to the pipeline scope, you can enable the iteration context using ","type":"text"},{"text":"contextualize: true","type":"text","marks":[{"type":"code"}]},{"text":":","type":"text"}]},{"type":"codeBlock","attrs":{"language":"yaml"},"content":[{"text":"pipeline:\n - data.mapping:\n input: ${path.to.list}\n iterate: true\n contextualize: true\n rules: |\n ...","type":"text"}]},{"type":"paragraph","content":[{"text":"See here for a complete example:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"yaml"},"content":[{"text":"vars:\n currentDate: ${@date.now()}\n \nbody: {\"people\": [\n {\n \"firstName\": \"Max \",\n \"lastName\": \"Smith\",\n \"age\": 48,\n \"birthDate\": \"01/12/1977\",\n \"hobbies\": [\"hiking\", \"biking\"],\n \"type\": \"customer\"\n },\n {\n \"firstName\": \"Diana \",\n \"lastName\": \"Serkson\",\n \"age\": 56,\n \"birthDate\": \"01/12/1967\",\n \"hobbies\": [\"reading\", \"swimming\"],\n \"type\": \"employee\"\n }\n ]}\n\npipeline:\n - data.mapping:\n input: ${body.people}\n iterate: true\n contextualize: true\n rules: |\n @text.upperCase(item.firstName) -> person.firstName,\n item.lastName -> person.surname,\n item.age -> person.age,\n item.birthDate -> person.dateOfBirth,\n item.hobbies -> person.hobbies,\n item.type -> person.type,\n index -> person.index,\n vars.currentDate -> person.mappingDate","type":"text"}]},{"type":"paragraph","content":[{"text":"For more details about the ","type":"text"},{"text":"contextualize","type":"text","marks":[{"type":"code"}]},{"text":" feature, see here: ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://logabit.atlassian.net/wiki/spaces/PA/pages/2548039682/#Contextualize-the-mapping-data"}},{"text":" .","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Mapping via FTL Template","type":"text"}]},{"type":"paragraph","content":[{"text":"An alternative way for mapping data from a source JSON to a target JSON is by using a template engine like the FreeMarker of the command ","type":"text"},{"text":"transform.ftl","type":"text","marks":[{"type":"code"}]},{"text":". See also here: ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://logabit.atlassian.net/wiki/spaces/PA/pages/2545647697"}},{"text":" .","type":"text"}]},{"type":"paragraph","content":[{"text":"Here is an example:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"yaml"},"content":[{"text":"body: {\n \"firstName\": \"Max \",\n \"lastName\": \"smith\",\n \"age\": 48,\n \"birthDate\": \"01/12/1977\",\n \"hobbies\": [\"hiking\", \"biking\"],\n \"type\": \"customer\"\n }\n\npipeline:\n - transform.ftl:\n template: |\n {\n \"person\": {\n \"firstName\": \"${body.firstName}\",\n \"surname\": \"${body.lastName}\",\n \"age\": ${body.age},\n \"dateOfBirth\": \"${body.birthDate}\",\n \"hobbies\": [\n <#list body.hobbies as hobby>\n \"${hobby}\"<#sep>, \n \n ],\n \"type\": \"${body.type}\"\n }\n }","type":"text"}]},{"type":"paragraph","content":[{"text":"Which gives you this output:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"yaml"},"content":[{"text":"{\n \"person\": {\n \"firstName\": \"Max \",\n \"surname\": \"smith\",\n \"ageas\": 48,\n \"dateOfBirth\": \"01/12/1977\",\n \"hobbies\": [\n \"hiking\",\n \"biking\"\n ],\n \"type\": \"customer\"\n }\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"You also can map JSON arrays using this approach. For example:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"yaml"},"content":[{"text":"body: [\n {\n \"firstName\": \"Max \",\n \"lastName\": \"smith\",\n \"age\": 48,\n \"birthDate\": \"01/12/1977\",\n \"hobbies\": [\"hiking\", \"biking\"],\n \"type\": \"customer\"\n },\n {\n \"firstName\": \"Sam \",\n \"lastName\": \"Walsh\",\n \"age\": 48,\n \"birthDate\": \"01/12/1977\",\n \"hobbies\": [\"swimming\", \"bowling\"],\n \"type\": \"customer\"\n }\n ]\n\npipeline:\n - transform.ftl:\n\n iterate: true\n # Use FreeMarker language here for mappings (PEL will not work here!)\n template: |\n [\n <#list body as item>\n {\n \"person\": {\n \"firstName\": \"${item.firstName}\",\n \"surname\": \"${item.lastName?cap_first}\",\n \"age\": ${item.age},\n \"dateOfBirth\": \"${item.birthDate}\",\n \"hobbies\": [\n <#list item.hobbies as hobby>\n \"${hobby}\"<#sep>, \n \n ],\n \"type\": \"${item.type}\"\n }\n }<#sep>, \n \n ]","type":"text"}]},{"type":"paragraph","content":[{"text":"Which gives you an output like this:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"json"},"content":[{"text":"[\n {\n \"person\": {\n \"firstName\": \"Max \",\n \"surname\": \"Smith\",\n \"age\": 48,\n \"dateOfBirth\": \"01/12/1977\",\n \"hobbies\": [\n \"hiking\",\n \"biking\"\n ],\n \"type\": \"customer\"\n }\n },\n {\n \"person\": {\n \"firstName\": \"Sam \",\n \"surname\": \"Walsh\",\n \"age\": 48,\n \"dateOfBirth\": \"01/12/1977\",\n \"hobbies\": [\n \"swimming\",\n \"bowling\"\n ],\n \"type\": \"customer\"\n }\n }\n]","type":"text"}]},{"type":"paragraph","content":[{"text":"Using a template engine for JSON mapping is not as clean as it is by using the ","type":"text"},{"text":"data.mapping","type":"text","marks":[{"type":"code"}]},{"text":" command but has huge flexibility.","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"Keep in mind that the FreeMarker template engine also uses the ","type":"text"},{"text":"${ } ","type":"text","marks":[{"type":"code"}]},{"text":"syntax to access its model data. ","type":"text"},{"text":"Do not confuse with Pipeline Expressions","type":"text","marks":[{"type":"strong"}]},{"text":": Inside the ","type":"text"},{"text":"template","type":"text","marks":[{"type":"code"}]},{"text":" parameter you can only use FreeMarker expression, ","type":"text"},{"text":"no","type":"text","marks":[{"type":"strong"}]},{"text":" Pipeline Expressions!","type":"text"}]}]},{"type":"paragraph","content":[{"text":"For the mapping functions (like date format, text manipulation and so on) you need to use the built-in functions of the FreeMarker template engine. See the ","type":"text"},{"text":"?cap_first","type":"text","marks":[{"type":"code"}]},{"text":" usage in the surname attribute in the example.","type":"text"}]},{"type":"paragraph","content":[{"text":"For FreeMarker, you can find the reference for the built-in functions here: ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://freemarker.apache.org/docs/ref_builtins.html"}},{"text":" ","type":"text"}]},{"type":"paragraph"}],"version":1}

Browser not supported