Hansoft JIRA integration manual Top Next

This manual takes you through all the necessary steps to successfully setup your Hansoft JIRA integration.

Introduction Top Previous Next

Hansoft/JIRA comparison (differences) Top Previous Next

Before going into more details regarding the integration it is important to explain the main differences betweenHansoft and JIRA regarding projects, data models and so on.

Item type, status and workflow differencesItems and tasks in JIRA and Hansoft differ in regards to type, workflow and statuses. All item types in JIRA are asso-ciated with a workflow and their item status is derived from that workflow. Items in Hansoft are defined by thesection from which they originate.

Items in Hansoft from the product backlog are neutral in the sense that they only exist in the product backlog andcan be typed as "user stories". Items in the Product Backlog can be committed to the project schedule where theycan be task scheduling items and be planned out gantt style, or they can be committed to sprints and be estimatedas agile items. Theses items do not have a workflow attached by default in Hansoft.

Items in the QA section does however always have the defined QA workflow applied.

Because of this difference, one important step in setting up your integration is replicating the JIRA workflows inHansoft for the item types which you are going to sync, so that the workflows can be properly applied andmatched when running the integration. Workflow matching is described in more detail in the installation part ofthis manual.

You can read more about workflow creation in Hansoft here: Creating matching workflows

Hansoft sections vs JIRA screensHansoft projects contains three main views where tasks and items are located; the product backlog, the projectschedule and the QA section (see screenshots at the bottom of this page).

The section that mostly resembles JIRA is the QA section which is a flat structure of items (bugs). Items in the QAsection always have an assigned workflow which makes this section easy to map towards JIRA.

The product backlog and project schedule within Hansoft are hierarchy based and supports a virtually unlimitedtree depth. JIRA items are organized in a flat structure with sub-tasks supplying a hierarchy of depth one.

Because of this difference in data structure, a thorough mapping of the two systems is needed when creating theJIRA filters and Hansoft reports used for syncing items. This is described more in detail in the Detailed installationinstruction section of the manual.

JIRA and Hansoft projectsIn a typical agile project we have our product backlog for planning and estimating tasks, the project schedulewhere we work on tasks and a QA section where we handle bugs and issues during development. In JIRA theseitems are of different types but stored in a flat structure. When integrating with Hansoft we most likely want thedifferent item types to be synced to the different sections of Hansoft (see the above section).

For each Hansoft section of your project you want to sync items to you need to setup the integration. In each sec-tion you create a report to filter out the items you wish to sync (picture 2). If you are syncing three different JIRAitem types to different sections in Hansoft you need to create three JIRA filters, one for each item type (see pic-ture 1).

Picture 1: JIRA filters syncing different item types to different sections in Hansoft

Picture 2: one report per section is used in Hansoft to specify which items that should be synced to JIRA

Picture 3: in this setup we sync two Hansoft sections to one project in JIRA and another Hansoft section to a secondJIRA project

Hansoft sections

Project schedule view

Product backlog

QA section

Technical overview Top Previous Next

Communication overviewThe Hansoft JIRA integration initiates communication with the JIRA server by contacting the servlet HansoftServicemodule added by installing the Hansoft Support JIRA version 2 plugin. The hostname of the JIRA integration serverand the number of an unused port on that server is sent to the servlet. The hostname and port are configured inthe JiraIntegrationSettings file as "NotificationHost" and "NotifcationPort". The servlet opens a TCP channel backto the JIRA integration server. This channel is then used for all communication between the integration and theJIRA server.

A simplified view of the integration communication between Hansoft and JIRA

Getting started Top Previous Next

Before starting the installation there are some prerequisites that need to be met.

•Hansoft server with a license with the SDK module active-- Hansoft server download: http://www.hansoft.com/support/downloads/-- Information about acquiring an SDK license: http://www.hansoft.com/sdk-integrations/

• Hansoft JIRA integration installer: Download SDK & integrations

•JIRA server version 4.1.1 or later

•JIRA Greenhopper plugin installed. This is needed for the integration to be able to properly sync Hansoft Sprintsand Releases to Versions in JIRANote: The Greenhopper plugin needs to be installed but does not have to be loaded in any projects in case youare not using this module

•A Windows server for running the integration

•Hansoft server requirements and recommendations can be found here: Hansoft system requirements

Installation and setup Top Previous Next

Overview Top Previous Next

Note: Before deploying the JIRA integration with your production Hansoft server, you should test your configurationagainst an isolated Hansoft test server and also a sample JIRA project. This will make the actual implementationmuch easier and ensure that a minimum of changes needs to be made after you go live.

In addition to the above we strongly recommend that you enable the e-mail notifications in the IntegrationSettingsfile. These notifications contain valuable information for when you are matching your Hansoft and JIRA workflowsfor example. You can read more about the config file here: Detailed installation instructions

