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
[More options can be found here: https://cloud.google.com/functions/docs/deploy#console]
First, 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:
- 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:
- 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"
- "zendesk_user_api_token"
- "gcp_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 “zendesk_user_api_token” is of the form and must have been generated by a Zendesk admin:
<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.
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.