Zendesk Sell App is an application written for Zapier Platform which utilizes Zendesk Sell Public API for building Zap workflows. Zendesk Sell App exposes mutliple triggers, actions and searches to allow users build integrations between different applications on their own. Zapier combines Triggers (like New Lead) and Actions (like Create Note) to perform an action in one app when a trigger occurs in another app.

Zendesk Sell (formerly Base) is a sales automation tool to enhance productivity, processes, and pipeline visibility for sales teams.

Zapier is a tool that allows you to connect the apps you use every day in order to automate tasks and save time. You can connect any of 1,400+ integrated apps together to make your own automations. Check this guide to better understand how Zapier works and how the building blocks like trigger, action, zap are used below.

Zendesk Sell App requires Node.js v8.10.0 (this is the version of Node which is used in Zapier infrastructure). You can develop using any version of Node you'd like, but your eventual code must be compatible with v8.10.0. You can simply download proper node environment using nvm. Additionally, yarn is used as a package manager so it has to be installed before going further.

git clone [email protected]:zendesk/zendesk-sell-for-zapier.git && cd zendesk-sell-for-zapier/
nvm use && yarn install

You are ready to install Zapier Platform CLI which is your gateway to creating applications in Zapier platform and connecting your Zapier account.

# Install the Zapier Platform CLI globally
yarn global add zapier-platform-cli

# Authorize Zapier to use your account's credentials
zapier login

Now it's time to connect your local copy of Zendesk Sell App to Zapier platform.

# Link your working directory with existing CLI application
zapier link

# or register new one in Zapier platform
zapier register "Zendesk Sell App"

Details about zapier command and its features can be found here.

Zendesk Sell App is written using TypeScript which requires code to be compiled before being validated or pushed to Zapier Platform. I recommend using predefined commands from package.json which always perform compilation (e.g. before uploading or running tests), this makes sure tests are being run on your current version.

If you want to build it on your own you can use:

# Compiles application on demand
yarn run build

# Starts ts compiler in watch mode
yarn run build-dev

The project has TSLint rules defined in tslint.json file so you can simply validate and fix your code using:

yarn run lint-fix

You can run all tests using the command shown below. The Runner will perform Zapier Validation to check if project is semantically correct (triggers/actions/searches are properly configured and attached to application) and then start executing unit tests with jest. (zapier-test will perform TypeScript compilation for you)

yarn run zapier-test

If you tests are passing and the codebase validation succeeds, we can move forward to the deployment

Zapier Apps become "immutable" after deployment which means that if we want to introduce changes we have to do it in a new version, deploy the application and then migrate users to new version if everything works. If this is your first deployment of Zendesk Sell App please check if OAuth2 is properly set up and environment variables are set. Detailed descriptions of Zapier deployments can be found here.

Let's assume that the current version of application is 1.0.0, we made some backward compatible changes and want to deploy them to the Zapier Platform to make them available for all users (if changes are not backward compatible you cannot migrate users to the new version, because it would corrupt their Zaps). We use Github actions which are defined in actions.yml file. When you create PR they will be triggered automatically.

This is how it looks like step by step:

• Replace version entry in package.json with next minor version 1.0.1
• Github action will run tests and push application, at this point Application is published, but all users are still using previous version
• Migrate test account to run tests and manually double check if everything works zapier migrate 1.0.0 1.0.1 [email protected]
• Migrate Sulik account to new version of application using this command zapier migrate 1.0.0 1.0.1 --user=[email protected]
• Run Suliks manually from here
• If you want to perform manual tests (and you have account in Zapier which has Zendesk Sell Application assigned) you can go to Zapier Editor and you should be able to use new version
• If application is private you have to promote it first zapier promote 1.0.1
• Migrate all the users to the newer version zapier migrate 1.0.0 1.0.1 100%
• The last two steps can be done from UI on Zapier developer site on versions menu:

All commands in one place:

export CURRENT_VERSION=1.0.0
export NEXT_VERSION=1.0.1

yarn run zapier-test && yarn run zapier-push
zapier migrate $CURRENT_VERSION $NEXT_VERSION [email protected]
zapier promote $NEXT_VERSION
zapier migrate $CURRENT_VERSION $NEXT_VERSION 100%

The index.ts is Zapier's entry point to the application, you can find declarations of all triggers, actions and searches there, which means that all operations defined there (unless they are hidden: true) will be visible to users and can be used while creating Zap flows. Actions, triggers and searches are stored per resource type (e.g. all operations related to deal can be found in deal/ directory), to make them more distinguishable actions has .action.ts suffix, triggers .trigger.ts and so on.

$ tree .
.
├── README.md
├── CHANGELOG.md
├── index.js
├── package.json
├── src
│    ├── auth
│    ├── common
│    ├── contact
│    ├── deal
│    ├── lead
│    ├── notesTasks
│    ├── products
│    ├── users
│    ├── utils
│    ├── index.ts
│    └── ...
├── build
│   └── build.zip
├── lib
│   └── ...
└── node_modules

Description of main directories in repository:

• src - sources and tests of all items that are present at runtime
  • auth - OAuth2 configuration for Zendesk Sell Public API
  • common - logic responsible for handling resources used in multiple places (e.g. custom fields, industry, tags etc). Also contains helpers for fetching and saving resources using Zendesk Sell Public API
  • contact, deal, lead, notesTasks, products - triggers, actions and searches related to specific resources
  • utils - helper utils for handling API requests, extracting data from envelopes, parsing errors, mocking Zapier Platform objects within tests etc.
  • index.ts - Zendesk Sell App entry point
• lib - contains ES5 files generateD by TypeScript compiler
• build - contains zips generateD by Zapier Platform CLI which will be uploaded during yarn zapier-push

Zendesk Sell App uses 3-legged OAuth2 flow which requires developer application to be defined on Zendesk Sell side. Details on how OAuth2 is implemented can be found here. In case of any problems with OAuth2, please verify if Redirect URL, ClientId and ClientSecret values are correct.

First, we need to set up developer application in Zendesk Sell to enable OAuth2 flow for application.

Login to your Zendesk Sell account and then go to: Settings -> OAuth2 -> Developer Apps (or use this link) and create a new developer application

Inputs:

• website - https://zapier.com
• redirect url - see below
• terms of service - https://zapier.com/legal
• logo - https://drive.google.com/file/d/1FtIASmDlXzyBlTmgcE1Yj2nou2QsRp2K/view?usp=sharing

RedirectUrl is generated immediately after uploading application into Zapier Platform (yarn run zapier-push), you can obtain it by typing: zapier describe --format=json | grep 'Redirect URI'

After creating Developer App on Zendesk Sell side you will get client_id and client_secret which have to be passed to Zapier application to allow authorization using OAuth2

zapier env <application_version> CLIENT_ID <value from devloper app>
zapier env <application_version> CLIENT_SECRET <value from devloper app>

• Mateusz Sękara (mateusz-sekara)
• Radosław Przebieglec (rprzebieglec)

Copyright 2019 Zendesk

Licensed under the Apache License, Version 2.0