Skip to main content
Sign In
 

 

 
Go Search
Home
Getting Started
Knowledge Base
Training
Discussions
Downloads
Platform SDK
  

 
 
VersionOne Community > Downloads > Integration Documentation > Jira
 
VersionOne JIRA Integration

VersionOne JIRA Integration

Table of Contents

Description
System Requirements
Downloads
Installation
1. Determine Install Location
2. Extract Files
3. Configure
4. Start up
5. Test the Service
6. Install as a Windows Service
Configuration
JIRA Configuration
VersionOne Configuration
ServiceHost Configuration

Description

The VersionOne JIRA Integration (V1JIRA) creates defects in VersionOne based on issues in JIRA. Using this integration your organization can manage and triage issues reported by customers and promote them to VersionOne once you determine a fix is necessary.

Once the integraion is installed and configured, JIRA users can specify which Issues require engineering attention and they will automatically appear as Defects in the VersionOne repository. Additionally, when the defect is closed in VersionOne, the integration updates the JIRA repository to relfect this change.

This integration supports multiple modes of operation.

  1. Assign an Issue — With this approach, Issues that require engineering attention are assigned to an "engineering" user in JIRA. This assignment is used to determine when to create Defects in VersionOne.

  2. Tag an Issue — With this approach Issues that require engineering attention are identified using custom fields on the Issue. The value of the custom field is used to indicate when to create Defects in VersionOne.

System Requirements

  • Operating System — Windows 2000, 2003

  • Framework — Microsoft .Net 2.0

  • VersionOne — Release 7.3 and above

  • JIRA — Tested with Release 3.10.2-#262

Downloads

The latest version of V1JIRA is available at V1: Integration Downloads.

Installation

These installation instructions assume that JIRA is already installed, configured, and working properly.

1. Determine Install Location

V1JIRA can be installed on any server with access network access to both your VersionOne installation and JIRA. Exact placement should be determined by your internal software management requirements. The integation server must meet the System Requirements stated above.

2. Extract Files

Download V1JIRA using the link above and extract it into a folder of your choice.

3. Configure

Configuration for the JIRA Integration is a 3 step process.

  1. Configure JIRA

  2. Configure VersionOne

  3. Configure ServiceHost

4. Start up

Open up the command prompt, navigate to your installation folder, and run the following command: 

VersionOne.ServiceHost.exe

If you have configured your system properly, you should see several [Info] messages followed by a [Startup] message.

5. Test the Service

  1. Create an Issue in JIRA

  2. Set the appropriate state in order for the issue to move to VersionOne

  3. Verify that the issue appears in VersionOne as a defect

  4. Close the defect in VersionOne

  5. Verify that the JIRA issue has been updated

Shut down the service host by pressing "Q" in the console window.

6. Install as a Windows Service

Run the following command from the console window: 

VersionOne.ServiceHost.exe --install

This command installs the service so it will will run under the account NT AUTHORITY\Local Service. Local Service must be given access privileges to the directory where the V1JIRA was installed so it can store its state and write to log files. Follow the steps below to change the security on the installation directory:

  1. Right click the installation folder from Windows Explorer.

  2. Select "properties".

  3. Select the "Security" tab.

  4. Click the "Add" button.

  5. Enter "Local Service" and click "OK".

  6. Click the "Allow" checkbox for the "Full Control" row .

  7. Click "OK" to save the changes.

For more information on how the Windows Service is configured see Service Host Configuration.

Configuration

JIRA Configuration

This section describes how to configure JIRA for use with VersionOne

  1. Enable the JIRA RPC plug-in.

    Figure 1. 


  2. Select or Create a JIRA User. The integration requires a valid JIRA User Id and a Password in order to connect. This user must have sufficient rights to accept work and modify issues (i.e. must be assigned to the Developer Role on the project).

  3. The integration requires that the project names used in JIRA must match the project names used in VersionOne.

  4. The next step depends the approach for pushing Issues to VersionOne

    • Assign an Issue

      If you choose to push Issues by assigning them to the user identified in step 2, proceed to the next step.

    • Tag an Issue

      If you want to push Issue to VersionOne using a Custom Field, you need to do the following:

      1. Create the Custom field. It is recommended that you use a Multi-Selection field.

      2. Populate this field.

      3. Note the id of this field. The id required by the integration is available to the JIRA Administrator. From the "View Custom Fields" page, select the "Screens" link in the "Operations" column for the desired field. In the URL, note the 'fieldId' value.

        Figure 2. 


  5. Create a Filter to select the Issues you want pushed to VersionOne. It's recommended that you create this Filter using the same credentials used by the integration (user identified in step 2). It's beyond the scope of this document to describe how to create Filters in JIRA, but here are some filter ideas

    • Assign an Issue

      Using this approach, the easiest Filter is based on who the issue is assigned to ("Current Assignee" assuming you are logged in as the user identified in step 2) and Issue Status (i.e. "Open")

      Figure 3. 


    • Tag an Issue

      Using this approach, the easiest Filter is based on the value of the Custom Field defined in step 4.

      Figure 4. 


  6. Determine how to prevent Issues from being pushed more than once. This decision is based on your Filter and how you want issues pushed to VersionOne

    • Assign an Issue

      Using this approach, the simplest option is to change the Status. To do this you need to know the ID of the Status you desire. This information is available to the JIRA Administrator on the "View Workflow Steps" page for the desired workflow. You need the ID number in the "Transistions" column for the "Step Name" you are transitioning from.

      Figure 5. 


    • Tag an Issue

      Using this approach, the simplest option is to change the value of the custom field. To do this you need to know the value you want set in the custom field.

  7. Do you need a custom field to hold a URL to the VersionOne Defect?

    By default the integration puts the VersionOne defect information in the "Comments" section of the Issue. This information includes a URL to the VersionOne Defect. You may optionally add another field to hold this data necessary. To do this create the custom field and note the 'fieldId' value. This value is available to the JIRA Administrator. From the "View Custom Fields" page, select the "Screens" link in the "Operations" column for the desired field. In the URL, note the 'fieldId' value.

    Figure 6. 


