Sign upSign InSign upSign InStefan WeberFollowITNEXT--1ListenShareManipulate and transform any Json document into an easy-to-handle format for your OutSystems application.Jsonata is a powerful data transformation and manipulation language for JSON data. The runtime library written in JavaScript was originally developed by IBM and later open sourced. Mikhail Barg later implemented the JSONata query and transformation language in native C# and based on his work I created a wrapping extension for the OutSystems platform.Deserializing JSON from REST APIs to OutSystems structures can be challenging in some situations likeJSONata assists in manipulating and converting source JSON data into a preferred target format, enabling pain-free deserialization in OutSystems. The key point is the “preferred target format,” since JSONata’s capabilities extend beyond addressing issues with source JSON data, enabling the transformation of any JSON data into any desired format. This includes a wide array of additional transformations and manipulations, such as data concatenation, element filtering, various calculations, and much more.Leveraging JSONata for transformation and manipulation of JSON data can help to reduce a server action flow in OutSystems drastically.In this article, I am referring to transforming JSON data consumed via a REST API, but JSONata can of course also be used to transform response data in exposed REST APIs or for any other use-case dealing with JSON data.Using JSONata is quite simple. You need a source JSON document and a JSONata definition.A JSONata definition contains all the instructions on how you want to transform and manipulate your source document.The JSONata Transformation Forge component — specifically the JSONata_IS module — contains a single server action that takes the source document (JsonInput) and the JSONata definition (JsonTransform) as input parameters and returns the transformed result (Result).To create and try out a JSONata definition you can use the JSONata Exerciser before using it in your application.JSONata is immensely powerful, and the learning curve can be steep. In this article, I want to give some first, but simple, examples to get up and running with JSONata transformations.More information on creating transformation and manipulation definitions can be foundFor our first example, we just want to concatenate text from multiple attributes into a single attribute.Our source JSON document looks like thiswhich we want to transform into a single attribute “displayName”. The resulting JSON should then look like thisTo concatenate the three attributes into a single attribute we use the following definition.You will find additional information on how to navigate and reference source JSON data in the JSONata documentation. For simple queries use the source attribute name directly. For nested objects use dot notation e.g. “address. Street”You can filter source data at any step using predicate filters. Look at the source documentThe contact data above has multiple phone numbers. We are only interested in the Office Phone number and our result document should look like this.We apply the following JSONata definitionWe apply a predicate filter to the “phoneNumbers” attribute by filtering to results where “type” is equal to “office”. Then we reference the number attribute.Attention. This predicate filter can return an array. Try adding another phone number of type “office” and review the result. You will now note that “officePhone” is an array with all phone numbers of type “office”. To ensure that it is only a single phone number you need to change your definition as follows to only use the first found office phone number.This is my personal favorite. In the past, I had to deal with some weird responses in two cases where an attribute can either be an object or an array of objects.Consider the following responses from an API. In the first JSON document the API returned an object for the attribute “authors” (single author). In the second JSON document, the “authors” attribute is an array of objects (multiple authors).First example — objectSecond example — array of objectsTo ensure that we can deserialize this easily in OutSystems into a unified structure we want to transform our source data of authors always into an array. We use the following definition to achieve thisThe $type expression returns the type of the “authors” attribute in the source document. If it is an array, we simply add the “authors” attribute (which is already an array). Otherwise, we wrap the source “authors” attribute with brackets, thus resulting in an array with a single object.Dealing with arbitrary attribute names is not that uncommon. Consider the following example source documentThe “version” attribute contains an object with attributes that have an unpredictable name, e.g. a unique version identifier. This structure cannot be deserialized by default in OutSystems, but if we modify the source versions attribute to an array of equivalent objects, we can. A target format could look like thisThe target format “versions” attribute is now an array and the arbitrary attribute name becomes an attribute (version) of an array element. To transform the source into this target format the following definition is usedWe iterate over the attributes of the “versions” source attribute and construct an object with “version” set to the $key and “createdOn” and “size” to the corresponding $value elements.The last example in this article is quite simple. It shows how to calculate a sum over an array of items.Here is the — quite simple — source documentWe have an array of items each with an amount. In our target structure we are only interested in the total sum of all items. Our target format should look like thisThe definition for creating a sum looks like the following by using the $sum expression for “items.amount”.The examples above should give you a quick overview of the possibilities you get with JSONata transformations. Check the JSONata documentation for additional transformation and manipulation capabilities.In the final part of this article, we look at how to integrate JSONata into an OutSystems application.Make sure that you already have downloaded the JSONata Transformation Forge component to your OutSystems factory.Next is to create a server action. For this example, we assume that you query a REST API first. The REST action you call returns the result as text. (Output set to data type of text which returns the whole JSON payload as text)JSONata is a powerful addition for complex JSON transformations and manipulations. It can drastically reduce your server action flows by offloading transformations to a definition file. The JSONata Transformation Forge component based on the work of Mikhail Barg makes it easy to integrate with your applications.Thank you for reading. I hope you liked it and that i have explained the important parts well. Let me know if not 😊If you have difficulties in getting up and running, please use the OutSystems Forum to get help. Suggestions on how to improve this article are very welcome. Send me a message via my OutSystems Profile or write a comment.Originally posted on “Transform JSON Data with JSONata in OutSystems (without.systems)”Some rights reserved----1ITNEXTDigital Craftsman, OutSytems MVP, AWS Community Builder and Senior Director at Telelink Business ServicesStefan WeberinITNEXT--Jacob FerusinITNEXT--8Juntao QiuinITNEXT--13Stefan WeberinITNEXT--Ricardo Pereira--2Sandeep Sai Kumar Kancharla--Nivaldo Pereira--Stefan WeberinITNEXT--Vidyadhar Baratam--Yuri BettinStackademic--2HelpStatusAboutCareersBlogPrivacyTermsText to speechTeams