Zendesk Plugin Setup Guide
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
Updated 6 days ago