A SystemWeaver Jira plugin has been developed that offers a solid integration between SystemWeaver and Jira. Jira reads data from SystemWeaver, and SystemWeaver can update Jira issues and create issues through the Jira REST API. This article describes how to install and configure the necessary components for the integration as well as what modifications need to be made to the Jira installation.


Prerequisites

  • Familiarity with your Jira installation and projects
  • Assignment of the SW Architect role in the SystemWeaver database
  • Assignment of Administrator role in Jira
  • An installation of the SystemWeaver swExplorer client
  • An installation of the SystemWeaver REST API. It should ideally be installed on the same machine as the SystemWeaver server it is accessing.
  • The SystemWeaver Jira plugin (e.g., swtabid-1.0.7.jar). Find the latest version on Jira Marketplace
  • The SystemWeaver SWExtension.Jira2.dll client extension
  • An installation of the SystemWeaver Monitor Service (use is optional, but recommended)

Solution Architecture

The architecture of the Jira integration uses the SystemWeaver REST API.


Instructions for installation and configuration are described below.


Installing the SystemWeaver REST API for JIRA

See Configuring the SystemWeaver REST API Server for configuration and Monitor Service for running the REST API as a service.


Installing the SystemWeaver Jira Plugin

In Jira, click on the Jira Administration cog icon and select Add-ons.



Next, click on Manage apps and Upload app.



Click Choose File on the next screen and select the file swtabid-1.0.X.jar provided by Systemite. The plugin will now be seen in the list of user/installed plugins. 


Jira Marketplace and Data Center

The SystemWeaver plugin for integration between SystemWeaver and Jira is also available via Jira Marketplace.

If you are running Jira Data Center, you can obtain the plugin file from Systemite or download it via Jira Marketplace. When running with Data Center, ignore any incompatibility messages. 


Next, click on Configure on the swtabid tab.



On the Administration screen, you will need to enter some information that the plugin needs in order to be able to show SystemWeaver issue information on a Jira tab.


Note: Each field has a label indicating plural configurations. If the Jira installation for some reason needs to communicate with several SystemWeaver servers, you can enter multiple values in each field and separate them with a semi-colon “;”.


Required Information

  • SW Servercodes: Enter a code for the SystemWeaver server you are connecting to. The code must match/be the same as the code that you enter in the SystemWeaver configuration for the SystemWeaver part of the plugin. 

Information is obtained from SystemWeaver through the SystemWeaver REST API, so you need to enter information needed to connect to the Rest API as well:

  • SW Usernames: Enter a SystemWeaver username. The user account must have a minimum of read access to the SystemWeaver items that Jira needs to display. 
  • SW Passwords: Enter the above username's password. 
  • Back-end Service Servers: Enter the server name for the REST API.
  • Back-end Service Server Ports: Enter the port for the REST API.
  • SW Server Machines: Enter the server for the SystemWeaver server application. This allows the SystemWeaver item urls to display in the Jira plugin. For use with multiple SystemWeaver server applications, use a semi-colon delimiter. The input order must match that of SW Server Ports. 
  • SW Server Ports: Enter the port for the SystemWeaver server application. For use with multiple SystemWeaver server applications, use a semi-colon delimiter. The input order must match that of SW Server Machines.
  • JIRA Custom Fields: Enter a dummy custom field id. Note: You will need to come back and update this value once the true custom field id value is generated upon field creation.


Plugin Options

The following options are available with plugin version 1.0.4 or later:

  • SSL True/False: Hypertext Transfer Protocol Secure (HTTPS) or Hypertext Transfer Protocol (HTTP) for secure communication over a computer network. The option can be set to "True" for HTTPS and 'False' for HTTP.
  • Floating True/False: Floating relationship between SystemWeaver's items and Jira's issues. Floating means that a Jira issue will be linked to the selected version of a SystemWeaver item version and will also float forward to later versions. When "True" is selectedusers can choose to create a floating relationship or not in the provided UI for creating Jira issues in SystemWeaver. "False" means that users will only be able to connect a specific SystemWeaver item version to a Jira issue.
  • Displayed Columns: XML configuration to control what SystemWeaver item information will be visible in Jira. The type of information that can be added to Jira are item description and properties (e.g., Version, Status, Type, LastChanged, and LastChangedBy) and item attributes of all types except 'Computed' and 'Custom' attribute types.  
    • The configuration includes the following tags:
      • <Swtabid> a grouping tag, which contains all the parts of configuration.
      • <DisplayedColumns> specifies columns to be added for holding SystemWeaver item information. The tag has two attributes:
        • itemProperties specifies the item properties to be added as columns. The possible values are Version, Status, Type, LastChanged, LastChangedBy and/or Description separated by semicolons.
        • itemAttributes specifies the item attributes to be added as columns. It is possible to add one or more attribute columns separated by semicolons. The format is {Column_Header : Attribute_SID}.

Example

