Documentation API Reference

jq cheat sheet

TheTransformaction uses ajqexpression to change JSON data within a ZIS flow. You specify this expression in the action'sexprparameter.

This article provides example jq expressions you can use in theexprparameter. 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 thejq playsite or thejq command-line tool. The article also covers limitations for jq in ZIS.

Important:Theexprparameter requires a valid JSON string value. Before using a jq expression in theexprparameter, 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 thejq manual.

Getting an object property

A jq expression consists one or more filters. Use anobject identifier-indexfilter 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 anarray indexfilter to get elements from a JSON array. The following expression extracts the first element from thefollower_idsarray.

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 theidof the second object in thecustom_fieldsarray.

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.

以下expression extracts the user id and shop level to output a newshop_levelobject.

Important:Double quotes (") are a JSON special character. Before using this expression in theexprparameter, 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 thecollaborator_idsandsubmitter_id属性到一个数组中。

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 theindex filterto 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 theanyfilter to cast the index as a boolean value.

以下expression checks theticket.tagsarray 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 theselectand index filters to compare a flat array to an array of objects. The following expression returnsusersobjects that have anidin thefollower_idslist.

jq expression:

             

              
[.ticket.follower_idsas$id_list|.users[]|select(.idas$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 thetostringfilter 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 toZIS 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

以下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

以下expression converts an array of objects into a flat object. The new object uses theidvalue as a key for the previous object'svalueproperty.

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@urifilter 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 thematchfilter to extract a pattern from a string using a regular expression (regex). For supported regex syntax, refer to there2 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+._-][email protected][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

以下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 severaldate-related functions. Thenowfunction gets the current time in seconds since the Unix epoch. You can use thestrftime这个时间戳函数格式。以下expression outputs the current date in a YYYY-MM-DD format.

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

jq expression:

             

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

Input:

             

              
{}

Result:

             

              
"2099-05-06"

Getting the difference between two arrays

Use thesubtraction (-) operatorto remove an array's elements from another array. The following expression returns elements from theemail_cc_idsarray that aren't in theuser_idsarray.

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 aparenthesis groupingto find the intersection of two arrays. The following expression returns elements that are in both theemail_cc_idsanduser_idsarrays.

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 thesubfilter 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

以下expression uses anif-then-elseconditional. 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: