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	Input Expand source { "people": [ {"first": "James", "last": "d"}, {"first": "Jacob", "last": "e"}, {"first": "Jayden", "last": "f"}, {"missing": "different"} ], "foo": {"bar": "baz"} }	Expression Expand source people[].first Result* Expand source [ "James", "Jacob", "Jayden" ]
Simple Filter	Input Expand source { "machines": [ {"name": "a", "state": "running"}, {"name": "b", "state": "stopped"}, {"name": "c", "state": "running"} ] }	Expression Expand source machines[?state=='running'].name Result Expand source [ "a", "c" ]
Function example	Input Expand source { "people": [ { "name": "b", "age": 30 }, { "name": "a", "age": 50 }, { "name": "c", "age": 40 } ] }	Expression Expand source max_by(people, &age).name Result Expand source "a"
Using arrays, filters, pipes and defining new json elements.	Input Expand source { "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 Expand source responses[?id == '3'].body.value[].{MyName: displayName,Mydescription: description}\| [?contains(MyName, 'SI') == `true`] Result Expand source [ { "MyName": "SI_Development", "Mydescription": "SI Automation" }, { "MyName": "BSS/SID", "Mydescription": "BSS/SID" } ]
Joining data together on a single new element while sorting them.	Input Expand source { "locations": [ {"name": "Seattle", "state": "WA"}, {"name": "New York", "state": "NY"}, {"name": "Bellevue", "state": "WA"}, {"name": "Olympia", "state": "WA"} ] }	Expression Expand source locations[?state == 'WA'].name \| sort(@)\| {WashingtonCities:join(', ', @)} Result Expand source { "WashingtonCities": "Bellevue, Olympia, Seattle" }
Evaluating element value of null and returning Boolean value.	Input Expand source {"name": null}	Expression Expand source name == null Result Expand source 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

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.

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

Failed Execution

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

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.

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.

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

Changelog

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

Initial Release