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.
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.
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 email@example.com 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 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.
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 correct information by checking that the SDK user is online, by the notification e-mail or in the logs. The log files are found in the JIRA integration install directory. When checking online status of the SDK user, remember that only the "Administrator" account can see SDK users in the user list.
Manual installation of plugin files, JIRA version 4.1 and newer
Note that only versions from 4.1.1 to 7.1 are supported! See integration requirements.
Copy 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).
Plugin installation through the web interface.
In 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.
The plugin 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 JIRA server and projects to perform data updates. When the Hansoft plugin is loaded 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 More..>the Customize project integration settings... in the Hansoft project you are integrating with JIRA.
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 http://)JIRA 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.
Read more about user matching here: User matching
JIRA 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 2
Note: 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 continuous feedback as to which settings are still to be filled in, if username or password is incorrect and so on.
In Hansoft you must create a report that filters/cover all the items, task or bugs that you want to be synchronized with JIRA. 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.
You then create a filter on the JIRA end to select the issues you want to synchronize to Hansoft. The filters on the JIRA side 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 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.
- 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.
- 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, JIRA-Agile, Releases and Sprints.
Max 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
- 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
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 e-mail 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.
Note: 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.
Integration settings file setup
It is strongly recommended that you enable e-mail 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 make the filter selection more manageable on the Hansoft side. The string specified in the settings file needs to prefix your JIRA filter name.
Example: "hansoft OurSyncFilter".
// Configure Hansoft Login
// You can specify several "HansoftDatabase" sections to connect to several servers at once.
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 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.
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
// 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 50300 // The port on the JIRA integration server listening for connections from the Hansoft plugin on the JIRA 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
// 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.