VersionOne Configuration

  1. Add "JIRA" to the list of valid Source

    Figure 7. 


  2. The integration needs a text field in VersionOne store the JIRA identifier. By default this is the Reference field. If you are already using this field, you'll need to create a custom text field and note the name

ServiceHost Configuration

The configuration file for the JIRA Integration is VersionOne.ServiceHost.exe.config. This section describes the elements in the ServiceHost configuration file.

Table 1. JiraService Element

NameDescription
JiraUrlFully qualified URL to JIRA Soap service
JiraUserNameValid JIRA Username. This user must have the authority to accept and modify work in the JIRA System
JiraPasswordPassword for specified user
CreateIssueFilterIdJIRA ID number for the Filter used to select which Issues are pushed to VersionOne
CreateFieldIdWhen using the "Tag Issue" approach, this field contains the JIRA ID of the custom field you want altered once the issue is in VersionOne. Make sure this field is part of the filter identified by the CreateIssueFilterId
CreateFieldValueWhen using the "Tag Issue" approach, this field contains the Value being set in the field identified by CreateFieldId. This value must cause the Issue to be returned in the filter identified by CloseIssueFilterId and not appear as a result in the filter identified by CreateIssueFilterId
CloseFieldIdWhen using the "Tag Issue" approach, this field contains the JIRA ID of the custom field you want altered once the issue is closed in VersionOne. Make sure this field is part of the filter identified by the CloseIssueFilterId
CloseFieldValueWhen using the "Tag Issue" approach, this field contains the Value being set in the field identified by CloseFieldId. This value must cause the Issue to disapear from both the CloseIssueFilterId and the CreateIssueFilterId
ProgressWorkflowWhen using the "Assign Issue" approach, this field must contain ID of the Workflow Transistion you want set once the defect is created in VersionOne. This value must cause the Issue to be returned in the filter identified by CloseIssueFilterId and not appear as a result in the filter identified by CreateIssueFilterId
ProgressWorkflowClosedWhen using the "Assign Issue" approach, this field must contain ID of the Workflow Transistion you want set once the defect is closed in VersionOne. This value must cause the Issue to disapear from both the CloseIssueFilterId and the CreateIssueFilterId
AssigneeStateChangedWhen using the "Assign Issue" approiach, this field must contain the name of the JIRA user to assign the issue when progressing the workflow to closed (ProgressWorkflowClosed) Alternately , the default value of -1will cause JIRA to automatically set the asignee based on workflow rules.
JiraIssueUrlTemplateTemplate used for creating link to JIRA issue in VersionOne
JiraIssueUrlTitleTitle on VersionOne link
SourceFieldValueThe value to set in the VersionOne Source field. This must be a valid VersionOne Source
DefectLinkFieldIdfieldId of JIRA custom field containing URL to VersionOne defect
JiraServiceFactoryDo not edit this field.

Example 1. JiraService Element when using the assignment approach.

Note : that elements ProgressWorkflow and ProgressWorkflowClosed contain data and elements CreateFieldId, CreateFieldValue, CloseFieldId, and CloseFieldValue are all empty

