killbill-zendesk-plugin

Plugin to mirror Kill Bill data into Zendesk.

Release builds are available on Maven Central with coordinates org.kill-bill.billing.plugin.ruby:zendesk-plugin.

Kill Bill compatibility

Plugin version	Kill Bill version
2.x.y	0.16.z
3.x.y	0.18.z

User data mapping

Zendesk attribute	Value
name	Kill Bill account name
external_id	Kill Bill account external key if specified, Kill Bill account id otherwise
locale	Kill Bill account locale
time_zone	Kill Bill account timezone
email	Kill Bill account email
phone	Kill Bill account phone
details	Kill Bill account address1, Kill Bill account address2, Kill Bill account city, Kill Bill account state or province, Kill Bill account postal code, Kill Bill account country

Usage

The plugin will automcatically listen to all account events (creation or update), and create or update the associated user in Zendesk.

If you need to trigger a refresh manually, the plugin exposes the following endpoint:

curl -v \
     -d'webrick=stupid' \
     -XPUT \
     "http://$HOST:8080/plugins/killbill-zendesk/users/<kb account id or kb external key>"

Given a Kill Bill account id or Zendesk user id, you can retrieve the Kill Bill - Zendesk mapping via:

curl -v \
     "http://$HOST:8080/plugins/killbill-zendesk/users/<kb account id or kb external key>"

Requirements

The plugin needs a database to keep a local mapping between Kill Bill account ids and Zendesk user ids (this is to work around indexing delays in Zendesk). The latest version of the schema can be found here.

Configuration

The plugin expects a zendesk.yml configuration file containing the following:

• If you are using username / password authentication:

curl -v \
     -X POST \
     -u admin:password \
     -H 'X-Killbill-ApiKey: bob' \
     -H 'X-Killbill-ApiSecret: lazar' \
     -H 'X-Killbill-CreatedBy: admin' \
     -H 'Content-Type: text/plain' \
     -d ':zendesk:
  :subdomain: 'mysubdomain'
  :username: 'email@domain.com'
  :password: 'password'
# Optional
#  :retry: true' \
     http://127.0.0.1:8080/1.0/kb/tenants/uploadPluginConfig/killbill-zendesk

• If you are using Token Authentication:

curl -v \
     -X POST \
     -u admin:password \
     -H 'X-Killbill-ApiKey: bob' \
     -H 'X-Killbill-ApiSecret: lazar' \
     -H 'X-Killbill-CreatedBy: admin' \
     -H 'Content-Type: text/plain' \
     -d ':zendesk:
  :subdomain: 'mysubdomain'
  :username: 'email@domain.com'
  :token: 'kX53RIXZKUFhZxSYhRxe7QGFocTkDmmERDxpcddF' 
# Optional
#  :retry: true' \
     http://127.0.0.1:8080/1.0/kb/tenants/uploadPluginConfig/killbill-zendesk

• If you are using OAuth:

curl -v \
     -X POST \
     -u admin:password \
     -H 'X-Killbill-ApiKey: bob' \
     -H 'X-Killbill-ApiSecret: lazar' \
     -H 'X-Killbill-CreatedBy: admin' \
     -H 'Content-Type: text/plain' \
     -d ':zendesk:
  :subdomain: 'mysubdomain'
  :username: 'email@domain.com'
  :access_token: 'kX53RIXZKUFhZxSYhRxe7QGFocTkDmmERDxpcddF'
# Optional
#  :retry: true' \
     http://127.0.0.1:8080/1.0/kb/tenants/uploadPluginConfig/killbill-zendesk