Programmers reference for Zendesk Reader

In TQL, specify the reader by its fully qualified name. To use this reader, set Global.ZendeskReader when creating a source, then configure its properties as needed.

Zendesk Reader properties

Property	Type	Default value	Notes
Access token	Password		Provide an externally generated OAuth token. Only used when the Auth Flow property toggle is on.
Auth Flow	Toggle	enabled	When the toggle is on, authentication uses an access token.
Connection profile name	Dropdown		When `Use connection profile` is toggled, you can select an existing connection profile from the dropdown or create a new one.
Connection retries	Text Box	3	Specifies the maximum number of connection attempts.
Connection timeout	Text Box	30s	Specifies a socket connection timeout in seconds. Cannot exceed 300 seconds.
Connection URL	Text Box		URL of the Zendesk endpoint.
Excluded objects	Text Box		A list of objects excluded from read operations. Typically used to create a list of exceptions when the Objects property includes wildcards. Must be entirely in lowercase.
Fetch size	Integer	100	The size of each batch to fetch. Maximum is 100. Applies to reads that use the standard Zendesk API, such as Initial load. For reads that use the Zendesk incremental export API, see Fetch size for incremental.
Fetch size for incremental	Integer	100	The number of tickets to fetch in each poll when the reader uses the Zendesk incremental export API in Incremental load or Automated mode. Each poll reads the tickets in the batch and their ticket comments, then sends the events downstream. A lower value makes events visible downstream sooner because each batch completes faster. A higher value reduces the number of API calls but delays the first events of each poll until the entire batch has been read.
Include archived tickets	Toggle	disabled	When enabled, Initial load reads the `tickets` object using the Zendesk incremental export API, which returns every ticket in the instance, including archived tickets, regardless of status. When disabled, Initial load reads only active tickets using the standard API. Zendesk automatically archives tickets 120 days after they are closed, and the standard API does not return archived tickets. Enable this property when the target must contain the complete ticket history. Applies only to the `tickets` object in Initial load mode. When `ticket_comments` is also selected, the reader retrieves the comments of archived tickets as well.
MaxConnections	Text Box	40	Maximum number of connections for the HTTP client pool.
Migrate schema	Toggle	disabled	When enabled, propagates object schema from the source to the target.
Mode	Dropdown Initial load Incremental load Automated mode	Initial load	Controls the basic behavior of the adapter. Use `InitialLoad` to read all existing data, then stop. Use `IncrementalLoad` to read new and changed data continuously from the Start Timestamp. Use `Automated` to perform an initial load and then switch automatically to continuous incremental reads without manual intervention. For the `tickets` and `ticket_comments` objects, each mode uses different Zendesk APIs. See API usage by mode for tickets and ticket comments.
Objects	Text Box		A semicolon-delimited (`;`) list of objects to read from the Zendesk instance. Values must be entirely in lowercase. Supports the `%` wildcard during Initial load only. Do not modify this property when recovery is enabled for the application.
Polling interval	Text Box	120s	Specify an integer followed by a unit: days (`d`), hours (`h`), minutes (`m`), or seconds (`s`). The reader polls the Zendesk instance at the specified interval.
Start Timestamp	Text Box		Specifies a time from which the adapter begins sync operations. Timestamps use UTC in the ISO 8601 format, for example `2024-01-31T01:42:33Z`. When no timestamp is provided for incremental load, the reader syncs from 60 seconds prior to the current time.
Thread pool count	Integer	0	Specifies the number of execution threads to use. Best performance typically uses one thread per object being synced. Ensure the connection pool size is greater than or equal to the number of execution threads to avoid halts during large ingestions. The `ThreadPoolCount` value must be less than the number of available processors. For example, if the system has eight processors, set `ThreadPoolCount` to 7 or lower.
Use connection profile	Toggle	false	When enabled, uses a saved connection profile rather than individual properties.
Username	Text Box		The email ID of a Zendesk user account.

Zendesk Reader supported objects

Zendesk Reader supports the following objects. Custom objects are not supported.