<JiraService disabled="0" class="VersionOne.ServiceHost.JiraServices.JiraHostedService, VersionOne.ServiceHost.JiraServices" >
	<!-- Jira Connectivity -->
	<JiraUrl>http://jirahost:8080/rpc/soap/jirasoapservice-v2</JiraUrl>
	<JiraUserName>versionone</JiraUserName>
	<JiraPassword>versionone</JiraPassword>
	
	<!-- Jira Filters -->
	<CreateIssueFilterId>10000</CreateIssueFilterId>
	
	<!-- Jira Fields to Update -->
	<CreateFieldId></CreateFieldId>
	<CreateFieldValue></CreateFieldValue>
	<CloseFieldId></CloseFieldId>
	<CloseFieldValue></CloseFieldValue>
	<ProgressWorkflow>4</ProgressWorkflow>
	<ProgressWorkflowClosed>5</ProgressWorkflowClosed>
	<AssigneeStateChanged>-1</AssigneeStateChanged>

	<!-- Jira Custom Field to hold URL to VersionOne defect -->
	<DefectLinkFieldId>customfield_10001</DefectLinkFieldId>
	
	<!-- VersionOne Links -->
	<JiraIssueUrlTemplate>http://jirahost:8080/browse/#key#</JiraIssueUrlTemplate>
	<JiraIssueUrlTitle>Jira</JiraIssueUrlTitle>

	<!-- VersionOne Source -->
	<SourceFieldValue>Jira</SourceFieldValue>

	<JiraServiceFactory>VersionOne.Jira.SoapProxy.JiraSoapServiceFactory, VersionOne.Jira.SoapProxy</JiraServiceFactory>
</JiraService>

Example 2. JiraService Element when using the custom field approach.

Note : that elements CreateFieldId, CreateFieldValue, CloseFieldId, and CloseFieldValue contain data and ProgressWorkflow and ProgressWorkflowClosed do not contain data 

<JiraService disabled="0" class="VersionOne.ServiceHost.JiraServices.JiraHostedService, VersionOne.ServiceHost.JiraServices" >
	<!-- Jira Connectivity -->
	<JiraUrl>http://jirahost:8080/rpc/soap/jirasoapservice-v2</JiraUrl>
	<JiraUserName>versionone</JiraUserName>
	<JiraPassword>versionone</JiraPassword>
	
	<!-- Jira Filters -->
	<CreateIssueFilterId>10010</CreateIssueFilterId>
	
	<!-- Jira Fields to Update -->
	<CreateFieldId>customfield_10000</CreateFieldId>
	<CreateFieldValue>Ready</CreateFieldValue>
	<CloseFieldId>customfield_10000</CloseFieldId>
	<CloseFieldValue>Closed</CloseFieldValue>
	<ProgressWorkflow></ProgressWorkflow>
	<ProgressWorkflowClosed></ProgressWorkflowClosed>
	<AssigneeStateChanged></AssigneeStateChanged>

	<!-- Jira Custom Field to hold URL to VersionOne defect -->
	<DefectLinkFieldId>customfield_10001</DefectLinkFieldId>
	
	<!-- VersionOne Links -->
	<JiraIssueUrlTemplate>http://jirahost:8080/browse/#key#</JiraIssueUrlTemplate>
	<JiraIssueUrlTitle>Jira</JiraIssueUrlTitle>

	<!-- VersionOne Source -->
	<SourceFieldValue>Jira</SourceFieldValue>

	<JiraServiceFactory>VersionOne.Jira.SoapProxy.JiraSoapServiceFactory, VersionOne.Jira.SoapProxy</JiraServiceFactory>
</JiraService>

Table 2. JiraServiceTimer Elements

NameDescription
IntervalNumber of milliseconds to wait between polls to the JIRA system
PublishClassDo Not Change

Example 3. 

This example polls every 60 seconds

<JiraServiceTimer disabled="0" class="VersionOne.ServiceHost.Core.Services.TimePublisherService, VersionOne.ServiceHost.Core">
	<Interval>60000</Interval>
	<PublishClass>VersionOne.ServiceHost.JiraServices.JiraHostedService+IntervalSync, VersionOne.ServiceHost.JiraServices</PublishClass>
</JiraServiceTimer>

Table 3. DefectWriterService Elements

NameDescription
ExternalIdFieldNameName of VersionOne field that holds the ID of the JIRA issue. Must be a text field
Settings
NameDescription
ApplicationUrlVersionOne Application URL
UsernameValid VersionOne Username. This user must have authority to create defects in the VersionOne projects being processed.
PasswordPassword for specified user
APIVersionThe minimum application version required for this hosted service.
IntegratedAuthFalse if using VersionOne native security, true is using Windows Integrated Security. If VersionOne is configured to use Windows Integrated Security, the account the service is running as must be a configured VersionOne user with a project role of Team Member or higher. Also, Username and Password should be empty if IntegratedAuth is true.

Example 4. 

<DefectWriterService disabled="0" class="VersionOne.ServiceHost.DefectServices.DefectWriterHostedService, VersionOne.ServiceHost.DefectServices">
	<ExternalIdFieldName>Reference</ExternalIdFieldName>
	<Settings>
		<ApplicationUrl>http://v1host/VersionOne/</ApplicationUrl>
		<Username>admin</Username>
		<Password>admin</Password>
		<APIVersion>7.2.0.0</APIVersion>
		<IntegratedAuth>false</IntegratedAuth>
	</Settings>
</DefectWriterService>

Copyright © 2008, VersionOne, Inc. All rights reserved. This document was generated 2008-01-22 23:14:01.