What's in this guide?

This guide is for Developers, Agencies, IT administrators, or other technical resources responsible for deploying your Omneo Zendesk Plugin instance.
Before you begin, you will need a copy of the source code, obtained from your Omneo Administrator.

This guide walks through the standard setup procedure for the Omneo Zendesk plugin.
This plugin is a standard Laravel app, that can be configured with a few steps.

For a brief overview of the purpose of this application, please review the helpcenter article.
In short, this plugin allows Omneo data to be viewed within Zendesk.
The plugin also syncs profiles, and creates interactions based on Zendesk tickets.

Prerequisites

Before installing the plugin, you will need:

From Omneo:

Omneo Domain
Omneo Token
Omneo Shared Secret

From Zendesk

Zendesk Subdomain
Zendesk Token
Zendesk Username
Zendesk Shared Secret

From Omneo

Omneo domain

This takes the form of example.omneoapp.io and is where your Omneo installation lives. If you login to your dashboard at foo.dashboard.omneo.io, your Omneo domain is foo.omneoapp.io

Omneo token

This is the secure token which identifies you to the API. It can be generated from the Omneo dashboard and is associated with your user account. It is advisable that you create a separate Omneo user specifically for your integration. You will need the following scopes.

create-webhooks Required during the install process to create inbound webhooks
delete-webhooks Required during the install process to purge old webhooks
read-tenants Required to read config via custom fields on the tenant
update-tenants Required during the install process to write config via custom fields on the tenant
update-profiles Required to write the Zendesk ID to a profile
create-interactions Required to create interactions from Zendesk events

Shared secret

You can obtain this secret from within your Omneo dashboard. It is used to verify that it is indeed Omneo sending webhook requests.

From Zendesk

Zendesk subdomain

This is the part in your Zendesk domain before the zendesk.com part. For example, if you login to Zendesk at foobar.zendesk.com, your subdomain is foobar.

Zendesk username

Username of the account through which you want the plugin to interact with Zendesk. You should ideally create a new Zendesk account just for this plugin.

Zendesk token

API token attached to the Zendesk account. This can be obtained from the Zendesk dashboard.

Zendesk shared secret

This is a secret which we configure Zendesk to use when sending webhook requests. It is not generated by Zendesk but is chosen by you, the installer of the Omneo Zendesk plugin when you run the install process.

Installation

Due to the lack of dependencies, installation is straight forward.

Upload plugin to a web server
Upload the contents of this repository to a web server. Remember to set your public directory to /public as with any other Laravel app.
Install Composer dependencies
composer install
Configure Omneo credentials
If using Elastic Beanstalk or other hosting platform which supports environment variables, you should configure the following from within the configuration interface.
If your platform does not support environment variables, copy .env.example to .env and configure them there.
APP_URL
OMNEO_DOMAIN
OMNEO_TOKEN
OMNEO_SECRET
Run installation command
Run the installation command and follow the instructions. This process will ask for your Zendesk configuration details and set up the various required processes within Omneo and Zendesk.

You are free to run this command as many times as you like.

php artisan install

Contributing

Running locally

Docker can be used to quickly get the project up and running locally.

Install Docker

Run docker-compose up in the project directory
Follow the installation steps above
Send requests to http://localhost:8080

Testing

Testing is handled using phpunit. To run the tests simply run phpunit in the project directory.
phpunit

Deployment

GCP Deployment

To deploy this into a GCP tenancy both the .circleci/config.yml pipeline file needs to contain a tenant specific deployment step, and CircleCI needs the following additional environment variables in the Context https://circleci.com/gh/organizations/omneo/settings#contexts corresponding to the tenant.

CircleCI Tenant Context Environment Variables:

PLUGIN_ZENDESK_APP_KEY The APP_KEY Environment Laravel Encryption Key - This key is used by the Illuminate encrypter service and should be set to a random, 32 character string, otherwise these encrypted strings will not be safe.
PLUGIN_ZENDESK_OMNEO_TOKEN The Omneo token for this plugin
For access to source code contact your Omneo Implementation Partner