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:
- 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.
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:
- Create API key
- 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: 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>-compute@developer.gserviceaccount.com).
- 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.