Installing the Dropzone Connector for Zendesk (GCP)

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 (‘zendesk-connector-setup’) to the root directory of the Cloud Shell session. Navigate to the ‘zendesk-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-zendesk-connector.zip -d ./

The gcp-zendesk-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-zendesk-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

First, 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

Note: Attempting 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:

• zendesk_portal_url: the URL of your Zendesk instance
• 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" - This is the validation key for the SendSafely Dropzone you are deploying the connector for. The Dropzone validation key is located on the Dropone tab of the SendSafely Edit Profile screen when viewing the profile of the Dropzone User. 
• "zendesk_user_api_token" - This is the Zendesk API Token used for authenticating to Zendesk. We recommend creating a dedicated service user in Zendesk for use with this API token.  
•  "gcp_sendgrid_api_key" - This is the Sendgrid API key used by the connector. Refer to the Appendix of this article for more information on generating a Sendgrid API key. 

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 syntax for specifying the “zendesk_user_api_token” is shown below. Make sure to include the "/token:" delimiter between the zendesk service user email address and the API Token as shown below: 

<admin-email>@<company-domain>/token:<API Key>

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 “zendesk-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 "Zendesk Ticket Number" or "Case Number".

Step 6: 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 default logic implemented within the connector and shows what actions will result under various circumstances.

If testing the connector fails, double check these common issues:

• Make sure that all settings are populated in Secret Manager
• Verify that the Function or Cloud Run can access Secret Manager:
  • Give Secret Manager Secret Accessor access to the default Compute Engine service account (i.e. <project_number>[e-mail]).
• Verify that Cloud Run allows unauthenticated invocations of the deployed function:

• Verify that Function variables are set (if deployment fails)
• Check the name of the Firestore Database. Use “(default)” as name, as this is what the NodeJS Firestore Client will try to connect to by default.

Appendix

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

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.