Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


Panel

Table of Contents
maxLevel6


Disclaimer

Your use of this download is governed by Stonebranch's Terms of Use, which are available here.

Overview

JSON Tool is a Universal Extension for handling input data in JSON format from different sources. This tool is utilized for reading, filtering and applying light transformations on JSON data.

Version Information

Template NameExtension NameVersionStatus
JSON Toolue-json-tool1.0.0Fixes and new Features are introduced.

Refer to Changelog for version history information.

Software Requirements

This integration requires a Universal Agent and a Python runtime to execute the Universal Task.

AreaDetails
Python Version

This integration is compatible with python versions 3.7 & 3.11

Universal Agent
  • Compatible with Universal Agent for Windows x64 and version >= 7.3.0.0.

  • Compatible with Universal Agent for Linux and version >= 7.3.0.0.

Universal Controller

Universal Controller Version >= 7.3.0.0.

Key Features

FeatureDescription

Query JSON and store Result

JSON Data can be Queried and transformed using JMESPath Syntax. Input Data can be retrieved from a File, from a UAC variable, or from a text field. Results can be stored as a File, or as Extension Output.

JMESPath Examples

Some powerful JMESPath examples are seen below. For a complete User Guide of JMESPath and testing the JMESPath expressions please refer to the official site, which includes an online JMESPath validator. 

Users are advised to test their input JSON and JMESPath expressions first on the official site.

ScenarioInput JSONExpression & Result

List Projection



Code Block
titleInput
collapsetrue
{
  "people": [
    {"first": "James", "last": "d"},
    {"first": "Jacob", "last": "e"},
    {"first": "Jayden", "last": "f"},
    {"missing": "different"}
  ],
  "foo": {"bar": "baz"}
}



Code Block
titleExpression
collapsetrue
people[*].first


Code Block
titleResult
collapsetrue
[
  "James",
  "Jacob",
  "Jayden"
]


Simple Filter


Code Block
titleInput
collapsetrue
{
  "machines": [
    {"name": "a", "state": "running"},
    {"name": "b", "state": "stopped"},
    {"name": "c", "state": "running"}
  ]
}




Code Block
titleExpression
collapsetrue
machines[?state=='running'].name


Code Block
titleResult
collapsetrue
[
  "a",
  "c"
]


Function example


Code Block
titleInput
collapsetrue
{
  "people": [
    {
      "name": "b",
      "age": 30
    },
    {
      "name": "a",
      "age": 50
    },
    {
      "name": "c",
      "age": 40
    }
  ]
}



Code Block
titleExpression
collapsetrue
max_by(people, &age).name


Code Block
titleResult
collapsetrue
"a"


Using arrays, filters, pipes and defining new json elements.



Code Block
titleInput
collapsetrue
{
    "responses": [
        {
            "id": "1",
            "status": 211,
            "body": {
                "jobTitle": "IT Administrator"
            }
        },
        {
            "id": "2",
            "status": 211,
            "body": {
                "displayName": "Hiku Michael",
                "jobTitle": null
            }
        },
        {
            "id": "3",
            "status": 211,
            "body": {
                "value": [
                    {
                        "displayName":"SI_Development",
                        "description":"SI Automation"
                    },
                    {
                        "displayName":"Comp EMEA",
                        "description":"Comp EMEA"
                    },
                    {
                        "displayName": "BSS/SID",
                        "description": "BSS/SID"
                    }					
                ]
            }
        }
    ]
}



Code Block
titleExpression
collapsetrue
responses[?id == '3'].body.value[].{MyName: displayName,Mydescription: description}| [?contains(MyName, 'SI') == `true`]


Code Block
titleResult
collapsetrue
[
  {
    "MyName": "SI_Development",
    "Mydescription": "SI Automation"
  },
  {
    "MyName": "BSS/SID",
    "Mydescription": "BSS/SID"
  }
]



Joining data together on a single new element while sorting them.


Code Block
titleInput
collapsetrue
{
  "locations": [
    {"name": "Seattle", "state": "WA"},
    {"name": "New York", "state": "NY"},
    {"name": "Bellevue", "state": "WA"},
    {"name": "Olympia", "state": "WA"}
  ]
}




Code Block
titleExpression
collapsetrue
locations[?state == 'WA'].name | sort(@)| {WashingtonCities:join(', ', @)}


Code Block
titleResult
collapsetrue
{
  "WashingtonCities": "Bellevue, Olympia, Seattle"
}


Evaluating element value of null and returning Boolean value.


Code Block
titleInput
collapsetrue
{"name": null}



Code Block
titleExpression
collapsetrue
name == null


Code Block
titleResult
collapsetrue
true



Supported Actions

Action: Query JSON Data

This action allows querying JSON Data coming through a File, a UAC Variable, or from a Text Field using JMESPath query language and storing the filtered result either on Extension Output and/or a File.

Configuration examples

Image Added
Scenario A: Input is a File and Output is a JSON file & Extension Output


Image Added
Scenario B: Input is a UAC Variable and Output is a JSON file & Extension Output


Image Added

Scenario C: Input is from Text Field and Output is a JSON file & Extension Output

Action Output

Output Type

Description 

Example

EXTENSION

