Skip to end of metadata
Go to start of metadata

The Zendesk connector is a REST-based connector that allows you to connect to Zendesk and import data into the ElastiCube Manager. With a Zendesk connector, you can return Zendesk objects such as users, tickets, groups etc, as tables and transform that data in the ElastiCube Manager.

This page will take you through the process of creating a custom Zendesk connector that you can use to import ticket and user data from the Zendesk REST API to your ElastiCube Manager. 

Defining the Zendesk Configuration File

When connecting to a data source, you must create a connector configuration file in JSON for each unique source. This file contains all the necessary information to connect, authenticate, fetch and transform data from a REST provider.

This section provides a sample Zendesk Configuration file that connects to the Zendesk REST API and imports two tables into the ElastiCube Manager.

Settings

The Settings object defines how Sisense will display the connector in the ElastiCube Manager, the folder where your connector file is located, and the Zendesk endpoint.  

 

Settings
{
  "Settings": {
    "Provider": "rest.zendesk.connector",
    "DisplayName": "Zendesk",    
    "MaxDocs": 10,
    "FetchSize": 1000,
    "Parameters": {
      "uri": "https://zndskusr.zendesk.com"
    }
  },


In this example, the value of Provider is “rest.zendesk.connector”. This should also be the name of the directory where the configuration file is stored as displayed below.



After saving the configuration JSON file, the next time you launch the ElastiCube Manager, the Zendesk connector is displayed when adding more data. The name you define as the value of DisplayName determines the name displayed in the ElastiCube Manager.

In this example, the value was Zendesk as displayed in the code sample and the image below.



The MaxDocs and FetchSize values determine how much data is returned and how much is returned before caching the data.

The final value you define is the connector’s endpoint as defined by the data source’s REST API. In this example, the value of the URI is https://zndskusr.zendesk.com.

Tables

The Tables object describes what data is fetched from the data source and how it is displayed in the ElastiCube Manager.

In this example, two tables are returned from Zendesk, Tickets and Users.  

Tickets

Zendesk tickets are how Zendesk users communicate with Agents. From the Zendesk API, you can pull data regarding tickets. For more information regarding the Tickets object returned from Zendesk, click here.

The following code sample shows the type of information you can define in the configuration JSON file to return data regarding tickets and how this information is displayed in the ElastiCube Manager.

 

Tickets
{
      "Name": "Tickets",
      "Schema": "Https",
      "Method": "GET",
      "Base": "[@Settings.Parameters.uri]",
      "Path": "api/v2/tickets.json",
      "Headers": {
        "Authorization": "Basic ADCxleGV5Lmasdf5rb0BzaXNlbnNlLmNvbS90b2tlge4309TbzNsergerkZ2dTZxb1lqR3ZEWUBBBdFN2134G"
      },
      "PathParameters": [],
      "QueryParameters": {},
      "Body": {},
      "DataFormat": "Json",
      "DataPath": "tickets",
      "PagingConfig": {
        "PageSize": "100",
        "NextPageURL": "next_page",
        "PagingMethod": "URL"
      },
      "Transformation": {
        "ExcludeList": [
          "tags"
        ],
        "TransformTypes": [
          {
            "Name": "created_at",
            "Type": "DateTime"
          },
          {
            "Name": "updated_at",
            "Type": "DateTime"
          }
        ],
            }
    },

 

The table below describes the values provided in the sample above:

 

Key

Value

Name

In this example, the name of the table is Tickets. This string value will be the name of the table as displayed in the ElastiCube Manager.

Schema

This value describes the protocol used to contact Zendesk. This is defined by the data source. In the sample above, Zendesk uses HTTPS.

Method

Defines the method in the request, in this sample GET.

Base

The endpoint of the datasource. In this sample, Sisense uses a placeholder "[@Settings.Parameters.uri]" to refer to the value defined in the Settings object.

For more information about how you can use placeholders to refer to values shared in memory or defined elsewhere in the JSON file, click here.

Path

This value defines the location of the data at the data source. Zendesk has stored the tickets information at /api/v2/tickets.json.

Headers

This object is used to supply Zendesk the authorization key for authenticating your request.

DataFormat

This value describes how the information is formatted. Currently, Sisense only supports JSON.

DataPath

The name of the top level key containing the data set.

PagingConfig

Information returned by Zendesk can be quite large, which means it might not be possible to return the data through a single HTTP request.

In this example, Sisense has defined the PageSize, NextPageURL, and PagingMethod.

Transformation

Through the Transformation object, the data returned from Zendesk is modified by Sisense according to the values you define.

In this example, the column “tags” returned by Zendesk is excluded and therefore not imported into the ElastiCube Manager.

The two columns “create_at” and “updated_at” are stored in the ElastiCube Manager as DateTime types instead of integers for example.

 

Users

The Users table is similar to the Tickets table in that it creates a new table within the ElastiCube Manager and uses the same communication protocol as the Tickets table. Where the Users table differs is in the path of the information to be retrieved and how that information is imported into the ElastiCube Manager.

The value of Base is the same as in the Tickets table. This value is a placeholder that refers to the URI endpoint located in the Settings object. The Path where the users.json file is stored is different; for the Users table, the value is "api/v2/users.json".

The second difference between this table and the Tickets table is how the information is imported. In this example, the column “Photo” is excluded from the data imported into the ElastiCube Manager. In addition, this table transforms the data in the column "last_login_at" to the Type DateTime.

Users
    {
      "Name": "Users",
      "Schema": "Https",
      "Method": "GET",
      "Base": "[@Settings.Parameters.uri]",
      "Path": "api/v2/users.json",
      "Headers": {
        "Authorization": "Basic ADCxleGV5Lmasdf5rb0BzaXNlbnNlLmNvbS90b2tlge4309TbzNsergerkZ2dTZxb1lqR3ZEWUBBBdFN2134G"
      },
      "PathParameters": [],
      "QueryParameters": {},
      "Body": {},
      "DataFormat": "Json",
      "DataPath": "users",
      "PagingConfig": {
        "PageSize": "100",
        "NextPageURL": "next_page",
        "PagingMethod": "URL"
      },
      "Transformation": {
        "ExcludeList": [
          "photo"
        ],
        "TransformTypes": [
          {
            "Name": "created_at",
            "Type": "DateTime"
          },
          {
            "Name": "updated_at",
            "Type": "DateTime"
          },
          {
            "Name": "last_login_at",
            "Type": "DateTime"
          }
        ]
      }
    }
 
For a full example of the Zendesk Configuration, click here.

Creating a Zendesk Configuration File

For Sisense to locate your configuration files, each connector you wish to add must be in a folder located in the following directory:

C:\Program Files\Sisense\DataConnectors\DotNetContainer\Connectors\

The folder should be named according to the convention REST.[NameofConnector].Connector

In the case of Zendesk, name the folder as follows:

C:\Program Files\Sisense\DataConnectors\DotNetContainer\Connectors\REST.Zendesk.Connector

In addition, you must include the Sisense REST Connector DLL file (Sisense.Connectors.RestConnector.dll) in your connector’s folder. You can retrieve this file from one of the sample REST connector files included in your Sisense installation located at ...Program Files\Sisense\DataConnectors\DotNetContainer\SampleRestConnectors.

After saving the configuration file and the Sisense REST Connector DLL file, the new Zendesk connector is displayed in the ElastiCube manager with your default connectors under Web Services.

Zendesk Full Example

The following is a full example of a Zendesk Configuration file. This example imports 8 tables in which various columns are modified when imported into the ElastiCube Manager as described in the examples above.

 

Zendesk
{
  "Settings": {
    "Provider": "rest.zendesk.connector",
    "DisplayName": "Zendesk",    
    "MaxDocs": 10,
    "FetchSize": 1000,
    "Parameters": {
      "uri": "https://zndskusr.zendesk.com"
    }
  },
  "Tables": [
    {
      "Name": "Comments",
      "Public": "False",
      "Schema": "Https",
      "Method": "GET",
      "Base": "[@Settings.Parameters.uri]",
      "Path": "api/v2/tickets/{0}/comments.json",
      "Headers": {
        "Authorization": "Basic YWxleGV5LmF2cmFtZW5rb0BzaXNlbnNlLmNvbS90b2tlbjpTY09TbzNkR0k0UFJKbldQakZ2dTZxb1lqR3ZEWURRR1dFNnlkYlhG"
      },
      "PathParameters": [ "[@Tables.Tickets.@~Doc.id]" ],
      "QueryParameters": {},
      "Body": {},
      "DataFormat": "Json",
      "DataPath": "comments"
    },
    {
      "Name": "Audits",
      "Public": "False",
      "Schema": "Http",
      "Method": "GET",
      "Base": "[@Settings.Parameters.uri]",
      "Path": "api/v2/tickets/{0}/audits.json",
      "Headers": {
        "Authorization": "Basic YWxleGV5LmF2cmFtZW5rb0BzaXNlbnNlLmNvbS90b2tlbjpTY09TbzNkR0k0UFJKbldQakZ2dTZxb1lqR3ZEWURRR1dFNnlkYlhG"
      },
      "PathParameters": [ "[@Tables.Tickets.@~Doc.id]" ],
      "QueryParameters": {},
      "Body": {},
      "DataFormat": "Json",
      "DataPath": "audits",
      "Transformation": {
        "ExcludeList": [
          "events.recipients",
          "events.attachments"
        ],
        "TransformTypes": [
          {
            "Name": "events.value",
            "Type": "String"
          },
          {
            "Name": "events.previous_value",
            "Type": "String"
          }
        ]
      }
    },
    {
      "Name": "Audits_Events",
      "Public": "False",
      "Schema": "Http",
      "Method": "GET",
      "Base": "[@Settings.Parameters.uri]",
      "Path": "api/v2/tickets/{0}/audits.json",
      "Headers": {
        "Authorization": "Basic YWxleGV5LmF2cmFtZW5rb0BzaXNlbnNlLmNvbS90b2tlbjpTY09TbzNkR0k0UFJKbldQakZ2dTZxb1lqR3ZEWURRR1dFNnlkYlhG"
      },
      "PathParameters": [ "[@Tables.Tickets.@~Doc.id]" ],
      "QueryParameters": {},
      "Body": {},
      "DataFormat": "Json",
      "DataPath": "audits",
      "Transformation": {
        "ExcludeList": [
          "recipients"
        ]
      }
    },
    {
      "Name": "Tickets",
      "Schema": "Https",
      "Method": "GET",
      "Base": "[@Settings.Parameters.uri]",
      "Path": "api/v2/tickets.json",
      "Headers": {
        "Authorization": "Basic YWxleGV5LmF2cmFtZW5rb0BzaXNlbnNlLmNvbS90b2tlbjpTY09TbzNkR0k0UFJKbldQakZ2dTZxb1lqR3ZEWURRR1dFNnlkYlhG"
      },
      "PathParameters": [],
      "QueryParameters": {},
      "Body": {},
      "DataFormat": "Json",
      "DataPath": "tickets",
      "PagingConfig": {
        "PageSize": "100",
        "NextPageURL": "next_page",
        "PagingMethod": "URL"
      },
      "Transformation": {
        "ExcludeList": [
          "tags"
        ],
        "TransformTypes": [
          {
            "Name": "created_at",
            "Type": "DateTime"
          },
          {
            "Name": "updated_at",
            "Type": "DateTime"
          }
        ],
        "LinkedTables": [
          {
            "Name": "Comments",
            "LinkedTableReference": "[@Tables.Comments.@~Doc.All]"
          },
          {
            "Name": "Audits",
            "LinkedTableReference": "[@Tables.Audits.@~Doc.All]"
          }
        ]
      }
    },
    {
      "Name": "Ticket_Metrics",
      "Schema": "Https",
      "Method": "GET",
      "Base": "[@Settings.Parameters.uri]",
      "Path": "api/v2/ticket_metrics.json",
      "Headers": {
        "Authorization": "Basic YWxleGV5LmF2cmFtZW5rb0BzaXNlbnNlLmNvbS90b2tlbjpTY09TbzNkR0k0UFJKbldQakZ2dTZxb1lqR3ZEWURRR1dFNnlkYlhG"
      },
      "PathParameters": [],
      "QueryParameters": {},
      "Body": {},
      "DataFormat": "Json",
      "DataPath": "ticket_metrics",
      "PagingConfig": {
        "PageSize": "100",
        "NextPageURL": "next_page",
        "PagingMethod": "URL"
      },
      "Transformation": {
        "TransformTypes": [
          {
            "Name": "created_at",
            "Type": "DateTime"
          },
          {
            "Name": "updated_at",
            "Type": "DateTime"
          },
          {
            "Name": "assignee_updated_at",
            "Type": "DateTime"
          },
          {
            "Name": "requester_updated_at",
            "Type": "DateTime"
          },
          {
            "Name": "status_updated_at",
            "Type": "DateTime"
          },
          {
            "Name": "initially_assigned_at",
            "Type": "DateTime"
          },
          {
            "Name": "assigned_at",
            "Type": "DateTime"
          },
          {
            "Name": "solved_at",
            "Type": "DateTime"
          },
          {
            "Name": "latest_comment_added_at",
            "Type": "DateTime"
          }
        ]
      }
    },
    {
      "Name": "Users",
      "Schema": "Https",
      "Method": "GET",
      "Base": "[@Settings.Parameters.uri]",
      "Path": "api/v2/users.json",
      "Headers": {
        "Authorization": "Basic YWxleGV5LmF2cmFtZW5rb0BzaXNlbnNlLmNvbS90b2tlbjpTY09TbzNkR0k0UFJKbldQakZ2dTZxb1lqR3ZEWURRR1dFNnlkYlhG"
      },
      "PathParameters": [],
      "QueryParameters": {},
      "Body": {},
      "DataFormat": "Json",
      "DataPath": "users",
      "PagingConfig": {
        "PageSize": "100",
        "NextPageURL": "next_page",
        "PagingMethod": "URL"
      },
      "Transformation": {
        "ExcludeList": [
          "photo"
        ],
        "TransformTypes": [
          {
            "Name": "created_at",
            "Type": "DateTime"
          },
          {
            "Name": "updated_at",
            "Type": "DateTime"
          },
          {
            "Name": "last_login_at",
            "Type": "DateTime"
          }
        ]
      }
    },
    {
      "Name": "Groups",
      "Schema": "Https",
      "Method": "GET",
      "Base": "[@Settings.Parameters.uri]",
      "Path": "api/v2/groups.json",
      "Headers": {
        "Authorization": "Basic YWxleGV5LmF2cmFtZW5rb0BzaXNlbnNlLmNvbS90b2tlbjpTY09TbzNkR0k0UFJKbldQakZ2dTZxb1lqR3ZEWURRR1dFNnlkYlhG"
      },
      "PathParameters": [],
      "QueryParameters": {},
      "Body": {},
      "DataFormat": "Json",
      "DataPath": "groups",
      "PagingConfig": {
        "PageSize": "100",
        "NextPageURL": "next_page",
        "PagingMethod": "URL"
      },
      "Transformation": {
        "TransformTypes": [
          {
            "Name": "created_at",
            "Type": "DateTime"
          },
          {
            "Name": "updated_at",
            "Type": "DateTime"
          }
        ]
      }
    },
    {
      "Name": "Organizations",
      "Schema": "Https",
      "Method": "GET",
      "Base": "[@Settings.Parameters.uri]",
      "Path": "api/v2/organizations.json",
      "Headers": {
        "Authorization": "Basic YWxleGV5LmF2cmFtZW5rb0BzaXNlbnNlLmNvbS90b2tlbjpTY09TbzNkR0k0UFJKbldQakZ2dTZxb1lqR3ZEWURRR1dFNnlkYlhG"
      },
      "PathParameters": [],
      "QueryParameters": {},
      "Body": {},
      "DataFormat": "Json",
      "DataPath": "organizations",
      "PagingConfig": {
        "PageSize": "100",
        "NextPageURL": "next_page",
        "PagingMethod": "URL"
      },
      "Transformation": {
        "TransformTypes": [
          {
            "Name": "created_at",
            "Type": "DateTime"
          },
          {
            "Name": "updated_at",
            "Type": "DateTime"
          }
        ]
      }
    }
  ]
}


 

 
  • No labels