Edit JSONata Unit

Edit JSONata Unit

Overview

The JSONata Unit is an action unit in the Flow Editor/Designer that enables a flow to query, transform, and manipulate JSON data using JSONata expression language. This unit lets you convert data without writing custom code, making it ideal for handling complex JSON structures.

What it does:
  1. Applies JSONata expressions to: 
    1. Extract specific fields from JSON.
    2. Transform JSON into a new structure.
    3. Perform calculations or conditional logic on JSON data.
  2. Outputs the transformed JSON for the next step in the flow.
How it works:
  1. Input: JSON data from a previous step (e.g., API response, document metadata).
  2. Expression: Define a JSONata expression (e.g., Account.Order.Product.(Price * Quantity)).
  3. Execution: The unit evaluates the expression against the input JSON.
  4. Output: Returns the transformed or filtered JSON.
Use case:
  1. API Integration: Extract only required fields from a large JSON response.
  2. Data Mapping: Convert nested JSON into a flat structure for easier processing.
  3. Business Logic: Calculate totals or apply conditions within JSON data.

Accessing JSONata Unit Properties

  1. To view/modify the unit property, click on the JSONata unit. Upon clicking the unit, a property panel opens below, and the unit gets highlighted.
  2. The property panel will open and display the following sections:
    1. Input
    2. Processing
    3. Output
  3. By default, all sections are displayed unless you have specified panel settings in the user settings.

Input Section

  1. The Input section provides the details on the inbound message, and the following tabs are provided in the section:
    1. Data section: The Data section provides the name of the processed units of the flow.
    2. Message: The Message section displays the inbound message of the selected unit. 
Image

Data Section

  1. The section provides details on inbound messages and lists units that have already been processed. The following message details will be shown:
    1. Complete Message:
      1. The Complete Message represents the entire message payload, including:
        1. Message Header
        2. Start Message
        3. Input Message
        4. Any additional structural elements
    2. Message Header:
      1. The Message Header contains metadata about the message rather than the message's business data.
      2. It helps the system understand how to handle the message. 
      3. It helps in tracking and tracing, routing, logging, and error handling.
    3. Start Message: 
      1. The Start Message is the initial structure received by the Start Unit when the flow begins.
        1. It defines the expected input format.
        2. It acts as the primary data structure for processing.
        3. It is usually defined using XML or JSON schema.
      2. This message becomes the main working data object throughout the flow.
    4. Input Message:
      1. The Input Message refers to the actual incoming payload provided to the flow at runtime.
        1. In testing → comes from the Test Message (XML).
        2. In production → comes from API, queue, subscription, etc.
      2. It populates the Start Message structure and is then used by downstream units like Mapping, Condition, or API calls.
    5. Already Processed Units:
      1. The units that are processed before the System Call unit will be listed here. The unit will be displayed by its name.
  2. You can click any unit to view the data processed by that unit. The message will be displayed in the 
Image
  1. A Search option is also provided to search for the unit name from the list.
  2. Enter the unit name in the search field, and the result will be displayed instantly.
  3. To close the search, click on the Clear (x) icon. 
Image
  1. A Sort icon is provided to arrange the list as needed.
  2. You can also arrange the units either in ascending order (A to Z) or descending order (Z to A) using the icon next to the search icon. By default, the units are arranged in ascending order.
  3. Click the Sort icon to switch to descending order.
  4. Click again to return to the default ascending order.
Image
  1. A Collapse icon is provided next to the Sort icon. You can use this function to increase the message's working area for better readability and more space.
  2. Click on the icon to collapse the listing. 
Image
  1. After clicking the Collapse icon, the listing collapses.
  2. However, you will still be able to view the icon of the respective units.
  3. When you hover over the icon, you can view the names of the units. Additionally, you can click any link to view its message.
Image

Message Section

  1. You can view the message of any of the units listed in the Data section.
  2. To view the message of any unit, click on the unit in the Data section. The message will be displayed instantly. 
Image
  1. A search option is also provided to find any node in the message.
  2. Enter the node name in the search field, and the result will be displayed instantly and highlighted.
  3. If more than one result is displayed, a navigation icon and a results counter are provided. You can navigate through the search results using the navigation icons.
  4. To close the search, click the 'x' icon. 
Image

Legends

  1. A legend icon is provided to help you understand the message. The color of the nodes indicates their status.
  2. Click the Legend icon to view the details. When you click the icon, the list will show the legend used in the message.
Image

Adjust Message Font Size

  1. A Font Size box is provided to increase or decrease the message's font size.
  2. The current font size will be shown in the box.
  3. Click on the box to increase or decrease the font size. 
