Read Help Center Articles

Overview

The Read Help Center Articles Snap retrieves article records from your Zendesk Help Center, with filtering options by article ID, section, category, label, user, or incremental export since a given date.

Each article record is emitted as a separate document on the output view. You can optionally sideload attachment metadata and user segment information alongside each article. Results can be sorted by various fields and limited using Max results.

Use the Incremental Export filter mode to retrieve only articles that have been created or updated since a specific timestamp, which is useful for synchronization pipelines. Unlike other filter modes, Incremental Export uses a next_page URL-based pagination mechanism, not cursor-based pagination.



Supported Accounts

Prerequisites

None.

Snap views

Type Description Examples of upstream and downstream Snaps
Input

This Snap has at most one document input view.

When connected, field values from the incoming document can be referenced in expression-enabled fields using the $ notation.

Output

This Snap has one document output view.

Each Help Center article is emitted as a separate document. When Include attachments is selected, attachment metadata is included in each article document. When Include user segments is selected, user segment information is included in each article document.

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: Read Help Center Articles

Filter mode

Dropdown list
Select the strategy for filtering the articles to retrieve.
  • All Articles: Select to retrieve all published articles in the Help Center.
  • By ID: Select to retrieve a single article by its Zendesk article ID. Requires the Article ID field.
  • By Section: Select to retrieve all articles in a specific Help Center section. Requires the Section field.
  • By Category: Select to retrieve all articles in a specific Help Center category. Requires the Category field.
  • By Label: Select to retrieve articles that match one or more labels. Requires the Labels field.
  • By User: Select to retrieve all articles authored by a specific user. Requires the User ID field.
  • Incremental Export: Select to retrieve all articles created or updated since a specific timestamp. Requires the Since date field. Useful for synchronization pipelines.

Default value: All Articles

Example: By Section

Article ID*

String/Expression

Appears when Filter mode is By ID.

Enter the numeric Zendesk article ID of the article to retrieve.

Default value: None

Example: 360001234567

Section*

String/Expression/ Suggestion

Appears when Filter mode is By Section.

Specify the Help Center section to filter by. Suggestions are populated from your Zendesk instance when the account is configured.

Default value: None

Example: Getting Started

Category*

String/Expression/ Suggestion

Appears when Filter mode is By Category.

Specify the Help Center category to filter by. Suggestions are populated from your Zendesk instance when the account is configured.

Default value: None

Example: Product Documentation

Labels*

String/Expression

Appears when Filter mode is By Label.

Enter a comma-separated list of article label names to filter by. Only articles that have all of the specified labels are returned.

Default value: None

Example: api,integration

User ID*

String/Expression

Appears when Filter mode is By User.

Enter the numeric Zendesk user ID of the article author to retrieve all articles authored by this user.

CAUTION: The By User filter mode may not function correctly in all deployments due to a known property key mismatch in the Snap. If no results are returned when using this mode, verify that the user ID is valid, or use the All Articles mode with downstream filtering instead.

Default value: None

Example: 123456789

Since date*

String/Expression

Appears when Filter mode is Incremental Export.

Enter the earliest update timestamp to use as the export start point. Only articles created or updated at or after this time are returned. Must be in ISO 8601 format. The value is converted internally to Unix epoch seconds before being submitted to the Zendesk API.

Default value: None

Example: 2024-01-01T00:00:00Z

Locale

String/Expression

Specify a locale to restrict results to articles in that locale. Leave empty to return articles in all locales.

Default value: en-us

Example: fr

Include attachments

Checkbox

When selected, the Snap makes an additional API call per article to retrieve attachment metadata, which is included in the article output document. This increases the number of API requests proportionally to the number of articles retrieved.

CAUTION: This field defaults to Selected, meaning attachment metadata is fetched by default. For large Help Centers, this can significantly increase API usage and execution time. Clear this field if attachment metadata is not needed.

Default value: Selected

Include user segments

Checkbox

When selected, the Snap retrieves and includes user segment information for each article. Segment data is cached to reduce the number of API calls.

When the article lists its segments in user_segment_ids, the Snap adds all of them as a user_segments array. When the article has a single user_segment_id, the Snap adds that segment as a user_segment object.

Default value: Not selected

Example: Selected

Sort by

Dropdown list
Select the field to sort results by. Valid values:
  • Updated At: Sort by the date the article was last updated.
  • Created At: Sort by the date the article was created.
  • Edited At: Sort by the date the article body was last edited.
  • Title: Sort alphabetically by article title.
  • Position: Sort by the article's position within its section.

Default value: Updated At

Example: Created At

Sort order

Dropdown list
Select the direction in which to sort results.
  • Ascending: Earliest to latest, or A to Z.
  • Descending: Latest to earliest, or Z to A.

Default value: Descending

Example: Ascending

Max results

Integer/Expression

Specify the maximum number of article records to emit per execution. Enter 0 or leave empty to emit all matching results.

Default value: 0

Example: 10

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.

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: 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.
Resource not found. Zendesk returned HTTP 404 (Not Found). The ID in the Snap settings or input document does not exist in your Zendesk instance, or the record was deleted. Verify the ID, and make sure the record still exists in Zendesk.
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.
The <field> provided is not valid An ID field, such as User ID or Ticket ID, received a value that is not a whole number. Zendesk ID fields accept integer values only. Enter the numeric Zendesk ID, or fix the expression so that it evaluates to one.
Article ID is required when filter mode is 'By ID' Filter mode is By ID and Article ID is empty, or evaluates to 0. Enter a value in Article ID.
Section is required when filter mode is 'By Section' Filter mode is By Section and Section is empty. Enter a value in Section.
Category is required when filter mode is 'By Category' Filter mode is By Category and Category is empty. Enter a value in Category.
User ID is required when filter mode is 'By User' Filter mode is By User and User ID is empty, or evaluates to 0. Enter a value in User ID.
Since date is required for incremental export Filter mode is Incremental Export and Since date is empty. Enter the time to export from, such as 2024-01-01T00:00:00Z.
Section '<name>' not found The value in Section does not match any section in your Zendesk instance. Select the section from the suggestions list, or verify that the value matches a section in your Zendesk instance exactly.
Category '<name>' not found The value in Category does not match any category in your Zendesk instance. Select the category from the suggestions list, or verify that the value matches a category in your Zendesk instance exactly.