lukeburden/django-zengo

A webhook processor and database cache for Zendesk users and tickets

Integrate Zendesk Support into your Django app

django-zengo

django-zengo is a Django app that provides conveniences for integrating with Zendesk.

It facilitates receiving webhook updates from Zendesk, detecting new tickets and changes to existing tickets.

Installation

pip install django-zengo

Usage

Configuring the webhook

Zengo comes with a view that processes messages sent by Zendesk and allows you to perform actions upon various Zendesk events.

Expose zengo.views.WebhookView

You need to configure your application to receive the webhook. To do so simply include it in your URL conf:

from django.contrib import admin
from django.urls import path

from zengo.views import WebhookView

urlpatterns = [
    path('admin/', admin.site.urls),
    path('zengo/webhook/', WebhookView.as_view())
]

Add required bits to settings.py

You need to tell Zengo how to authenticate with Zendesk:

• ZENDESK_EMAIL is the email of the Zendesk account you will use to interact with the API.
• ZENDESK_TOKEN generated for the user above in the Zendesk web interface.
• ZENDESK_SUBDOMAIN must match the subdomain used in your Zendesk account.

As seen below, you need to specify And you need to set a shared secret so that the webhook view can trust incoming messages from Zendesk:

• ZENGO_WEBHOOK_SECRET generated by your good self; make it long and random!

So, your settings should appear something along the lines of:

ZENDESK_EMAIL = "[email protected]"
ZENDESK_TOKEN = "<token-from-zendesk-webui>"
ZENDESK_SUBDOMAIN = "example"

ZENGO_WEBHOOK_SECRET = "<replace-me-with-a-great-password>"

Configure Zendesk to send events

Zendesk allows for many integrations, but for the purposes of Zengo we just need to be told when a ticket has been changed.

Log in as an administrator in Zendesk, and visit Settings > Extensions > Targets > add target > HTTP target.

Add an HTTP target with a URL of your service, and choose the POST method. Ensure you've added a secret query parameter to the URL where your webhook is accessible, such that the webhook view can authorize Zendesk's webhook sends.

Next, you must configure a trigger to use the target. Visit Business Rules > Triggers > Add trigger. Add a condition that suits your needs, such as, Ticket is updated, or Ticket is created, and select an action of Notify target, selecting the previously configured target. For JSON body, enter the following:

{
    "id": "{{ ticket.id }}"
}

You're done! Now whenever a ticket is created or updated in Zendesk, you should have an event being processed in your application.

Note: for development, I recommend using the excellent ngrok to proxy requests through to your localhost.

Performing actions upon receiving Zendesk events

When Zengo receives a webhook from Zendesk, it will fetch the latest state of the ticket from Zendesk's APIs, compare how this differs to the state in the local database models, and fire a signal indicating what has happened. In your application, you attach receivers to the signal that is most relevant to your need.

from django.dispatch import receiver

from zengo.signals import ticket_created


@receiver(ticket_created)
def handle_new_ticket(sender, ticket, context, **kwargs):
    # perform your custom action here
    pass

Signals

You can connect to the following signals.

• zengo.signals.ticket_created - fires when a ticket is encountered for the first time.
• zengo.signals.ticket_updated - fires when a ticket previously encountered is changed, or has a new comment added.

Contribute

django-zengo supports a variety of Python and Django versions. It's best if you test each one of these before committing. Our Circle CI Integration will test these when you push but knowing before you commit prevents from having to do a lot of extra commits to get the build to pass.

Environment Setup

In order to easily test on all these Pythons and run the exact same thing that CI will execute you'll want to setup pyenv and install the Python versions outlined in tox.ini.

If you are on Mac OS X, it's recommended you use brew. After installing brew run:

$ brew install pyenv pyenv-virtualenv pyenv-virtualenvwrapper

Then:

pyenv install -s 3.6.10
pyenv install -s 3.7.6
pyenv install -s 3.8.1
pyenv virtualenv zengo 3.8.1
pyenv shell zengo 3.6.10 3.7.6
pip install detox

To run the test suite:

$ detox

django-zengo's Issues

Having trouble with users while listening to tickets being created

Getting the error Invalid field name(s) for model ZendeskUser: 'user'. for every ticket.

Here is the full traceback:

`\apps\zengo\views.py, line 39, in post
        if not self.validate_secret():
            return HttpResponseForbidden(strings.secret_missing_or_wrong)
        processor = get_processor()
        try:
            event = processor.store_event(request.body.decode("utf-8"))
        except ValidationError as ve:
            return HttpResponseBadRequest(ve.message)
        processor.begin_processing_event(event) …
        return HttpResponse()

\apps\zengo\service.py, line 360, in begin_processing_event
            raise ValidationError(strings.data_no_ticket_id)
        event.remote_ticket_id = data["id"]
        event.save(update_fields=("remote_ticket_id", "updated_at"))
        return event
    def begin_processing_event(self, event):
        return self.process_event_and_record_errors(event) …
    def process_event_and_record_errors(self, event):
        try:
            # potentially serialize processing per-ticket such that there isn't
            # doubling up on signals firing
            with self.acquire_ticket_lock(event.remote_ticket_id):

\apps\zengo\service.py, line 367, in process_event_and_record_errors
        return self.process_event_and_record_errors(event)
    def process_event_and_record_errors(self, event):
        try:
            # potentially serialize processing per-ticket such that there isn't
            # doubling up on signals firing
            with self.acquire_ticket_lock(event.remote_ticket_id):
                self.process_event(event) …
        except Exception:
            logger.exception(
                "Failed to process Zendesk event",
                extra=dict(
                    event_id=event.id,

\zengo\service.py, line 399, in process_event
        # take a snapshot of the ticket and its comments in their old state
        pre_sync_ticket = models.Ticket.objects.filter(zendesk_id=ticket_id).first()
        pre_sync_comments = []
        if pre_sync_ticket:
            pre_sync_comments = list(pre_sync_ticket.comments.all())
        post_sync_ticket, created = get_service().sync_ticket_id(ticket_id) …
        post_sync_comments = list(post_sync_ticket.comments.all())
        # build update context for passing downstream
        update_context = {
            "pre_ticket": pre_sync_ticket,

\apps\zengo\service.py, line 219, in sync_ticket_id
                # store their latest photo JSON data
                photos_json=json.dumps(remote_zd_user.photo),
            ),
        )
        return instance
    def sync_ticket_id(self, ticket_id):
        return self.sync_ticket(self.client.tickets(id=ticket_id)) …
    def sync_ticket(self, remote_zd_ticket):
        """
        Create or update local representations of a Zendesk ticket, its comments
        and all associated Zendesk users.

\apps\zengo\service.py, line 249, in sync_ticket
            [remote_zd_ticket.requester]
            + [c.author for c in remote_comments if c.author_id != -1]  # noqa
        )
        users = list(users)
        users.sort(key=lambda u: u.id)
        # sync the users and establish a mapping to local records
        user_map = {u: self.sync_user(u) for u in users} …
        defaults = dict(
            requester=user_map[remote_zd_ticket.requester],
            subject=remote_zd_ticket.subject,
            url=remote_zd_ticket.url,
            status=models.Ticket.states.by_id.get(remote_zd_ticket.status.lower()),

\apps\zengo\service.py, line 249, in <dictcomp>
            [remote_zd_ticket.requester]
            + [c.author for c in remote_comments if c.author_id != -1]  # noqa
        )
        users = list(users)
        users.sort(key=lambda u: u.id)
        # sync the users and establish a mapping to local records
        user_map = {u: self.sync_user(u) for u in users} …
        defaults = dict(
            requester=user_map[remote_zd_ticket.requester],
            subject=remote_zd_ticket.subject,
            url=remote_zd_ticket.url,
            status=models.Ticket.states.by_id.get(remote_zd_ticket.status.lower()),

\apps\zengo\service.py, line 201, in sync_user
            remote_zd_user = self.create_remote_zd_user_for_local_user(local_user)
        return remote_zd_user
    def sync_user(self, remote_zd_user):
        """
        Given a RemoteZendeskUser instance, persist it as a local ZendeskUser instance.
        """
        instance, created = models.ZendeskUser.objects.update_or_create( …
            zendesk_id=remote_zd_user.id,
            defaults=dict(
                # attempt to resolve the local user if possible
                user=self.get_local_user_for_external_id(remote_zd_user.external_id),
                alias=remote_zd_user.alias,
                email=remote_zd_user.email,`

CircleCi Status Badge

You need to generate badge according to your master branch.