This article describes how to install and configure the SystemWeaver add-on in Jira.

• Installing the SystemWeaver Jira Add-on
• Configuring the Add-on
  • Jira Cloud
  • Jira Server
  • Required Information
  • Plugin Options
  • Example Plugin Configurations
  • Request Update
• Creating a Custom Field in Jira
  • Adding the Custom Field to Jira Screens
  • Epic Issue Type

Prerequisites

• Familiarity with your Jira installation and projects
• Familiarity with your SystemWeaver installation
• Assignment of Administrator role in Jira
• An installation of the SystemWeaver REST API. Ideally installed on the same machine as the SystemWeaver server application that it is accessing.
• The SystemWeaver Jira plugin:
   

  Jira Type	Application Delivery
  Jira Server (local installation)	Obtain swtabid in Atlassian Marketplace. The swtabid plugin file can also be included in your regular SystemWeaver product delivery.
  Jira Cloud	Find in https://marketplace.atlassian.com/
  Jira Data Center	Obtain swtabid in Atlassian Marketplace. The swtabid plugin file can also be included in your regular SystemWeaver product delivery. Ignore any incompatibility messages.

Installing the SystemWeaver Jira Add-on

In Jira, click on the Administration/Settings cog icon and select Apps in Jira Cloud or Add-ons in Jira Server.

If you have not retrieved the add-on from Marketplace, click Find new apps to search for it. 

For Jira Server, click Upload app and Choose File on the next screen and select the file swtabid-1.0.X.jar provided by Systemite or downloaded from the Marketplace. The plugin will now be seen in the list of user-installed plugins. 

Configuring the Add-on

Open the configuration screen for the Add-on. 

Jira Cloud

Under Apps, select the SystemWeaver Admin Page. 

Jira Server

Click on Manage apps. 

Find the swtabid installed app, and click on Configure.

On the configuration screen, you will need to enter some information that the plugin needs in order to display SystemWeaver item information in Jira issues.

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. Note: This setting is only applicable for Jira Server installations; not Jira Cloud.

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 Username: Enter a valid SystemWeaver username. The user account must have a minimum of read access to the SystemWeaver items that Jira needs to display. 
• SW Password: Enter the above username's password. 
• SW JIRA REST API URL: Enter the URL for the SW Rest API, e.g., https://swdb.systemite.net:6001  Note: This setting is only applicable for Jira Cloud installations; not Jira Server local installations.
• Back-end Service Server: Enter the server name for the REST API. Note: This setting is only applicable for Jira Server installations; not Jira Cloud.
• Back-end Service Server Port: Enter the port for the REST API. Note: This setting is only applicable for Jira Server installations; not Jira Cloud.

SystemWeaver server information and Jira Custom Field:

• SW Server Machine: Enter the server for the SystemWeaver server application. This allows the SystemWeaver item urls to display in the Jira plugin. When using a Jira local server installation with multiple SystemWeaver server applications, use a semi-colon delimiter. The input order must match that of SW Server Ports.
• SW Server Port: 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 Field: 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. This must be set to "True" if RequireHttps is set to "true" in the SystemWeaver Rest API configuration. Note: This setting is only applicable for Jira Server installations; not Jira Cloud.
• 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 selected, users 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. Note: This setting is only applicable to Jira Server installations; not Jira Cloud. 
• 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, as well as RVF attribute types with Jira Cloud. Note: It is not possible to display Description in Jira Cloud. 
  • 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="Name;Version;Status;Type;LastChanged;LastChangedBy" itemAttributes="{Req Source:ASID;}"/>
</Swtabid> 

Click Save to save the configuration.

Example Plugin Configurations

Jira Cloud

Jira Server

Request Update

If Manage add-ons/apps 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 [email protected].

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. 

The instructions below are for Jira Server, however, configuration of a custom field in Jira Cloud is similar. Refer to your Jira application Help for assistance as needed. 

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.