jq cheat sheet

The Transform action uses a jq expression to change JSON data within a ZIS flow. You specify this expression in the action's expr parameter.

This article provides example jq expressions you can use in the expr parameter. If you're new to jq, you can use these examples as a starting point when writing your own expressions. You can test the expressions using the jq play site or the jq command-line tool. The article also covers limitations for jq in ZIS.

Important: The expr parameter requires a valid JSON string value. Before using a jq expression in the expr parameter, escape any JSON special characters with a leading backslash (\). For example, use \" to escape double quotes.

Disclaimer: Zendesk provides this article for instructional purposes only. Zendesk does not support or guarantee the jq expressions in this article. For complete jq documentation, refer to the jq manual.

Getting an object property

A jq expression consists one or more filters. Use an object identifier-index filter to get properties from a JSON object. The following expression extracts a ticket id from a nested ticket object.

jq expression:

.ticket_event.ticket.id

Input:

{
  "ticket_event": {
    "ticket": {
      "id": 27642,
      "subject": ["enterprise", "production"]
    }
  }
}

Result:

27642

Getting an array element

Use an array index filter to get elements from a JSON array. The following expression extracts the first element from the follower_ids array.

jq expression:

.ticket_event.ticket.follower_ids[0]

Input:

{
  "ticket_event": {
    "ticket": {
      "follower_ids": [35334, 234, 123456]
    }
  }
}

Result:

35334

Getting an array element's object property

Combine the array index and object identifier-index filters to get a property from an array of objects. The following expression gets the id of the second object in the custom_fields array.

jq expression:

.ticket_event.ticket.custom_fields[1].id

Input:

{
  "ticket_event": {
    "ticket": {
      "custom_fields": [
        {
          "id": 12345,
          "value": "745"
        },
        {
          "id": 27648,
          "value": "yes"
        }
      ]
    }
  }
}

Result:

27648

Creating an object

To create a JSON object, wrap the output in curly brackets ({}). This is useful if your integration only uses a few properties from a larger object.

The following expression extracts the user id and shop level to output a new shop_level object.

