Omneo for Zendesk App - Developer Guide

Prerequisites

Before installing the plugin, you will need to get your hands on the following.

Omneo credentials

  • 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.

Zendesk credentials

  • 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.

1. 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.

2. Install Composer dependencies

composer install

3. 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

4. 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.

  1. Install Docker
  2. Run docker-compose up in the project directory
  3. Follow the installation steps above
  4. 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

Additional reading: 

What is Clienteling? 

Introducing Clienteling for Zendesk App