otoyo/zen_ex

Zendesk REST API client for Elixir

zen_ex

Zendesk REST API client for Elixir

zen_ex is composed of Models and Entities. See Usage.

Installation

Add zen_ex to your list of dependencies in mix.exs:

def deps do
  [{:zen_ex, "~> 0.8.0"}]
end

Update your dependencies:

% mix deps.get

Add your Zendesk settings to your config:

config :zen_ex,
  subdomain: System.get_env("ZENDESK_SUBDOMAIN"),
  user: System.get_env("ZENDESK_USER_EMAIL"),
  api_token: System.get_env("ZENDESK_API_TOKEN")

And set above environment variables.

See also: Generating a new API token

Usage

# List users
{:ok, %{entities: users}} = ZenEx.Model.User.list()

# Show user
{:ok, user} = ZenEx.Model.User.show(1)

# Create user
{:ok, user} = ZenEx.Model.User.create(%ZenEx.Entity.User{name: "otoyo", email: "[email protected]"})

# Paginate tickets
{:ok, collection} = ZenEx.Model.Ticket.list(per_page: 100, sort_order: "desc")
tickets = collection.entities
next_tickets = collection |> ZenEx.Collection.next

# Show ticket
{:ok, %{entities: ticket}} = ZenEx.Model.Ticket.show(1)

# Create ticket
{:ok, ticket} = ZenEx.Model.Ticket.create(%ZenEx.Entity.Ticket{subject: "My printer is on fire!", description: "But no problem."})

See also under ZenEx.Model.

Supporting multiple Zendesk configs

You may need to interact with more than one instance of Zendesk. In order to facilitate that there is a small override that can be put into the Process dictionary that will tell it to look for config settings keyed against a class name.

For details...

For example:

config/config.exs

config :zen_ex,
  subdomain: System.get_env("ZENDESK_SUBDOMAIN"),
  user: System.get_env("ZENDESK_USER_EMAIL"),
  api_token: System.get_env("ZENDESK_API_TOKEN")

config :zen_ex, ZendeskAlt,
  subdomain: System.get_env("ZENDESK_ALT_SUBDOMAIN"),
  user: System.get_env("ZENDESK_ALT_USER_EMAIL"),
  api_token: System.get_env("ZENDESK_ALT_API_TOKEN")

Then whenever you want to use the alternate config, before using anything in the zen_ex library make sure to add a line of code like the following:

Process.put(:zendesk_config_module, ZendeskAlt)

Anytime you use the zendesk library after that it will use the alternate config until you remove that process dictionary entry. It is good practice to put it back when you are done.

Process.put(:zendesk_config_module, nil)

If you do not add a :zendesk_config_module key to the Process dictionary then it will continue to use the default zen_ex config settings.

Supported API

Capabilities	Entities
Ticketing	Users
	User Identities
	Tickets
	Dynamic Content Items
	Dynamic Content Item Variants
	Locales
	Job Statuses
Help Center	Categories
	Sections
	Articles
	Translations

Contribution

Please make an Issue or PR.

zen_ex's Issues

Spec for ZenEx.Model.Ticket.Show does not include `nil` return type

Great library - enjoying it so far.

I did find one tiny issue that's throwing me some Dialyzer warnings. The spec on line 35 for ZenEx.Model.Ticket.Show does not account for nil. I think that's because HTTPotion's spec for get doesn't include that possibility, either.

Unfortunately, it's possible to get a nil when the element doesn't exist on Zendesk:

iex(1)> ZenEx.Model.Ticket.show(-123)
nil

That also rings true for Locale and User:

iex(2)> ZenEx.Model.User.show(-123)
nil
iex(3)> ZenEx.Model.Locale.show(1231238129321381293912389)
nil

I can submit a quick PR that adds the nil return type for the specs and link it here if that works.

Don't ignore the HTTP status code

Context

• zendesk developers | Introduction | Requests

  Status codes

  Responses may have the status codes described in the following sections.

  200 range

  400 range

  500 range

• zendesk developers | Ticketing | MANAGING TICKETS | Creating and updating tickets | Protecting against ticket update collisions
  • describes a valid use case where the HTTP status code of 409 can be expected and should properly be handled.
  • This is also linked from the API Reference | TICKETS | Update Ticket
• zendesk developers | Introductions | Rate limits | Monitoring your request activity

  If the rate limit is exceeded, the API responds with a HTTP 429 Too Many Requests response code and a body that details the reason for the rate limiter kicking in. The response has a Retry-After header that tells you for how many seconds to wait before retrying.

Problem

Current behavior:

Mix.install([
  {:poison, "~> 3.1"},
  {:tesla, "~> 1.4.4"},
  {:zen_ex, "~> 0.7.0"}
])

import ZenEx.HTTPClient, only: [_build_entity: 2]
alias Tesla.Env
alias ZenEx.Entity.Ticket

decode_as = [ticket: Ticket]
status = 409
body = """
{
  "description": "Safe Update prevented the update due to outdated ticket data.
                   Please fetch the latest ticket data and try again.",
  "error": "UpdateConflict"
}
"""
response = %Env{body: body, status: status}
response |> _build_entity(decode_as)
# => nil