Image
  1. After clicking the Font Size box, a slider will appear below it.
  2. Use the slider to increase or decrease the font size. 
  3. As you slide, the change in size will be reflected in the message instantly.  
  4. The supported font size ranges from 8 to 72.
Image

Switch Between Code and Tree View

  1. By default, the message will be displayed in Tree View.
  2. Click on the Switch to Code View icon.
Image
  1. The inbound message gets switched to code view.
  2. Click the icon again to switch back to tree view mode.
Image

View/Modify Input Message (Tree View)

  1. You can view the inbound message in tree/code view.
  2. By default, the message will be displayed in tree view. Switch to tree view mode if you are in code view.
  3. Please note that you cannot edit a message in tree view mode. The message will be displayed in read-only mode. To edit the message, switch to code view. 
  4. The tree view provides the following icons in the toolbar:
    1. Find: This option allows you to find any parameter in the inbound message.
    2. Font Size: You can set the message font for clearer viewing. The available font size range is from 8 to 24. Select the desired value from the drop-down.
    3. Show Legend: Provide the list of the legend used in the message.
Image

View/Modify Inbound Message (Code View)

  1. To view the message in code view, switch to code view by clicking on the icon.
Image
  1. The code view will show the message in XML format. You can edit the message in this mode as needed.
  2. A toolbar is provided to help you to edit the message efficiently. The code view provides the following icons in the toolbar:
    1. Cut: 
      1. Function: Removes the selected text or object from its current location and places it on the clipboard.
      2. Use Case: Moving content from one place to another.
    2. Copy:
      1. Function: Copies the selected text or object to the clipboard without removing it from its original location.
      2. Use Case: Duplicating content.
    3. Paste:
      1. Function: Inserts the clipboard content into the current location.
      2. Use Case: Adding previously cut or copied content.
    4. Find:
      1. Function: Searches for specific text or patterns within the document or code.
      2. Use Case: Quickly locating words, phrases, or code snippets.
    5. Replace:
      1. Function: Finds specific text and replaces it with new text.
      2. Use Case: Updating repeated terms or correcting errors throughout a document.
    6. Beautify:
      1. Function: Formats code or text to make it more readable and properly indented.
      2. Use Case: Cleaning up messy code for better readability.
    7. Word Wrap:
      1. Function: Ensures that long lines of text automatically wrap to fit within the visible window without horizontal scrolling.
      2. Use Case: Easier reading and editing of long lines.
    8. Maximize: 
      1. Function: Expands the editor or window to full screen for better focus and visibility.
      2. Use Case: Working without distractions or seeing more content at once.
  3. Once you have modified the message, click the Save button to save the changes.
Image

View Variables

  1. The section will display the defined variables. You can create global or local variable on the section.
  2. To open the Variable section, click on the Variable menu.
Image
  1. A list of the variables gets displayed. The list provides both global and local variables.
    1. Global Variables: 
      1. A global variable is one declared at a higher level and accessible from any part of the flow.
      2. Key Characteristics: 
        1. Accessible throughout the entire flow
        2. Can be used by multiple units
        3. Retains its value during the flow execution
      3. When to Use:
        1. Shared configuration values
        2. Data that must be reused across multiple units
        3. Environment-level settings
    2. Local Variables:
      1. A local variable is declared inside a specific unit or block and can only be accessed within that scope.
      2. Key Characteristics: 
        1. Limited visibility
        2. Exists only within the unit
        3. Not accessible outside the specific unit
      3. When to Use:
        1. Unit-specific logic
        2. Temporary calculations
        3. Intermediate processing values
Image

Add Variables

  1. To add variables, click on the (+) icon as shown on the screen.
Image
  1. An Add Variable pop-up will appear, displaying the following fields. All fields are mandatory.
  2. Variable Name:
    1. It is a text field; you can enter the variable name in this field.
    2. You are free to use any name of your choice.
  3. Scope:
    1. You need to select the variable scope from the drop-down.
    2. The following scopes are provided in the drop-down:
      1. Local: A local variable is declared within a specific unit and can be accessed only by that unit. 
      2. Global: A global variable is one declared at a higher level and accessible to all units from any part of the flow.
  4. Variable Type:
    1. Once you have selected the scope, select the variable type from the drop-down.
    2. The following variable types are available:
      1. Fixed: A fixed variable has a constant value that you manually define, and it does not change during execution. 
      2. User: A user variable gets its value from user input.
      3. Expression: An expression variable is calculated using logic or formulas.
  5. Once you have filled all the fields, click on the Add button.
  6. Click Cancel to close the pop-up.
