The Zendesk data source surfaces a Zendesk Support account as Forest collections. It exposes tickets, users and organizations (with each ticket carrying its comment thread inline) on top of the Zendesk REST API, so you can browse and edit them from your Forest project alongside your other data sources.
This is the Zendesk data source (Zendesk data inside Forest). If you want to embed Forest data and actions inside Zendesk tickets instead, see the Zendesk app. forest_admin_datasource_zendesk.
module ForestAdminRails
class CreateAgent
def self.setup!
datasource = ForestAdminDatasourceZendesk::Datasource.new(
subdomain: ENV['ZENDESK_SUBDOMAIN'],
username: ENV['ZENDESK_USERNAME'],
token: ENV['ZENDESK_API_TOKEN']
)
@create_agent = ForestAdminAgent::Builder::AgentFactory.instance.add_datasource(datasource, {})
customize
@create_agent.build
end
end
end
Configuration
The datasource authenticates against Zendesk using an API token. All three options are mandatory; the back-end fails fast with a ForestAdminDatasourceZendesk::ConfigurationError if any of them is missing or blank.
| Option | Description |
|---|
subdomain | The subdomain of your Zendesk account (e.g. acme for https://acme.zendesk.com). |
username | The email address associated with the API token (typically a Zendesk admin/agent account). |
token | A Zendesk API token generated from Admin Center → Apps and integrations → APIs → Zendesk API. |
forest_admin_datasource_zendesk gem also ships two action plugins (CreateTicketWithNotification and CloseTicket) that you can attach to any host collection. See the Zendesk plugins page for details.
Provided collections
Once the data source is registered, three collections are added to your Forest project:
| Collection | Primary endpoint | Notes |
|---|
ZendeskTicket | Search API (/api/v2/search?query=type:ticket) | Full read/write. Embeds requester, assignee, organization and an inline comments thread. |
ZendeskUser | Search API (/api/v2/search?query=type:user) | Full read/write. |
ZendeskOrganization | Search API (/api/v2/search?query=type:organization) | Full read/write. |
Relationships
The following relationships are exposed automatically:
ZendeskTicket.requester → ZendeskUser (foreign key requester_id)ZendeskTicket.assignee → ZendeskUser (foreign key assignee_id)ZendeskTicket.organization → ZendeskOrganization (foreign key organization_id)ZendeskUser.organization → ZendeskOrganizationZendeskUser.requested_tickets → ZendeskTicketZendeskOrganization.users → ZendeskUserZendeskOrganization.tickets → ZendeskTicket
Zendesk has no standalone /comments/{id} endpoint, so comments are not exposed as their own collection. Instead, each ZendeskTicket carries a structured comments array column that is fetched lazily from /api/v2/tickets/{id}/comments only when the projection asks for it (i.e. when comments is rendered on the detail view or referenced in a custom action).
Each entry has the following shape:
| Field | Type | Source |
|---|
id | Number | Zendesk comment id |
body | String | Plain-text body |
html_body | String | HTML-formatted body |
public | Boolean | true for public replies, false for internal notes |
author_email | String | Resolved through a single users/show_many call across all visible authors |
author_name | String | Same |
created_at | Date | Comment creation timestamp |
ZendeskTicket.description on creation (Zendesk converts the description into the first comment).
Custom fields
Custom fields configured in your Zendesk account are introspected at back-end boot and added to the matching collection’s schema:
- Ticket custom fields are exposed as
custom_<zendesk_id> columns on ZendeskTicket.
- User and organization custom fields are exposed using their Zendesk
key (or custom_<zendesk_id> if no key is set) on ZendeskUser / ZendeskOrganization.
The Forest column type is derived from the Zendesk field type:
| Zendesk field type | Forest column type |
|---|
text, textarea, regexp, partialcreditcard | String |
integer, decimal, lookup | Number |
date | Dateonly |
checkbox | Boolean |
dropdown, tagger | Enum |
multiselect | Json |
If introspection fails (network error, missing scope, …) the datasource degrades gracefully: the corresponding collection is still registered without the custom fields, and a warning is logged.
Capabilities
Filters
The condition tree is translated into a Zendesk Search API query. The following operators are supported:
| Operator | Translation |
|---|
EQUAL, NOT_EQUAL | field:value / -field:value |
IN, NOT_IN | repeated field:value clauses |
GREATER_THAN, LESS_THAN, BEFORE, AFTER | field>value / field<value |
PRESENT, BLANK | field:* / -field:* |
- Only the
AND aggregator is supported. Mixing OR between conditions raises UnsupportedOperatorError. The Zendesk Search API has no general OR operator, so silently rewriting an OR filter would return wrong results.
- An empty
IN / NOT_IN raises UnsupportedOperatorError rather than matching everything.
- A nil value passed with
EQUAL / NOT_EQUAL / IN raises an explicit error: use PRESENT / BLANK to filter for absence.
- Filtering
ZendeskTicket.requester_email = "x@y.z" is rewritten to Zendesk’s requester:x@y.z operator.
Date filter values are interpreted at start-of-day in the caller’s timezone before being sent to Zendesk.
Sorting
Only fields that the Zendesk Search API can sort on are honoured. Other sort directives are silently ignored:
ZendeskTicket: created_at, updated_at, priority, status, ticket_typeZendeskUser: created_at, updated_at, nameZendeskOrganization: created_at, updated_at, name
Forest’s offset/limit pagination is translated to Zendesk’s page / per_page. The Search API caps per_page at 100; larger limits are clamped.
Aggregations
Only Count aggregation without grouping is supported. Any other aggregation raises a ForestException, the Zendesk Search API has no group-by primitive.
Search
The free-text search bar is enabled on ZendeskTicket, ZendeskUser and ZendeskOrganization. The search term is appended to the query that is built from the active filters, so the count badge and the rendered list always agree.
Writes
Create, update and delete are supported on ZendeskTicket, ZendeskUser and ZendeskOrganization. Custom fields are folded into the appropriate Zendesk payload structure (custom_fields for tickets, user_fields / organization_fields for users and organizations).
A few fields are intentionally read-only:
id, url, created_at and updated_at are ignored on writes.- On
ZendeskTicket, description is only written on creation (where Zendesk turns it into the first comment); it is silently dropped on update because Zendesk exposes no write endpoint for it.
ZendeskTicket.requester_email is computed at read time from the requester’s profile and cannot be written directly.
Logging
The datasource uses Rails.logger when available, and falls back to Logger.new($stderr). You can override it explicitly:
ForestAdminDatasourceZendesk.logger = MyLogger.new
ForestAdminDatasourceZendesk::APIError that wraps the underlying Zendesk error.
Source code
This connector is open source. Browse the code or contribute on GitHub: forest_admin_datasource_zendesk. 