returns nothing

Expected

In order to troubleshoot and properly handle non 200-range errors, I want to know the HTTP status code and the raw response body

Problem during ticket creation with gzip compression

While ticket creation:
ZenEx.Model.Ticket.create(%ZenEx.Entity.Ticket{subject: "TestTicket", description: "Please ignore it."})

I'm getting error:

  body: %{
    "error" => "Unprocessable Entity",
    "message" => "Server could not parse JSON"
  },

I found that problem is related to Tesla.Middleware.Compression on https://github.com/otoyo/zen_ex/blob/main/lib/zen_ex/http_client.ex#L11

Without this middleware - ticket was created successfully.
Can you remove this middleware, or make it optional?
Thanks

Ticket creation

Suggestion to extend TicketEntry:

• to support requestor fields

%TicketEntry{
...
  requester: %{
          name
          email
  }
}

• also good to have ability add html version of comment

%TicketEntry{
...
  comment: %{
        html_body: html_body
   }
}

Searching users is broken for our Zendesk instance

Hello,

Thank you for sharing your work, ZenEx is really useful and straightforward to use 👍.

I'm having an issue when searching users. For instance running:

iex> ZenEx.Model.User.search(%{email: "[email protected]"})
%ZenEx.Collection{
  count: 1,
  decode_as: [users: [ZenEx.Entity.User]],
  entities: nil,
  next_page: nil,
  previous_page: nil
}

should have :entities set. But it doesn't because the JSON payload returned contains the list of users found in the :users key instead of :results:

GET https://subdomain.zendesk.com/api/v2/users/search.json?query=test

{
    "users": [
        {
            "id": 422109096513,
            "url": "https://subdomain.zendesk.com/api/v2/users/422109096513.json",
            ...
        }
    ],
    "next_page": null,
    "previous_page": null,
    "count": 1
}

I've temporarily fixed it for us by updating ZenEx.Model.User.search/2 to:

  def search(query) do
    "/api/v2/users/search.json?query=#{query}"
    |> HTTPClient.get(users: [User])
  end

Cheers,

Mathieu

Contributing to ZenEx

Howdy @otoyo 👋 We've recently adopted Zendesk at System76 and want to leverage this library in our integration. As it stands it is missing a few endpoints we need. We'd like to contribute those changes in addition to some other minor changes, but before opening up a bunch of PRs we thought we'd talk through the changes we're making in our fork:

1. We're adding endpoints for Organizations, OrganizationMembers, and Identities. We have others on the horizon we'll be including.
2. Migrating to Finch in place of HTTPoison now that the latter is deprecated
3. Setting up GitHub Actions for mix format, test, and credo.
4. Expanding test coverage by using Mox at the HTTP layer

Are any of these changes thing you would be interested in having upstream?

Typespec errors

Thanks for providing some typespec information, although I'm not sure if I can trust them, as Dialyzer shows a lot of errors. It would be awesome to get them resolved.

Don't assume JSON response

Context

According to the ZenDesk documentation (and my own real-life observations):
zendesk developers | Introduction | Requests

You may get a text/plain response in case of an error like a bad request. You should treat this as an error you need to fix.

Problem

The current behavior:

Mix.install([
  {:poison, "~> 3.1"},
  {:tesla, "~> 1.4.4"},
  {:zen_ex, "~> 0.7.0"}
])

import ZenEx.HTTPClient, only: [_build_entity: 2]
alias Tesla.Env
alias ZenEx.Entity.Ticket

decode_as = [ticket: Ticket]
status = 400
body = "<html><body>Error: Foo</body></html>"
response = %Env{body: body, status: status}

response |> _build_entity(decode_as)

which returns the exception:

** (Poison.SyntaxError) Unexpected token at position 0: <
    (poison 3.1.0) lib/poison/parser.ex:57: Poison.Parser.parse!/2
    (poison 3.1.0) lib/poison.ex:83: Poison.decode!/2
    (zen_ex 0.7.0) lib/zen_ex/http_client.ex:77: ZenEx.HTTPClient._build_entity/2

Expected

In order to troubleshoot and fix the error, I want to know the HTTP status code and the raw response body in a {:error, reason} response, eg:

{:error, "Unexpected response with HTTP status code 400 and body: \"<html><body>Error: Foo</body></html>\""}

API supported params aren't being passed

I'm not able to pass params such as "role" to the User model
users = ZenEx.Model.User.list(role: "agent").entities
which is supported by the API
https://developer.zendesk.com/rest_api/docs/core/users#filters

It looks like ZenEx.Query.build only allows a few params
@params [:ids, :per_page, :sort_order]

Any way that limitation could be removed, so any filters passed, get passed through to the API?
I can create a PR, but wanted to check first

Httpotion dependency no longer maintained

According to https://hex.pm/packages/httpotion, the httpotion package is deprecated. Httpotion is a dependency of zen_ex.