Our Dropzone Connector for Zendesk allows you to integrate your SendSafely Hosted Dropzone with Zendesk. The Connector is available to subscribers on SendSafely Business and Enterprise plans. Once configured, the connector updates existing Zendesk tickets with SendSafely secure links for file downloads. The connector uses the Dropzone lookup field (Ticket ID) to associate inbound files with the appropriate ticket in Zendesk. This value can either be entered by the customer at the time of Dropzone file submission, or, more commonly, embedded in the Dropzone URL that is provided to the customer by a Zendesk agent.

Below are the steps for creating and configuring the MS Azure connector using an Azure Resource Manager template (ARM template).

Prerequisites

The steps outlined in this article assumes the following prerequisites:

• You already have a SendSafely account with a Dropzone enabled. Refer to the “Initial Dropzone Setup” section of the Hosted Dropzone article for steps on how to enable. 
• You have an OAuth client for Zendesk that will allow the connector to authenticate and read/update cases in Zendesk (refer to the "Creating an OAuth client in Zendesk" section in the Appendix of this article for instructions on creating a Zendesk OAuth client). 
• You have permissions within MS Azure to setup and deploy new resources. Specifically you will need permission to:
  • Create a new Azure Function triggered by an HTTP request
  • Create a new Azure Cosmos Table 
  • Create a new Communication Service
  • Create a new Log Analytics Workspace
  • Create a new Storage Account
  • Create a new Key Vault Secret (via Key Vault)
  • Create a new Managed Identity for use by the Azure Function

Prior to beginning this setup please contact support@sendsafely.com for instructions on how to obtain the ARM template file, which is required for Step 1 below.

Step 1: Deploy from ARM template to new resource group

From the Azure portal search bar, search for “deploy a custom template” and then select it from the available options.

Click “Build your own template in the editor”.

Then click “Load file” from the ribbon menu. 

After uploading the ARM template (which you received from your SendSafely Support representative), click “Save”.

On the “Custom Deployment” screen, select the Azure subscription to create the resource group under. Select “Create new” and enter a name for the new resource group, i.e. “zendesk-connector”.

There are a number of mandatory fields to populate:

• Azure Connector Owner: email address to receive connector errors.
• Zendesk Portal URL: must include PROTOCOL (i.e. https://) and be your default Zendesk URL  (i.e. https://your-company.zendesk.com/) and NOT a custom URL, e.g. https://support.your-company.com/.
• SendSafely Validation Key: secret validation key for dropzone that is receiving submissions (do not confuse with the dropzone ID)
• Zendesk OAuth Client ID: acquired in "Creating an OAuth client in Zendesk" below.
• Zendesk OAuth Client Secret: acquired in "Creating an OAuth client in Zendesk" below.

There are also some optional fields, which can be configured now or post-deployment:

• Comment Submitter Matches Requester: When ticket is updated with a dropzone submission, and the submitter email MATCHES the original ticket requester email, the comment is either public or private.
• Comment Submitter Does Not Match Requester: If the submitter email does NOT match the original ticket requester email, a private comment is added to the ticket. You also have the option to disallow such submissions and email the dropzone connector owner.

Step 2: Review and deploy

Once you have entered the required information, click “Review and create”.

A validation step will run, and once it is complete, click “Create” to begin the deployment.

Once deployment is complete, move onto the next step.

Step 3: Configure Webhook URL in SendSafely

On the Deployment screen, click “Outputs” on the left-hand sidebar, to view the function URL that was output as part of the deployment process.

Copy the function URL to the clipboard.

Log in to your SendSafely portal as either the Dropzone owner or as a SendSafely Admin and navigate to the Dropzone profile. Under Notification Settings, select the "Use a Webhook for notifications" option and paste in the WebhookUrl. 

You should also make sure that the "Form Input Label" value is set to something intuitive like "Zendesk Ticket Number" or "Case Number". 

Step 4: Test the Connector (Final Step)

Once you complete the steps above, you should be able to browse to the Dropzone URL and update any valid ticket. If you have not already done so, we recommend that you create a Zendesk macro for inserting Dropzone links into your tickets (refer to the "Creating a Macro to Zendesk for Inserting the Dropzone Link" section of the Appendix below). 

The following diagram depicts the logic implemented within the connector and shows what actions will result under various circumstances.

Note: Updating Key Vault secrets

Access to Key Vault is achieved via Managed Identities and role-based access control. 

This means that you cannot, by default, manually edit secrets stored in Key Vault, via the Azure Portal, following the deployment steps above. 

If you need to edit secrets in Key Vault after deployment, you will first need to add yourself as as Key Vault Administer: 

• Go to Key Vault resource, and select Access Control (IAM) from sideblade
• Select Add  and "Role Assignment" - Select "Key Vault Administrator" and select "Next" 
• On the "Add role assignment" page, assign access to "User, group, or service principal" and click Select members
• Select your user account from the sideblade that opens.
• Then click 'Review + assign' to complete the process. 

Once the above steps are complete, you will now be able to manually edit secrets in Key Vault, by:

• Navigating to relevant Key Vault
• Selecting `Objects > Secrets` from the side-blade.

Appendix

Creating an OAuth client in Zendesk

Note. You may wish to perform this step with a shared/admin service account rather than one tied to a specific employee, as Zendesk attributes API activity from this client to whoever created it.

1. In the Zendesk Admin Center, navigate to Apps and integrations > APIs > OAuth clients.
2. Click Add OAuth client.
3. Enter the following:
   • Name. SendSafely Dropzone Connector (or similar)
   • Client Kind: Confidential. Required for the connector's server-to-server authentication to work.
   • Redirect URLs. This field isn't used by the connector. If Zendesk requires it to proceed, enter your Zendesk portal URL (e.g., https://yourcompany.zendesk.com) as a placeholder, otherwise leave it blank.
4. Click Save.
5. Copy the Secret immediately, as Zendesk only displays it once. If you navigate away before copying it, you'll need to generate a new one.

Creating a Macro to Zendesk for Inserting the Dropzone Link

In order to make it convenient for agents to send the correct Dropzone link to customers, we recommend creating a custom macro that can be used to automatically insert the Dropzone link into an agent's reply.

The below instructions are for inserting a link into a support ticket. If you wish to insert a Dropzone link into a Messaging or Chat conversation, follow the macro instructions here.

Browse to Admin > Manage > Macros > Add Macro to create a new macro .

Note that the Dropzone URL also allows you to pre-popluate the ticket id in the URL so that your customer does not have to know the correct ticket id to use. The {{ticket.id}} placeholder within the Zendesk macro template can be used to automatically insert the correct ticket ID in the URL as demonstrated below.

NOTE: You must surround the entire Dropzone URL with the {% raw %} and {% endraw %} tags to avoid having Zendesk attempt to pre-populate the ticket id before the ticket has been submitted. If you do not do this, then the macro will not work effectively in cases where the ticket id has not yet been assigned (like when creating a new ticket). 

Take care to ensure that the Zendesk Rich Content editor does not incorrectly try to format your macro URL as a hyperlink. When this happens you will see a portion of the macro URL turn blue. If this happens, click the blue text and choose the trash can icon so that the entire URL is black. 

BAD MACRO:

GOOD MACRO:

Once the macro has been saved, agents will have the option to use the macro from the bottom of the agent console when replying to a ticket.