The extension output provides the following information:

  • “exit_code“, “status_description“: General info regarding the task execution.

  • “invocation”.“fields”: The task configuration used for this task execution.

  • “result“.filtered_json_text“: The filtered JSON output. It can be an object or a list depending on the filtering result. It is null in case the filtering result is empty.

  • “result“.“filtered_json_file“: The output file path where JSON data is stored. It is null in case the filtered JSON data is not saved to a file.
  • “result”.“errors“: List of errors that might have occurred during execution.


Expand
titleSuccessful Execution


Code Block
{
	"exit_code": 0,
    "status_description": "Task executed successfully.",
	"invocation": {
        "fields": { ... },
    },
	"result": {
         "filtered_json_text": {
             "WashingtonCities": "Bellevue, Olympia, Seattle"
         }
	     "filtered_json_file": "/home/USERS/JohnDoe/json_output.json"
      }
}



Expand
titleFailed Execution


Code Block
{
	"exit_code": 1,
    "status_description": "Data Validation Error: Invalid JMESPath expression 'wrong expression'",
	"invocation": {
        "fields": { ... },
    },
        "result": {
         "errors": [
             "Data Validation Error: Invalid JMESPath expression 'wrong expression'"
         ]
    }
}




Input Fields

NameTypeDescriptionVersion Information

Action

Choice

The action performed upon the task execution.

  • Query JSON Data

Introduced in 1.0.0

Input Source

Choice

The Input source of JSON Data. Available Options:

  • File
  • Variable
  • Text Field

Introduced in 1.0.0

Filename

Text

Full Path of the File used as input. It has to be in JSON format.

Required only if Input Source field is set to “File”. 

Introduced in 1.0.0

Variable Name

Text

A UAC Variable name. The variable needs to be accessible in the context of task execution and contains data in JSON format.

Required only if Input Source field is set to “Variable”.

Introduced in 1.0.0

Text

Large Text

A Text field that contains data in JSON format.

Required only if Input Source field is set to “Text Field”.

Introduced in 1.0.0

JMESPath Expression

Large Text

A JMESPath Expression. Users are encouraged to find information on the syntax and capabilities at the JMESPath official site which has also an online expression validator.

Introduced in 1.0.0

Data Output

Multiple Choice

Controls where the filtered JSON output is stored. Available options:

  • Extension Output
  • File

Introduced in 1.0.0

Output Filename

Text

Full Path of the File used as Output.

Required only if Data Output field is set to “File”.

Introduced in 1.0.0

Exit Codes

Exit CodeStatusStatus DescriptionMeaning
0Success

“Task executed successfully.“

Successful Execution

1Failure

“Execution Failed: <<Error Description>>”

Generic Error. Raised when not falling into the other Error Codes.

20Failure

“Data Validation Error: <<Error Description>>“

Input fields validation error.

21Failure“Expression Evaluation: The provided input JSON and JMESPath expression resulted in no match or to null value.“The provided input JSON and JMESPath expression resulted in no match or to null value.

In some use cases users might want to configure the exit code 21 as a success scenario from business point of view. This can be done by configuring the task under the “Result Processing Details” section.

Image Added

Configuring the task to retrieve status Success under Result Processing Details in case of no match found or null value.

STDOUT and STDERR

STDOUT is empty and STDERR provides additional information to the user for the task execution.

Note

The populated content can be changed in future versions without notice. Backward compatibility is not guaranteed.


How To

Import Universal Template

To use the Universal Template, you first must perform the following steps.

  1. This Universal Task requires the Resolvable Credentials feature. Check that the Resolvable Credentials Permitted system property has been set to true.

  2. To import the Universal Template into your Controller, follow these instructions.

  3. When the files have been imported successfully, refresh the Universal Templates list; the Universal Template will appear on the list.

Modifications of this integration, applied by users or customers, before or after import, might affect the supportability of this integration. For more information refer to Integration Modifications.

Configure Universal Task

For a new Universal Task, create a new task, and enter the required input fields.

Anchor
integration_modifications
integration_modifications

Integration Modifications

Modifications applied by users or customers, before or after import, might affect the supportability of this integration. The following modifications are discouraged to retain the support level as applied for this integration.

  • Python code modifications should not be done.

  • Template Modifications

    • General Section

      • "Name", "Extension", "Variable Prefix", and "Icon" should not be changed.

    • Universal Template Details Section

      • "Template Type", "Agent Type", "Send Extension Variables", and "Always Cancel on Force Finish" should not be changed.

    • Result Processing Defaults Section

      • Success and Failure Exit codes should not be changed.

      • Success and Failure Output processing should not be changed.

    • Fields Restriction Section

      The setup of the template does not impose any restrictions. However, concerning the "Exit Code Processing Fields" section.

      i. Success/Failure exit codes need to be respected.

      ii. In principle, as STDERR and STDOUT outputs can change in follow-up releases of this integration, they should not be considered as a reliable source for determining the success or failure of a task.

Users and customers are encouraged to report defects, or feature requests at Stonebranch Support Desk.

Document References

This document references the following documents:

Document LinkDescription

Universal Templates

User documentation for creating, working with and understanding Universal Templates and Integrations.

Universal Tasks

User documentation for creating Universal Tasks in the Universal Controller user interface.

JMESPath

JMESPath Official Site

Anchor
changelog
changelog

Changelog 

ue-json-tool-1.0.0 (2024-04-11)

Initial Release