<Swtabid>

    <DisplayedColumns itemProperties="Version;Status;Type;LastChanged;LastChangedBy;Description" itemAttributes="{Identity:2RQID};{String:RATI};{Date:DATE};{User:2AP2};{Boolean:4NIV};{External reference:XRFA};{Float:2AP5};{Integer:FP03};{RVF:TSCA};{Text:CONS};{XML:CHXM};{Enumeration:10KI}"/>

</Swtabid>


Click Save to save the configuration.


Example Plugin Configuration


Request Update

If Manage add-ons in Jira indicates the swtabid plugin is incompatible with your Jira instance, follow the instructions to request an update (note that this requires a connection to Atlassian Marketplace) or contact support@systemite.se.


Creating a Custom Field in Jira

The next step is to create the custom field mentioned in the previous section. The id for the custom field is system-generated, so you need to go back to the plugin configuration and replace the dummy value in JIRA Custom Fields

Click on the Jira Administration cog icon and select Issues.



On the left-hand side under FIELDS, click on Custom fields.



In the upper right-hand part of the screen, click on Add custom field.



In the Select a Field Type dialog, find the type Text Field (multi-line), select it and click Next.



Enter a Name and a Description for the multi-line text field. The name could be anything, but since it will hold SystemWeaver item ids, we suggest something that describes the context, e.g., SW Items. Click Create.



After the custom field has been created, you will need to look up its id. You can find it by clicking on the Jira Administration cog icon, selecting Issues and clicking on Custom fields. Find the custom field you have created (in this example, it is "SW Items"). Click on the cog drop-down to the far right of the custom field. When you hover over the menu, the custom field id will display in the lower left corner of the web browser. In our example, the id is 10007. 

When you enter this value in the configuration, you need to add the prefix customfield_.  So, in this example, the value in the configuration will be customfield_10007.



Adding the Custom Field to Jira Screens

Users will want to be able to create Jira issues from within SystemWeaver. So, you will need to add the new custom field to all Jira screens where they are needed. Otherwise, users will get an error message that the custom field does not exist.  When you do this, you will be adding it to a second tab so it is hidden from everyday use. Due to a quirk in Jira, you will also need to add an additional dummy custom field to the first tab to make this work. So, create an extra dummy custom field of type Text Field (single line), for example. In the below example, a dummy field has been added called Info



Next, add the custom fields to the screens as needed. Click on the Jira Administration cog, select Issues and then Screens. Here, click on Configure for each screen you need to change.



Click thebutton to add a new tab. On the new tab, add the custom field (in our example below, "SW Items").


On the first tab, add the dummy custom field that you created. In the below example, the Info" field is added to the Fältflik tab. Again, Jira requires this for the functionality to work.



When you are done, review how a Jira issue will look. The Jira plugin adds a new tab called SystemWeaver to the Activity section at the bottom of an issue. The tab shows all items connected to the viewed issue. The issue is linked to the items using the item ids. Thanks to the SystemWeaver back-end service for JIRA, information about the items such as Name, Status, Type, etc. is viewable. In the Details section, you will see the two custom fields that you created (in the example, the dummy Info field on the first Fältflik tab and the SW Items field on the SW Items second tab). 



Click on the tab with SW Items to view the SystemWeaver item ids. Had these not be configured for placement on the second tab, they would always be shown on the Jira issue which could be distracting for users. 


Note: You may want to consider hiding or locking down the SW Items field so that users do not accidentally modify the value(s) which would break the link between issue and item(s). 



Epic Issue Type

The Epic issue type in Jira behaves differently than other issue types. When you create an Epic issue from within SystemWeaver, some extra information is needed. The Epic issue type has a special custom field that you need to be aware of. You also need to know the id of the Epic issue type. To find the issue type id, click on the Jira Administration cog icon and select Issue types. Look for the Epic issue type and hover over Edit. The issue type id will display in the lower left-hand corner. In this example, it is 10001. Remember this id for the SystemWeaver configuration.


You will also need the custom field id for Epic name. Click on Custom fields and look for the Epic-name field. Click on the cog drop-down to the far right of Epic-name. Hover over Screens. The custom field id can be seen in the lower left-hand corner. In this example, it is customfield_10004. Remember this for the SystemWeaver configuration.




Note on Required Custom Fields: As of release R36, standard Jira custom field types are supported in the Jira extension. This means that issue types with these types of required fields can be populated by users when creating Jira issues via SystemWeaver. A list of all the custom field types (standard and advanced) can be found in here.

A few of the custom fields require certain formats according to the Jira standard: 

  • Labels: For multiple labels, use the “,” character to separate labels.
    Example: Label1,Label2 will create Label1 and Label2 in Jira. 
  • URL field: Format: https://www.systemite.se
  • Cascading select list: Select a primary option with the possibility to select a secondary option linked to the first option.
    Example: Select Parent 1, Parent 1 Child 1 or Parent 1 Child 2.
  • Date time picker: Format: 1991-05-28 13:37 (yyyy-mm-dd hh-mm)

