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

Transcription

1 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 between Hansoft and JIRA regarding projects, data models and so on. Item type, status and workflow differences Items and tasks in JIRA and Hansoft differ in regards to type, workflow and statuses. All item types in JIRA are associated with a workflow and their item status is derived from that workflow. Items in Hansoft are defined by the section from which they originate. Items in Hansoft from the product backlog are neutral in the sense that they only exist in the product backlog and can be typed as "user stories". Items in the Product Backlog can be committed to the project schedule where they can be task scheduling items and be planned out gantt style, or they can be committed to sprints and be estimated as 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 in Hansoft for the item types which you are going to sync, so that the workflows can be properly applied and matched when running the integration. Workflow matching is described in more detail in the installation part of this manual. You can read more about workflow creation in Hansoft here: Creating matching workflows Hansoft sections vs JIRA screens Hansoft projects contains three main views where tasks and items are located; the product backlog, the project schedule and the QA section (see screenshots at the bottom of this page).

2 The section that mostly resembles JIRA is the QA section which is a flat structure of items (bugs). Items in the QA section 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 unlimited tree 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 the JIRA filters and Hansoft reports used for syncing items. This is described more in detail in the Detailed installation instruction section of the manual. JIRA and Hansoft projects In a typical agile project we have our product backlog for planning and estimating tasks, the project schedule where we work on tasks and a QA section where we handle bugs and issues during development. In JIRA these items are of different types but stored in a flat structure. When integrating with Hansoft we most likely want the different 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 section you create a report to filter out the items you wish to sync (picture 2). If you are syncing three different JIRA item types to different sections in Hansoft you need to create three JIRA filters, one for each item type (see picture 1). Picture 1: JIRA filters syncing different item types to different sections in Hansoft

3 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 second JIRA project

4 Hansoft sections Project schedule view Product backlog QA section

5 Technical overview Top Previous Next Communication overview The Hansoft JIRA integration initiates communication with the JIRA server by contacting the servlet HansoftService module added by installing the Hansoft Support JIRA version 2 plugin. The hostname of the JIRA integration server and the number of an unused port on that server is sent to the servlet. The hostname and port are configured in the JiraIntegrationSettings file as "NotificationHost" and "NotifcationPort". The servlet opens a TCP channel back to the JIRA integration server. This channel is then used for all communication between the integration and the JIRA server.

6 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: -- Information about acquiring an SDK license: Hansoft JIRA integration installer: Download SDK & integrations JIRA server version or later JIRA Greenhopper plugin installed. This is needed for the integration to be able to properly sync Hansoft Sprints and Releases to Versions in JIRA Note: The Greenhopper plugin needs to be installed but does not have to be loaded in any projects in case you are not using this module A Windows server for running the integration Hansoft server requirements and recommendations can be found here: Hansoft system requirements

7 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 configuration against an isolated Hansoft test server and also a sample JIRA project. This will make the actual implementation much 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 notifications in the IntegrationSettings file. These notifications contain valuable information for when you are matching your Hansoft and JIRA workflows for 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 the SDK 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 and update 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 Hansoft server 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 JIRA server and projects to perform data updates. You also need the server name and port for the JIRA server that you want 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 the JIRA 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 directory. 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.

8 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 potential troubleshooting 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 to create 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.

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

10 The SDK account is used by the integration to perform updates on the Hansoft server.if you do not have the option to create SDK Users contact to enable the SDK module on your Hansoft license. Launch the JIRA integration installer.

11

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

13

14 Once the installation has been completed the integration will launch. You can verify that you specified the correct information by checking that the SDK user is online, by the notification or in the logs. The log files are found in 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 installed on JIRA. Manual installation of plugin files, JIRA version 4.1 and newercopy the Hansoft plugin from the JIRA integration 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 that support loading of plugins through the web GUI (see below).

15 Plugin installation through the web interfacein JIRA version 4.2 or newer the plugin can be loaded directly from the Plugins 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 corresponds to the version of JIRA you run. In this example we are running JIRA 4.3 and I select that plugin file.

16 Theplugin will then be uploaded and installed.

