Installing the Dropzone Connector for Jira (AWS Lambda)

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 3 of this article.

Below are the steps for creating and configuring the AWS Lambda connector using CloudFormation. You should host the Lambda Connector in your AWS environment.

Prerequisites

The steps outlined in this article assume the following prerequisites:

• You have permissions within AWS to setup and deploy new resources. Specifically you will need permission to:
  • Create a new Lambda Function 
  • Create a new DynamoDB Table 
  • Create a new SNS Topic (Simple Notification Service)
  • Create a new API (API Gateway Service)
  • Create a new AWS Secret (AWS Secrets Manager )
  • Define a custom IAM Role for the Lambda Function 

Prior to beginning this setup please contact [e-mail] for instructions on how to obtain the CloudFormation template file, which is required for Step 3 below.

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 - Create stack and specify template

First, create a stack by logging into your AWS account. Choose us-east-1 as your region. The CloudFormation template must be deployed in us-east-1, as it queries resources from that region. Browse to the CloudFormation console. Choose:  AWS -> CloudFormation -> Create stack -> With new resources (standard)

Under "Step 1: Specify template" select the following options and click next:

• Prepare template: Template is ready
• Template source:  Upload a template file 
• Template file: The YAML obtained from your SendSafely account representative or SendSafely Support 

Step 4 - Specify stack details

Next, name the stack and populate the following mandatory parameters:

• Email Address for Error Notifications: This is the email address to notify when the Dropzone Connector encounters an errors
• Jira Base Url: The URL for your Jira portal
• Jira Project Key: The prefix for the issue numbers in the Jira project

NOTE: After the stack is created, the address specified in Email Address for Error Notifications (in this example [e-mail]) will receive an email to confirm the SNS subscription. If you do not confirm the SNS subscription, you risk data loss in the event of a connector failure (e.g., if AWS goes down).

Step 5 - Configure stack options

For this step we recommend that you leave the default values and click the "Next" button. CloudFormation will automatically create a new role for the connector that has the minimum permissions needed for it to run correctly. 

Step 6 - Review

Review and acknowledge the required resources and capabilities then click "Create stack"

The Stack may take several minutes to create. You can view the status from the CloudFormation > Stacks screen. Once the entire process completes successfully, the stack will have a status of "CREATE_COMPLETE". You can view a complete list of the resources that were created from the "Resources" tab.  This includes the Lambda function and supporting AWS resources.

Step 7 - Confirm the SNS subscription for Error Reporting

The address specified for the Email Address for Error Notifications should have received an email to confirm the SNS subscription. Click Confirm subscription to enable the alerts. If you do not confirm the SNS subscription, you risk data loss in the event of a connector failure (e.g., if AWS goes down).

Step 8 - Configure Webhook URL in SendSafely

On the Stack "Outputs" tab, copy the WebhookUrl to your clipboard. In the example below, the URL is https://6jne53v4hujuj4xsk7nuyyuh5e0wxnei.lambda-url.us-east-1.on.aws/ (your stack will have a different URL). 

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 "Jira Issue Number" or "Issue Number". 

Step 9 - Update Secrets Manager

Click on the SecretsManager link of the Stacks Resources tab in AWS to update the jira_admin_email, jira_admin_token, and sendsafely_validation_key values.

Once the fields are updated, click Save.

Step 10 - Update Environment variables (optional)

Navigate to the Lambda function for the Jira connector, click into the Configuration tab, and edit the following (optional) Environment variables:

• NEW_TICKET_IF_TICKET_CLOSED: if true, a Dropzone submission to a valid Jira issue with a status of 'Done' will create a new issue with a secure link to the submission
• NEW_TICKET_ON_INVALID_SUBMISSION: if true, a Dropzone submission to a invalid Jira issue will create a new issue with a secure link to the submission

Once the fields are updated, click Save.

Step 11 - 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}}.

The dropzone URL (that customers will upload files to) should follow the format:

https://<your-company-portal>/dropzone/<dropzone-name>/{{issue.key}}

Step 12 - Test the Dropzone Connector using a valid Issue

Once you complete the steps above, you should be able to browse to the Dropzone URL and upload secure files and messages to a Jira 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].