Second installment of our series on FileMaker integration with Web Services. Check the Intro and the first article about the Dropbox API if you’ve missed them.
Zendesk
This week we’ll have a look at the Zendesk API. If you’re new to Zendesk, it is a customer service software and support ticket system. At Goya we use it for all our support on both the BaseElements plugin and RESTfm.
When someone has a question or an inventive use for one of our products, they jump on Zendesk and create a ticket. Sometimes even the best developers need advice.
To allow that we need to add them to our support when they sign up for the sponsorship program. Doing it manually is repetitive and prone to error, and we are developers, so we’ve automated the process using the Zendesk API.
Like we do with Dropbox, we use the BaseElements plugin to do HTTP calls in a FileMaker script. If the terminology is new or you want to refresh your understanding of Web Services, the links in the Intro are a good starting pooint.
The requests we want to send to Zendesk are of two types:
- retrieve the list of users already signed up
- add a new user to the support system
To execute these requests we need to know what type of action they are (in HTTP terms the type of action is called “verb”), where we need to send them (the url or endpoint) and what parameters are necessary (body).
The first request translates to a HTTP GET verb (retrieving data) while the second one is a HTTP POST (send data).
The base url for the Zendesk API is
https://{subdomain}.zendesk.com/api/v2/
(ie https://baseelementsplugin.zendesk.com/api/v2/).
To test the code in this article and run the demo you will need a Zendesk subdomain, if you don’t have one you can create a trial one.
Before actually calling them we need to authenticate ourselves to the API. Zendesk accepts both OAuth and Basic Authentication. An example of a Token in the headers was covered in the previous article about Dropbox so this time we’ll use the basic username and password integration, but still using a Token to protect our real password.
Authentication
To generate a Token in the Zendesk API we need to go to the Settings page (only accessible to Agents or Owners of the channel):
https://{subdomain}.zendesk.com/agent/admin/api/settings
and enable the Token Access
Once we obtain a token, this is associated to the email address we use to log in to Zendesk and we will be able to pass them to the BaseElements plugin functions like this:
BE_HTTP_POST ( url ; body ; email & "/token" ; token )
Get the Users list
To retrieve all the existing users on our Zendesk channel, we can use the users.json,/code> endpoint. The full url will look like https://{subdomain}.zendesk.com/api/v2/users.json.
The request can be filtered to obtain only users with specific roles but in our case we want everyone, so the body of our request will be empty.
The following puts all the parts together (authentication, verb, endpoint, body) and uses the BaseElements plugin function BE_HTTP_GET to call the API:
BE_HTTP_GET ( "https://{subdomain}.zendesk.com/api/v2/users.json" ; "" ; email & "/token" ; token )
If our request is successful the response JSON will contain nodes for each one of the support users
{
"users": [
{
"id": 1234567,
"name": "Salvatore Colangelo",
...
},
{
"id": 7654321,
"name": "Nicholas Orr",
...
}
]
}To generate records in our database we can extract the data parsing the JSON using the function BE_JSONPath:
BE_JSONPath ( $json ; "$.users[0].name" ) applied to the JSON example above will return "Salvatore Colangelo".
Add a new user
Having a list that we can manage from FileMaker is useful, but our main goal is to add a new sponsor to the support system. The Zendesk API gives us a flexible endpoint that can be used both for creating a new user or to update an existing one
https://{subdomain}.zendesk.com//api/v2/users/create_or_update.json
This time we are sending data to Zendesk so we'll have to populate the body of our request. The parameters the API expect are the name of the new user, their email address and if necessary we can specify a role for the new user. If we don't specify one (our case) they will be assigned the end-user role.
The body of the request to add the user Nicholas Orr as an end user to the support is
{
"user":
{
"name": "Nicholas Orr",
"email": "nick@example.org"
}
}As said earlier this request is a HTTP POST so we'll use BE_HTTP_POST to send it
BE_HTTP_POST( https://{subdomain}.zendesk.com//api/v2/users/create_or_update.json ; {"user": {"name": "Nicholas Orr", "email": "nick@example.org"}} ; email & "/token" ; token )
So now Nick will be able to ask everything he wants to know about the plugin!
The Zendesk API can be used for tasks a lot more complex than this (we have clients creating tickets and updating them all from FileMakers) but the basics are the same explained in this article. Send us questions if you find an interesting endpoint you want to use.
Like last week, a complete example file (along with the Dropbox one) is available to sponsors of the BaseElements plugin, in the folder we share via the Dropbox API.
Now that we have shared the folder and linked the users to support, it's time to add them to our mailing list. Next week: FileMaker and Mailchimp.
Salvatore is our web services and integration expert, passionate about linking any API useful to our clients (or us!) to FileMaker. He loves to share ideas and a good story, and as a speaker at DevCon he manages to do both.