17 Create or obtain a JIRA account for your JIRA server. The JIRA Integration uses this account to log into the JIRA server 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 this group. This is just a precautionary step to give you control over which JIRA user is allowed to be used by the integration.you also need the server name and port for the JIRA server that you want to connect to.note: The integration only supports a single JIRA user for synching the data.you are now ready to setup the integration in the desired Hansoft 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...

18 Fill in the required information as described below.jira host: The URL to the JIRA server to which the integration should connect. This is the same URL your users use to login to the JIRA server (must contain user & password: Login details for the JIRA user you have created for the integration.user settings: Tick this option if you want the integration to create ghost users for all JIRA users that cannot be matched to Hansofts users. This is recommended. Rear more about user matching here: User matchingjira group used for user synchronization: The JIRA group, or groups, from which to sync users to Hansoft. Can be an already existing group or a new one which will then 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 integration tries to match towards existing Hansoft users.status: As you configure the integration, this area will display

19 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 synchronized with JIRA. This report is used in step 7 when the item sync is setup. Reports are not global across your project but are local to the different sections in Hansoft (Product Backlog, Project Schedule and QA) so the report needs to be setup in the view you are configuring the integration for. Note: Make sure to test this report properly so that it returns the desired result before deploying it. 2.

20 More detailed guidance on how to use the query filter in Hansoft can be found in the below video: You then create a filter on the JIRA end to select he issues you want to syncronize to Hansoft.The filters on the JIRA side needs to be created by the JIRA user used by the integration.

21 In the second tab of the integration settings you specify the parameters for the sync in more detail.enable JIRA Projects: Here you select which JIRA projects that the integration should be able to sync towards. Note that the integration can sync towards multiple JIRA projects at once. You can for example sync one issue type from on JIRA project, and another issue type from another JIRA project.replication settings:- Default JIRA project for new items in 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 by default get this item type in JIRA.- Filter for issues to replicate from JIRA to Hansoft: Select which JIRA filter the integration should use to find the issues to be synced over from JIRA to Hansoft. (for the above enabled JIRA projects)- Report for items to replicate from Hansoft to JIRA: Select which Hansoft report the integration should use to find the issues to be synced over from Hansoft to JIRA.- Report for milestones and sprints that should be unarchived in JIRA: Select which Hansoft report the integration should use to find the milestones and sprints that should be unarchived in JIRA. More details are found here JIRA versions, Greenhopper, Releases and SprintsMax issues 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 sync from 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 created by the integration on the JIRA side. If you want all columns to be created, including deactivated ones, tick this option. - Create fields for Hansoft summaries in JIRA: Tick this if you want Hansoft calculated summaries to be synced to JIRA. - 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

22 The last step is to ensure that you have the correct Hansoft user(s) bound to the correct JIRA user(s). This is done automatically by the integration based on user name and address, but you have the option to review, and if needed, 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 user account shown in the drop list.this group setting is found here: JIRA user group settingsnote: If an update is done to an item by a user that is not bound to a user account on the corresponding system, the users setup in the integration is recorded as having made the update.

23 Integration settings file setup It is strongly recommended that you enable notifications to ensure that you are informed about the integration status. * JiraFilterNameFilter: This option is used to limit the amount of JIRA filters that the integration makes available in the project configuration. Because filters can be shared to all users, and across JIRA projects, the amount of filters to be synced can be rather high. This option is used to throttle the list and and make the filter selection more manageable on the Hansoft side. This option uses the filter search functionality found in JIRA through the regular web client. An easy way of testing your filter setup is to login to JIRA using the integration user used by the integration and then construct the search string there. When you are satisfied with the search result you can simply copy the search string to the integration file and restart the integration service. Configure the Hansoft Login Top Previous Next

24 ////////////////////////////////////////////////////////////////////////////////////////// // Configure Hansoft Login // You can specify several "HansoftDatabase" sections to connect to several servers at once. HansoftDatabase { Host localhost Port // The IP address or DNS name of the Hansoft server to connect to. // 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 the default value is used. // Configure certificate for this connection to a Hansoft server EnableCertificates 0 // Enable usage of certificates PublicCertificatePath "" // If found the file overrides PublicCertificateData PublicCertificateData "" // Server public certificate PrivateKeyPath "" // If found the file overrides PrivateKeyData PrivateKeyData "" // 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 1 CertificateVerificationDepth 9 // You can reduce this if you have a known certificate depth CACertificatePath "" // If set and found the file overrides CertificateCACertificateData CACertificateData "" // Certificate Authority data PathToCRLs "" // Certificate Revocation List store directory, disabled if empty CRLPath "" // If found the file overrides CertificateCRLData CRLData "" // Certification Revocation List data

25 } ////////////////////////////////////////////////////////////////////////////////////////// // 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- // The port on the JIRA integration server listening for connections from the Hansoft plugin on the J- 00 IRA server. JiraFilterNameFilter "hansoft" // The filter used to filter the filters that are available in configuration // Fuzzy matching strength (0-1.0, default is 0) 0 means only a faster caseinsensitive match will be made. A suitable starting value for fuzzy matching is FuzzyMatchingStrength ////////////////////////////////////////////////////////////////////////////////////////// // Configure Notification EnableLogging 0 // Logs communication with the smtp server to the "Log " folder to enable debugging settings Server smtpout.hansoft.se ServerPort sFromName "Hansoft Jira Integration" // The SMTP server to send s through. // The port of the SMTP server to send s through. // The name appearing in the from field on sent s. sFrom "" // The appearing in the from field on sent s. ServerLoginName "" // The login name to use to login to the SMTP server. Leave blank to disable login. ServerLoginPassword "" // The password to use to login to the SMTP server. SecurityProtocol"None" // The security protocol to use, available options are: None, SSL or TLS