Dependency note: some secondary objects depend on related primary objects. For example, comments- or metrics-oriented objects may require that the corresponding primary ticket or user objects are also selected. If a secondary object is selected without its primary, reads may return empty results.

Object name	Supported modes	Checkpoint field	Supported operations	Scope	Notes
`Account_attributes`	Initial Load	updated_at	Insert	read
`Activities`	Initial Load	updated_at	Insert	read
`Audit_logs`	Initial Load	created_at	Insert	read
`Automations`	Initial Load	None	Insert	read
`Bookmarks`	Initial Load	created_at	Insert	read
`Brands`	Initial Load	updated_at	Insert	read
`Custom_roles`	Initial Load	updated_at	Insert	read
`Custom_statuses`	Initial Load	updated_at	Insert	read
`Deleted_tickets`		deleted_at		read
`Deleted_users`	Initial Load	updated_at	Insert	read
`Group_memberships`	Initial Load	updated_at	Insert	read
`Groups`	Initial Load	updated_at	Insert / Update	read
`Items`	Initial Load	updated_at	Insert	read
`Locales`	Initial Load	updated_at	Insert	read
`Macros`	Initial Load	updated_at	Insert	read
`Organization_fields`	Initial Load	updated_at	Insert	read
`Organization_memberships`	Initial Load	updated_at	Insert	read
`Organization_subscriptions`	Initial Load	created_at	Insert	read
`Organizations`	All	updated_at	Insert / Update	read
`Recipient_addresses`	Initial Load	updated_at	Insert	read
`Requests`	Initial Load	updated_at	Insert	read
`Resource_collections`	Initial Load	updated_at	Insert	read
`Routing_attribute_definitions`	Initial Load	updated_at	Insert	read
`Satisfaction_ratings`	Initial Load	updated_at	Insert	read
`Satisfaction_reasons`	Initial Load	updated_at	Insert	read	Reading these objects requires you to change some Zendesk settings. See Zendesk help > Support > Using Support ticketing system > Measuring success > Working with satisfaction reasons.
`Sessions`	Initial Load	None	Insert	read
`Settings`	Initial Load			read
`Sharing_agreements`	Initial Load	updated_at	Insert	read
`Slas` (SLA policy)	Initial Load	updated_at	Insert	read
`Suspended_tickets`	Initial Load	None	Insert	read
`Tags`	Initial Load	None	Insert	read
`Target_failures`	Initial Load	created_at	Insert	read
`Targets`	Initial Load	created_at	Insert	read
`Ticket_audits`	Initial Load	created_at	Insert	read
`Ticket_comments`	All	updated_at	Insert / Update	read	Requires the `tickets` object to be selected. In Incremental load and Automated mode, the reader captures new comments and comment redactions from the Zendesk ticket events incremental export instead of re-reading all comments on a ticket. Redactions are delivered as update operations. See API usage by mode for tickets and ticket comments.
`Ticket_events`	Incremental	time	Insert	read
`Ticket_fields`	Initial Load	updated_at	Insert	read
`Ticket_forms`	Initial Load	updated_at	Insert	read
`Ticket_metric_events`	Incremental	time	Insert	read
`Ticket_metrics`	Initial Load	updated_at	Insert	read
`Tickets`	All	updated_at	Insert / Update	read	By default, Initial load returns only active tickets. Enable Include archived tickets to also return archived tickets. See API usage by mode for tickets and ticket comments.
`Triggers`	Initial Load	updated_at	Insert	read
`User_fields`	Initial Load	updated_at	Insert	read
`Users`	All	updated_at	Insert / Update	read
`Workspaces`	Initial Load	None	Insert	read

API usage by mode for tickets and ticket comments

Zendesk Reader uses different Zendesk APIs to read the tickets and ticket_comments objects depending on the selected mode, and in Automated mode it switches APIs when the initial load completes. The API in use determines which tickets are returned, how comments are captured, and where duplicate events can occur, so use the following table to choose the mode and properties that match the data you need at the target.