Important: Double quotes (") are a JSON special character. Before using this expression in the expr parameter, escape any double quotes with a leading backslash (\").

jq expression:

{ "shop_level": .shop.level, "user_id": .user.id }

Input:

{
  "shop": {
    "level": "platinum"
  },
  "user": {
    "id": 12345
  }
}

Result:

{
  "shop_level": "platinum",
  "user_id": 12345
}

Creating an array

To create an array, wrap the output in square brackets ([]). The following expression combines the collaborator_ids and submitter_id properties into a single array.

jq expression:

[ .ticket.collaborator_ids[], .ticket.submitter_id ]

Input:

{
  "ticket": {
    "collaborator_ids": [35334, 234],
    "submitter_id": 76872
  }
}

Result:

[35334, 234, 76872]

Checking an array for a specific element

Use the index filter to get the index of the first occurrence of an element in an array. If the element doesn't exist in the array, the filter returns a null value. You can then use the any filter to cast the index as a boolean value.

The following expression checks the ticket.tags array for the "enterprise" tag. If the array contains the tag, the expression returns true. Otherwise, the expression returns false.

jq expression:

.ticket.tags | any(index("enterprise"))

Input:

{
  "ticket": {
    "tags": ["enterprise", "production"]
  }
}

Result:

true

Comparing a flat array to an array of objects

Combine the select and index filters to compare a flat array to an array of objects. The following expression returns users objects that have an id in the follower_ids list.

jq expression:

[ .ticket.follower_ids as $id_list | .users[] | select( .id as $id | $id_list | index($id) )]

Input:

{
  "ticket": {
    "follower_ids": [389861386794, 389867211733]
  },
  "users": [
    {
      "id": 7123854387,
      "name": "John Doe",
      "role": "admin"
    },
    {
      "id": 389861386794,
      "name": "Jane Roe",
      "role": "agent"
    },
    {
      "id": 389867211733,
      "name": "Mary Major",
      "role": "agent"
    }
  ]
}

Result:

[
  {
    "id": 389861386794,
    "name": "Jane Roe",
    "role": "agent"
  },
  {
    "id": 389867211733,
    "name": "Mary Major",
    "role": "agent"
  }
]

Converting a number to a string

Use the tostring filter to convert a non-string value to a string. The following expression changes the ticket id value to a string.

Tip: For an example action using this filter, refer to ZIS action: Converting a number to a string.

jq expression:

.ticket.id | tostring

Input:

{
  "ticket": {
    "id": 35436
  }
}

Result:

"35436"

Converting a flat array into an array of objects

The following expression adds a static property to a list of ids and returns the output as an array of objects.

jq expression:

[ .ids[] | { "action": "delete", "id": . }]

Input:

{
  "ids": [1, 2, 3]
}

Result:

[
  {
    "action": "delete",
    "id": 1
  },
  {
    "action": "delete",
    "id": 2
  },
  {
    "action": "delete",
    "id": 3
  }
]

Converting an array of objects into a flat object

The following expression converts an array of objects into a flat object. The new object uses the id value as a key for the previous object's value property.

jq expression:

[ .ticket.custom_fields[] | { (.id|tostring): .value }]

Input:

{
  "ticket": {
    "custom_fields": [
      {
        "id": 4413535756049,
        "value": 123
      },
      {
        "id": 4413550635025,
        "value": 456
      },
      {
        "id": 4413558696721,
        "value": null
      },
      {
        "id": 4413643104785,
        "value": null
      }
    ]
  }
}

Result:

{
  "4413535756049": 123,
  "4413550635025": 456,
  "4413558696721": null,
  "4413643104785": null
}

Encoding a string as a URI

Use the @uri filter to encode a string as a URI.

jq expression:

.username | @uri

Input:

{
  "username": "john+doe"
}

Result:

"john%2Bdoe"

Extracting a pattern from a string

Use the match filter to extract a pattern from a string using a regular expression (regex). For supported regex syntax, refer to the re2 documentation. The following expression extracts the first matching email address from a ticket description.

Important: Escape any JSON special characters in the regex pattern.

jq expression:

.ticket.description | match("([a-zA-Z0-9+._-]+@[a-zA-Z0-9._-]+.[a-zA-Z0-9_-]+)"; "i") | .string

Input:

{
  "ticket": {
    "description": "My email address is [email protected]."
  }
}

Result:

"[email protected]"

Extracting numbers from a string

The following expression uses the match filter to extract the first set of numbers from a string.

Important: Escape any JSON special characters in the regex pattern.

jq expression:

.ticket.subject | match("\\d+") | .string

Input:

{
  "ticket": {
    "subject": "Printer 12345 is on fire!"
  }
}

Result:

"12345"

Getting the current date

jq supports several date-related functions. The now function gets the current time in seconds since the Unix epoch. You can use the strftime function to format this timestamp. The following expression outputs the current date in a YYYY-MM-DD format.

Tip: For an example action using these functions, refer to ZIS action: Getting the current date.

jq expression:

now | strftime("%Y-%m-%d")

Input:

{}

Result:

"2099-05-06"

Getting the difference between two arrays

Use the subtraction (-) operator to remove an array's elements from another array. The following expression returns elements from the email_cc_ids array that aren't in the user_ids array.

jq expression:

.email_cc_ids - .user_ids

Input:

{
  "email_cc_ids": [1, 2, 3, 7],
  "user_ids": [1, 3, 4, 5]
}

Result:

[2, 7]

Getting the intersection of two arrays

Use the subtraction operator and a parenthesis grouping to find the intersection of two arrays. The following expression returns elements that are in both the email_cc_ids and user_ids arrays.

jq expression:

.email_cc_ids - (.email_cc_ids - .user_ids)

Input:

{
  "email_cc_ids": [1, 2, 3, 7],
  "user_ids": [1, 3, 4, 5]
}

Result:

[1, 3]

Replacing substrings in a string

Use the sub filter to replace substrings using regex. The following expression replaces "john" with "richard".

Important: Escape any JSON special characters in the regex pattern.

jq expression:

.email | sub("john";"richard";"i")

Input:

{
  "email": "[email protected]"
}

Result:

"[email protected]"

Replacing a missing or null property

The following expression uses an if-then-else conditional. The conditional checks whether objects in the "user" array contain an "alias" property. If the "alias" key is missing or the "alias" value is null, the expression sets the object's "alias" as an empty string.

jq expression:

.users[] | if (.alias) then . else . + {"alias": ""} end

Input:

{
  "users": [
    {
      "name": "Joseph Doe",
      "alias": "Joe"
    },
    {
      "name": "Jane Doe",
      "alias": null
    },
    {
      "name": "John Doe"
    }
  ]
}

Result:

{
  "name": "Joseph Doe",
  "alias": "Joe"
}
{
  "name": "Jane Doe",
  "alias": ""
}
{
  "name": "John Doe",
  "alias": ""
}

Limitations

The Transform action doesn't support the following jq features:

• Environment variables, such as $ENV or env
• Modules
• Streaming