The Dropzone Connector bridges the SendSafely Dropzone and the Salesforce platform. The connector ingests the SendSafely generated secure link & related metadata, and updates the target Salesforce case via the Salesforce REST API. If the case is unable to be updated via the Salesforce API call, a notification email is sent to the Dropzone owner and file submitter.
Prerequisites
This article assumes the following prerequisites:
- You already have a SendSafely account with a Dropzone enabled. Refer to the “Initial Dropzone Setup” section of this article for steps on how to enable: https://sendsafely.zendesk.com/hc/en-us/articles/360004713432-Hosted-Dropzone-Set-Up
- You have a Refresh Token for Salesforce that will allow the connector to authenticate and read/update cases in Service Cloud. Refer to the Appendix at the end of this article for steps on how to configure a Connected App in Salesforce and obtain a Refresh Token.
- You have obtained the deployment package (code) for the SendSafely Lambda Dropzone Connector from your SendSafely Integration Consultant
- 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
Step-by-Step Integration Guide
1. Create a new SNS Topic for Alerting
a. SNS > Topics > Create Topic.
You should only need to provide a name for the topic (ie “Dropzone Error Reporting”). No other configuration is required, all of the default values are sufficient. You do not need to specify an access policy as we will grant access using a custom policy later.
b. Copy the ARN of the topic once created (needed for later)
c. Create a subscription to the topic using your email address for testing
- Will require you to “accept” a verification link once you subscribe
2. Create a DynamoDB Table for storing Dropzone Submissions
a. DynamoDB > Create Table
b. Give the table a unique name (ie DropzoneSubmissions)
c. Create a primary key named “itemId” of type “String”
No other configuration is required, all of the default values are sufficient. You do not need to specify an access policy as we will grant access using a custom policy later.
3. Create a new entry in AWS Secrets Manager for sensitive configuration parameters
a. AWS Secrets Manager > Secrets > Store a new secret (launch the guided wizard setup)
b. For Step 1, under “Secret Type” choose “Other type of secret”
c. Add a new key/value pair for each of the following values:
- sendsafely_validation_key
- salesforce_consumer_key
- salesforce_consumer_secret
- salesforce_refresh_token
d. For Step 2, Name the secret with a unique name (ie DropzoneConfigParams)
e. For Step 3, Disable automatic rotation
f. For Step 4, review and press “Store”
4. Create the Lambda Function
a. AWS Lambda > Create Function
b. When prompted, choose “Author from scratch
c. Give the function a unique Name (ie ServiceCloudDropzoneConnector)
d. Choose “Node.js 10.x” as the runtime
e. Under Permissions, choose “choose or create an execution role” and select the “Create a new role with basic Lambda permissions” option, then press “Create Function”
The lambda function will be created with sample code that returns “Hello from Lambda”. We will upload the real Dropzone Connector lambda code in a later step.
5. Create the API Gateway Endpoint
a. API Gateway > Create API
b. Choose “REST” as the protocol, and “New API”. Under Settings, give the API a unique name (ie DropzoneConnectorEndpoint). Then press “Create API”
c. Under “Resources” choose “Create Method”. Choose “POST” from the drop down menu, then press the checkbox icon, which should reveal the setup screen.
d. On the setup screen, choose “Lambda Function” as the Integration Type, and check the box next to “Use Lambda Proxy Integration”. Under “Lambda Function” specify the ARN of your Lambda Function and press “Save”.
You will be notified with an alert saying “You are about to give API Gateway permission to invoke your Lambda function”. Press OK.
e. After the endpoint is created, you will be presented with a screen that looks like this:
f. Press the “Test” lightning bolt icon to launch the Method Test screen. Leave the Request body blank and press the “Test” button. You should see a response come back on the right side of the screen that says “Hello from Lambda”.
g. Next, from the “Actions” menu choose “Enable CORS”. The default values populated on the screen can be used. Press “Enable CORS and replace existing CORS headers”. When prompted to confirm method changes, press the “Yes, replace existing values”.
h. Finally, from the “Actions” menu choose “Deploy API”. For “Deployment Stage” choose “[New Stage] “. Create a unique stage name (ie “prod-connector”) and then press “Deploy”
After pressing “Deploy” a screen should appear that shows the “Invoke URL” for the API endpoint. This will be the web hook URL you configure for your SendSafely Dropzone.
6. Update the Lambda Function Code and Define Configuration
a. Browse back to the Lambda console and open the function that was created in Step 4. Under the “Function Code” section, choose “Upload a ZIP file” from the “Code entry type” drop down. Attach the ZIP file provided to you by the SendSafely Integration team, and press the “Save” button at the top right corner of the screen.
b. Under the “Environment Variables” section, populate the following key/value pairs:
- aws_dynamo_db_table - The DynamoDB table name created in Step 2 (ie DropzoneSubmissions).
- If this variable is omitted, submission tracking within DynamoDB will be disabled and duplicate submissions cannot be detected.
- aws_secrets_manager_secret_name - The name of the secrets entry defined in Step 3d (ie DropzoneConfigParams).
- aws_sns_reporting_topic_arn - The ARN of the SNS topic created in Step 1.
- If this variable is omitted, error reporting via SNS will be disabled. Cloud watch entries for any errors will still be created but no proactive alerting will occur.
After populating the environment variables, press the “Save” button at the top
The following additional environment variables are OPTIONAL:
- salesforce_is_sandbox - Indicates whether to authenticate a salesforce sandbox environment. This value defaults to “false” if not specified.
- salesforce_sendsafely_link_destination - The Service Cloud object to post case notifications to. Valid values are CaseComment or FeedComment. This value defaults to “FeedComment” if not specified.
c. Under the “Basic Settings” section of the page, update the timeout value to 1 minute.
7. Configure the IAM Policy for your Lambda Function
a. From the Lambda Function console, open your Dropzone Connector Lambda function and browse down to the “Execution Role” section of the screen. Press the “View the [Rolename] role on the IAM console” link to launch the IAM console.
Expand the policy node and press the “Edit Policy” button to launch the policy editor.
If you wish to use the Visual Editor, you will need to individually add the following permissions by pressing the “Add additional permissions” link on the bottom right corner of the Visual Editor interface.
- Service: DynamoDB
- Actions:
- Read -> GetItem
- Write -> PutItem
- Resources:
- Table -> [ARN of DybamoDB Table that you created]
- Service: SNS
- Actions:
- Write -> Publish
- Resources:
- Topic -> [ARN of SNS Topic that you created]
- Service: Secrets Manager
- Actions:
- Read -> GetSecretValue
- Resources:
- Secret -> [ARN of Secret that you created]
If you wish to use the JSON editor instead, then you can overwrite the entire JSON policy document with one that models the following (replace your ARN for each resource entry). We show you the before and after below because you will need to preserve the entries that are already present within the policy:
Before:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "logs:CreateLogGroup",
"Resource": "arn:aws:logs:xxxxx:XXXxxxxxXX:*"
},
{
"Effect": "Allow",
"Action": [
"logs:CreateLogStream",
"logs:PutLogEvents"
],
"Resource": [
"arn:aws:logs:xxxxx:xxxxx:log-group:/aws/lambda/xxxxx:*"
]
}
]
}
After:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": [
"logs:CreateLogStream",
"sns:Publish",
"secretsmanager:GetSecretValue",
"dynamodb:PutItem",
"dynamodb:GetItem",
"logs:PutLogEvents"
],
"Resource": [
"arn:aws:logs:xxxxx:xxxxx:log-group:/aws/lambda/xxxxx:*",
"arn:aws:dynamodb:xxxxx:xxxxx:table/xxxxx",
"arn:aws:logs:xxxxx:xxxxx:log-group:/aws/lambda/xxxxx:*",
"arn:aws:sns:xxxxx:xxxxx:xxxxx",
"arn:aws:secretsmanager:xxxxx:xxxxx:secret:xxxxx"
]
},
{
"Sid": "VisualEditor1",
"Effect": "Allow",
"Action": "logs:CreateLogGroup",
"Resource": "arn:aws:logs:xxxxx:xxxxx:*"
}
]
}
Appendix - Setting up a Connected App in Salesforce and Obtaining a Refresh Token
a. Follow the steps outlined here to set up a new Connected App in Salesforce: https://sendsafely.zendesk.com/hc/en-us/articles/360040234451
b. Launch the getRefreshToken.js script provided within the deployment setup package for the Salesforce Dropzone Connector. That script will require you to enter the following values obtained during the Connected App setup:
- Salesforce Consumer Key
- Salesforce Consumer Secret
Once the above items are provided, the script will produce a URL that you must copy/paste into your browser while authenticated to Salesforce. This URL will prompt you for permission to authorize the app to run.
Once authorized, you will be redirected to a screen that says "Remote Access Application Authorization". In the URL you will see a value that says code=XXXX where XXXX is the Authorization Code. Please copy that value (excluding the code= portion of the value) and provide it to the script when prompted.
Once the script verifies the Authorization Code, it will print the Refresh Token to the screen. The Refresh Token is a credential for Service Cloud. Make sure you do not store it unprotected or disclose it to anyone.