Image
  1. The newly added variable gets added to the list.
  2. Now you can edit the variable and set the values.
Image

Edit Variables

  1. To edit any variable, hover over the variable band and click on the Edit icon.
  2. Based on the variable type, the edit screen will open.
Image

    Edit Fixed Variable Type

    1. On clicking the edit icon, the Fixed Variable pop-up will open.
    2. You can modify the value in the Value field. This field is mandatory and cannot be left blank.
    3. Once the modification is complete, click the Save button.
    4. Click on the Cancel button to close the pop-up. 
    Image

    Edit User Defined Variable Type

    1. On clicking the edit icon, the User Variable pop-up will open. You can modify the following fields:
      1. Label: This field allows you to change the label of the variable.
      2. Description: This field allows you to change the existing description.
      3. Mandatory: Make the variable mandatory or non-mandatory using the Yes or No from the drop-down. 
      4. Data Type: This field allows you to set the data type for the selected variable. 
      5. Default Value: Set the default value for the selected variable. 
    2. Once the modification is complete, click the Save button.
    3. Click on the Cancel button to close the pop-up. 
    Image

    Edit Expression Variable Type

    1. On clicking the edit icon, the Expression Variable pop-up will open.
    2. You can modify the existing expression of the variable. You can define the expression in the expression field. If you need any variable in your expression, you can drag and drop it from the list. Please note that you cannot use (drag & drop) the selected variable in your expression. 
    3. Once the modification is complete, click the Save button.
    4. Click on the Cancel button to close the pop-up.
    Image

    Delete Variables

    1. To delete any variable, hover over the variable band and click on the Delete icon.
    Image
    1. A Delete Variable pop-up will appear.
    2. Click on the Yes button to delete the chosen variable.
    3. Click on the No button close the pop-up.
    Image

    Processing Section

    The Processing section provides the configuration details of the selected unit and provides the following tabs. You can switch between the tabs by clicking on them:
    1. Details Tab: The Details Tab contains the general information and basic properties of the flow. Typically includes the unit name and its description.
    2. Configuration Tab: Defines the technical setup and runtime-related settings. Typically includes payload handling, exposed objects, and error-handling settings.
    3. Design: The Design Tab is the visual workspace where you build the actual flow logic. Typically includes request document, key handling, error handling, etc.
    Image

    Details Tab

    The Details tab provides basic details of the JSONata unit, including its name and description. The Details tab is displayed by default. It provides the following fields:
    1. Name: 
      1. The unit name is provided in this section, and you may modify the existing name within this field.
      2. Click the field to update the unit's name.
      3. Upon completing the modifications, click the 'Save' button in the action area of the screen.
    2. Description: 
      1. This field describes the processing unit, and you can modify the existing description.
      2. Click the field to edit the unit's description.
      3. Once you are done with the modification, click the Save button in the action area of the screen.
    Image

    Configuration Tab

    1. To switch to the Configuration tab, click it. The Configuration tab provides configuration details for the JSONata unit.
    2. The following fields will be shown on the tab:
      1. Payload Handling
      2. Continue flow on error
      3. Exposed Object
    3. Click any of the bands to view and modify the settings. 
    Image

    Payload Handling

    This setting allows you to define how a flow receives, processes, transforms, and passes message data (payload) between units during execution. In simple terms, it allows you to select the specific payload that you do not want to process.
    1. Expand the band by clicking it. Once expanded, you will see the Remove for further processing field.
    2. Click the field to view the available payload. Select the payload you do not want to process.
    3. You can also type the payload type in the field; the entered payload is listed, and then select it.
    Image
    1. The selected payload is added to the field as a chip. The chip contains the 'X' icon; you can remove the payload by clicking the 'X' icon.
    2. Once you have added the payloads you do not want to process, click the Save button.
    Image

    Continue Flow on Error

    Continue Flow on Error is a configuration option that allows a flow to continue executing even if a specific unit encounters an error. Instead of stopping the entire flow, execution moves to the next configured step.
    1. A toggle switch is provided on the band, and by default, it is disabled.
    2. To allow the process to continue despite an error, enable the toggle switch.
    3. Click the Save button to save the configuration.
    Image

    Exposed Object

    An Exposed Object is a data structure or variable that is made available outside the flow as part of its output. It defines what information the flow will return to the calling system.
    1. Expand the band by clicking it. Once expanded, you will see the Object drop-down field.
    Image
    1. Click the field to view the available objects. Select the required object that you want to process.
    Image
    1. Once the object is selected, click the Save button.
    Image

    Design Tab

    1. To switch to the Design tab, click it. The Design tab provides configuration details for the JSONata unit.
    2. The following fields will be shown on the tab:
      1. Request Document
      2. Storage
      3. JSONata
      4. Inbound Parameter
      5. Outbound Format
      6. Outbound Parameter
    3. Click any of the bands to view and modify the settings. 
    Image

    Request Document

    A request document is a structured data message sent from one system to another when a request is made. It defines the format and content of the transmitted data in JSON format.
    1. Expand the band by clicking it. Once expanded, you will see the Data Source field.
    2. Fx - Function:
      1. This field supports the Expression Builder, which helps you create logical expressions or formulas without writing complex code. An expression is a combination of Fields / Variables, Operators, Values, and Functions. It allows you to write your own expression. 
      2. It provides a structured interface where you can:
        1. Select fields or variables
        2. Choose operators (like =, ≠, >, <, AND, OR, NOT)
        3. Add functions such as string, date, and math functions
        4. Build conditions step by step to ensure syntax is correct.
    3. You can drag and drop any nodeset from the Input section into the Data Source field. Open any message in the Input section, then drag the nodeset into the field.
    4. Please note that you can only drop one nodeset into the field. If you drop a new nodeset on top of an existing nodeset, the existing nodeset will be replaced by the new one. 
    Image

    Storage

    1. Expand the band by clicking it. Once expanded, you will see the Storage field. 
    2. Click on the drop-down to view the list of available options:
      1. JSONata belongs to automation
      2. JSONata belongs to the partner's library
    3. Select an appropriate option from the drop-down.
    4. Once the storage option is selected, click Save.
    Image

    JSONata

    JSONata is a lightweight query and transformation language for JSON data. It works similarly to XPath (for XML), but specifically for JSON structures.
    1. Expand the band by clicking it.
    2. A drop-down will display the name of the current JSON file. If you have not added any JSON yet, you can add the JSON file by using the plus icon next to the field.
    Image
    1. The drop-down will display the used JSON name, and the JSON will appear below.
    2. You can make modifications to JSON.
    3. A toolbar is provided to help you with smooth editing.
    4. An Expand/Collapse icon is provided to expand the working area.
    5. Click on the icon to expand or collapse the stylesheet.
    Image

    Add New JSON File
    1. Click on the plus icon.
    2. On clicking the (+) icon, an Add JSONata pop-up will open.
    Image
    1. Enter the name of the stylesheet in the Name field.
    2. Click the Add button to add the stylesheet. Upon clicking the Add button, a new stylesheet will be added to the list. Please remember that this JSONata file provides the standard structure. You need to edit the JSON to your requirements to use it.
    3. After making modifications, click the Save button. 

    Image

    Inbound Parameter

    1. Expand the band by clicking it. Once expanded, you will see the following fields:
      1. XML attribute identifier: A unique attribute name used to identify an attribute within an XML element.
      2. XML attributes parent link identifier: Defines the relationship between a child element and its parent element.
      3. Default Data Type: Defines the default data type assigned to the attribute.
      4. Name Space Handling: Used to manage XML namespaces and avoid naming conflicts.
      5. Object Handling: Defines how XML elements and attributes are mapped into objects or classes. 
    2. Once the section is closed, the number of the selected inbound parameters will be displayed. For example, if one parameter is added to the field, the closed band will display '1'.
    Image

    Conditions to display the Inbound Parameter section:
    1. Once the request document is pulled, the system will know whether it is an XML or a JSON file.
    2. If the request document is XML, show the Inbound Parameter field.
    3. If the request document is JSON, disable the Inbound Parameter field.
    4. If there is no request document, disable the Inbound Parameter field.
    Image

    XML attribute identifier
    1. An XML attribute identifier is a unique name used to identify an attribute within an XML element.
    2. It is a text box field.
    3. Enter the attribute identifier from the XML.
    XML attribute parent link identifier
    1. An XML attribute parent link identifier establishes a relationship between a child element and its parent element.
    2. It is a text box field.
    3. Enter the value from the XML.
    Default data type
    1. It is a drop-down field.
    2. Select the appropriate data type (values are provided by the API, such as a string).
    3. Defines the default data type assigned to the attribute.
    Name Space Handling
    1. Namespace handling is the process of managing XML namespaces to avoid naming conflicts between elements and attributes that have the same name but different meanings.
    2. It is a drop-down field.
    3. Select a value from the drop-down provided by the API, such as a URI (prefix).
    Object Handling
    1. Object handling refers to how XML data is mapped to objects. It defines how elements, attributes, and hierarchies are converted into objects, fields, or classes.
    2. It is a drop-down field.
    3. Select the appropriate object mapping option.
    Image

    Outbound Format

    1. Expand the band by clicking it. Once expanded, you will see the Outbound Format section.
    2. It is a drop-down field with JSON and XML as options. By default, the JSON option will be selected. However, you can change the value to XML as needed.
    Image

    Conditions to display the Outbound Parameter section
    1. If the JSON is selected in the field, the Outbound Parameter field will be disabled.
    2. If the XML is selected, the Outbound Parameter field will be enabled.
    Image

    Outbound Parameter

    1. Expand the band by clicking it. Once expanded, you will see the following fields:
      1. XML attribute identifier: A unique attribute name used to identify an attribute within an XML element.
      2. XML attributes parent link identifier: Defines the relationship between a child element and its parent element.
      3. Object Handling: Defines how XML elements and attributes are mapped into objects or classes. 
      4. Object name indicator: Specify which XML element or attribute represents the name of an object during XML-to-object mapping.
    2. Once the section is closed, the number of the selected outbound parameters will be displayed. For example, if one parameter is added to the field, the closed band will display '1'.
    Image
    XML attribute identifier
    1. An XML attribute identifier is a unique name used to identify an attribute within an XML element.
    2. It is a text box field.
    3. Enter the attribute identifier from the XML.
    XML attribute parent link identifier
    1. An XML attribute parent link identifier establishes a relationship between a child element and its parent element.
    2. It is a text box field.
    3. Enter the value from the XML.
    Object Handling
    1. Object handling refers to how XML data is mapped to objects. It defines how elements, attributes, and hierarchies are converted into objects, fields, or classes.
    2. It is a drop-down field.
    3. Select the appropriate object mapping option.
    Object name indicator
    1. The Object Name Indicator is a text field used to specify which XML element or attribute represents an object's name during XML-to-object mapping.
    2. It is a text field for entering the attribute or identifier name.
    Image

    Output Section

    The Output section displays the unit's final output message. The Output Message of the system call unit is the data generated after the unit completes execution. This final output of the unit is then passed to the next unit in the flow. The Output section provides the message in XML and JSON format on different. You can switch between the tabs by clicking on them:
    1. Message Tab
    2. JSON Message Tab


    Message Tab

    1. By default, the Message tab is displayed, and the message is shown in tree view mode.

    Search

    1. A search option is also provided to find any node in the message.
    2. Enter the node name in the search field, and the result will be displayed instantly and highlighted.
    3. If more than one result is displayed, a navigation icon and a results counter are provided. You can navigate through the search results using the navigation icons.
    4. To close the search, click the 'x' icon. 
    Image

    Legends

    1. A legend icon is provided to help you understand the message. The color of the nodes indicates their status.
    2. Click the Legend icon to view the details. When you click the icon, the list will show the legend used in the message.
    Image

    Adjust Message Font Size

    1. A Font Size box is provided to increase or decrease the message's font size.
    2. The current font size will be shown in the box.
    3. Click on the box to increase or decrease the font size. 
    Image
    1. After clicking the Font Size box, a slider will appear below it.
    2. Use the slider to increase or decrease the font size. 
    3. As you slide, the change in size will be reflected in the message instantly.  
    4. The supported font size ranges from 8 to 72.

    Switch Between Code and Tree View

    1. By default, the message will be displayed in Tree View.
    2. Click on the Switch to Code View icon.


    JSON Tab

    1. Click the JSON Message tab to view the message in JSON format.
    2. You can view the Output message in the tree/code view.
    3. By default, the message will be displayed in tree view. Switch to tree view mode if you are in code view.
    4. Please note that you cannot edit a message in tree view mode. The message will be displayed in read-only mode. To edit the message, switch to code view. 
    5. The tree view provides the following icons in the toolbar:
      1. Find: This option allows you to find any parameter in the inbound message.
      2. Font Size: You can set the message font for clearer viewing. The available font size range is from 8 to 24. Select the desired value from the drop-down.
      3. Show Legend: Provide the list of the legend used in the message.
    1. To view the message in code view, switch to code view by clicking on the icon.




      • Related Articles

      • Edit JSONata Unit

        Edit JSONata Unit

      • Edit Component Flow

        Overview The flow editor feature in OneEnterprise enables you to visually modify and refine component flow through an intuitive interface. This functionality permits direct interaction with the flow structure of the component. The flow editor offers ...

      • JSONata Unit

        JSONata Unit Overview Purpose: The JSONata Unit is an action unit in the Flow Editor/Designer that enables a flow to query, transform, and manipulate JSON data using JSONata expression language. This unit lets you convert data without writing custom ...

      • Edit XSLT Unit

        Edit XSLT Unit

      • Edit Database Unit

        Edit Database Unit