Installing the Dropzone Connector for Jira (Google Apps Script)

Our Dropzone Connector for Jira allows you to integrate your SendSafely Hosted Dropzone with Jira Software Cloud and Jira Service Desk. Once configured, the connector can be used to attach and associate files with any existing Jira issue. A SendSafely secure link will be added to the issue so that Jira users can download and view the attached files.

The connector uses the Dropzone lookup field (Issue ID) to associate inbound files with the appropriate issue in Jira. This value can be embedded in the Dropzone URL provided to the customer by the agent, per Step 4 of this article.

The Dropzone connector can be implemented as a Google Apps Script, as an AWS Lambda function, or as a Zap.

Below are the steps for creating and configuring a Dropzone connector for Jira using a Google Apps Script. You should host the Google Apps Connector in your Google Workspace environment.

Step 1 - Obtain a Jira API Token

Obtain a Jira API Token for the connector script to use. For this step, you'll need to be logged into Jira with the identity you want the connector to use for updating issues. Follow the instructions below:

For security purposes, SendSafely recommends regularly rotating API tokens. Note that SendSafely will, under certain circumstances, host a prospective customer’s connector for them during a pilot period. On conversion, we require the customer to generate a new API token upon transitioning to a self-hosted connector.

Step 2 - Enable your SendSafely Dropzone 

If you have not already done so, follow the instructions outlined here to turn on your SendSafely Dropzone.

Step 3 - Configure and Deploy the Connector in Apps Script 

The Connector Script is what allows your SendSafely Dropzone to connect to the Jira platform. The script receives the SendSafely-generated secure link and related metadata, and updates the target Jira issue using the Jira API (authenticated using the API token from Step 1 above). If the issue is unable to be updated via the API call, the connector will send a notification email to the Dropzone owner with details of the error that occurred.

To proceed, make sure you have a copy of the latest SendSafely Dropzone Connector Google Apps Script. If you do not already have a copy of the connector, you can request it from [e-mail].

3a. Copy the Connector Template into your Google Drive

Note: the account you are logged into Google Drive with will be the account used for sending notification emails if the Jira update fails, for example when the customer provides an invalid issue number. As such, you will ideally want to use a generic login or configure your account to be able to send email on behalf of a generic alias (see here for steps on how to configure sending on-behalf-of in Gmail: https://support.google.com/mail/answer/22370?hl=en).

3b. Configure the Script Properties and Deploy the Script 

From the Spreadsheet view, select the “Extensions” menu, and then “Apps Script".

From the Code.gs view in the Script Editor complete the following steps:

i. Select Run > Run function > Setup. You will be prompted by Google to grant the necessary permissions for this script to work. Click “Allow”.

ii. Populate all of the required script properties (File > Project Properties > Script Properties)

• sendsafely_validation_key - The Dropzone Validation Key for the account that owns the Dropzone. You can obtain this value from the "Dropzone" section of the "Edit Profile" screen in the SendSafely portal
• company_name - Your company's name as you want it to appear within notification messages.
• jira_api_token - The API Token for Jira obtained from Step 1 above.  Note that the syntax of the token should be "[e-mail]:XXXXXX" where [e-mail] is the email address of the account that owns the API token (used in Step 1) and XXXX is the token value.  
• jira_base_url - Your Jira portal address (ie company.atlassian.net)
• sender_email - This should be the user that owns/runs the connector. If this user is authorized by Gmail to send email on behalf of another address, you can choose another authorized address.

iii. Select Publish > Deploy as web app

• Under "Project Version", choose "New"
• Under "Execute as" choose "me"
• Under "Who has access" choose "anyone, even anonymous"

Note: Anonymous users will only be able to execute the script but not view its contents. For security purposes, the script only accepts data that is encrypted using the shared validation key to prevent tampering. 

3c. Enable the Apps Script URL as your the Dropzone Webhook 

After pressing "Deploy" copy the Current web app URL and perform the following steps to update the SendSafely Dropzone Webhook and Form Input Label. 

• Log into the SendSafely web portal and navigate to Edit Profile-> Dropzone.
• Paste the copied URL into the "Use a Webhook for notifications:" under Notification Settings.
• If you have not already done so, update the "Form Input Label" option to say "Jira Issue Id" (instead of "Name").

Step 4 - Set up Automation for Jira

You'll now set up Automation in the Project settings to provide users the Hosted Dropzone URL that they'll submit files you. You can set up this Automation to fire off on issue creation in Jira (if you want Hosted Dropzone URLs to appear in all of your issues on this board, e.g.), or set up a manual trigger. In either case, you'll append the issue number to the Hosted Dropzone URL in that automation with the smart value {{issue.key}}

Step 5 - Test the Dropzone using a valid Issue

Once you complete the steps above, you should be able to browse to the Dropzone URL and upload a secure file to any valid issue. The following diagram depicts the logic implemented within the connector and shows what actions will result under various circumstances.

After following the steps above, your Dropzone Connector for Jira should be fully functional. If you require assistance setting up the Jira Dropzone Connector, or have questions on any of the above implementation steps, please contact [e-mail].