ZIS links

A ZIS link stores a relationship between two data objects. In most cases, the objects are in different systems. For example, you can link a Zendesk ticket id to a Slack message id.

A single ZIS link models a one-to-one relationship. To model a one-to-many relationship, use the same object in multiple links. For example, you can use multiple links to associate a single Zendesk user profile id with several Shopify order ids.

Built-in link actions

You can use the following built-in actions to manage links in a ZIS flow:

Creating a ZIS link

You can create a link using the CreateLink action. The action requires the following parameters:

Aleft_objectthat contains data for one object in the link
Aright_objectthat contains data for the other object in the link
Alink_typestring that describes the relationship between the objects. Several links can share the same link type.

Theleft_objectandright_objectparameters also require anameproperty. Thenameproperty contains the data you want to link. Along with the link type, the left object name and right object name uniquely identify a link.

The following state uses a CreateLink action to link a Zendesk ticket id to a Slack message id.

             
              "TicketToMessage.CreateLink":{"Type":"Action","ActionName":"zis:common:action:CreateLink","Parameters":{"link_type":"ticket_to_message_link","left_object":{"name.$":"$.input.ticket_event.ticket.id"},"right_object":{"name.$":"$.post_message_response.message.ts"}},"Next":"NextState"}

The action creates a link in the ZIS Links Service. The action scopes the link to the ZIS flow's Zendesk account and integration. Example response:

             
              {"link":{"account_id":12345678,"integration":"INTEGRATION_NAME","left_object":{"name":"1234567"},"link_type":"ticket_to_message_link","right_object":{"name":"1234567890.123456"},"uuid":"f5a31f96-880f-bede-ddfc-8c9500da090e"}}

Name attributes

Thenameproperty supports key-value pairs called name attributes. You can use name attributes to include several pieces of data in an object's name. Name attributes also let you label the data in a name.

名称属性需要特殊的语法。对separate an attribute's key and its value, use:. To include multiple name attributes in anamevalue, use the/separator. Example:

             
              "TicketToMessage.CreateLink":{"Type":"Action","ActionName":"zis:common:action:CreateLink","Parameters":{"link_type":"ticket_to_message_link","left_object":{"name.$":"ticket_id:{{$.input.ticket_event.ticket.id}}"},"right_object":{"name.$":"channel:{{$.send_message_response.message.channel}}/thread_ts:{{$.send_message_response.message.ts}}"}},"Next":"NextState"}

The response includes name attributes in the object'sname_attrsproperty.

             
              {"link":{"account_id":12345678,"integration":"INTEGRATION_NAME","left_object":{"name":"ticket_id:1234567","name_attrs":{"ticket_id":1234567}},"link_type":"ticket_to_message_link","right_object":{"name":"channel:zendesk-tickets/thread_ts:1234567890.123456","name_attrs":{"channel":"zendesk-tickets","thread_ts":1234567890.123456}},"uuid":"f5a31f96-880f-bede-ddfc-8c9500da090e"}}

Metadata

Each object also supports an optionalmetadataproperty. You can use the property to store arbitrary data for an object.

             
              "TicketToMessage.CreateLink":{"Type":"Action","ActionName":"zis:common:action:CreateLink","Parameters":{"link_type":"ticket_to_message_link","left_object":{"name.$":"ticket_id:{{$.input.ticket_event.ticket.id}}"},"right_object":{"name.$":"channel:{{$.send_message_response.message.channel}}/thread_ts:{{$.send_message_response.message.ts}}","metadata":{"team_name.$":"$.get_team_info_response.team.name"}}},"Next":"NextState"}

The response includes ametadataproperty for the object.

             
              {"link":{"account_id":12345678,"integration":"INTEGRATION_NAME","left_object":{"name":"ticket_id:1234567","name_attrs":{"ticket_id":1234567}},"link_type":"ticket_to_message_link","right_object":{"metadata":{"team_name":"My Corp"},"name":"channel:zendesk-tickets/thread_ts:1234567890.123456","name_attrs":{"channel":"zendesk-tickets","thread_ts":1234567890.123456}},"uuid":"f5a31f96-880f-bede-ddfc-8c9500da090e"}}

Loading ZIS links

You can use the LoadLinks action to look up existing links. The action matches links based on the following parameters:

link_type
left_object_name
OR
right_object_name
OR
left_object_nameandright_object_name

Note:You can't match links based on an object's metadata.

To use the action's response in later states of the ZIS flow, specify aResultPath.

             
              "TicketToMessage.LoadLinks":{"Type":"Action","ActionName":"zis:common:action:LoadLinks","Parameters":{"link_type":"ticket_to_message_link","left_object_name.$":"ticket_id:{{$.input.ticket_event.ticket.id}}"},"ResultPath":"$.link_results","Next":"NextState"}

