Create Ticket

Overview

The Create Ticket Snap creates one or more tickets in your Zendesk instance, using either the REST API with optional batching or the Bulk API.

The Snap reads the ticket data from the location in each input document that the Data path field points to. That location can hold one ticket object or an array of ticket objects. Use the API mode field to choose how the tickets are sent:

  • REST API: With a Batch size of 1, the Snap creates each ticket with its own request and writes the created ticket to the output view. With a larger batch size, the Snap accumulates tickets and submits each batch as a single request, which Zendesk processes as a background job.
  • Bulk API: The Snap submits tickets in batches of 100 as background jobs. Recommended when you create more than 1000 tickets.

For background jobs, the Snap waits for each job to complete, then writes one output document for each ticket the job created and one error document for each ticket it could not create.



Supported Accounts

Prerequisites

None.

Snap views

Type Description Examples of upstream and downstream Snaps
Input

This Snap has exactly one document input view.

Each input document carries the ticket data to create, at the location that Data path points to. The Snap provides a ticket input schema, so you can map the ticket fields in an upstream Mapper Snap. In that schema, comment is marked as required.
Output

This Snap has at most one document output view.

With the REST API and a Batch size of 1, each output document is the ticket that Zendesk created. Otherwise, each output document is the background job's result for one ticket, including the new ticket's id and its index in the batch.
Learn more about Error handling.

Snap settings

Note: Learn about the common controls in the Snap settings dialog.
Field/Field set Description

Label*

String

Specify a unique name for the Snap. Modify this to be more appropriate, especially if more than one of the same Snaps is in the pipeline.

Default value: Create Ticket

Example: Create support tickets
Data path*

Expression

Enter the path in the input document that resolves to the ticket object, or to an array of ticket objects, to send to Zendesk. Enter $ to use the entire input document.

Default value: $ticket

Example: $tickets
API mode

Dropdown list
Select how the Snap sends tickets to Zendesk.
  • REST API: Select to send synchronous requests, one per ticket or one per batch, as set in Batch size.
  • Bulk API: Select to submit tickets in batches of 100 as asynchronous background jobs. Recommended when you create more than 1000 tickets.

Default value: REST API

Example: Bulk API
Batch size

Integer

Appears when API mode is REST API.

Enter the number of tickets to accumulate before sending a single request, from 1 through 100. With 1, the Snap creates each ticket with its own request. With a larger value, the Snap sends each batch as one request, which Zendesk processes as a background job.

Default value: 1

Example: 50
Retry attempts

Integer/Expression

Enter the number of times the Snap should retry the API call on connection errors or 5xx responses. On a 429 response, the Snap automatically retries after the interval specified in the server's Retry-After header, overriding the Retry interval value. On a 401 response, the Snap reloads the account credentials and retries before counting the attempt against this limit.

Default value: 5

Example: 3
Retry interval (seconds)

Integer/Expression

Enter the number of seconds to wait between retry attempts. The Snap also waits this long between checks on a background job's status, and checks up to 100 times.

Default value: 3

Example: 5

Snap execution

Dropdown list
Choose one of the three modes in which the Snap executes. Available options are:
  • Validate & Execute: Performs limited execution of the Snap and generates a data preview during pipeline validation. Subsequently, performs full execution of the Snap (unlimited records) during pipeline runtime.
  • Execute only: Performs full execution of the Snap during pipeline execution without generating preview data.
  • Disabled: Disables the Snap and all Snaps that are downstream from it.

Default value: Execute only

Example: Validate & execute

Troubleshooting

Error Reason Resolution
Unable to connect to Zendesk: <details> The Snap could not connect to your Zendesk instance with the selected account, because of an authentication or network problem. Verify the subdomain and credentials in the account, and that the Snaplex can reach your Zendesk instance. Then run the pipeline again.
Authentication failed. Zendesk rejected the account credentials with HTTP 401 (Unauthorized). Verify the credentials in the account, then run the pipeline again.
Invalid request. Zendesk rejected the request with HTTP 400 (Bad Request) or HTTP 422 (Unprocessable Entity). The reason field in the error document shows which. Review the Snap settings and the values in the input document, correct any value that Zendesk does not accept, and run the pipeline again.
Access denied. Zendesk returned HTTP 403 (Forbidden). The Zendesk user behind the account does not have permission for the requested resource. Use an account whose Zendesk user has at least the Agent role, or the permissions the operation requires.
Rate limit exceeded. Zendesk returned HTTP 429 (Too Many Requests), and the rate limit was still exceeded after the Snap's automatic retries. Reduce the volume of requests, for example by retrieving fewer records per run, or schedule the pipeline outside peak hours.
Zendesk server error. Zendesk returned HTTP 500, 502, 503, or 504, and the error persisted after the configured retries. Wait a few minutes and run the pipeline again. If the error recurs, increase Retry attempts or Retry interval (seconds).
Network error while calling Zendesk. The Snap could not reach Zendesk, for example because of a connection timeout or a DNS failure. Verify that the Snaplex can reach your Zendesk instance, then run the pipeline again.
Data path: Invalid expression result: <expression> -> null The input document has no value at the location that Data path points to. Fix the Data path expression so that it matches the structure of the input document, or map the ticket data to that location in an upstream Snap.
No ticket data resolved from the configured Data path. The value at Data path is not a ticket object or an array of ticket objects, or the array contains an item that is not an object. Point Data path to a ticket object or an array of ticket objects.
An error document whose error field holds a Zendesk error code, such as TicketImportFailed, with the cause in the details field. A background job finished, but Zendesk could not create one of the tickets in the batch. For example, details shows Description: cannot be blank. Correct the ticket data that details identifies, then resubmit that ticket. The other tickets in the batch were created.
Zendesk bulk job <job ID> did not complete successfully. Zendesk reported the background job as failed. The reason field shows the job status and Zendesk's message. Correct the input that the message identifies, then run the pipeline again.
Timed out waiting for Zendesk bulk job <job ID> to complete. The background job did not finish within 100 status checks. Check the job's status in Zendesk before you rerun the pipeline, because the job may still complete and create the tickets. To wait longer, increase Retry interval (seconds).