Authentication, Filtering & Sorting

Please be sure of your agent type and version and pick the right documentation accordingly.

Node.js

This is the documentation of the forest-express-sequelize and forest-express-mongoose Node.js agents that will soon reach end-of-support.

forest-express-sequelize v9 and forest-express-mongoose v9 are replaced by @forestadmin/agent v1.

Please check your agent type and version and read on or switch to the right documentation.

Ruby on Rails

Python

PHP

Authentication, Filtering & Sorting

Get authenticated to the Zendesk API

You first need to generate an authentication token to access the Zendesk API. We are going to use the basic authentication mechanism. More details provided here. The 2 parameters required are: a user email (agent) that is allowed to access Zendesk, and the API Key that you can retrieve from the Zendesk console:

These 2 parameters can be environment variables like this;

services/forest-smart-collection-helpers.js

function getToken() {
  const authEmail = process.env.ZENDESK_AUTH_EMAIL;
  const apiKey = process.env.ZENDESK_API_TOKEN;
  return Buffer.from(`${authEmail}/token:${apiKey}`).toString('base64');
}

Filtering and Sorting using the API

Zendesk API allows you to filter and sort the tickets/users, plus paginate the result.

What we need first, is to implement a way to transform the Forest Admin filtering, sorting and pagination convention to the Zendesk API format.

Learn more about how to authenticate, filter and sort with the Zendesk API.

Filtering

services/forest-smart-collection-helpers.js

function getFilterConditions(params) {
  let filters = [];
  if (params.filters) {
    let filtersJson = JSON.parse(params.filters);
    if (filtersJson.aggregator) {
      filters = filtersJson.conditions;
    } else {
      filters = [filtersJson];
    }
  }

  let filterConditions = [];
  if (params.search) {
    filterConditions.push(params.search);
  }
  for (let filter of filters) {
    if (filter.field === 'id') {
      filterConditions.push(`${filter.value}`);
    } else {
      // This example shows the equals, greater than and lower than conditions
      // cf. Search operators => https://support.zendesk.com/hc/en-us/articles/203663226-Zendesk-Support-search-reference#topic_lhr_wsc_3v
      let operator = ':';
      switch (filter.operator) {
        case 'before':
          operator = '<';
          break;
        case 'after':
          operator = '>';
          break;
      }
      filterConditions.push(`${filter.field}${operator}${filter.value}`);
    }
  }
  return filterConditions;
}

Sorting

services/forest-smart-collection-helpers.js

function getSort(params, options) {
  let sort_by = options.default_sort_by || '';
  let sort_order = options.default_sort_order || '';

  let sort = params.sort;
  if (sort) {
    let asc = true;
    if (sort.startsWith('-')) {
      asc = false;
      sort = sort.substring(1);
    }

    const collectionName = options.collection_name;
    const authorized_fields = Liana.Schemas.schemas[collectionName].fields
      .filter((field) => field.isSortable)
      .map((field) => field.field);

    if (authorized_fields.includes(sort)) {
      sort_by = sort;
      sort_order = asc ? 'asc' : 'desc';
    }
  }
  return { sort_by, sort_order };
}