The response contains an array of matching links and their count.

             
              {"count":1,"links":[{"account_id":12345678,"integration":"INTEGRATION_NAME","left_object":{"name":"ticket_id:1234567","name_attrs":{"ticket_id":1234567}},"link_type":"ticket_to_message_link","right_object":{"metadata":{"team_name":"My Corp"},"name":"channel:zendesk-tickets/thread_ts:1234567890.123456","name_attrs":{"channel":"zendesk-tickets","thread_ts":1234567890.123456}},"uuid":"f5a31f96-880f-bede-ddfc-8c9500da090e"}]}

后来子流的状态可以访问响应se from theResultPath. For example, the following state references a name attribute in the links array.

             
              "ThreadMessageOnTicketUpdate":{"Type":"Action","ActionName":"zis:INTEGRATION_NAME:action:PostToSlack","Parameters":{"thread_ts.$":"$.link_results.links[0].right_object.name_attrs.thread_ts","text.$":"$.input.ticket_event.comment.body"},"Next":"NextState"}

Wildcard matching

In a LoadLinks action, theleft_object_nameandright_object_nameparameters support values with a trailing wildcard (*). You can use a trailing wildcard to match an object name based on a prefix.

Note:The wildcard must be the last character in the value. A value of only "*" is not supported.

For example, the following state uses a LoadLinks action with a trailing wildcard in theleft_object_nameparameter. The action matches links with a left object name that begins with "ticket_id:".

             
              "TicketToMessage.LoadLinks":{"Type":"Action","ActionName":"zis:common:action:LoadLinks","Parameters":{"link_type":"ticket_to_message_link","left_object_name":"ticket_id:*"},"ResultPath":"$.link_results","Next":"NextState"}

No matching links

If the LoadLinks action finds no matching links, the response returns a count of "0" and an empty links array.

             
              {"count":0,"links":[]}

You can use the count to determine if a link already exists. For example, the followingChoice stateadds branching logic based on a link count.

             
              "TicketToMessage.LinkChoice":{"Type":"Choice","Choices":[{"Variable":"$.link_results.count","NumericEquals":0,"Next":"SendMessageOnTicketCreate"},{"Variable":"$.link_results.count","NumericEquals":1,"Next":"ThreadMessageOnTicketUpdate"}],"Default":"MultipleLinksError"}

Updating a ZIS link

You can use the PatchLink action to make partial updates to objects in a link.

The action requires the link's currentlink_type,left_object_name, andright_object_name. The action also requires a newright_object,left_object, or both. Any new objects must include anameproperty. The action only changes the objects and properties you specify.

Note: You can't use the PatchLink action to change thelink_type.

For example, the following state uses the PatchLink action to update thenameandmetadata.org_email_domainof a link's right object. The action doesn't change the left object or other metadata of the right object.

             
              "TicketToMessage.PatchLink":{"Type":"Action","ActionName":"zis:common:action:PatchLink","Parameters":{"link_type":"ticket_to_message_link","left_object_name.$":"ticket_id:{{$.input.ticket_event.ticket.id}}","right_object_name.$":"channel:{{$.send_message_response.message.channel}}/thread_ts:{{$.send_message_response.message.ts}}","right_object":{"name.$":"channel:{{$.send_message_response.message.channel}}/thread_ts:{{$.send_message_response.message.ts}}","metadata":{"org_email_domain.$":"$.get_team_info_response.team.email_domain"}}},"Next":"NextState"}

Deleting a ZIS link

You can use the DeleteLink action to delete a link. The action requires the link'slink_type,left_object_name, andright_object_name.

             
              "TicketToMessage.DeleteLink":{"Type":"Action","ActionName":"zis:common:action:DeleteLink","Parameters":{"link_type":"ticket_to_message_link","left_object_name.$":"ticket_id:{{$.input.ticket_event.ticket.id}}","right_object_name.$":"channel:{{$.send_message_response.message.channel}}/thread_ts:{{$.send_message_response.message.ts}}"},"Next":"NextState"}

Rate limits

The built-in link actions make requests to theZIS Links API. These requests are subject toAPI rate limits.

Best practices

Don't store secrets in ZIS links. Links aren't encrypted and are accessible using the ZIS Links API. Depending on your integration, data in a ZIS link may be accessible in connected systems.

Getting Started

Integration design guidelines

Developer Guide

Zendesk Integration Services examples

Zendesk Integration Services tutorials