Home

Dev Documentation

Building the Plugin

3.3.x - Requires Atlassian Plugin SDK (amps) version 6.2.6

You must install the SDK before you can build this version of the plugin. To build the plugin, you must do the following:

1. atlas-clean - This removes the target folder and its contents (if it exists), providing you with a clean workspace in which to build.

2. atlas-package - This creates the local target folder, compiles the source, and create the plugin jar file. Then, you install this plugin jar file (file name hub-jira-1.0.0.jar) into the Add-Ons section of your Jira server.

3. You can use the atlas-run command to run the plugin locally on your machine.

4. Use atlas-debug if you want to debug the plugin.

Refer to the Atlassian SDK documentation for further information on installing and using the Atlassian SDK, located at:

https://developer.atlassian.com/docs/getting-started/set-up-the-atlassian-plugin-sdk-and-build-a-project

Design Overview

The following pertains to v2.0:

Package Structure

At a high level, the plugin consists of the following components (the bolded names are the corresponding package names):

• config: the configuration screen
• task: periodically run by JIRA
  • conversion of hub notifications to events
  • issue creation
  • setup of Hub-specific JIRA objects (Issue Types, etc.)
• common: classes used by both config and task classes

Task Processing / Classes

The task reads recent notifications from the Hub, converts each notification to zero, one, or multiple Events (an Event is a set of instructions on what needs to be done in JIRA), and finally acts on each Event to create/re-open/comment-on a Jira Issue (ticket).

The important classes are:

• The task (JiraTask) is scheduled by HubMonitor and periodically invoked by JIRA. It runs JiraTaskTimed with a timeout.
• JiraTaskTimed interacts extensively with JIRA, while HubJiraTask interacts with the Hub. JiraTask:
  • Reads the plugin configuration details
  • Creates Hub-specific JIRA objects
  • Invokes HubJiraTask
• HubJiraTask
  • Calculates the notification date range to request
  • Instantiates the services needed
  • Invokes TicketGenerator to do the work (read notifications and create/re-open/comment-on a Jira Issues)
• TicketGenerator:
  • Uses NotificationService to fetch notifications from the Hub
  • Uses JiraNotificationProcessor to translate them into Events. An event contains a set of instructions for JiraIssueHandler (everything it needs to know about the issue to create/re-open/comment-on).
  • Uses JiraIssueHandler to create/re-open/close/comment-on one issue per Event.
• JiraNotificationProcessor uses ConverterLookupTable to get, for each incoming notification, the appropriate Converter.
• ConverterLookupTable has a Map that maps notification types (NotificationItem subclasses) to converters.
• A Converter converts a notification into one or more Events. Each Converter is notification-type-specific.
• An Event may be a PolicyEvent or a VulnerabilityEvent. Their interface is identical, but they use type-specific overridden methods to generate the values they return (e.g. getUniquePropertyKey(), getIssueSummary(), getIssueDescription(), etc.).
• JiraIssueHandler knows how to create/update issues in JIRA. An Event tells it what to do.