26 SendAdmin sTo "" // The address to send administrative s to. SendAdmin sToName "Admin" // The name for the address to send administrative s 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", "SubAndMainProjectManagers". "MainProjectManagers", "ReadOnly". Can later be changed in the project custom column settings. / //} Sharing JIRA filters Top Previous Next Sharing JIRA filters for integration use When 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, the integration is limited to one user per JIRA server it is syncing too. Instead of having this user creating the filters needed for the syncing, you can simply share filters to the user instead. This way you can easily make existing filters available to the integration. Creating matching workflows Top Previous Next

27 Introduction Note: Before all workflows in the enabled JIRA projects are correctly matched with their Hansoft counterparts, no items will be synced to JIRA. For more information about working with workflows in Hansoft, please consult the Hansoft online manual: Feel free to contact us at 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 associated with 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. Restrictions The restriction models in Hansoft and JIRA are too disparate to be automatically setup by the integration. It is therefore important that you map your data flows in the two systems and ensure that the desired restrictions are applied by the system where the data update is triggered. Name matching The workflow matching between JIRA and Hansoft is name based so it is important that both your workflow and all workflow steps are all named exactly like their counterpart in JIRA. There is an option to override this name matching 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 integration install directory. The option to import a workflow is found in the "More" menu in the workflow editor.

28 The basic workflow Picture 1 shows the steps of the "jira" workflow, the standard JIRA workflow. The corresponding workflow in Hansoft would look as picture 2. Picture 2:

29 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:

30 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

31 In JIRA, rules for progressing a workflow are setup in the transition connecting two statuses. In Hansoft a connection does not have specific rules, it is simply connecting two statuses. "Transition" rules are setup within the statuses themselves 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 workflow to the next step, we then edit the "Open" status. As seen in screenshot 5 we specify that a new comment must be 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 a specific requirement towards a single status we create a "Transition" like in picture 6.

32 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 be setup 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 "resolution" is set in JIRA. Right click the "Closed" status and select "JIRA workflow settings".

33 In this window you now have 2 drop down lists. The "JIRA status" is currently set to match by status name. This is the default setting and the "Closed" status in Hansoft will then be matched to the "Closed" status in the corresponding JIRA workflow. If needed, this menu can be used override the built in name matching and instead link a Hansoft workflow 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 matching. The second drop down "JIRA resolution" is used to specify what "resolution" should be set to when the workflow reaches 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.

34 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 section in Hansoft, the workflow matching setup is expanded with an additional drop down in the JIRA workflow settings dialogue. The first dropdown is used to select the JIRA workflow you want to match status and resolution for. Apart from this first dropdown the configuration is the same as for workflows in the other Hansoft sections.

