Use Transports
Summary
Transports are channels that allow remote two way interaction with JIRA via JEMH. JEMH provides all transports with per-event enablement as well as support for customisable TEXT and HTML notifications. In addition, commands can be issued via Transports:
How Transports fit into JEMH
Typically, Transports can be added to JEMH by installing an additional add-on in JIRA. However as of JEMH 2.0.0, this is not the case for HipChat and SMS transports as they are now built-in.
Each Transport provides some specific communication functionality. It provides a default set of templates for the standard JIRA issue events in both text and HTML format, including subject content if appropriate (like for example in the standard Email Transport). When a user configures a Project Mapping, the Transport provides these default templates to JEMH as needed.
JEMH provides the configuration interface for each Transport, as well as event enablement and template selection via the Event Listener's Transport tab.
JEMH also collects the CommandSet's that each Transport provides. JEMH provides a few basic issue operations (watch/label/set priority) that will be expanded over time, including /help that generates a full list of all Commands grouped by their contributing CommandSet. Whilst Transports can contribute CommandSets, its not required - a Transport has access to all pre-existing commands.
Transport Features
A Transport that is added via an add-on must store its configuration locally, usually through the use of the Active Objects API. A configuration is made up of Keys and Values, and are passed to JEMH via public DTO objects provided through the public JEMH API. Currently support is not typed, all values are passed as simple text. Transports are required to implement a validate method for configuration, and also to send a testMessage to verify connectivity.
Transport Disablement
Disabling a Transport add-on through the JIRA Add-ons section will cause it to disappear from JEMH user interface. The disabled Transport will not receive notifications and should not retrieve from its related service.
Templates
Transports must contribute a set of templates that are appropriate for that Transport, for example, email templates are not appropriate for SMS, and vice versa, a Transport can expose text and html components, subjects too in future. The Templates exposed by Transport add-ons are considered defaults, much in the same way the JEMH uses JIRA default templates.
When installed, the TemplateSet IssueEvent user interface expands from just offering named events to offering the additional selection of the Transport (top right in the diagram below). To help manage multiple custom TemplateSets for different transports, the displayed list can be dynamically filtered:
The contributing Transport add-on defines what content is required, and will cause the enablement of Subject, HTML and TEXT content for edit via the TemplateSet UI.
Deleting a Transport TemplateSet will not be possible whilst it is referred by a Transport.
The customisation of templates is not required, it is optional!
Configuring Transports
For information on configuring specific JEMH Transports, see the related wiki page:
Associating a Project Mapping with a Transport Configuration
Project Mappings are used to associate events occurring in a target project with Transports. Transports can be used by multiple Project Mappings. In order for a Transport to work, a Project Mapping must be attached to it and enabled for use with the Transport.
For the purpose of this wiki guide, you will be shown how to link a project mapping to the HipChat Transport, although the process should be the same for any other.
If you have not created a Project Mapping already, create one on the Email Transport screen, or click "New Project Mapping" under your Transport of choice. You should see the Project Mapping edit screen:
Unless you wish to configure the mapping for email communication now (see this guide for more information), just enter your target project key(s) and press Submit to save. You should now see a mapping under your Transport:
At this point, we need to enable the target Transport for use with this mapping, and select the events that this Transport will notify for. To do this, make sure you are on your chosen Transports page, and click edit . You will then be taken to a screen where these changes can be made. Using the HipChat Transport in our example, it looks like this:
Select the Transport configuration that you want to associate with this Project Mapping. Then, select a template for the events that you want the Transport to notify for:
After clicking submit, the Transport configuration will be associated with the Project Mapping.
Configuration Checkist
Transport configuration is created and modified
A Project Mapping for the Project that events are to be broadcast from was created
Project Mapping was configured to use the Transport Configuration, and specific JIRA events have been selected by choosing a template for each event
Testing Transport configuration
Create an issue in the project specified in your project mapping:
The Transport will receive the event and render the content using the applicable template and broadcast. In this case, HTML:
Sending commands via Transports
Commands are different to directives which you may be familiar with. While directives are supplied in an email body that is sent to JEMH for processing, commands are not part of the issue creation process. Their purpose is to allow users to interact with issues remotely.
Testing Commands
With the Transport configured, now is the time to lookup commands. The bundled Command Set in JEMH includes /help that is useful for listing all known commands, grouped by the contributing Command Set, /help command can also be used to bring up specific command help.
Bundled Commands
priority example: priority ABC-123 blocker
watch example: watch ABC-123
unwatch example: unwatch ABC-123
label example: label ABC-123 this that theother
New additional Commands?
These can be deployed as via new plugins, potentially even along with new Transport implementations.
How Does Security Work?
This is going to be transport specific. The example, HipChat, uses the registered users email address to correlate with a JIRA user, if they aren't the same, then JEMH/JIRA will fail various permission checks. Future Features could allow only a subset of users to interact via Transports.