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 either be entered by the customer at the time of Dropzone file submission, or can be embedded in the Dropzone URL provided to the customer by the agent. The Dropzone connector can be implemented as a Google Apps Script or by using our Zapier App.
Below are the steps for creating and configuring a Dropzone connector for Jira using a Google Apps Script. Information on our Zapier connector can be found here. 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.
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".
At the time of this writing, the new Google Apps Script editor does not currently support editing script properties. To complete the required configuration steps below, click the “Use classic editor” button at the top right corner of the screen and proceed with the steps below.
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 "firstname.lastname@example.org:XXXXXX" where email@example.com 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 - 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 firstname.lastname@example.org.