To run the Hansoft JIRA integration you need to have a Hansoft license with the SDK module enabled. To enable theSDK module on your license or request a SDK sandbox license contact support@hansoft.com.

The Hansoft JIRA Integration runs as a Hansoft SDK client process, that logs on to the JIRA server to read/write andupdate data.

The Installation proceeds roughly as follows (more detailed instructions follow):

1.Create an SDK user in your Hansoft database. The JIRA Integration uses this account to log into the Hansoftserver to create and modify data. When this user is Online the information specified in the settings file is correct.

2.Create or obtain a user account for your JIRA server. The JIRA Integration uses this account to log into the JIRAserver and projects to perform data updates. You also need the server name and port for the JIRA server that youwant to connect to.

3.Obtain the network address and port of the SMTP mail-server that the JIRA Integration needs to send out its e-mail notifications. If the server requires authentication, obtain or create the username/password pair that theJIRA Integration is to use.

4.Install the JIRA integration on the system that will act as the JIRA notification listener .

5.Enter the JIRA information in the JiraIntegrationSettings file in JIRA integration installation folder.

6.Install the integration plugin on your JIRA server. The plugin .jar files are found in the integration install dir-ectory.

7.Go to the Integration settings in for the applicable view(s) in Hansoft.

8.Specify which JIRA projects that you want Hansoft to synchronize/get data from.

9.Create a report in Hansoft that filters out the items that should be synchronized with JIRA.

10.Create a query filter in JIRA to specify which issues that should be synced to Hansoft.

Detailed installation instructions Top Previous Next

Make sure to read the Getting started section for setup prerequisites.

Tip: Name the SDK user and the integration user on the JIRA side the same. This will make it easier for any potentialtroubleshooting you may need to do.

Create an SDK user in your Hansoft database. The JIRA Integration uses this account to log into the Hansoft server tocreate and modify data. Login to Hansoft using the

"Administrator" account. This is the only account permitted to create SDK users.

Select the Create SDK user option in the Administration tab.

Set a name and password for the SDK User. Each integration needs its own SDK User. If two integration have thesame SDK User specified only one will be able to connect at a time.

The SDK account is used by the integration to perform updates on the Hansoft server.If you do not have the option tocreate SDK Users contact support@hansoft.se to enable the SDK module on your Hansoft license.

Launch the JIRA integration installer.

In this step the installer will open up the integration settings file for configuration. You can update it right away oropen it at a later time. Bear in mind that the integration needs to be restarted for any changes done to the settingsfile after the installation to take effect. The settings file is located in the integration install directory specified instep 3.More details about the settings file are found at the end of this page (Link).

Once the installation has been completed the integration will launch. You can verify that you specified the correctinformation by checking that the SDK user is online, by the notification e-mail or in the logs. The log files are foundin the JIRA integration install directory specified in previous steps. When checking online status of the SDK user,remember that only the "Administrator" account can see SDK users in the user list.

To allow for communication between the JIRA integration and JIRA the Hansoft integration plugin must be installedon JIRA. Manual installation of plugin files, JIRA version 4.1 and newerCopy the Hansoft plugin from the JIRA integ-ration folder to the "JIRA install directory\Application Data\JIRA\plugins\installed-plugins" folder on the JIRA server.Restart the JIRA server for the plugin to be loaded.This method works for all versions of JIRA, including the ones thatsupport loading of plugins through the web GUI (see below).

Plugin installation through the web interfaceIn JIRA version 4.2 or newer the plugin can be loaded directly from thePlugins menu under the System folder in the Administration in JIRA. Start by clicking the "Upload Plugin" button.

In the popup menu select "Browse" and navigate to the integration install directory. Select the .jar file which cor-responds to the version of JIRA you run. In this example we are running JIRA 4.3 and I select that plugin file.

Theplugin will then be uploaded and installed.

Create or obtain a JIRA account for your JIRA server. The JIRA Integration uses this account to log into the JIRAserver and projects to perform data updates. When the Hansoft plugin is loaded (see step 3 above) a group called"hansoft-plugin-users" is created. The JIRA user that is to be used by the integration needs to be a member of thisgroup. This is just a precautionary step to give you control over which JIRA user is allowed to be used by the integ-ration.You also need the server name and port for the JIRA server that you want to connect to.Note: The integrationonly supports a single JIRA user for synching the data.You are now ready to setup the integration in the desiredHansoft section. The settings are accessed via the More... menu in the Hansoft project you are integrating with JIRA, Customization and settings and the Customize project integration settings...

