Zendesk Connector

Zendesk connector enables the indexing of tickets, and help center articles.

Prerequisites

The following configuration should be set on your Zendesk instance, by the account owner or an admin user, before configuring the Zendesk connector.

• Go to Zendesk admin panel
  • https://{your-zendesk-subdomain}.zendesk.com/admin/apps-integrations/apis/zendesk-api/settings
• Enable “API access”
  • If you don’t see such an option, it means it’s already enabled.
• Enable “Token access”
• Create a new API token
  • If you already have an API token other integrations, it’s still advised to create a new one for the Zendesk connector, and provide a descriptive name such as atolio-connector-token. Note the token value since you cannot retrieve it after its creation. The token will be used to configure the connector.
• Create a new admin user
  • If you already have an admin user for other integrations, it’s still advised to create a new admin user for the Zendesk connector, and provide a descriptive username such as atolio-connector-admin-user@<your-org-domain>. The username will be used to configure the connector.

After the configuration, your API settings page should look like the following:

Provide Configuration

Provide the following configuration and answers to your Deployment Engineer:

• Your Zendesk subdomain
• API token, ideally the one you newly created under the name atolio-connector-token
• Admin user, ideally the one you newly created under the name atolio-connector-admin-user@<your-org-domain>
• Whether you want “Help Center” content to be indexed or not
  • “Help Center” is an optional feature of Zendesk for hosting user-generated content (e.g., articles). If you use this feature and want your Help Center content to be indexed, mention this to your Deployment Engineer for them to configure it appropriately.
  • If you’re not sure if your organization uses “Help Center” functionality, try visiting https://{your-zendesk-subdomain}.zendesk.com/knowledge. A 404 error means your org is not using it.

Deployment engineer will also generate a “webhook secret”, and add it to the configuration. Please do not alter the configuration of any “webhook” or “trigger” starting with the word lumen. These are configured by the connector automatically, to index content changes in real-time.

Content Filtering

Atolio supports the ability to avoid certain content from being indexed at all. You can provide inclusions or exclusions with respect to each resource type.

• Users can be filtered w.r.t. their emails.
• Groups can be filtered w.r.t. their names.
• Organizations can be filtered w.r.t. their names.
• Tickets can be filtered w.r.t. their statuses (e.g., “open”, “closed”)

For Help center content:

• User Segments can be filtered w.r.t. their names.
• Articles can be filtered w.r.t. their section IDs.
  • Section ID is a number that can be identified by executing the following command:
    • curl -L -u "{admin-user}/token:{admin-token}" https://{zendesk-subdomain}.zendesk.com/api/v2/help_center/articles/{article-id}.json | jq ".article.section_id"
    • Replace {admin-user}, {admin-token}, {zendesk-subdomain}, and {article-id} values appropriately.

An example of inclusions/exclusions file would be as follows:

resources:
    user:
        excluded:
            - super_secret_user@example.com
    group:
        included:
            - A group name
            - Another group name
    organization:
        included:
            - An organization name
    user_segment:
        included:
            - A segment name
    ticket:
        excluded: 
            - closed  # ticket status
    article:
        excluded:
            - "12345" # section id

If you need content filtering, provide the inclusions & exclusions similar to the file above to your Deployment Engineer.