35 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 JIRA when progressing workflows from the Hansoft side. In JIRA you can have different resolutions for the same workflow, for example closed with resolution "Fixed" and closed with resolution "Won't fix". If this is the case you need to create a workflow step for each of the alternatives in Hansoft and map the resolutions to match. In order to avoid confusion and make it clear for your users we recommend that you name your Hansoft workflow steps with the resolution to which they are matched. An example Hansoft QA workflow supporting two JIRA workflows, where one of them has two Closed statuses with different resolutions, could look like this.

36 Column matching Top Previous Next Hansoft JIRA integration columns and matchings JIRA columns created in Hansoft by the integration are appended with (JIRA) to be easily distinguishable. Similarly all Hansoft columns created in JIRA are appended with [Hansoft]. Project specific Hansoft columns will in addition to the 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 additional 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.more information found here. Example: Estimated Ideal Days [Hansoft Stat]

37 URL columns The integration makes URL columns available on both the JIRA and Hansoft side to make it easy to jump between items in the two systems. In Hansoft this column is called "JIRA URL (section name)" and the corresponding column in 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 is found in the Administration tab in Hansoft.

38 JIRA attachments default column When the integration is running a column will be available in Hansoft by default which contains links to the attachments of a synced item. This column is called "Attachments (JIRA, Hansoft section)". These links can be used to quickly 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 for storage 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 a couple of core columns that are directly matched between the two systems however and they are described in more

39 detail below. The two columns associated with assignment and work remaining have some logic associated with them 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 from Hansoft. The first user in that list will be set as "Assignee" in JIRA. Using the "assign to" functionality in JIRA will update "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 the Product Backlog to estimate User Stories. These are then committed to Sprints where the teams break them down and give them estimates on "Work remaining". Since there is no 1-1 connection on how this works in the two systems 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 not change "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 value for "Work remaining" it is recommended that you set hours in JIRA as well to avoid confusion. This option is found under "Issue Features" in the "System" tab of JIRA.

40 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 date For Task Schedule items synced to JIRA "Due date" will be matched with the Hansoft "Finish" date. For QA or Product Backlog items, which do not have finish dates of their own, this is not populated. If these items are committed 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 JIRA integration settings file. First you need to know the full path to the custom field that you want to add, including the plugin key (e.g <full.plugin.key>:<customfieldname>). Second, decide what type of Hansoft column the field should

41 be mapped as. The possible types are "Text", "Hyperlink", "DropList", "Integer", "Float", "DateTime", "MultiLineText", "People", "TimeSpent", "MultiSelectionDropList", "DateTimeWithTime". You also need to set the initial access right when the column is created, possible values are "AllProjectMembers", "SubAndMainProjectManagers". "MainProjectManagers", "ReadOnly". The access rights can later be changed in the 'Customize columns' 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 information such as reporter, assignee, comments et cetera. Ghost users in Hansoft are free user objects generally used for planning. They are not full accounts in the sense that they cannot login and so, not perform any actions on the Hansoft side what so ever. In the event that your JIRA user base is larger than your Hansoft user base, the integration 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 not have a user object on the Hansoft side to replicate this action. It is strongly advised that you enable this option to ensure good user information on all synced items and avoid getting "missing matching user" notifications sent by the integration. Placement of new JIRA issues in Hansoft hierarchy Top Previous Next Overview One difference between Hansoft and JIRA is that Hansoft supports a virtually unlimited hierarchy depth for the Product Backlog and Project Schedule views, whereas JIRA utilizes a more flat structure. Since new items being synced from JIRA does not have any hierarchy data they are by default placed in the root of the hierarchy in the section to which they are synced.

42 Configuring where to place newly synced JIRA issues When the integration us fully configured in your Hansoft section of choice, the Product Backlog in my example, a right-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.

43 When a new item is synced from JIRA to Hansoft, the integration checks all items configured as insert locations. If the 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 that you 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 from JIRA 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 documents are added on the JIRA side the migration must be run again.

44 Migration option in the right click menu in Hansoft

45 Attachment in the Hansoft attachment list Stat and Summary columns Top Previous Next Summary Summary columns are used for numerical columns in hierarchies. This number is calculated from the child items of a parent item and is not stored in the database. If the summary information is needed in JIRA you need to enable this column. In the example below the "Estimated days" on "Main story" is not set, it is calculated from the sub-items. Stat Like 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

