/
JSON Tool

JSON Tool

Jan 15, 2026

 

Disclaimer

Your use of this download is governed by Stonebranch’s Terms of Use.

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

Template Name

Extension Name

Version

Status

JSON Tool

ue-json-tool

2 (Current 2.0.0)

Fixes and new Features are introduced. Compatibility starts from UAC/UAG 7.6.0.0 onwards.

Version 2.0.0 is a major release introduces breaking changes that might affect some customers depending on their setup. Administrators are strongly advised to refer to Changelog for more information on the changes introduced in this release.

 

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

Area

Details

Python Version

This integration is compatible with Python version 3.11.

Universal Agent

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

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

Universal Controller

Universal Controller Version >= 7.6.0.0.

Key Features

Feature

Description

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

Scenario

Input JSON

Expression & Result

List Projection

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

Simple Filter

Input
{ "machines": [ {"name": "a", "state": "running"}, {"name": "b", "state": "stopped"}, {"name": "c", "state": "running"} ] }
Expression
machines[?state=='running'].name
Result
[ "a", "c" ]

Function example

Input
{ "people": [ { "name": "b", "age": 30 }, { "name": "a", "age": 50 }, { "name": "c", "age": 40 } ] }
Expression
max_by(people, &age).name
Result
"a"

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

Input
{ "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" } ] } } ] }
Expression
responses[?id == '3'].body.value[].{MyName: displayName,Mydescription: description}| [?contains(MyName, 'SI') == `true`]
Result
[ { "MyName": "SI_Development", "Mydescription": "SI Automation" }, { "MyName": "BSS/SID", "Mydescription": "BSS/SID" } ]

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

Input
{ "locations": [ {"name": "Seattle", "state": "WA"}, {"name": "New York", "state": "NY"}, {"name": "Bellevue", "state": "WA"}, {"name": "Olympia", "state": "WA"} ] }
Expression
locations[?state == 'WA'].name | sort(@)| {WashingtonCities:join(', ', @)}
Result
{ "WashingtonCities": "Bellevue, Olympia, Seattle" }

Evaluating element value of null and returning Boolean value.

Input
{"name": null}
Expression
name == null
Result
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

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

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

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

Action Output

Output Type

Description 

Example

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.

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

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

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.

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.

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.

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

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

Changelog 

ue-json-tool-2.0.0 (2026-01-15)

Deprecations and Breaking Changes

  • Breaking Change: Dropping support for Agents with version <= 7.5 and for Python 3.7.

Enhancements

  • Added: Improving Python compatibility with future Agent versions.

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

Initial Release