Introduction

A SystemWeaver Jira plugin has been developed that offers a solid integration between SystemWeaver and Jira. This document describes how to install 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 Back-end service (Systemite.swAppServer.WebAPIHostConsole), incl. plugins
  • The SystemWeaver Jira plugin (swtabid-1.1.0-SNAPSHOT.jar)
  • The SystemWeaver SWExtension.Jira2.dll client extension
  • An installation of the SystemWeaver Monitor Service (use is optional, but recommended)

Installing the SystemWeaver Back-end Service for JIRA


The SystemWeaver Back-end Service is a Windows executable that communicates with the SystemWeaver server. The executable is called Systemite.swAppServer.WebAPIHostConsole.exe. It works as a standalone web server that can host plugin-dlls. The plugins reside in a plugins folder and the plugin for the back-end service is Systemite.swAppServer.SwRestPlugin.dll. To install, you need to modify two configuration files. 


Systemite.swAppServer.WebAPIHostConsole.exe.config

First, change the Systemite.swAppServer.WebAPIHostConsole.exe.config. In the swAppServer portion, change <port> to the port you want the back-end service for JIRA to listen to. This port must be open in the firewall so the Jira server can access this port over the network. Regular users do not need to be able to access the port. In the below example, the port used is 1351.

<swAppServer>
     <host>+</host>
     <port>1351</port>
...


Further down in the file there is a <swServer> tag. Here, modify the values for <host> and <port>. Enter the ip-adress and port number to the SystemWeaver server. The server and port must be accessible over the network from the host of Systemite.swAppServer.WebAPIHostConsole.exe.

<swServer>
     <host>sys7</host>
     <port>1349</port>
</swServer>


Systemite.swAppServer.SwRestPlugin.dll.config

You will also need to modify the file Systemite.swAppServer.SwRestPlugin.dll.config in the plugins folder. The server needs to impersonate the SystemWeaver user configured for the Jira plugin. The only user that can do that is the SystemWeaver user called system. Enter the system account's username and password in the config file. Look for this settings segment and enter the password for the user system where it says pw in this example. An administrator can change the password for system if that is needed.

<setting name="User" serializeAs="String">
     <value>system</value>
</setting>
<setting name="Password" serializeAs="String">
     <value>pw</value>
</setting>


When the above is completed, this back-end server needs to be started. This is done by right-clicking on Systemite.swAppServer.WebAPIHostConsole.exe and selecting Run as administrator.


It can be tested with rest-aware applications like Postman. For example, enter this url in Postman http://restapiserver:restapiport/api/swplugin/item?xid=url:swap://swserver:swport/x040000000000098B, but replace the following:

  • restapiserver with the ip-address of the back-end server
  • restapiport with the port
  • swserver with the SystemWeaver server
  • swport with the port
  • x040000000000098B with an existing item id in the server.

You will also need to select Basic Auth in Postman and enter username and password for a user in SystemWeaver. If everything works, the back-end server will return a JSON record of the item.



Using the SystemWeaver Monitor Service to run the Back-end Service for JIRA

The back-end service for JIRA can be set up to be run by the SystemWeaver Monitor Service. Instructions for how to configure and run the Monitor Service can be found in Installing the SystemWeaver Monitor Service. For the back-end service for JIRA to run successfully by the monitor service, the service must be run by a local administrator so that it can be accessed from outside the server.


Example

Below is an example <Server> configuration for the back-end server for JIRA. 

To have it restart automatically, set the restart attribute to "true". 

Enter a value for the <startDelay> attribute to enable the main server to come up before the back-end server. 

Enter the location to the back-end server executable in the <exe> tab.

<Server restart="true" startDelay="10000"> 
    <exe>D:\src\ServerMonitorTest\Port 1351 Rest\Systemite.swAppServer.WebAPIHostConsole.exe</exe>
</Server>



Installing the SystemWeaver Jira Plugin

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



Next, click on Manage add-ons and Upload add-on.



Select Browse on the next screen and select the file swtabid-1.0.0-SNAPSHOT.jar provided by Systemite. The plugin will now be seen in the list of user/installed plugins. Next, click on Configure on the swtabid tab.



On this next 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 “;”. 


For SW Servercodes, enter a code for the SystemWeaver server you are connecting to. The code must match and 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 back-end service for JIRA, so you need to enter information needed to connect to the SystemWeaver back-end server. 

  • Enter a SystemWeaver username in SW Usernames and its password in SW Passwords. The user account must have a minimum of read access to the SystemWeaver items that Jira needs to display. 
  • Enter the server name and port for the back-end service for JIRA in Rest API Servers and Rest API Server Ports respectively.
  • So that SystemWeaver item urls will display in the Jira plugin, enter the server and port of the SystemWeaver installation in SW Server Machines and SW Server Ports respectively. 


Lastly, enter a dummy custom field id value in JIRA Custom Fields. Note that you will need to come back and update this value once the true custom field id value is generated upon field creation.


Click Save to save the configuration.


Example


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 update the 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 press 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 the 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.



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 Jira Rest API. 
  • <MainProject>: the project used the most. 
  • <Customfield>: the custom field created for SystemWeaver items. 
  • <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>
            <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>
            <Epic>     
                <EpicTypeId>10001</EpicTypeId>
                <CustomField>customfield_10004</CustomField>
                <EpicName>Epic issue</EpicName>
            </Epic>
        </Jira>
    </Jiras>
    <ItemType>RBFN,RQ,JTCS</ItemType>
    <ServerCode>SW</ServerCode>
</JiraConfiguration>