Installing the Dropzone Connector for Salesforce (GCP)

Prerequisites

1. Set up a Connected App in Salesforce

Follow the steps outlined here to set up a new Connected App in Salesforce: https://sendsafely.zendesk.com/hc/en-us/articles/360040234451

2. Obtain a Refresh Token 

Use the getRefreshToken.js script to obtain a Salesforce Refresh Token for the Dropzone Connector to use. The script can be downloaded here: https://github.com/SendSafely/Code-Examples/tree/master/Obtain%20Salesforce%20Refresh%20Token

The script will require you to enter the following values obtained during the Connected App setup:

1. Salesforce Consumer Key
2. 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. 

Step 1: Create GCP project and upload files to (Legacy) Cloud Shell Editor

Create a new project from the GCP Console. Then, from the Navigation Menu, select “Cloud Shell Editor”. Your support representative will provide you with a ZIP file containing the function code and the Terraform template.

Select “Use the Legacy Editor” from the top ribbon:

Once the legacy Cloud Shell Editor has loaded, create a new folder (‘salesforce-connector-setup’) to the root directory of the Cloud Shell session. 

Navigate to the ‘salesforce-connector-setup’ folder, then select “File > Upload Files”. Upload the ZIP folder containing both the function code and terraform template.

From a new Cloud Shell Terminal window, unzip the ZIP folder using the following command:

$ unzip gcp-salesforce-connector.zip -d ./

The gcp-salesforce-connector/ directory should appear in the Cloud Shell file explorer. 

Navigate to the terraform/ directory, either via the file explorer or from the terminal window:

$ cd gcp-salesforce-connector/terraform/

Step 2: Deploy from Terraform Template

Confirm you are in the correct project (the project you created earlier) using the following command:

$ gcloud config get project

To change the project, use:

$ gcloud config set project <PROJECT_ID>

You can use the following command to get a list of the active projects and their Project_ID values:

$ gcloud projects list

[More options can be found here: https://cloud.google.com/functions/docs/deploy#console]

First, you need to enable the Cloud Resource Manager API by running the following command:

$ gcloud services enable cloudresourcemanager.googleapis.com

Then, enable the following resources required by the Dropzone Connector:

$ gcloud services enable artifactregistry.googleapis.com  cloudfunctions.googleapis.com cloudbuild.googleapis.com eventarc.googleapis.com  firestore.googleapis.com iam.googleapis.com logging.googleapis.com pubsub.googleapis.com run.googleapis.com  secretmanager.googleapis.com storage.googleapis.com serviceusage.googleapis.com

[Trying to enable these resources from the terraform template can result in syncing issues]

Update the variables.tf file with the required parameters from the Cloud Shell Editor:

• gcp_dropzone_connector_owner: Email address that will get notifications if errors occur
• gcp_notification_email_address: Email address that will send notifications to submitters

Then initialize the Terraform template from within the /terraform directory:

$ terraform init

Run plan to ensure there are no errors:

$ terraform plan

Then apply the template (this may take a couple minutes):

$ terraform apply

If the application completes without error, you will see the function URL (function_uri) outputted to the console (along with some other information)

Step 3: Configure SendGrid Email Service

To use SendGrid to send emails, there are two steps:

1. Create API key
2. Verify control of either a single email address or a domain

Navigate to SendGrid from the GCP Marketplace (see Appendix I for more details), using the Search Bar to find the SendGrid Email API:

From the navigation bar in SendGrid (on the left hand side) Settings > API Keys and click on the “Create API Key” button:

You can customize the levels of access of this API key, and we advise the approach of “least privilege”, selecting “Restricted Access” and setting the following:

•  “Mail Send”: Full Access
• “Sender Authentication”: Read Access

To verify control of an email address or domain, navigate to Settings > Sender Authentication and select the appropriate option from the Sender Identity panel.

Step 4: Update Secret Manager

During deployment, the three default secrets were created with placeholder values:

• "sendsafely_validation_key"
• "gcp_sendgrid_api_key" 
• “salesforce_consumer_key”
• “salesforce_consumer_secret”
• “salesforce_refresh_token”

You will now need to update them with the correct values. From the sidebar menu, click “Security > Secret Manager”.

Click into each individual entry, and select “+NEW VERSION”. Add the actual secret value and check “Disable all past versions”.

Note, the “salesforce_user_api_token” must have been generated by a Salesforce admin. 

Once all the secrets are updated, move onto the next step (where you update the SendSafely Dropzone that you are using as a connector) .

Note: if you are using another email provider or are taking an alternative approach to sending emails, feel free to amend / ignore the “gcp_sendgrid_api_key” secret. 

If using an alternative email provider, you will need to adjust the “sendEmail.js” module of the connector.

Step 5: Configure Webhook URL in SendSafely

You now need to update the SendSafely dropzone with the Cloud Function webhook URL. 

You can find this function URL in the Cloud Shell Editor terminal, once deployment of the Terraform template has been completed.

You can also find this URL by going to “Cloud Functions” in the Navigation Menu, and clicking on the “salesforce-connector” function.

Within the “Function Details” view, you will see the URL displayed along the top of the screen. Copy this 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 "Salesforce Ticket Number" or "Case Number".

Step 6: Create a Quick Text or Template for ease of use

Salesforce provides information on how to create a Quick Text and how to create a Template. We recommend using something like the following text for either, replacing yourcompany.sendsafely.com with your Hosted Dropzone URL:

“Please use the following link to securely upload your files: https://yourcompany.sendsafely.com/dropzone/servicecloud/{!Case.CaseNumber}”

If you wish to pre-populate your customer’s email address in addition to their case number, you can do so using the following Quick Text or Template:

“Please use the following link to securely upload your files: https://yourcompany.sendsafely.com/dropzone/servicecloud/{!Case.CaseNumber}/{!Contact.Email}”

Step 7: Test the Connector (Final Step) 

Ensure that the connector is working by making a Dropzone submission with an existing Case Number provided in the Form Input Label, and verifying that the secure link to that Dropzone submission is added to the Case.

Common issues include:

• Not setting all secrets in Secret Manager
• Function or Cloud Run cannot access Secret Manager:
  • give Secret Manager Secret Accessor access to the default Compute Engine service account (i.e. <project_number>[e-mail]).
• Cloud Run not allowing unauthenticated invocations of the deployed function:

• Function Variables not set (e.g. if deployment fails)
• Wrong name for Firestore Database. Use “(default)” as name, as this is what the NodeJS Firestore Client will try to connect to by default.

Appendix 1: Generating SendGrid API Key

To generate a SendGrid API key, you will need to access your SendGrid account via the Google Marketplace. 

From the Google Cloud Navigation Menu, select “Marketplace”, and type “SendGrid Email API” into the search bar to return the correct service.

Then click “Manage on Provider” to be taken to your SendGrid dashboard.

From the sidebar menu, select “Settings > API Keys” and click “Create API key”. Give the key a name and provide it with “Full Access” then click “Create & View”. Copy the API key shown on the next page, which should begin with “SC.XXXXXXXXXX”, and update GCP Secret Manager with it.