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 AWS Lambda connector using CloudFormation.
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 AWS to setup and deploy new resources. Specifically you will need permission to:
- Create a new Lambda Function
- Create a new DynamoDB Table
- Create a new SNS Topic (Simple Notification Service)
- Create a new API (API Gateway Service)
- Create a new AWS Secret (AWS Secrets Manager )
- Define a custom IAM Role for the Lambda Function
Prior to beginning this setup please contact support@sendsafely.com for instructions on how to obtain the CloudFormation template file, which is required for Step 1 below.
Step 1: Create stack and specify template
First, create a stack by logging into your AWS account. Choose us-east-1 as your region. The CloudFormation template must be deployed in us-east-1, as it queries resources from that region. Browse to the CloudFormation console. Choose: AWS -> CloudFormation -> Create stack -> With new resources (standard)
Under "Step 1: Specify template" select the following options and click next:
- Prepare template: Template is ready
- Template source: Upload a template file
- Template file: The YAML obtained from your SendSafely account representative or SendSafely Support
Step 2: Specify stack details
Next, name the stack and populate the following mandatory parameters:
- errorReportingEmail: This is the email address to notify when the Dropzone Connector encounters an errors
- resourcePrefix: A value prepended to resources created by this template so that you can uniquely identify them (must begin with a letter and contain only alphanumeric characters)
- zendeskPortal: The URL for your Zendesk portal
- zendeskUsePublicComments: When set to true, upload notifications will be posted to tickets as a public comment. When set to false, upload notifications are posted to tickets as a private note and only visible to agents.
NOTE: After the stack is created, the address specified in errorReportingEmail (in this example support@companyxyz.com) will receive an email to confirm the SNS subscription. If you do not confirm the SNS subscription, you risk data loss in the event of a connector failure (e.g., if AWS goes down).
Step 3: Configure stack options
For this step we recommend that you leave the default values and click the "Next" button. CloudFormation will automatically create a new role for the connector that has the minimum permissions needed for it to run correctly.
Step 4: Review
Review and acknowledge the required resources and capabilities then click "Create stack"
The Stack may take several minutes to create. You can view the status from the CloudFormation > Stacks screen. Once the entire process completes successfully, the stack will have a status of "CREATE_COMPLETE". You can view a complete list of the resources that were created from the "Resources" tab. This includes the Lambda function and supporting AWS resources.
Step 5: Confirm the SNS subscription for Error Reporting
The address specified for the errorReportingEmail should have received an email to confirm the SNS subscription. Click the Confirm subscription link to enable the alerts. If you do not confirm the SNS subscription, you risk data loss in the event of a connector failure (e.g., if AWS goes down).
Step 6: Configure Webhook URL in SendSafely
On the Stack "Outputs" tab, copy the WebhookUrl to your clipboard. In the example below, the URL is https://cgzg5pdtb5.execute-api.us-east-1.amazonaws.com (your stack will have a different URL).
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 7: Update Secrets Manager
Lastly, click on the SecretsManager link of the Stacks Resources tab in AWS to update the sendsafely_validation_key and zendesk_user_api_token values
- sendsafely_validation_key - The Dropzone Validation Key for the account that owns the Dropzone. You can obtain this value from the Dropzone profile in the SendSafely portal
- zendesk_user_api_token - The API Token for Zendesk. Note that the syntax of the token should be "user@company.com/token:XXXXXX" where user@company.com is the email address of the account that owns the API token and XXXX is the token value.
Once the fields are updated, click Save.
Step 8: 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.
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.
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.
Obtaining a Zendesk API Token
In order to obtain a Zendesk API Token for the connector, you'll need to be logged into Zendesk with admin privileges. In Zendesk, go to Admin > Channels > API > Settings. Under "Token Access" press the "+" button to obtain a new token.
For security purposes, SendSafely recommends regularly rotating API tokens. Note that SendSafely will, under certain circumstances, host a prospective customer’s connector for them during a pilot period. On conversion, we require the customer to generate a new API token upon transitioning to a self-hosted connector.
For additional assistance setting up the Zendesk Dropzone Connector, contact support@sendsafely.com.
Comments
0 comments
Please sign in to leave a comment.