The Zendesk meshlet supports the following configuration directives listed below in additional to the general configurations supported by all ServiceBond meshlets For questions, contact Perspectium Support.


(info) NOTE: Default values refer to the configuration's value if the configuration is not specified in the meshlet configuration file.

DirectiveDefault ValueRequiredDescription

perspectium:

    meshlet:

          scheduler:

              pollingInterval: 180000

180000Yes

The time for the meshlet to wait in between polling for changes in Zendesk. This value is in milliseconds i.e. 180000 = 180 seconds (3 minutes).

(info) NOTE: For the search queryMethod (see below), this value will need to be 180000 (180 seconds) at a minimum since it can take up to a few minutes for new resources (i.e. new tickets created) to be indexed and available through the Search API.

perspectium:
    meshlet:
          scheduler:
              pollingInterval: 180000

apiTokenAuth

false

No

Indicates whether you want to authenticate your Zendesk connection with an API token instead of basic authentication. 

perspectium:
	zendesk: 
		apiTokenAuth: true
urlBase
Yes

The base portion of the Zendesk API URL. Since Zendesk includes the resources being interacted with as part of the URL (i.e. https://subdomain.zendesk.com/api/v2/tickets.json, https://subdomain.zendesk.com/api/v2/users.json, etc.), we separate the URL so we can easily add the different resources below.

perspectium:
	zendesk: 
		urlBase: https://subdomain.zendesk.com/api/v2/
urlSuffix
Yes

The ending (suffix) for the Zendesk API URL. Usually this is .json for API URLs such as https://subdomain.zendesk.com/api/v2/tickets.json

perspectium:
	zendesk: 
		urlSuffix: .json
urlResources
Yes

The resources being interacted with through the API. Each resource should be listed out with a and contain the following properties:

PropertyDescription
nameName of the resource i.e. ticket
urlURL of the resource i.e. tickets.json
parameters

(Optional) Any URL parameters for this resource such as ?filename=%s

In the case of attachments, %s is recognized as the filename. 

perspectium:
	zendesk:    
        urlResources:
              -  name: ticket
                 url: tickets
              -  name: attachment
                 url: uploads
                 parameters: ?filename=%s
defaultCreateDescription

New ticket from integration

No

Since Zendesk requires a description to be the first comment added, a default description to use if no description is specified when the meshlet receives a message from the other ITSM app like ServiceNow.

This ensures the ticket is created successfully since it uses the default description as specified here if no description was specified in the incident coming from the other ITSM app.

perspectium:
	zendesk:    
        defaultCreateDescription: New ticket from integration

(info) NOTE: If the other ITSM app being integrated supports entering both a comment and a description when the ticket is created (such as ServiceNow), you will need to map it properly in the Common Incident so both can appear in Zendesk as one comment on ticket creation. Contact Perspectium Support for more information.

defaultAttachmentComment

Attachment added to ticket

No

Zendesk requires attachments be added as part of a comment to the ticket. By default, the attachment is added with a comment Attachment added to ticket but you can use your own comment for when attachments are added into Zendesk by setting this configuration.

perspectium:
	zendesk:    
        defaultAttachmentComment: Attachment added to ticket
defaultCorrelateResponse
No

For when you configure ServiceNow to send back a .correlate message to Zendesk, this message can appear as a comment on the Zendesk ticket so those looking at the ticket in Zendesk will know the ticket was created in ServiceNow.

perspectium:
	zendesk:    
        defaultCorrelateResponse: Ticket created successfully in ServiceNow
correlationFieldId
Yes

The Zendesk Field ID of the Correlation ID custom field in Zendesk that holds the unique identifier in the other ITSM app being integrated with Zendesk i.e. the sys_id in ServiceNow. This field should be created as detailed here.

perspectium:
	zendesk:    
         correlationFieldId: 7655609750043
correlationDisplayFieldId
No

The Zendesk Field ID of the Correlation Display custom field in Zendesk that holds the customer-facing identifier in the other ITSM app being integrated with Zendesk i.e. the number in ServiceNow. This field should be created as detailed here.

perspectium:
	zendesk:    
         correlationFieldId: 7655609750043
userId
Yes

The Zendesk ID for the user entered in perspectium.auth.username. This field will be used to check for any updates in Zendesk made by this user ID so they can be skipped to avoid looping updates back and forth between Zendesk and other ITSM app being integrated.

perspectium:
	zendesk:    
          userId: 7603423341591
historicalCommentstrueNo

For when a ticket in Zendesk triggers being integrated and whether or not we should get all the comments previously entered prior to the ticket triggering the integration.

If true, all comments will be sent.

If false, comments entered prior to the integration being triggered will not be sent.

perspectium:
	zendesk:    
          historicalComments: true
notifyZendeskErrorfalseNo
To enabling creating a new ticket in Zendesk when there is an error with Perspectium. This is useful when you want to trigger a notification in Zendesk for Perspectium errors. See notifications in Zendesk for more information.
perspectium:
	zendesk:    
          notifyZendeskError: true
defaultErrorMessagePerspectium ErrorNo

Related to the notifyZendeskError configuration, the error message to display when creating a new ticket in Zendesk due to an error with Perspectium to trigger a notification. See notifications in Zendesk for more information.

perspectium:
	zendesk:    
          defaultErrorMessage: Perspectium Error
ticketSleepTimer60000No

The time for the meshlet to wait ("sleep") before trying any new requests if it it reaches the results or rate limits to ensure the meshlet is not locked out of accessing the API. This value is in milliseconds i.e. 60000 = 60 seconds.

perspectium:
	zendesk:    
          ticketSleepTimer: 60000
queryMethod
Yes

The method to query for changes in Zendesk for sharing out to the other ITSM app being integrated. Options are either search or cursor.

If the method is search, the API will use the Search API to query for changes. Records will be queried based on any changes greater than the last query time along with any filter conditions specified in the query configuration below. The first time the meshlet runs, it will query for all changes since the meshlet first started. If you want to get all tickets, use either the cursor method or set the query string to have an older date.

perspectium:
	zendesk:    
          queryMethod: search

If the method is cursor, each time records are queried, the API leaves a cursor where it last retrieved records from. On the next query, it will get all records since this last cursor. See cursor export for more information.

(info) NOTE: This method does not support filtering and will return all tickets modified since the last cursor.

perspectium:
	zendesk:    
          queryMethod: cursor

(info) NOTE: If you switch the query method from one approach to another (i.e. switch it from search to cursor), you will need to delete the lastQueryTime.dat file in the data folder where the meshlet is installed.

query
Yes, if queryMethod is search

This configuration only works if the queryMethod configuration is search. This allows you to specify query conditions for records that should be shared from Zendesk. Valid formats for query conditions can be found as detailed at Search API and Support search reference.

perspectium:
	zendesk:    
          query: priority>low

If you include the updated or created condition in your query string, this will override the default check of looking for tickets that meet your condition(s) and were last updated since the last time the meshlet queried for changes. You can use the syntax as described in the Search API and Support search reference (spaces or +) for having multiple conditions together.

For example, this query will find tickets updated since July 1, 2022 that have the dog tag:

perspectium:
	zendesk:    
          query: updated>=2022-07-01 tags:dog
startOffset360000NoThis configuration only works if the queryMethod configuration is search. This value is in milliseconds i.e. 360000 = 360 seconds (6 minutes). If this configuration is not specified, the default value is 360000 (360 seconds = 6 minutes).

Since it can take up to a few minutes for new resources (i.e. new tickets created) to be indexed and available through the Search API, this offset is used to control the time range from when the meshlet queries looking for changes in Zendesk. Since the pollingInterval controls how often the meshlet queries for changes in Zendesk, the startOffset along with the endOffset control the range of time the meshlet should look for changes.

For example, with the default values of startOffset 360000 and endOffset 180000, every time the meshlet queries for changes it will look for records updated between 6 minutes ago and 3 minutes ago. This ensures we capture all changes, giving time for changes to be indexed and available through the Search API and ensuring we don't capture any duplicate changes.

endOffset180000No

This configuration only works if the queryMethod configuration is search. This value is in milliseconds i.e. 180000 = 180 seconds (3 minutes). If this configuration is not specified, the default value is 180000 (180 seconds = 3 minutes).

See the startOffset configuration above for further details on this configuration.

startTime(blank)No

This configuration only works if the queryMethod configuration is cursor. The start time when the meshlet first runs to query for ticket changes from. That is, it looks for any tickets that have been changed (updated or inserted) since this time on first start. After the first run using this start time, the meshlet will only query for changes since the last time it ran.

This value should be entered in epoch time format in UTC/GMT time. See https://www.epochconverter.com/ to translate into this format.

If this value is blank, it will query for all ticket changes when the meshlet first runs. 

For example, this will query for changes to tickets the first time the meshlet runs:

perspectium:
	zendesk:    
         startTime: 

And this will query for all changes to tickets since 2022-08-09 1:38:42 AM (2022-08-08 6:38:42 PDT) the first time the meshlet runs:

perspectium:
	zendesk:    
         startTime: 1660009122
ticketPageSize1000No

This configuration only works if the queryMethod configuration is cursor. This specifies the number of tickets to query at a time. This value is to control performance so as to not slow down the meshlet and/or your Zendesk environment so as to not query for too many records at one time. If there are more tickets than the value specified here, it will grab it the next time when it queries for the next "page" (batch).

1000 is the maximum value allowed.

perspectium:
	zendesk:    
          ticketPageSize: 100
  • No labels