Installing the Dropzone Connector for Zendesk (Microsoft Azure)

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 API Token for Zendesk that will allow the connector to authenticate and read/update cases in Zendesk (refer to the "Obtaining a Zendesk API Token" section in the Appendix of this article for instructions on obtaining a Zendesk API Token). 
• 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 [e-mail] 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 API token: secret entry, which must be generated by a Zendesk admin
• Zendesk Email: email address of the Zendesk admin who has generated the Zendesk API key

Note: The "Zendesk API token" and "Zendesk email" values are combined (by the ARM template) to form a string of the following format:

• <email address>/token:<API token>

This value is stored in the Key Vault Secret named zendesk-user-api-token.
If you are manually updating Key Vault, you will need to manually format the string correctly, using the format specified (ensuring the "<" and ">" placeholder characters are replaced as well).

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

{% raw %}https://demo.sendsafely.com/dropzone/zendesk/{{ticket.id}}{% endraw %}

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.