Panel

Table of Contents

maxLevel	6

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 Name	Extension Name	Version	Status
JSON Tool	ue-json-tool	1.0.0	Fixes 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.

Area	Details
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

Feature	Description
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.

Scenario

Input JSON

Expression & Result

List Projection

Code Block

title	Input
collapse	true

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

Code Block

title	Expression
collapse	true

people[*].first

Code Block

title	Result
collapse	true

[
  "James",
  "Jacob",
  "Jayden"
]

Simple Filter

Code Block

title	Input
collapse	true

{
  "machines": [
    {"name": "a", "state": "running"},
    {"name": "b", "state": "stopped"},
    {"name": "c", "state": "running"}
  ]
}

Code Block

title	Expression
collapse	true

machines[?state=='running'].name

Code Block

title	Result
collapse	true

[
  "a",
  "c"
]

Function example

Code Block

title	Input
collapse	true

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

Code Block

title	Expression
collapse	true

max_by(people, &age).name

Code Block

title	Result
collapse	true

"a"

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

Code Block

title	Input
collapse	true

{
    "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

title	Expression
collapse	true

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

Code Block

title	Result
collapse	true

[
  {
    "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

title	Input
collapse	true

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

Code Block

title	Expression
collapse	true

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

Code Block

title	Result
collapse	true

{
  "WashingtonCities": "Bellevue, Olympia, Seattle"
}

Evaluating element value of null and returning Boolean value.

Code Block

title	Input
collapse	true

{"name": null}

Code Block

title	Expression
collapse	true

name == null

Code Block

title	Result
collapse	true

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

title	Successful 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

title	Failed 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

Name	Type	Description	Version 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 Code	Status	Status Description	Meaning
0	Success	“Task executed successfully.“	Successful Execution
1	Failure	“Execution Failed: <<Error Description>>”	Generic Error. Raised when not falling into the other Error Codes.
20	Failure	“Data Validation Error: <<Error Description>>“	Input fields validation error.
21	Failure	“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.

This Universal Task requires the Resolvable Credentials feature. Check that the Resolvable Credentials Permitted system property has been set to true.
To import the Universal Template into your Controller, follow these instructions.
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 Link	Description
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

Versions Compared

Old Version 1

New Version Current

Key

Disclaimer

Overview

Version Information

Software Requirements

Key Features

JMESPath Examples

Supported Actions

Action: Query JSON Data

Configuration examples

Action Output

Input Fields

Exit Codes

STDOUT and STDERR

How To

Import Universal Template

Configure Universal Task

Integration Modifications

Document References

Changelog

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

Page Comparison

Versions Compared

Old Version 1

New Version Current

Key

Disclaimer

Overview

Version Information

Software Requirements

Key Features

JMESPath Examples

Supported Actions

Action: Query JSON Data

Configuration examples

Action Output

Input Fields

Exit Codes

STDOUT and STDERR

How To

Import Universal Template

Configure Universal Task

Integration Modifications

Document References

Changelog

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