Mode	tickets	ticket_comments
Initial load	Reads a full snapshot of active tickets from the standard tickets API, paging with a cursor until every ticket has been read. When Include archived tickets is enabled, reads from the Zendesk incremental export API instead, which returns all tickets in the instance, including archived tickets.	For each ticket read, calls the per-ticket comments API to retrieve every comment on that ticket. Comments are read for the same set of tickets that the tickets read returns, so enabling Include archived tickets also retrieves the comments of archived tickets.
Incremental load	Reads from the Zendesk incremental export API starting at Start Timestamp. Returns only tickets that changed since that point, as full ticket records. Each poll reads up to Fetch size for incremental tickets.	Reads from the Zendesk ticket events incremental export starting at Start Timestamp. Only new comments and comment redactions are extracted from the ticket event stream. Existing comments on a ticket are not re-read when the ticket changes.
Automated	Performs the initial load using the standard tickets API (or the incremental export API when Include archived tickets is enabled), then switches to the Zendesk incremental export API to read changed tickets continuously.	Performs the initial load using the per-ticket comments API, then switches to the Zendesk ticket events incremental export to read new comments and redactions continuously.

Mode

tickets

ticket_comments

Initial load

Reads a full snapshot of active tickets from the standard tickets API, paging with a cursor until every ticket has been read.

When Include archived tickets is enabled, reads from the Zendesk incremental export API instead, which returns all tickets in the instance, including archived tickets.

For each ticket read, calls the per-ticket comments API to retrieve every comment on that ticket. Comments are read for the same set of tickets that the tickets read returns, so enabling Include archived tickets also retrieves the comments of archived tickets.

Incremental load

Reads from the Zendesk incremental export API starting at Start Timestamp. Returns only tickets that changed since that point, as full ticket records. Each poll reads up to Fetch size for incremental tickets.

Reads from the Zendesk ticket events incremental export starting at Start Timestamp. Only new comments and comment redactions are extracted from the ticket event stream. Existing comments on a ticket are not re-read when the ticket changes.

Automated

Performs the initial load using the standard tickets API (or the incremental export API when Include archived tickets is enabled), then switches to the Zendesk incremental export API to read changed tickets continuously.

Performs the initial load using the per-ticket comments API, then switches to the Zendesk ticket events incremental export to read new comments and redactions continuously.

Because Automated mode uses different APIs before and after the switch, tickets and comments that change while the initial load is running can be read twice: once by the initial load and again from the incremental export after the switch. Configure the target to tolerate these duplicates by using merge semantics or by configuring Striim to ignore RECORD_ALREADY_EXISTS errors. See Duplicate events in incremental ticket-event exports.

In Incremental load and Automated mode, a redacted comment is delivered as an update operation. When the target is configured for append mode, the original comment and the redaction are written as separate rows, so the number of comment rows at the target can exceed the comment count reported by Zendesk. Use merge mode at the target to keep a single row per comment.

Datatype support

Striim type	Example Zendesk data	Notes
String	Names, emails, IDs represented as strings, JSON text	Default mapping for textual fields and JSON blobs not expanded into columns.
Long	Integer identifiers, counters	Whole-number fields.
Double	Durations, numeric metrics	Floating-point fields.
boolean	Flags such as `active`, `verified`	True/false fields.
String	`created_at`, `updated_at`, and other timestamp fields	Zendesk Reader emits timestamp values as ISO 8601 UTC strings, not as `org.joda.time.DateTime`. When writing to a relational target that uses a native timestamp datatype, define the target column as a string type. See Timestamp columns in relational targets in the Limitations section of the Operational considerations topic.
java.lang.Object	Nested structures, arrays	Used when a field is heterogeneous or complex; may be serialized as JSON.

Duplicate events in incremental ticket-event exports

ZendeskReader uses Zendesk's time-based ticket_events incremental export endpoint for Incremental Load and Automated Load. Because Zendesk uses the previous page's end_time as the start_time for the next page or poll, events at that boundary can be returned more than once. This behavior prevents events with the same timestamp from being skipped.

Configure the downstream target to handle duplicate records by using merge semantics or by configuring Striim to handle RECORD_ALREADY_EXISTS errors. For Zendesk ticket events, use id and created_at to identify duplicates.

For more information, see Zendesk's Incremental Exports API documentation.