46 Ideal Days" column. If we then indent the sub-tasks that value will be replaced with a new "Estimated Days" calculated from the subitems. The old value of 2 days is however still stored in the Hansoft database and the calculated "Estimated Days" is presented by the client. In order to expose the "correct" value of "Estimated Ideal Days" in JIRA, the 0 value is stored in 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\application Data\JIRA\plugins\installed-plugins" or by uninstalling it in the Plugins view in the JIRA administration.

47 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. notifications The integration can be setup to send notifications about errors. Details about the settings file can be found here: Settings file All integration configuration errors are sent to the Administrator 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 address of the user responsible for the edit and notify them. The integration first looks for an address on the Hansoft side. If none can be found there it checks the linked user on the JIRA side for an address. If the integration is not enabled for the responsible user the will instead be sent to the Administrator address specified in the settings file. JIRA integration status dialogue The integration adds a status tool for finding any syncing errors between Hansoft and JIRA to any project in which the integration is active. To access the status dialogue right-click any item and choose 'Show JIRA Integration status

48 dialogue': The status dialogue will display any current errors that are preventing syncing, as well as informing you about current syncing tasks. Two options exists, 'Auto refresh', which will continuously update the status dialogue and 'Enable Stack 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:

49 Database connection pool size To prevent deadlock scenarios when the Hansoft integration is synchronizing issues, we recommend increasing the database 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

50 JIRA hosted on Linux - number of open files When hosting JIRA on a Linux server the Java virtual machine might run out of file handles. Typically the limit is set to 2048 files per process and if this limit is reached the integration will start reporting exceptions when syncing issues. This article from Atlassian describes how these variables can be modified to allow for more open files: Num open files Examining the integration logs The log files for the integration are found in the integration install directory under /Log/. Whenever you are troubleshooting your setup it is recommended to first check the log files for any reported errors. Could not connect to notification host This 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 between your JIRA server and the server running the Hansoft JIRA integration is allowed through your network to resolve these types of errors. Enabling JIRA logging When the integration has been installed you have the option to enable Hansoft integration logging. Add the following lines to the atlassian-jira\web-inf\classes\log4j.properties file. The JIRA service must then be restarted for the 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

51 log4j.additivity.se.hansoft = false JIRA versions, Greenhopper, Releases and Sprints Top Previous JIRA Versions - Hansoft Sprints and Releases In JIRA, Versions are used to plan out your project in time and enables you to tag issues to these Versions. In Hansoft this is primarily done using Releases, together with Sprints, in the timeline view in your Project Schedule. When the integration is syncing a project, all Versions in JIRA are made available in a custom column in Hansoft, just like any other JIRA specific attributes. See the Column matching section for more info on this. Since Sprints and Release in Hansoft 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 the Versions 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 in this 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 the same 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 selected report. Note: Even though you can configure the different sections to use a report for un-archiving Versions, the report in question must be created in the Project Schedule section in Hansoft.

52 Greenhopper With the Greenhopper plugin in JIRA you can link two Versions together in a parent-child relationship to create a type of sprint object. In Hansoft this is more intimately represented by the Sprint object which you can tag to a Release to track development progress on a higher level. When a Sprint is tagged to a Release in Hansoft, the corresponding Versions in JIRA will also be connected with the Release as the parent in the relationship. Likewise, an agile item in Hansoft which is committed to a sprint will in JIRA be tagged to the corresponding Version. Updating start and end dates The integration only supports syncing of Sprints/Releases created in Hansoft, meaning that you cannot retroactively sync existing Versions to Hansoft. Rescheduling of synced Versions must also be done on the Hansoft side. Updates

53 made to a Versions "Start/End Date" on the JIRA side will just be resynced by the integration to the start/end dates found in Hansoft. Fix Version - Committed to Sprint / Tagged to Release In Hansoft, Sprints, Product Backlog items and Task Schedule tasks can be Tagged to a Release and Agile items can be committed to Sprints. This relationship to a Sprint or Release in Hansoft is connected to the Fix Version column in JIRA. Version Description Note: Do not update this field for synced items. The Version Description field in JIRA is used by the integration to identify the items. Updating this field will cause the integration to lose its identifier for the item and a new Version will be created.