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:

1. In your workflow, select the (+) icon and add a JSON JQ Transform task.
2. In Script params, add the parameter that the JQ expression will evaluate.
3. 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.
• 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.