JSON JQ Transform
The JSON JQ Transform task allows the processing of JSON data using jq.
A JSON JQ Transform task evaluates a queryExpression
using jq syntax to transform JSON data provided as input parameters. The task processes the data based on the specified query, and the output is a transformed JSON object or array.
Task parameters
Configure these parameters for the JSON JQ Transform task.
Parameter | Description | Required/Optional |
---|---|---|
inputParameters | JSON object containing the configuration data for task execution. Supports string, number, boolean, null, and object/array. | Required. |
inputParameters.queryExpression | A string representing a JQ (JSON Query) expression. This expression is used to transform the JSON data. | Required. |
Task configuration
This is the task configuration for a JSON JQ Transform task.
{
"name": "json_transform",
"taskReferenceName": "json_transform_ref",
"type": "JSON_JQ_TRANSFORM",
"inputParameters": {
"persons": [
{
"name": "some",
"last": "name",
"email": "mail@mail.com",
"id": 1
},
{
"name": "some2",
"last": "name2",
"email": "mail2@mail.com",
"id": 2
}
],
"queryExpression": ".persons | map({user:{email,id}})"
}
}
Task output
The JSON JQ Transform task will return the following parameters.
Parameter | Description |
---|---|
resultList | List of results returned by the JQ expression. |
result | The first element of the resultList. |
error | Optional error message if the JQ query fails. |
Adding a JSON JQ Transform task in UI
To add a JSON JQ Transform task:
- In your workflow, select the (+) icon and add a JSON JQ Transform task.
- In Script params, add the parameter that the JQ expression will evaluate.
- In JQ expression, enter the expression to be evaluated.
Examples
Here are some examples for using the JSON JQ Transform task.
Using JSON JQ Transform task in a workflow
Consider the following sample workflow to demonstrate the JSON JQ Transform task. This example illustrates how to concatenate two arrays using a JQ expression.
The workflow definition for this example is as follows:
// workflow definition
{
"name": "jq_example_task",
"taskReferenceName": "my_jq_example_task_ref",
"type": "JSON_JQ_TRANSFORM",
"inputParameters": {
"key1": {
"value1": [
"a",
"b"
]
},
"key2": {
"value2": [
"c",
"d"
]
},
"queryExpression": "{ key3: (.key1.value1 + .key2.value2) }"
}
}
The input parameters for the task include:
- key1/value1—An object key1 containing an array value1 with elements ["a", "b"].
- key2/value2—An object key2 containing an array value2 with elements ["c", "d"].
The queryExpression key holds a JQ expression that operates on these parameters:
{ key3: (.key1.value1 + .key2.value2) }—This expression concatenates the arrays value1 and value2 into a single array under key3.
On running the workflow, the task output is generated as follows:
{
"result": {
"key3": [
"a",
"b",
"c",
"d"
]
},
"resultList": [
{
"key3": [
"a",
"b",
"c",
"d"
]
}
]
}
- result—Contains the result of queryExpression, where key3 holds the concatenated array ["a", "b", "c", "d"].
- resultList—Stores all results generated by the queryExpression, which in this case is a single entry similar to result.
Cleaning up a JSON response
This example demonstrates how to filter and format data from an API response using a JSON JQ Transform task. The goal is to retrieve a list of "stargazers" (users who have starred a repository) from GitHub and simplify the output to include only the relevant information: starred_at and login parameters for users who starred the repository after a specified date.
In this example, an HTTP task initiates an API call to GitHub to retrieve a list of stargazers. The API response snippet (for a single user) is as follows:
[
{
"starred_at": "2016-12-14T19:55:46Z",
"user": {
"login": "lzehrung",
"id": 924226,
"node_id": "MDQ6VXNlcjkyNDIyNg==",
"avatar_url": "https://avatars.githubusercontent.com/u/924226?v=4",
"gravatar_id": "",
"url": "https://api.github.com/users/lzehrung",
"html_url": "https://github.com/lzehrung",
"followers_url": "https://api.github.com/users/lzehrung/followers",
"following_url": "https://api.github.com/users/lzehrung/following{/other_user}",
"gists_url": "https://api.github.com/users/lzehrung/gists{/gist_id}",
"starred_url": "https://api.github.com/users/lzehrung/starred{/owner}{/repo}",
"subscriptions_url": "https://api.github.com/users/lzehrung/subscriptions",
"organizations_url": "https://api.github.com/users/lzehrung/orgs",
"repos_url": "https://api.github.com/users/lzehrung/repos",
"events_url": "https://api.github.com/users/lzehrung/events{/privacy}",
"received_events_url": "https://api.github.com/users/lzehrung/received_events",
"type": "User",
"site_admin": false
}
}
]
Assuming the task reference for the HTTP task is hundred_stargazers_ref, the task configuration filters this data to focus only on the starred_at and login parameters for users who starred the repository after a specified date. This date is passed as a workflow input parameter ${workflow.input.cutoff_date}
.
Using JSON JQ transform task to transform this data:
{
"name": "jq_cleanup_stars",
"taskReferenceName": "jq_cleanup_stars_ref",
"inputParameters": {
"starlist": "${hundred_stargazers_ref.output.response.body}",
"queryExpression": "[.starlist[] | select (.starred_at > \"${workflow.input.cutoff_date}\") |{occurred_at:.starred_at, member: {github: .user.login}}]"
},
"type": "JSON_JQ_TRANSFORM"
}
The input contains the following parameters:
- starlist—Contains the JSON data retrieved from the GitHub API, which is the response body obtained from the HTTP task.
- queryExpression—Uses JQ syntax to filter and format the data:
- select(.starred_at > "${workflow.input.cutoff_date}")—Filters entries where starred_at is after ${workflow.input.cutoff_date}.
- { occurred_at: .starred_at, member: { github: .user.login } }—Constructs a JSON object with occurred_at set to the starred_at value and member containing GitHub login from user.
- queryExpression—Uses JQ syntax to filter and format the data:
- The entire queryExpression is enclosed in [] to denote that it's intended to produce an array of JSON objects. Each object corresponds to a user who meets the specified criteria (starred_at after
${workflow.input.cutoff_date}
.)
Output JSON
The queryExpression filters the JSON data, selecting entries where starred_at meets the specified date criteria, and formats the output JSON as follows:
{
"occurred_at": "date from JSON",
"member": {
"github": "github Login from JSON"
}
}
This output provides a simplified view of the stargazers who starred the repository after the specified cutoff date.