Configuring the SystemWeaver Jira Extension

The integration between SystemWeaver and Jira involves the use of a SystemWeaver extension called SWExtension.Jira2.dll. This extension will need to be located in the client installation in the swExplorerExtensions folder for each user that wants to use the integration. The extension will need to be configured by a user with the Architect role using the swExplorer client. After logging in, click on File Configure the explorer.



A list of available views will display on the Item views tab. If the SWExtension.Jira2.dll extension file has been correctly placed in the swExplorerExtensions folder, the Architect will see Jira in the list. To activate the extension, select the entry and check the Active box. Next, click Edit configuration to change the configuration. 


Tip: Click View example XML, to view an example configuration that you can copy and use to create your configuration.



In the Edit XML dialog, add the configuration for the extension. It should look something like the example below. You can add several Jira instances inside the <Jiras> tag, each within its own <Jira> tag. In the below example, there are two.


First, enter a code inside the <ServerCode>. In the below example, the code is SW. This code must match the SW Server codes field in the Jira plugin configuration. 

Next, configure which item types should activate the extension. This is done using the <ItemType> tag. Several item types can be used and separated by a semi-colon “,”, e.g., "RBFN,RQ,JTCS". (Note that this will be changing to “;” in a later version). If you want to activate the plugin on all item types, use the sid I.


Then, for each Jira instance <Jira>, enter the following: 

  • <Name>: a descriptive name for the Jira. 
  • <BasUrl>: the url for the SystemWeaver Back-end Service for JIRA
  • <MainProject>: the project used the most. 
  • <Customfield>: the custom field created for SystemWeaver items. 
  • <Relationship Floating=""/>: the relationship type between SystemWeaver's item and Jira's issues, the attribute Floating specifies if the relationship floats fowards to newer versions or not. Possible values are 'True' or 'False'.
  • <Epic>: information for the Epic issue type if that is used. See the Epic Issue Type section above for how to retrieve this information.
    • <EpicTypeId>: the id for epic type. 
    • <CustomField>: the custom field that is used for Epic Name. 
    • <EpicName>: a value that will be used for the Epic Name. 


Example

<JiraConfiguration>
<Jiras>
<Jira>
<Name>Jira1</Name>
<BaseUrl>http://srv-app-01:8080</BaseUrl>
<MainProject>ADLV3</MainProject>
<CustomField>customfield_10007</CustomField>
<Relationship Floating="True"/>
<Epic>
<EpicTypeId>10001</EpicTypeId>
<CustomField>customfield_10004</CustomField>
<EpicName>Epic issue</EpicName>
</Epic>
</Jira>
<Jira>
<Name>Jira2</Name>
<BaseUrl>http://srv-build-01:8084</BaseUrl>
<MainProject>AT01</MainProject>
<CustomField>customfield_10007</CustomField>
<Relationship Floating="False"/>
<Epic>
<EpicTypeId>10001</EpicTypeId>
<CustomField>customfield_10004</CustomField>
<EpicName>Epic issue</EpicName>
</Epic>
</Jira>
</Jiras>
<ItemType>RBFN,RQ,JTCS</ItemType>
<ServerCode>SW</ServerCode>
</JiraConfiguration>

Configuring Extension for Use with Test Domain

There is an option to extend the integration to use with the Test domain


One use case would be, e.g., to create a Jira issue linked to a failed test case. A user would select a Test Case with a result node attribute value of "Failed" in a particular Test specification context and create a Jira issue. The Test specification is stored as an attribute in Jira. The Jira issue could then be assigned to users who can handle the test case that failed. 


To do this, you will need to add the Test SIDs to ItemType:


<ItemType>JBTE;JTCS;JTSP;JSES</ItemType>


 as well as the following tags: 


<Test>JSES</Test> 

<TestSuite>JBTE</TestSuite> 

<TestSpecification>JTSP</TestSpecification> 

<TestNodePath>ISSP;ITEC</TestNodePath> 

<TestCase>JTCS</TestCase> 

<TestAttribute>PTCS</TestAttribute> 


Test Domain Example

<JiraConfiguration>
<Jiras>
<Jira>
<Name>Jira1</Name>
<BaseUrl>http://srv-app-01:8080</BaseUrl>
<MainProject>ADLV3</MainProject>
<CustomField>customfield_10007</CustomField>
<Relationship Floating="True"/>
</Jira>
</Jiras>
<ItemType>RBFN;RQ;JBTE;JTCS;JTSP;JSES</ItemType>
<Test>JSES</Test>
<TestSuite>JBTE</TestSuite>
<TestSpecification>JTSP</TestSpecification>
<TestNodePath>ISSP;ITEC</TestNodePath>
<TestCase>JTCS</TestCase>
<TestAttribute>PTCS</TestAttribute>
<ServerCode>SW</ServerCode>
</JiraConfiguration>