Fill in the required information as described below.JIRA host: The URL to the JIRA server to which the integrationshould connect. This is the same URL your users use to login to the JIRA server (must contain http://)JIRA user &password: Login details for the JIRA user you have created for the integration.User settings: Tick this option if youwant the integration to create ghost users for all JIRA users that cannot be matched to Hansofts users. This is recom-mended. Rear more about user matching here: User matchingJIRA group used for user synchronization: The JIRAgroup, or groups, from which to sync users to Hansoft. Can be an already existing group or a new one which willthen be created by the integration. You can specify multiple groups, separating them using semi colon. For example:Group 1; Group 2Note: This does not create users in Hansoft. It is merely used to list JIRA users which the integ-ration tries to match towards existing Hansoft users.Status: As you configure the integration, this area will display

continuous feedback as to which settings are still to be filled in, if user name or password is incorrect and so on.

1.In Hansoft you must create a report that filters/cover all the items, task or bugs that you want to be syn-chronized with JIRA. This report is used in step 7 when the item sync is setup. Reports are not global across yourproject but are local to the different sections in Hansoft (Product Backlog, Project Schedule and QA) so thereport needs to be setup in the view you are configuring the integration for. Note: Make sure to test this reportproperly so that it returns the desired result before deploying it.2.

More detailed guidance on how to use the query filter in Hansoft can be found in the below video:http://www.hansoft.com/videoitem/hansoft-7-0-reporting-tool/

You then create a filter on the JIRA end to select he issues you want to syncronize to Hansoft.The filters on the JIRAside needs to be created by the JIRA user used by the integration.

In the second tab of the integration settings you specify the parameters for the sync in more detail.Enable JIRA Pro-jects: Here you select which JIRA projects that the integration should be able to sync towards. Note that the integ-ration can sync towards multiple JIRA projects at once. You can for example sync one issue type from on JIRAproject, and another issue type from another JIRA project.Replication settings:- Default JIRA project for new itemsin Hansoft: Items created in Hansoft and synced over to JIRA should by default be created in this JIRA project.-Default JIRA issue type for new items in Hansoft: Items created in Hansoft and synced over to JIRA should bydefault get this item type in JIRA.- Filter for issues to replicate from JIRA to Hansoft: Select which JIRA filter theintegration should use to find the issues to be synced over from JIRA to Hansoft. (for the above enabled JIRA pro-jects)- Report for items to replicate from Hansoft to JIRA: Select which Hansoft report the integration should useto find the issues to be synced over from Hansoft to JIRA.- Report for milestones and sprints that should beunarchived in JIRA: Select which Hansoft report the integration should use to find the milestones and sprints thatshould be unarchived in JIRA. More details are found here JIRA versions, Greenhopper, Releases and SprintsMaxissues to replicate from JIRA to Hansoft: Limits the amount of issues that the integration will sync at a maximum.If the list of issues returned by the JIRA filtered specified exceeds the specified limit, the integration will the syncfrom the top of the list until the specified limit is reached.

Minimum issues expected in JIRA filter: If the JIRA filter returns less items than specified the integration will halt.This prevents accidental deletion of items by removing or changing filters

Column settings:

- Create fields for deactivated Hansoft columns in JIRA: By default only the columns activated in Hansoft are createdby the integration on the JIRA side. If you want all columns to be created, including deactivated ones, tick thisoption.

- Create fields for Hansoft summaries in JIRA: Tick this if you want Hansoft calculated summaries to be synced toJIRA. - Create fields suitable for statistics in JIRA: Tick this if you want fields useful for JIRA dashboards.

Note: These two settings are explained in more detail here: Stat and Summary

The last step is to ensure that you have the correct Hansoft user(s) bound to the correct JIRA user(s). This is doneautomatically by the integration based on user name and e-mail address, but you have the option to review, and ifneeded, make changes on a per user level in Hansoft. After the installation of the integration you will have a JIRA tab for all users and it allows you to enable/disable the binding and also to manually pair it with any JIRA useraccount shown in the drop list.This group setting is found here: JIRA user group settingsNote: If an update is done toan item by a user that is not bound to a user account on the corresponding system, the users setup in the integrationis recorded as having made the update.

Integration settings file setup

It is strongly recommended that you enable e-mail notifications to ensure that you are informed about the integ-ration status.

* JiraFilterNameFilter: This option is used to limit the amount of JIRA filters that the integration makes available inthe project configuration. Because filters can be shared to all users, and across JIRA projects, the amount of filtersto be synced can be rather high. This option is used to throttle the list and and make the filter selection more man-ageable on the Hansoft side. This option uses the filter search functionality found in JIRA through the regular web cli-ent. An easy way of testing your filter setup is to login to JIRA using the integration user used by the integration andthen construct the search string there. When you are satisfied with the search result you can simply copy the searchstring to the integration file and restart the integration service.

Configure the Hansoft Login Top Previous Next

//////////////////////////////////////////////////////////////////////////////////////////

// Configure Hansoft Login

// You can specify several "HansoftDatabase" sections to connect to several servers at once.

HansoftDatabase

{

Host localhost // The IP address or DNS name of the Hansoft server to connect to.

Port 50256 // The port of Hansoft server to connect to.

Database "Company projects" // The Hansoft database to connect to.

    User JIRASDKUser     // The SDK account in the Hansoft database to connect to.    Password hpmadm                 // The password for the SDK account in the Hansoft database to connect to.SDKSessionTimeout 0   // The number of seconds until the SDK session timeouts if it cannot communicate with the Hansoft server. If set to 0 th-e default value is used.

// Configure certificate for this connection to a Hansoft server

EnableCertificates 0 // Enable usage of certificatesPublicCertificatePath "" // If found the file overrides PublicCertificateDataPublicCertificateData "" // Server public certificatePrivateKeyPath "" // If found the file overrides PrivateKeyDataPrivateKeyData "" // Private key

// Use these settings to specify a certificate authority that is not in your OS trust store. The OS trust store will still be used // to authenticate the Hansoft server in addition to these settings.

CertificateVerifyHostnameMatches 1CertificateVerificationDepth 9 // You can reduce this if you have a known certificate depthCACertificatePath "" // If set and found the file overrides CertificateCACertificateDataCACertificateData "" // Certificate Authority data

PathToCRLs "" // Certificate Revocation List store directory, disabled if emptyCRLPath "" // If found the file overrides CertificateCRLDataCRLData "" // Certification Revocation List data

}

//////////////////////////////////////////////////////////////////////////////////////////

// Plugin Configuration

// Used for communication between the Hansoft plugin on the JIRA server and the integration.

NotificationHost localhost   // The IP address or DNS name of the host the JIRA integration runs on. 

NotificationPort 503-00               // The port on the JIRA integration server listening for connections from the Hansoft plugin on the J-

IRA server.JiraFilterNameFilter "hansoft" // The filter used to filter the filters that are available in configuration

FuzzyMatchingStrength 0.0 // Fuzzy matching strength (0-1.0, default is 0) 0 means only a faster case-insensitive match will be made. A suitable starting value for fuzzy matching is 0.25

//////////////////////////////////////////////////////////////////////////////////////////

// Configure Email Notification

EmailEnableLogging 0 // Logs email communication with the smtp server to the "LogEmail" folder to enable debugging email settings

EmailServer smtpout.hansoft.se // The SMTP server to send emails through.

EmailServerPort 2525 // The port of the SMTP server to send emails through.

EmailsFromName "Hansoft Jira Integration"       // The name appearing in the from field on sent emails.

EmailsFromEmail "" // The email appearing in the from field on sent emails.

EmailServerLoginName "" // The login name to use to login to the SMTP server. Leave blank to disable login.

EmailServerLoginPassword "" // The password to use to login to the SMTP server.

EmailSecurityProtocol"None" // The email security protocol to use, available options are: None, SSL or TLS

EmailSendAdminEmailsTo "" // The email address to send administrative emails to.

EmailSendAdminEmailsToName "Admin" // The name for the email address to send administrative emails to.

//////////////////////////////////////////////////////////////////////////////////////////

// Configure JIRA Custom Fields

// Here you can add write access for JIRA custom fields, you can specify several "CustomFieldMapping" sections

//CustomFieldMapping

//{

//CustomField "" // The full path of the custom field to be handled, form: "<full.plugin.key>:<customFieldName>"

/-/

HansoftType ""// How Hansoft will treat this value, possible values: "Text", "Hyperlink", "DropList", "Integer", "Float", "DateTime", -"MultiLineText", "People", "TimeSpent", "MultiSelectionDropList", "DateTimeWithTime"

/-/

AccessRight ""// Initial access right when this column is first created, possible values: "AllProjectMembers", "SubAndMainProjectMan-agers". "MainProjectManagers", "ReadOnly". Can later be changed in the project custom column settings.

//}

Sharing JIRA filters Top Previous Next

Sharing JIRA filters for integration useWhen configuring the JIRA integration in your Hansoft projects you specify a JIRA user for the integration to use.One of the things this user is used for is listing filters for deciding which issues should be synced from the JIRA side(see Detailed installation instructions). Even though different Hansoft projects can sync to different JIRA servers, theintegration is limited to one user per JIRA server it is syncing too. Instead of having this user creating the filtersneeded for the syncing, you can simply share filters to the user instead. This way you can easily make existing filtersavailable to the integration.

Creating matching workflows Top Previous Next

IntroductionNote: Before all workflows in the enabled JIRA projects are correctly matched with their Hansoft counterparts, noitems will be synced to JIRA.

For more information about working with workflows in Hansoft, please consult the Hansoft online manual:http://hansoft.com/manuals/71/English/projects_pkw_workflows.htm

Feel free to contact us at support@hansoft.se for any integration setup questions you have.

Items in Hansoft do not have workflows linked to them by default, but since all item types in JIRA are associatedwith a workflow we must replicate the JIRA workflows in Hansoft for the item types the integration will sync.

In the example below we will create the standard JIRA workflow in Hansoft.

To help you get started there is an example of the default JIRA workflow in the "More" menu in the workflow editor.You can use this workflow during your initial setup to get an understanding of how the workflow matching is done.

RestrictionsThe restriction models in Hansoft and JIRA are too disparate to be automatically setup by the integration. It is there-fore important that you map your data flows in the two systems and ensure that the desired restrictions are appliedby the system where the data update is triggered.

Name matchingThe workflow matching between JIRA and Hansoft is name based so it is important that both your workflow and allworkflow steps are all named exactly like their counterpart in JIRA. There is an option to override this name match-ing if needed on a per status level. See the "resolution" section below: Resolution settings

In order to get you started the default workflow XML (jira_default_workflow.xml)can be found in your integrationinstall directory. The option to import a workflow is found in the "More" menu in the workflow editor.

The basic workflowPicture 1 shows the steps of the "jira" workflow, the standard JIRA workflow.

The corresponding workflow in Hansoft would look as picture 2.

Picture 2:

At a glance this might look like a bit of a tangle but it is easier if we look at the statuses one by one. Let's take the"Open" status as an example.

The "Open" status is connected to three other statuses, "In Progress", "Resolved", "Closed", through three transitions(Transitions in Hansoft and JIRA differs, see below).

Picture 3:

The "Open" status and corresponding transitions (connections in Hansoft) would be setup like in picture 4.

Picture 4:

Simply repeat this for the other statuses of your workflow and you are done.

Transition rules

In JIRA, rules for progressing a workflow are setup in the transition connecting two statuses. In Hansoft a connectiondoes not have specific rules, it is simply connecting two statuses. "Transition" rules are setup within the statusesthemselves or in a specific "Transition" connection between two statuses.

If we take the setup from picture 2 and say that we want specific data to be filled in for a user to progress the work-flow to the next step, we then edit the "Open" status. As seen in screenshot 5 we specify that a new comment mustbe added to the item before progressing it to the next workflow step.

Picture 5:

The new comment will be required regardless of which status the user want to progress to. If we want to make aspecific requirement towards a single status we create a "Transition" like in picture 6.

In this transition I now specify that a comment must be filled in in order to progress to the next status. When using a"Transition" I can also specify which users, or groups, that are allowed to make the transition.

Picture 6:

JIRA resolution settings on Hansoft workflows:

In JIRA, "resolution" is a mandatory field for certain workflow statuses. In order to support this, "resolution" must besetup for each workflow step in Hansoft where it is mandatory or where it should be cleared.

We continue the example from above. We now want to make sure that if we complete an item from Hansoft "res-olution" is set in JIRA. Right click the "Closed" status and select "JIRA workflow settings".

In this window you now have 2 drop down lists. The "JIRA status" is currently set to match by status name. This is thedefault setting and the "Closed" status in Hansoft will then be matched to the "Closed" status in the correspondingJIRA workflow. If needed, this menu can be used override the built in name matching and instead link a Hansoftworkflow step to a specific JIRA workflow step.

If possible we recommend that you name the statuses the same to avoid unnecessary confusion in your data match-ing.

The second drop down "JIRA resolution" is used to specify what "resolution" should be set to when the workflowreaches this step in Hansoft. We set it to "Fixed".

The other way around we also need to specify that "resolution" should be cleared when moving from say "Closed" to"New". We then edit the "New" status in and specify that "resolution" should be set to "No resolution".

Repeat this for all statuses where "resolution" is mandatory to be set to a specific value or cleared.

Workflow matching in the QA section.

Since Hansoft only has a single workflow in the QA section, but you can sync multiple issue types to a single sectionin Hansoft, the workflow matching setup is expanded with an additional drop down in the JIRA workflow settings dia-logue. The first dropdown is used to select the JIRA workflow you want to match status and resolution for. Apartfrom this first dropdown the configuration is the same as for workflows in the other Hansoft sections.

JIRA workflow statuses with multiple resolutions.

As we described earlier you need to map JIRA resolution in Hansoft in order for it to properly propagate to JIRAwhen progressing workflows from the Hansoft side. In JIRA you can have different resolutions for the same work-flow, for example closed with resolution "Fixed" and closed with resolution "Won't fix". If this is the case you need tocreate a workflow step for each of the alternatives in Hansoft and map the resolutions to match. In order to avoidconfusion and make it clear for your users we recommend that you name your Hansoft workflow steps with the res-olution to which they are matched.

An example Hansoft QA workflow supporting two JIRA workflows, where one of them has two Closed statuses withdifferent resolutions, could look like this.

Column matching Top Previous Next

Hansoft JIRA integration columns and matchingsJIRA columns created in Hansoft by the integration are appended with (JIRA) to be easily distinguishable. Similarlyall Hansoft columns created in JIRA are appended with [Hansoft]. Project specific Hansoft columns will in addition tothe Hansoft tag have their project name in square brackets as well.

Example: "Database ID [Hansoft, Support project]"

Summary fields for numeric columns

In order for the integration to properly work with summaries, all numerical Hansoft columns will generate two addi-tional fields in JIRA: Stat and Summary. These columns should not be deleted or updated manually.

The option to enable the Summary and Stat columns are set up per integration in the sync settings dialogue.Moreinformation found here.

Example: Estimated Ideal Days [Hansoft Stat]

URL columns

The integration makes URL columns available on both the JIRA and Hansoft side to make it easy to jump betweenitems in the two systems. In Hansoft this column is called "JIRA URL (section name)" and the corresponding columnin JIRA is called "Item URL [Hansoft, Project name]".

URL in Hansoft:

URL in JIRA:

Note: In order for the Hansoft URL:s to be properly generated the server hostname must be specified. This option isfound in the Administration tab in Hansoft.

JIRA attachments default column

When the integration is running a column will be available in Hansoft by default which contains links to the attach-ments of a synced item. This column is called "Attachments (JIRA, Hansoft section)". These links can be used toquickly jump to attachments stored on the JIRA side.

In addition to this column the integration has a functionality to easily download all attachments of a synced item forstorage on the Hansoft side. This is described in more detail here: Migrating attachments

Specific column matching

As described above all system specific columns will be created and available for use in the two systems. There are acouple of core columns that are directly matched between the two systems however and they are described in more

detail below. The two columns associated with assignment and work remaining have some logic associated withthem whereas the other four columns are simply matched.

1.Hansoft "Assigned to" - JIRA "Assignee"For single user assignments the two columns are simply synced between the two systems.

Hansoft supports multiple assignees whereas JIRA does not. In order to support this the "Assigned to [Hansoft]"column in JIRA is used. The "Assigned to [Hansoft]" column in JIRA contains a list of all the assigned users fromHansoft. The first user in that list will be set as "Assignee" in JIRA. Using the "assign to" functionality in JIRA willupdate "Assignee" and add a single user in the "Assigned to [Hansoft]" list, clearing the other assignees in the list.If you wish to use multi assignment from JIRA you must use the "Assigned to [Hansoft]" field to assign users.

2.Hansoft "Work remaining" - JIRA "Logged work", "Estimated", "Remaining"

Estimation works differently in Hansoft and JIRA. In Hansoft "Estimated ideal days" or "Points" are used in theProduct Backlog to estimate User Stories. These are then committed to Sprints where the teams break them downand give them estimates on "Work remaining". Since there is no 1-1 connection on how this works in the two sys-tems it is setup as below.If "Estimated" is not set in JIRA and an item with "Work remaining" is synced from Hansoft, both "Estimated" and"Remaining" will be set to the "Work remaining" value. Following updates to "Work remaining" in Hansoft will notchange "Estimated" but will only update "Remaining"."Logged work" does not have a corresponding column in Hansoft and is not synced.

Tip: In JIRA you have the option to set the format of the "Remaining" field. Since Hansoft uses hours as base valuefor "Work remaining" it is recommended that you set hours in JIRA as well to avoid confusion. This option is foundunder "Issue Features" in the "System" tab of JIRA.

3.Hansoft "Item name" - JIRA "Summary"Simple match.

4.Hansoft "Comments" - JIRA "Comment"Simple Match

5.Hansoft "Originally created by" - JIRA "Reporter"Simple match

6.Hansoft "User story / Detailed description" - JIRA "Description"Simple match

7.Hansoft Finish - JIRA Due dateFor Task Schedule items synced to JIRA "Due date" will be matched with the Hansoft "Finish" date. For QA orProduct Backlog items, which do not have finish dates of their own, this is not populated. If these items are com-mitted to a sprint the JIRA "Due date" will be set to the Hansoft "Finish" date of the sprint they are committed to.

Adding write access for JIRA custom fields.The JIRA integration supports adding write access for custom JIRA fields in Hansoft. This is done by editing the JIRAintegration settings file. First you need to know the full path to the custom field that you want to add, including theplugin key (e.g <full.plugin.key>:<customFieldName>). Second, decide what type of Hansoft column the field should

be mapped as. The possible types are "Text", "Hyperlink", "DropList", "Integer", "Float", "DateTime","MultiLineText", "People", "TimeSpent", "MultiSelectionDropList", "DateTimeWithTime". You also need to set the ini-tial access right when the column is created, possible values are "AllProjectMembers", "SubAndMainPro-jectManagers". "MainProjectManagers", "ReadOnly". The access rights can later be changed in the 'Customizecolumns' settings in Hansoft.

User matching Top Previous Next

What does it do?The integration tries to match JIRA users to Hansoft users in order to be able to properly sync user related inform-ation such as reporter, assignee, comments et cetera. Ghost users in Hansoft are free user objects generally usedfor planning. They are not full accounts in the sense that they cannot login and so, not perform any actions on theHansoft side what so ever. In the event that your JIRA user base is larger than your Hansoft user base, the integ-ration has the option to create Ghost users in Hansoft in order to properly sync the user information.

Why is this important?In the scenario where an item synced in JIRA gets assigned to a user not found in Hansoft, the integration does nothave a user object on the Hansoft side to replicate this action. It is strongly advised that you enable this option toensure good user information on all synced items and avoid getting "missing matching user" notifications sent bythe integration.

Placement of new JIRA issues in Hansoft hier-archy

Top PreviousNext

OverviewOne difference between Hansoft and JIRA is that Hansoft supports a virtually unlimited hierarchy depth for theProduct Backlog and Project Schedule views, whereas JIRA utilizes a more flat structure. Since new items beingsynced from JIRA does not have any hierarchy data they are by default placed in the root of the hierarchy in the sec-tion to which they are synced.

Configuring where to place newly synced JIRA issuesWhen the integration us fully configured in your Hansoft section of choice, the Product Backlog in my example, aright-click menu item will be available on your items.

In this menu you select a report to use for finding new items synced from JIRA.

When a new item is synced from JIRA to Hansoft, the integration checks all items configured as insert locations. Ifthe new item is found by one of the reports, the integration will place the item at this location in the hierarchy.

Note: These insert location reports are only checked when an item is created in Hansoft from JIRA, meaning thatyou are free to move the item from the initial placement once it has been created.

Migrating attachments Top Previous Next

The integration offers a one-click option to migrate attachments from JIRA to Hansoft of your synced items.

Simply mark and right click the item(s) you want to migrate attachments for and click "Migrate attachments fromJIRA to Hansoft". The attachments will now be available in the Hansoft attachment list. See screenshots below.

Note: This is not a syncing of attachments, it is a one time copy of them from JIRA to Hansoft. If additional doc-uments are added on the JIRA side the migration must be run again.

Migration option in the right click menu in Hansoft

Attachment in the Hansoft attachment list

Stat and Summary columns Top Previous Next

SummarySummary columns are used for numerical columns in hierarchies. This number is calculated from the child items ofa parent item and is not stored in the database. If the summary information is needed in JIRA you need to enablethis column.

In the example below the "Estimated days" on "Main story" is not set, it is calculated from the sub-items.

StatLike the example above this column is used when numerical values are calculated on broken down items.Let's say we have the setup like in the screenshot below. "Main story" has an original value set in the "Estimated

Ideal Days" column.

If we then indent the sub-tasks that value will be replaced with a new "Estimated Days" calculated from the sub-items. The old value of 2 days is however still stored in the Hansoft database and the calculated "Estimated Days" ispresented by the client. In order to expose the "correct" value of "Estimated Ideal Days" in JIRA, the 0 value is storedin the "Stat" column.

Upgrading the integration Top Previous Next

Install the new Hansoft JIRA integration.

Delete the old integration plugin either by deleting the plugin .jar file found in "JIRA install directory\ApplicationData\JIRA\plugins\installed-plugins" or by uninstalling it in the Plugins view in the JIRA administration.

Install the updated plugin. Instructions can be found here: Plugin installation

Troubleshooting Top Previous Next

This section contains information on how to troubleshoot potential errors in your setup.

E-mail notificationsThe integration can be setup to send e-mail notifications about errors. Details about the settings file can be foundhere: Settings file

All integration configuration errors are sent to the Administrator e-mail address specified in the settings file.

When an error is reported on the user level (say a rejected update) the integration will check for the e-mail addressof the user responsible for the edit and notify them. The integration first looks for an e-mail address on the Hansoftside. If none can be found there it checks the linked user on the JIRA side for an e-mail address.

If the integration is not enabled for the responsible user the e-mail will instead be sent to the Administrator e-mailaddress specified in the settings file.

JIRA integration status dialogueThe integration adds a status tool for finding any syncing errors between Hansoft and JIRA to any project in whichthe integration is active. To access the status dialogue right-click any item and choose 'Show JIRA Integration status

dialogue':

The status dialogue will display any current errors that are preventing syncing, as well as informing you about cur-rent syncing tasks. Two options exists, 'Auto refresh', which will continuously update the status dialogue and 'EnableStack Trace Dumps' which will write out a full thread dump from the integration when it is enabled. Note that if the'Auto refresh' option is enabled the 'Enable stack trace dump' option will continuously generate new trace dumps:

Database connection pool sizeTo prevent deadlock scenarios when the Hansoft integration is synchronizing issues, we recommend increasing thedatabase connection pool size to at least 32.

This tool can be used if you do not want to manually edit the JIRA settings file: JIRA configuration tool

JIRA hosted on Linux - number of open filesWhen hosting JIRA on a Linux server the Java virtual machine might run out of file handles. Typically the limit is setto 2048 files per process and if this limit is reached the integration will start reporting exceptions when syncingissues.

This article from Atlassian describes how these variables can be modified to allow for more open files: Num openfiles

Examining the integration logsThe log files for the integration are found in the integration install directory under /Log/. Whenever you aretroubleshooting your setup it is recommended to first check the log files for any reported errors.

Could not connect to notification hostThis error is displayed when the Hansoft integration plugin, on the JIRA side, is making a call back to the host server,which is running the JIRA integration, and the connection request is denied. Make sure that a connection betweenyour JIRA server and the server running the Hansoft JIRA integration is allowed through your network to resolvethese types of errors.

Enabling JIRA loggingWhen the integration has been installed you have the option to enable Hansoft integration logging. Add the fol-lowing lines to the atlassian-jira\WEB-INF\classes\log4j.properties file. The JIRA service must then be restarted forthe changes to take effect.

---------------------------------------------------------------------------------------------------############################################################# Hansoft JIRA integration LOGGING LEVELS# Writing INFO or DEBUG sets the level of detail in logging############################################################

log4j.logger.se.hansoft = INFO, console, filelog

log4j.additivity.se.hansoft = false----------------------------------------------------------------------------------------------------

JIRA versions, Greenhopper, Releases andSprints

Top Previous

JIRA Versions - Hansoft Sprints and ReleasesIn JIRA, Versions are used to plan out your project in time and enables you to tag issues to these Versions. In Hansoftthis is primarily done using Releases, together with Sprints, in the timeline view in your Project Schedule. When theintegration is syncing a project, all Versions in JIRA are made available in a custom column in Hansoft, just like anyother JIRA specific attributes. See the Column matching section for more info on this. Since Sprints and Release inHansoft are time planning objects, they are synced to JIRA as Versions.

The integration will sync all Sprints/Releases in Hansoft to JIRA as Versions. You can however configure which of theVersions on the JIRA side that are archived or not to avoid cluttering the Versions list for your users.

This is done with a report in the Project Integration Settings just as for your regular items. If no report is selected inthis drop down, all synced Versions will be un-archived and available for use on the JIRA side. If you select a report,only those sprints and releases found by that report will be un-archived in JIRA.

If you are using a custom column value to decide which items that get synced to JIRA, for example, you can use thesame report for both your regular items and sprint/releases.

Archiving a Sprint in Hansoft will archive the corresponding Version in JIRA even though it is found by the selectedreport.

Note: Even though you can configure the different sections to use a report for un-archiving Versions, the report inquestion must be created in the Project Schedule section in Hansoft.

GreenhopperWith the Greenhopper plugin in JIRA you can link two Versions together in a parent-child relationship to create atype of sprint object. In Hansoft this is more intimately represented by the Sprint object which you can tag to aRelease to track development progress on a higher level. When a Sprint is tagged to a Release in Hansoft, the cor-responding Versions in JIRA will also be connected with the Release as the parent in the relationship. Likewise, anagile item in Hansoft which is committed to a sprint will in JIRA be tagged to the corresponding Version.

Updating start and end datesThe integration only supports syncing of Sprints/Releases created in Hansoft, meaning that you cannot retroactivelysync existing Versions to Hansoft. Rescheduling of synced Versions must also be done on the Hansoft side. Updates

made to a Versions "Start/End Date" on the JIRA side will just be resynced by the integration to the start/end datesfound in Hansoft.

Fix Version - Committed to Sprint / Tagged to ReleaseIn Hansoft, Sprints, Product Backlog items and Task Schedule tasks can be Tagged to a Release and Agile items canbe committed to Sprints. This relationship to a Sprint or Release in Hansoft is connected to the Fix Version column inJIRA.

Version DescriptionNote: Do not update this field for synced items. The Version Description field in JIRA is used by the integration toidentify the items. Updating this field will cause the integration to lose its identifier for the item and a new Versionwill be created.