JIRA 4 Installation & User Guide

Print this topicEmail this topic

Note: This documentation applies to JIRA version 4.4 or older. If you are using JIRA version 5.2 or newer, please refer to the Rally Connector for JIRA 5 Installation & User Guide.

Get JIRA Connector

The Rally JIRA connector can synchronize JIRA Bugs with Rally Defects or Stories. The connector runs on a computer behind your firewall using Ruby and JIRA's SOAP API. Most fields between the two systems can be synchronized. This connector supports JIRA 4.0 - 4.4.

General Setup Hardware/Software:

  1. The following people will be involved in getting fields setup in both Rally and JIRA:
    • A JIRA administrator user who can create a custom field on JIRA Issue types.
    • A Rally administrator user who can create a custom field on the Rally artifact you want to synchronize with JIRA.
  2. Think about the process you want to setup between Rally and JIRA:
    • What problem are you trying to solve?
    • Where do objects start and end their lifecycle?
  3. Which fields need updated? Identify a test Project in JIRA to use for testing.
  4. Identify a test Rally Workspace/Project to use for testing.
  5. Decide on a computer where the connector will run.

Once you have completed steps 1-5 above, please download the connector and proceed with the installation and configuration.

Connector downloads:

Also, our Rally Integrations FAQ and Best Practices contains some very useful information.

Revision history:

  • 2.8.8-154 - 18-Dec-2012
    • Enhancements:
      • Minor logging improvements.
    • Fixes:
      • DE15642: Email notification of errors and warnings, in the <Emailer> feature, would not send email if the <Level> was set to Error.
    • Known issues:
      • (none)
  • 2.8.6-151 - 17-Oct-2012
    • Enhancements/Fixes:
      • Added artifact ID to message string.
      • Added more debug output in Rally connection section.
      • Improved performance by removing refresh on Workspace read in find-workspace loop.
      • Updated to rally_api 0.6.0 gem.
      • Added more logging for <LogLevel>Any</LogLevel>.
      • Fixed issue with <RallyJiraCommentLinker> and newlines. (DE14416)
    • Known issues/limitations:
      • If Rally Discussions are being copied to JIRA Comments, the JIRA comments must not be edited. Otherwise it will cause the Discussions/Comments to be recursively copied back and forth between the two systems, growing in length each on each iteration (DE15702).
  • 2.8.1-148 - 25-Jul-2012
    • Enhancements/Fixes:
      • Log file now shows the name of the REF returned by the transform_in() function of a RallyReferenceFieldHandler on the map_fields_to_rally call.
      • Fixed an issue where a project named "TEST" would be returned erroneously on a query for project "TEST+".
      • Change to throw exception on find by ExternalID if results are nil.
      • Added a check for exception instead of nil for jira_connection.find_by_external_id
      • Added <RallyJiraCommentLinker>
      • Added fix to check users and jira-users groups.
  • 2.7.9-139 - 03-Jul-2012
    • Enhancements/Fixes:
      • Improved testing code.
      • Fixed issue where attachments were being duplicated if updates were going in both directions.
      • Fixed several minors issues.
      • Adding debug logging to attachment linker.
      • Added <RallyDateTimeFieldHandler>.
      • Added ability for FormattedID in JIRA to have lower case prefix (us123) or upper case prefix (US123)
      • Added subfield specifications on CopySelectors from Rally using the precopy feature
      • Added <JiraUserToEmailFieldHandler>
      • Added XML include capability so common text can be included as a separate file
      • Modified <CrosslinkUrlField> Rally artifact link construction to match WSAPI
      • Added support for JIRA's Components field
      • Added <UpdateSelectors> (similar to <CopySelectors>)
      • Added many-to-one (& many-to-fewer) Enum field handling
      • Added <CrosslinkUrlField> tag for weblinking
      • Added support for JIRA's Affects Versions and Fix Versions fields.
      • Added support for multiple <CopySelectors> (replaced the single <CreationFilter>)
      • Added support in calls to RallyFieldHandler to pass the Rally Artifact rather than the field value (If you have written a custom Field Handler which inherits from RallyFieldHandler, you will need to update your code. Field Handlers inheriting from OtherFieldHandler are okay.)

Introduction

The Rally Connector for JIRA allows customers to use Rally for Agile lifecycle management while still using JIRA for defect management. The connector provides synchronization capability between JIRA and Rally through four services, described below.

Overview of features

The Rally Connector for JIRA runs as a Ruby script on a machine inside your network. The connector is configured through an XML file. A log file is created to track all changes made in Rally and JIRA by the connector. The connector requires that a custom field exists in each system to store the unique id of the linked objects in the other system. The connector copies fields from Rally or JIRA based on a field mapping specified in the configuration file. Standard and custom fields can be mapped between the two systems.

The connector provides four services to synchronize objects between Rally and JIRA:

  • Copy issues created in JIRA to Rally work items
  • Copy work items created in Rally to JIRA issues
  • Update Rally work items based on changes made to JIRA issues
  • Update JIRA issues based on changes made to Rally work items

The configuration file specifies which services to run, and in what order.

The Rally Connector supports synchronizing top-level JIRA issues (Bug, New Feature, Improvement, Task or your Custom Issue type) but not JIRA sub-level types (for example, sub-task). We recommend mapping the Rally Defect work item type to JIRA Bug and Rally User Story work item type to the other JIRA top-level issue types.

It is important to recognize that the data models of Rally and JIRA are not identical and, as such, the two systems are only partially compatible. We recommend you take some time to identify the key data items you want to track in both systems and consider what you want the policy to be as far as having a primary system of record. You'll see specific information later in this document discussing some of the trade-offs to be considered and some potential approaches.

The remainder of this document assumes mapping the Rally Defect work item type to a JIRA Bug issue type. If you are mapping another JIRA issue type, you'll need to have a modified jira_config.xml file to accommodate that scenario. In general, you can follow this document, substituting your JIRA issue type for Bug and User Story for Defect when referencing the Rally work item type if your scenario differs from the one presented here.

Software and hardware requirements

The following are the hardware and software requirements to install and run the Rally Connector for JIRA:

  • A Rally subscription
  • A Windows, Mac, or Linux computer
  • Ruby 1.9.2-p290 and Rubygems, if not using the Windows installer. The supplied Windows installer automatically installs a self-contained Ruby environment along with the connector. (Note: The connector will not work with Ruby 1.8.x or 1.9.1)
  • A working instance of JIRA 4.0 through 4.4. Please note that JIRA 4.0 does not allow issues without an assignee to be created via the API. There are several ways to work around this behavior, including:
    • Turn on "Allow Unassigned Issues" in JIRA, under Global Settings - General Configuration on the Administration page
    • Set up a field handler for Mapping Users and explicitly map Rally's "Owner" to JIRA's "Assignee"
    • Specify a default assignee by adding the following to your configuration file in the <JiraConnection> section as follows:
      <Config>
              ....
              <JiraConnection>
                      ....
                      <FieldDefaults>
                              <Field><Name>Assignee</Name><Default>someuser</Default></Field>
                              ....
                      </FieldDefaults>
                      ....

Pre-installation checklist

  1. Access to a test environment/installation of JIRA
  2. Rally administrator privileges are needed for setup, but only user access is needed to run the connector
  3. Proxy server details if the machine used to run the connector uses a proxy server to connect to Rally or JIRA
  4. A JIRA user with Administrator privileges
  5. Enable remote API calls in JIRA:
    • On the Administration tab, click General Configuration under the Global Settings section.
    • Accept Remote API Calls (under the Options heading) should be ON- if not, use Edit Configuration to turn it on.
  6. Ensure that the JIRA RPC plugin is installed and enabled:

Determine how to handle Closed issues in JIRA

By default, JIRA does not allow issues with a status of Closed to be updated. When issues are first copied from JIRA to Rally (the COPY_JIRA_TO_RALLY service), the connector needs to update the RallyID custom field in each issue with the object id of the corresponding Rally defect. If the issue is closed, the update will fail, and the RallyID will remain empty. The next time the connector runs, that issue will appear to be a "new" issue (not yet copied to Rally), and the connector will copy it again, creating a duplicate. For this reason, we recommend including a <CopySelectors> section in your configuration file within the <JiraConnection> section. For example:

<Config>
        ....
        <JiraConnection>
                ....
                <CopySelectors>
                        <CopySelector>Status != Closed</CopySelector>
                        ....
                </CopySelectors>
                ....

This will prevent the connector from trying to copy closed Jira issues to Rally.

Alternatively, you can configure JIRA to allow updating Closed issues. Follow the instructions here to enable editing of closed issues in JIRA.

Installation

Basic installation steps

  1. Install the connector (run the installer or extract the zip).
  2. Make configuration changes in Rally and the other system.
  3. Edit the jira_config.xml to reflect your environment.
  4. Run rally2_jira_connector to start the synchronization process.

Install the connector

(Optional) If your site uses a proxy server to access Rally, you will need to set the http_proxy environment variable. To accomplish this on Windows 7:

  • Click on Start, right-click on Computer, select Properties
  • Click on Advanced system settings
  • In the new "System Properties" window, click on Environment Variables...
  • A new window opens titled "Environment Variables", under "System variables", click on New...
  • In the window titled "New System Variables", enter http_proxy in the "Variable name:" field, and enter your proxy's full HTTP Url in the Variable value: field (should be something like http://www-cache:8000)
  • Click OK (3 times) to save and exit this process.
  • You may need to restart your system in order for the change to take effect.

Installation for Windows

Double-click the RallyConnectorforJiraInstall-x.x.x-yyy.exe to bring up the install wizard. Follow the prompts to complete the installation.

installcq

The Windows installer will install the following files (by default in "C:\Program Files\RallyConnectorforJira" on WinXP, and in "C:\Program Files (x86)\RallyConnectorforJira" on Vista and Win7):

  1. field_handlers - A folder for custom field handers.
  2. jira_config.xml - Sample configuration file.
  3. jira_issue_workflow.xml - Sample configuration file for JIRA Bug workflow steps.
  4. jira_workflow.xml - Sample configuration file for JIRA workflow steps.
  5. rally2_jira_connector.exe - Executable to run the connector.
  6. startjira.bat - Batch file that automatically runs the connector and shows the log file (useful for testing).
  7. unins000.dat - Uninstall utilities.
  8. unins000.exe - Uninstall utilities.
  9. WinTail - Utility to tail the log file output for debugging purposes. This is a free text file tail utility for Windows, generously made available by Bare Metal Software Pty Ltd. for redistribution without restriction. We have found it to be far superior to Notepad and other text editors for watching log files in real time as they are updated by the connector.

Installation for Linux and Mac

  1. Extract the contents of the zip file "RallyConnectorforJira-Ruby-x.y.z-bbb.zip" locally on your machine (such as C:\rally for Windows or /Users/jpkole/Downloads/ on a MAC). The contents of the ZIP file:
    • field_handlers - An internal folder used by the connector
    • jira4r-0.0.x.gem - Ruby interface to the JIRA SOAP API
    • jira_config.xml - Sample configuration file
    • jira_issue_workflow.xml - Workflow configuration file for Issues in JIRA workflow
    • jira_workflow.xml - Workflow configuration file for Defects in JIRA workflow
    • rally2_jira_connector.rb - Ruby file you will use to run the connector
    • yeti-x.x.x.gem - Gem (library) that includes all of the code needed for the connector
  2. Install the required Ruby gems from a public gem repository by entering:
    sudo gem install builder
    sudo gem install rally_rest_api
    sudo gem install rally_api
    sudo gem install rest-client
    sudo gem install xml-simple
    sudo gem install mumboe-soap4r
    sudo gem install nokogiri
    sudo gem install sanitize
  3. If you are using a proxy, add "-p http://proxyhost:portnumber" to the command line, e.g.:
    sudo gem install -p http://proxyhost:portnumber builder
  4. Answer yes to any questions about installing required dependencies.
  5. Install the yeti and jira4r gems by navigating to wherever you extracted the zip file and issuing the following commands:
    sudo gem install yeti*.gem
    sudo gem install jira4r*.gem

Make configuration changes in Rally and JIRA

Create an External ID field in Rally

The External ID custom field in Rally is used by the connector to record the Key of the corresponding JIRA issue.

  1. Log into Rally as a Workspace or Subscription administrator.
  2. Go to SetupWorkspaces & Projects.
  3. Click on the Workspace that you wish to map to JIRA. This will take you to the Detail page for the given Workspace.
  4. Click on Work Products & Fields and ensure the Work Product Type selected is Defect or User Story (whatever work item you are mapping).
  5. Click ActionsNew Field.
  6. Enter a Name of JiraKey, Display Name of JiraKey (name and display name must match), and type of String. Note: you can choose a different name (like JiraID) for the custom field in Rally, but the name you choose must conform to these rules:
    • Begin with an uppercase letter
    • Less than 41 characters (40 is the maximum for display name)
    • No underscores, dashes, or spaces.
  7. Click Save & Close.

Make note of the name of this field. Once you start using the connector, this will contain the JIRA key (such as TST-213) of the JIRA issue you are mapping between the two systems.

Create an External ID field in JIRA

In the JIRA system, we recommend a custom field be created which will be used to record the Rally Object ID (OID) of the corresponding Rally artifact. The underlying database for the JIRA instance should support this External ID field being up to 14 digits in length.

FOR JIRA 4: You may need to contact your JIRA administrator to perform these steps:

  1. On the Administration tab in the navigation panel, click Custom Fields in the Issue Fields section.
  2. On View Custom Fields page, click Add Custom Field.
  3. On Create Custom Field (Step 1 of 2), select the Number Field button and click Next.
  4. On Create Custom Field (Step 2 of 2), do the following:
    1. Enter RallyID (no quotes) for the Field Name.
    2. Enter a Description if you wish.
    3. Choose Any Issue Type or a specific top level issue (Bug, New Feature, Improvement, Task or your Custom Issue type) for Applicable Issue Types.
    4. Choose Global Context or select a specific project under Applicable Context.
    5. Click Finish.
  5. On Associate Field to Screens, choose the screens on which you want to see the custom field. Typically, checking all the check boxes is best. The View Custom Fields page should reappear with your newly created custom field displayed.
  6. Click Configure in the Operations available for your custom field.
  7. On the Configuration page for the custom field, click the link on the right labeled Edit Default Value.
  8. On Set Custom Field Defaults, enter -1 for the default value and click the Set Default button.

FOR JIRA 5: You may need to contact your JIRA administrator to perform these steps:

  1. On the Administration tab in the navigation panel, click Custom Fields in the Issue Fields section.
  2. On the Custom Fields page, click Add Custom Field (near top right).
  3. On the Create Custom Field: Choose the field type (Step 1 of 2) page, select the Number Field radio button. The click Next >> (near bottom right).
  4. On the Create Custom Field - Details (Step 2 of 2), do the following:
    1. Enter RallyID (no quotes) for the Field Name.
    2. Enter a Description if you wish.
    3. Leave Choose Search Template set to Number Searcher.
    4. Under Choose applicable issue types, choose Any issue type or a specific top level issue (Bug, New Feature, Improvement, Task, etc.
    5. Under Choose applicable context, choose Global context; or pick a specific project after selecting Apply to issues under selected projects.
    6. Click Finish.
  5. Under Associate field RallyID to screens, choose the screens where you wish to see the custom field. Typically, the best option is to select all three screens (Default Screen, Resolve Issue Screen and Workflow Screen). Then click Update.
  6. The Custom Fields page should reappear with your newly created custom field displayed.
  7. Under the gear icon, to the right of your new custom field name, select Configure
  8. On the Configure Custom Field: RallyID page, click on Edit Default Value.
  9. On the Set Custom Field Defaults page, enter -1 in the box next to RallyID. Then click the Set Default button.

Create a CrosslinkUrlField in Rally

It can be useful to have a clickable link in the Rally artifact which will bring up the corresponding JIRA issue in a browser. The <CrosslinkUrlField> XML element in the <RallyConnection> section of the configuration file is where to specify the name of the custom field in Rally which will contain this link (URL). Use the same sort of process in Rally as you used for the JIRAKey field above.

  • We suggest a field name of JIRALink
  • Must be a String type of field
  • Make note of the name of this field for when you customize the <RallyConnection> section of your connector configuration file (see section 4.4)

Create a CrosslinkUrlField in JIRA

It can be useful to have a clickable link in the JIRA issue that will bring up the corresponding Rally artifact in a browser window. The <CrosslinkUrlField> element in the <JiraConnection> section of the configuration file allows you to specify the name of the custom field that will contain this link (URL). Use the same sort of process in JIRA as you used for the for the RallyID field above.

  • We suggest a field name of RallyLink or RallyURL
  • Must be a URL Field or Free Text type of field
  • Make note of the name of this field for when you customize the Jira section of your connector configuration file (see section 4.4)

Set up Rally states and resolutions

There are two additional setup steps required for the connector to successfully push issues through the JIRA workflow. We recommend starting with a JIRA project that uses the default JIRA workflow. Once the connector is working successfully, you can transition to a custom workflow.

Create an additional Reopened state for Rally work items:

  1. Log into Rally as a Workspace or Subscription administrator.
  2. Go to Setup → Workspaces & Projects.
  3. Click on the Workspace that you wish to map to JIRA. This will take you to the Detail page for the given Workspace.
  4. Click on Work Products & Fields and ensure the Work Product Type selected is Defect or whatever work item you are mapping.
  5. Find the State field and click its edit icon at the far right.
  6. Add a State named Reopened.
  7. Click Save & Close.

Make choice lists for resolution match between the two systems

  1. Log into Rally as a Workspace or Subscription administrator.
  2. Navigate to Setup → Workspaces & Projects.
  3. Click on the Workspace that you wish to map to JIRA. This will take you to the Detail page for the given Workspace.
  4. Click on Work Products & Fields and ensure the Work Product Type selected is Defect or User Story (whatever work item you are mapping).
  5. Find the Resolution field and click its edit icon at the far right.
  6. Edit the list of resolutions to make them match the corresponding list in JIRA
  7. Click Save & Close.

The list of resolutions in JIRA can be edited from the Administration tab, by clicking the Resolutions link in the Issue Setting section in the navigation panel on the left.

Alternatively, you can use an OtherEnumFieldHandler to create a one-to-one mapping between Rally resolutions and JIRA resolutions. This approach is described more fully in Mapping drop-down values.

Configure JIRA workflow

The default (read-only) JIRA workflow has a condition on the Start Progress, Stop Progress, and Resolve Issue transitions that restricts the ability to execute the transition to the issue's assignee. Since the connector user (<User> under <JiraConnection>) will likely not be the assignee for many issues, the connector will fail to progress those issues through the workflow and update their status when copying or updating based on changes in Rally. If your usage scenario includes COPY_RALLY_TO_JIRA or UPDATE_RALLY_TO_JIRA, you'll need to modify your workflow to remove these conditions.

If you're using the default JIRA workflow, create a modified workflow as follows:

  1. Use the Copy link for the jira workflow on the View Workflows page to create a copy of the default workflow.
  2. On the Workflows page, select Steps in the new workflow to display the transitions.
  3. Click on the Start Progress transition. Under the "Only assignee can execute this transition," click the Delete link.
  4. Repeat for the Stop Progress and Resolve Issue transitions.
  5. Create a new Workflow Scheme to contain the new workflow, and assign the new workflow to it for Issue Type Bug.
  6. Associate the new workflow scheme with your test project.

If you are already using a custom JIRA workflow, make it inactive, make edits as described above to remove any conditions on transitions, and re-activate it.


Configuration file syntax

Each major section is surrounded by a tag to delineate that section. In the example above, here is a description of each section:

  • RallyConnection
    Defines the connection information for Rally, including Rally URL, user, password, and so on.
  • JiraConnection
    Defines the connection information for Jira, including the JIRA URL, user, password, artifact type, and so on.
  • Connector
    Defines the field mapping between the two systems. Generally, strings should be mapped to strings, integers to integers, and so on. In JIRA, field names are generally specified with the first letter capitalized, such as Summary, Priority.
  • ConnectorRunner
    Specifies parameters related to the services the connector is to run and how often to run the services./dt>

Definition of XML tags in the configuration file, by section

 

XML tags in the <RallyConnection> section:

Tag Name Description Sample Values
     
<RallyConnection>
Required
Opening parent tag for this section.  
<Url>
Required
Server used to connect to Rally (excluding the HTTPS prefix, as the connector adds "https://" to whatever is specified). sandbox.rallydev.com
rally1.rallydev.com
myRally.mydomain.com
192.168.23.24
<User>
Required
Login name for user to make the Web Services requests to create/update work items in Rally. user@company.com
<Password>
Required
Password for user to make the Web Services requests to create/update work items in Rally. Note: The first time the connector runs, it will encode the password so it is not saved in plain text. mypassword
<WorkspaceName>
Required
Workspace in Rally you want to copy/update work items. My Workspace
MyWorkspace
<Projects>
Required
Contains a list of Project tags. Each tag refers to one Rally project that will be used when finding new Rally work items to copy to the other system. For updating work items from Rally to the other system, all projects in <WorkspaceName> are considered. At least one Rally project must be specified in this tag. <Project>Rally1</Project> <Project>Rally2</Project>
<ArtifactType>
Required
Type of artifact you want to create/update in Rally. (Defect, defect),
(Story, UserStory, HierarchicalRequirement), TestCase
<ExternalIDField>
Required
Rally custom string field (name and display name must be identical) that stores the unique id for the other system. Refer to the Create an External ID field in Rally section above. JiraID
<CrosslinkUrlField> Rally custom field containing a hyperlink to the corresponding bug in JIRA. JIRALink
<CopySelectors>
   <CopySelector>
      expression
   </CopySelector>
   ....
</CopySelectors>
Criteria to use when finding new Rally issues to copy to JIRA. An individual expression has the form <field> <relation> <value>, where:
   <field> is the name of a Rally artifact field,
   <relation> is one of =, !=, gt, lt, gte, lte.
   <value> is a valid value for the <field>.
You can have multiple CopySelector criteria within the CopySelectors. All given CopySelector conditions are AND'ed together.
<CopySelector>State = Open</CopySelector>
<UpdateSelectors>
   <UpdateSelector>
      expression
   </UpdateSelector>
   ....
</UpdateSelectors>
Criteria to use when finding existing issues in Rally that should be updated to JIRA. An individual selector specification has the form <field> <relation> <value>, where
<field> is the name of a Rally artifact field,
<relation> is either = or !=, and
<value> is a valid value for the <field>.
You can have multiple UpdateSelector criteria within the UpdateSelectors. All given UpdateSelector conditions are AND'ed together.
<UpdateSelector>Release != alpha</UpdateSelector>
</RallyConnection>
Required
Closing parent tag for this section.  

Tip: Escape special characters contained in a Rally Workspace or Project name that are markup sensitive. For example:

"&" ampersand becomes "&amp;"
">" greater than becomes "&gt;"
"<" less than becomes "&lt;"

Example: "Research & Development" → "Research &amp; Development"

 

XML tags in the <JiraConnection> section:

Tag Name Description Sample Values
     
<JiraConnection>
Required
Opening parent tag for this section.  
<Url>
Required
JIRA server name (or IP address) and port. Syntax is server:port myjiraserver:8080
<User>
Required
JIRA username (must belong to jira-administrators group). jirauser
<Password>
Required
Password for the JIRA user. Note: The first time the connector runs, it will encode the password so it is not saved in plain text. mypassword
<ArtifactType>
Required
JIRA issue type for the issues you want to create/update in JIRA. Bug, Task, Initiative, Defect
<FieldDefaults> Set a default value for a JIRA field. <Field><Name>JIRAfieldname</Name><Default>defaultvalue</Default></Field>
<IDField> JIRA field used to store the unique id of an issue, defaults to key. key
<ExternalIDField>
Required
JIRA custom field of type Number Field that stores the unique id for a Rally work item. For more information, refer to the Create an External ID field in JIRA section above. RallyID
<CrosslinkUrlField> JIRA custom field (free text) containing text of a hyperlink to the corresponding artifact in Rally. RallyURL
<Project>
Required
Specify the JIRA Project Key name which contains the issues to be associated with Rally work items. Be sure to specify the JIRA Project Key and not the JIRA Project Name. The Project Key is a string of uppercase characters entered as the "Key" when the Project was created. TST
<CopySelectors>
   <CopySelector>
      expression
   </CopySelector>
   ....
</CopySelectors>
Criteria to use when finding new JIRA issues to copy to Rally. An individual selector specification has the form: <field> <relation> <value>, where
<field> is the name of a JIRA issue field,
<relation> is one of =, !=, gt, lt, gte, lte.
<value> is a valid value for the <field>.
You can have multiple CopySelector criteria within the CopySelectors. All given CopySelector conditions are AND'ed together.
<CopySelector>Status != Closed</CopySelector>
<CopySelector>Priority = Low</CopySelector>
<UpdateSelectors>
   <UpdateSelector>
      expression
   </UpdateSelector>
   ....
</UpdateSelectors>
Criteria to use when finding existing issues in JIRA that should be updated to Rally. An individual selector specification has the form <field> <relation> <value>, where
<field> is the name of a JIRA issue field,
<relation> is either = or !=, and
<value> is a valid value for the <field>.
You can have multiple UpdateSelector criteria within the UpdateSelectors. All given UpdateSelector conditions are AND'ed together.
<UpdateSelector>Release != alpha</UpdateSelector>
</JiraConnection>
Required
Closing parent tag for this section.  

 

XML tags in the <Connector> section:

Tag Name Description Sample Values
     
<Connector>
Required
Opening parent tag for this section.  
<FieldMapping>
Required
Determine what fields map between the two systems. See Field Mapping section below.
<OtherFieldHandlers> (opening tag)  
   <OtherEnumFieldHandler>
      ....
   <OtherEnumFieldHandler>
Allows a user to map non-alike drop-down values between the two systems. See Mapping drop-down values section in the FAQ.
   <JiraCollectionFieldHandler>
      <FieldName>
         fieldname
      </FieldName>
   </JiraCollectionFieldHandler>


Used to declare a JIRA collection field. Valid only in the direction of Jira to Rally.
(opening tag)

AffectsVersions, Components, FixVersions
(closing tag)
   <JiraNewlineFieldHandler>
      <FieldName>
         fieldname
      </FieldName>
   </JiraNewlineFieldHandler>


Used to declare a JIRA field to be processed, having newlines converted.
(opening tag)

Description

(closing tag)
   <JiraUserToEmailFieldHandler>
      <FieldName>
         name-of-field
      </FieldName>
   </JiraUserToEmailFieldHandler>


Used to declare the JIRA field to be used for finding an email address.
(opening tag)

Reporter

(closing tag)
</OtherFieldHandlers> (closing tag)  
<RelatedObjectLinkers> For more complex mappings of fields (like collections).  
    <RallyAttachmentLinker /> Used to copy attachments between JIRA and Rally (bi-directional). Can be used on any object which supports attachments (in Rally: tasks, defects, stories and tests; in Jira: any issue type with attachments).  
    <RallyJiraCommentLinker /> Used to copy Discussions or Comments between Rally and JIRA.
WARNING: There is a known limitation with this feature. Once Rally Discussions have been sync'ed with JIRA Comments, they should never be modified in JIRA, otherwise it will cause a recursive copy, back and forth between the two systems, with the Discussions/Comments growing with each iteration. This occurs because the connector compares the two sets of Discussions/Comments, and if they are not identical, it assumes they need to be re-synced; however, Rally Discussions are read-only (once they have been created), so an edited Comment in JIRA is copied to Rally as a new Discussion, and at that point the Discussions/Comments between the two system will be out of sync again, and this loop will continue indefinitely.
See Jira-config-RallyJiraCommentLinker.pxml for example.
</RelatedObjectLinkers> (closing tag)  
</Connector>
Required
Closing parent tag for this section.  

 

XML tags in the <ConnectorRunner> section:

Tag Name Description Sample Values
     
<ConnectorRunner>
Required
Opening parent tag for this section.  
<Preview> Allows you to enable a preview mode for testing where NO objects are copied/updated in either system. false (default)
true
<LogLevel> Determines what type of messages are written to the log file. The highest level is Debug where all messages are displayed. The default log level is Info. Fatal, Error, Warn, Info, Debug
<Services>
Required
Determine what type of services to run. Be careful if you update in both directions because whichever system runs the update first will overwrite the updates of the other system. COPY_JIRA_TO_RALLY, COPY_RALLY_TO_JIRA, UPDATE_JIRA_TO_RALLY, UPDATE_RALLY_TO_JIRA
</ConnectorRunner>
Required
Closing parent tag for this section.  

Edit the configuration file

A sample configuration file, jira_config.xml, was included in the exe or zip file and should be in the root directory of the installation. This is the directory you specified during the wizard-based Windows install (such as C:\Program Files\RallyConnectorforJira) or where you extracted the zip file. We recommend making a backup copy of the jira_config.xml in case you need to reference a valid configuration file later.

Edit jira_config.xml and enter the appropriate values between each begin and end tag.

<Config>
        <RallyConnection>
                <Url>rally1.rallydev.com</Url>
                <WorkspaceName>Workspace Name</WorkspaceName>
                <Projects>
                        <Project>Project</Project>
                </Projects>
                <User>user@company.com</User>
                <Password>password</Password>
                <ArtifactType>Defect</ArtifactType>
                <ExternalIDField>JiraKey</ExternalIDField>
        </RallyConnection>

        <JiraConnection>
                <Url>http://jiraserver:port</Url>
                <User>jirauser</User>
                <Password>jirapassword</Password>
                <ArtifactType>bug</ArtifactType>
                <ExternalIDField>RallyID</ExternalIDField>
                <Project>The Project Key (not the project name)</Project>
                <WorkflowFile>jira_issue_workflow.xml</WorkflowFile>
                <CopySelectors>
                        <CopySelector>Status != Closed</CopySelector>
                </CopySelectors>
        </JiraConnection>

        <Connector>
                <FieldMapping>
                        <Field><Rally>Name</Rally>       <Other>Summary</Other></Field>
                        <Field><Rally>Description</Rally><Other>Description</Other></Field>
                        <Field><Rally>State</Rally>      <Other>Status</Other></Field>
                        <Field><Rally>Resolution</Rally> <Other>Resolution</Other></Field>
                </FieldMapping>

                <OtherFieldHandlers>
                        <JiraNewlineFieldHandler>
                                <FieldName>Description</FieldName>
                        </JiraNewlineFieldHandler>

                        <OtherEnumFieldHandler>
                                <FieldName>Status</FieldName>
                                <Mappings>
                                        <Field><Rally>Submitted</Rally> <Other>Open</Other></Field>
                                        <Field><Rally>Open</Rally>      <Other>In Progress</Other></Field>
                                        <Field><Rally>Reopened</Rally>  <Other>Reopened</Other></Field>
                                        <Field><Rally>Fixed</Rally>     <Other>Resolved</Other></Field>
                                        <Field><Rally>Closed</Rally>    <Other>Closed</Other></Field>
                                </Mappings>
                        </OtherEnumFieldHandler>
                </OtherFieldHandlers>
        </Connector>

        <ConnectorRunner>
                <Preview>false</Preview>
                <Services>COPY_JIRA_TO_RALLY,  UPDATE_RALLY_TO_JIRA</Services>
        </ConnectorRunner>
</Config>

Tip: Incrementally set up the connector! Start with a basic configuration file, test that you can connect to JIRA and Rally in a "test" environment. Once you validate this is setup correctly, then start customizing the field mapping and field handler sections.

Field mapping

The field mapping section is located between the <Connector> tags in the configuration file and defines what fields map between the two systems.

For example, this definition sets up a mapping between the Rally field Name with the field Headline in the other system. On a create or update, the connector will only update the Name field in Rally and the Headline field in the other system.

<Config>
        ....
        <Connector>
                <FieldMapping>
                        <Field><Rally>Name</Rally><Other>Headline</Other></Field>
                </FieldMapping>
                ....
        </Connector>
        ....

When you set up your mapping between the two systems, ensure the fields are compatible between the two systems (an integer field should map to an integer field in the other system, a rich text should map to a rich text in the other system).

Otherwise, you might experience situations where information is not created/updated between the two systems and you will see an error in the log file. For example, the connector will post an error for a particular work item if you try to post a string to a custom field of type integer in Rally.

You can add subsequent mappings by appending to this list. For example, this sets up a mapping to Rally Name >> Headline, Rally Description >> Description, Rally Priority >> Priority:

<Config>
        ....
        <Connector>
                <FieldMapping>
                        <Field><Rally>Name</Rally><Other>Headline</Other></Field>
                        <Field><Rally>Description</Rally><Other>Description</Other></Field>
                        <Field><Rally>Priority</Rally><Other>Priority</Other></Field>
                </FieldMapping>
                ....
        </Connector>
        ....

If you are mapping a drop-down value in Rally to the other system, this assumes that the drop-down values match. Otherwise, the connector will throw an error letting you know the value was not found in the list.

If your drop-down values are different between the two systems, see the section Mapping drop-down values.

Other multiple value fields

JIRA has several fields that can have multiple values that are not as bounded as State or Resolution fields. Examples of this type of field are FixVersion(s), AffectsVersion(s) and Component(s). The connector accommodates these fields but the mapping direction should be specified as TO_RALLY only. In the course of mapping from JIRA to Rally, if there are multiple values for the field, they will be copied to Rally (or updated in Rally) as a string of comma separated values.

Determine how to handle the Description field

  1. Maximum length.
    Note that Rally's Description field on the Artifact object is limited to a maximum of 32,768 characters, where as the Description field in JIRA can be larger. The connector will not copy an artifact from JIRA to Rally if the Description field contains more than 32,768 characters. It will issue a error like this:
      WARN : RallyConnection.initialize -
            <Errors>
            <OperationResultError>
                    Validation error: Defect.Description length is greater than the maximum length of 32768
            </OperationResultError>

            <OperationResultError>
                    Validation error: Card.WorkProductDescription length is greater than the maximum length of 32768
            </OperationResultError>
            </Errors>
  2. Rich Text Formatting
    Also, within both Rally and JIRA, the Description field can be in a rich text format (RTF).

    The specific type of markup to achieve the RTF nature can differ between Rally and JIRA. Also, you can elect to have the Description field in either system consist of just plain text, without any markup.

    In Rally, the internal editor for the Description field supports HTML markup.

    In JIRA, the Description field can be HTML markup (with a prefixing {html} tag and a suffixing {html} tag) but by default, JIRA uses their own markup that is more like wiki-text. Rally strongly recommends that you if you want to use rich text for the Description field, that you identify which of the two systems (Rally or JIRA) that you want to be the authoritative system for this field and that you specify the directionality to match this (eg. <Direction>TO_RALLY or TO_JIRA</Direction>). Should you decide to make JIRA the authoritative system for the Description field and use the native JIRA markup, the description (when copied to Rally) will display as plain text with the JIRA markup embedded. An option in this case where you want the JIRA system to be the authoritative system with respect to the Description field, is to use HTML markup which will then result in the same presentational aspects seen in the Rally system after the item has been copied or updated. Choosing this latter option requires that you surround your Description in JIRA with the {html} tags and use the JiraHTMLFieldHandler for the Description field. To use the <JiraHTMLFieldHandler> add the following block in the <Connector> section of your jira_config.xml file (substitute the name of your specific configuration file).

    <Config>
            ....
            <Connector>
                    ....
                    <OtherFieldHandlers>
                            <JiraHTMLFieldHandler>
                                    <FieldName>Description</FieldName>
                            </JiraHTMLFieldHandler>
                            ....

    Rally recommends that a policy be communicated to your end users as to what system should be used to create/edit the description and the desired markup scheme (if any). Of course, the description can be viewed in either system.

    If you elect to use plain text (without markup) in the Description field, be aware that JIRA and Rally handle line breaks in text fields differently. The \n newline character is used in JIRA descriptions, while Rally uses the HTML <br /> markup. The jira_config.xml shipped with the connector contains the following XML to enable the JiraNewlineFieldHandler, which automatically translates between these two encodings for the Description field:

    <Config>
            ....
            <Connector>
                    ....
                    <OtherFieldHandlers>
                            <JiraNewlineFieldHandler>
                                    <FieldName>Description</FieldName>
                            </JiraNewlineFieldHandler>
                            ....

    If you do not want this behavior, simply remove the lines above from your configuration file. Currently, only the Jira Description field is supported.

Mapping the CreationDate of an artifact

In Rally, the CreationDate on an artifact is a read-only field. It is populated by the underlying database and therefore the user can not modify this field. If a configuration file maps a field from JIRA into this Rally field, it will be silently ignored (no data is copied or updated in this Rally field), and there will be no indication in the log file that the action was ignored.

Field handlers

The field handlers are documents in other parts of this document:

Running the connector

Once the jira_config.xml is set up, you can start running the connector. To start the connector, use one of the following command lines:

For Windows:
    rally2_jira_connector.exe  jira_config.xml

For Linux:
    ruby  rally2_jira_connector.rb  jira_config.xml

Tip: For Windows, we ship a startjira.bat file to make it easier to test. Double-click on the batch file to automatically run the connector and open the log file in WinTail to watch the log messages generated by the connector. This is an easy way to confirm that the connector is working properly, or to discover any errors.

Tip: For Linux, use the Unix command tail -f rallylog.log to watch log messages written to the log file.

Optionally, you can add a number to the end of the command line that specifies the time in minutes the connector should "sleep" between successive executions of all services. The default is 15 minutes. We recommend sleep intervals of no less than 10 minutes. For example:

For Windows:
    rally2_jira_connector.exe  jira_config.xml  10

For Linux:
    ruby  rally2_jira_connector.rb  jira_config.xml  10

To stop the service, use Control-C in the command shell.

Multiple configuration files

If you want to map to more than one workspace in Rally, or if you want to map multiple artifact types, or if you need to map to multiple containers (such as domain/projects in Quality Center or ClearQuest databases) in the other system, setting up multiple configuration files may make sense.

To run multiple instances of the connector for different configuration files, pass in the list of config files as arguments to the rally2_jira_connector.rb script or rally2_jira_connector.exe.

For Windows:
    rally2_jira_connector.exe  config_workspaceA.xml  config_workspaceB.xml

For Linux:
    ruby  rally2_jira_connector.rb  config_workspaceA.xml  config_workspaceB.xml

The connector will process the configuration files based on the command line argument order, and processes one file at at time.

Once it processes every configuration file, the connector will sleep based on the sleep value. The default is 15 minutes. To change the sleep value between runs, set this value (in minutes) as the last command line argument. We recommend a sleep value of 10 minutes or more and advise against anything less.

For Windows:
    rally2_jira_connector.exe  config_workspaceA.xml  config_workspaceB.xml  10

For Linux:
    ruby  rally2_jira_connector.rb  config_workspaceA.xml  config_workspaceB.xml  10

Troubleshooting the connector

  1. See log file for messages:

    Once the connector is running, all errors are written to a log file in the current working directory where the connector was invoked. Informational messages, warning and errors are written to the log file depending on the value of the <LogLevel> tag in the <ConnectorRunner> section of the configuration file.

    To see the most recent log messages on Windows, rename the extension of the WinTail file from .dat to .exe and then double-click on the WinTail.exe and browse to the rallylog.log file.

  2. Connector validation:

    Before the connector starts synchronizing objects between the two systems, it performs a validation that confirms:

    • Connecting to Rally is successful
    • Connecting to the JIRA system is successful
    • Fields in the field mapping exist in Rally
    • Each field handler has a corresponding field mapping section in the configuration file.

    To confirm the validation is successful without moving objects between the two systems, the <Preview> tag in the configuration file to may be set to true. This helps to experiment with different configuration options while debugging an issue.

  3. Custom field precaution, for ExternalID:

    The copy operation for the COPY_JIRA_TO_RALLY service is driven by the value in the custom field set up in JIRA to hold the identifier for the corresponding artifact in Rally. We often refer to this field as the ExternalID. Precautions:

    • This custom field must be defined as an Number Field and must be set up to have a default value of -1 (as outlined here).
    • JIRA items that exist before this custom field is (properly) define will not have the default value of -1 (as required), but instead it will be NULL. Because of this, the JIRA query to identify items eligible to be copied to Rally will not find these items. Should you want to include these items in the copy, perform a bulk update operation in JIRA to set the value of the ExternalID custom field -1 for items whose current value is NULL.
  4. Custom field precaution, in general:

    When defining a JIRA custom field, say to receive some field from Rally, the valid "Screens" must be declared during this process. Furthermore, the "Default Screen" must be selected at minimum (I am unsure about the requirements of the other two: "Resolve Issue Screen" and "Workflow Screen").

    If the "Default Screen" is not selected, and the field is declared "Required", and a Field Defaults is supplied in the XML configuration file too, you may see an error like the following (in this case, a JIRA custom field named Severity was created as "Required", without the "Default Screen" being checked):

    ERROR : JiraConnection.rescue in attempt_create - Trying to create issue:
                            'JPKole's test' resulted in exception SOAP::FaultError
     WARN : JiraConnection.initialize - com.atlassian.jira.rpc.exception.RemoteValidationException: {} :
                            [Severity: Severity is required.]
     WARN : ConnectorRunner.exception - Message com.atlassian.jira.rpc.exception.RemoteValidationException: {} :
                            [Severity: Severity is required.]
  5. Mapping to required fields in Rally:

    When mapping a field from JIRA to Rally, if the field is marked Required in Rally, yet the field is empty in JIRA, then a COPY_JIRA_TO_RALLY service will produce an error. In the following log file snippet, the Rally field Resolution was marked required, but no data was supplied for it on the JIRA side:

      ANY : ConnectorRunner.process_service - Starting Service COPY_JIRA_TO_RALLY
    DEBUG : Finding method getIssuesFromJqlSearch
     INFO : JiraConnection.find_new - Found 1 new issues in JIRA
    DEBUG : Connector.block in map_fields_to_rally - Mapping Summary(Xyz) - to - Name(Xyz)
    ....
     WARN : RallyConnection.initialize -
                            <Errors> <OperationResultError>
                                    Validation error: Defect.Resolution should not be null
                            </OperationResultError> </Errors>
      ANY : ConnectorRunner.process_service - Finished Service COPY_JIRA_TO_RALLY
    DEBUG : Finding method logout
     INFO : JiraConnection.disconnect - Disconnected from JIRA
  6. Mapping Rally Project to Jira custom field:

    When mapping the Project field from Rally to a custom field in JIRA of type Text Field (< 255 characters), a <RallyReferenceFieldHandler> for Project must be used (more information here). If not, the following log file snippet will be seen:

      ANY : ConnectorRunner.process_service - Starting Service COPY_RALLY_TO_JIRA
     INFO : RallyConnection.find_new - Find New Rally storys
                  [.....]
     INFO : RallyConnection.find_new -   Found 1 new storys in Rally
     INFO : Connector.copy_to_other - Copy US385 to JIRA
    DEBUG : Connector.block in map_fields_to_other - Mapping Name(Test) - to - Summary(Test)
    DEBUG : Connector.block in map_fields_to_other - Mapping Project(P1) - to - Rally Component(P1)
    DEBUG : Finding method createIssue
    ERROR : JiraConnection.rescue in attempt_create - Trying to create issue: 'Test' resulted in exception NameError
     WARN : JiraConnection.initialize - uninitialized constant Continuation
     WARN : ConnectorRunner.exception - Message uninitialized constant Continuation
      ANY : ConnectorRunner.process_service - Finished Service COPY_RALLY_TO_JIRA
  7. Could not log in to JIRA:
    When specifing the tag in the configuration file for JIRA, this string was used:
    <Url>https://doh.atlassian.net/login.jsp</Url>
    but it should have been:
    <Url>https://doh.atlassian.net</Url>
    As a result, the following log file snippet was seen:

     INFO : JiraConnection.connect - Connecting to JIRA at https://doh.atlassian.net/login.jsp as user Obama
    ERROR : JiraConnection.rescue in connect - Could not log in to JIRA
    ERROR : JiraConnection.initialize - 404: Not Found
    ERROR : ConnectorRunner.exception - Message 404: Not Found
    ERROR : ConnectorRunner.exception - Stack Trace
                <DIR>=/Users/jpkole/.rvm/gems/ruby-1.9.2-p290/gems/mumboe-soap4r-1.5.8.6/lib/soap
    ERROR : ConnectorRunner.block in exception - <DIR>/streamHandler.rb:267:in `send_post'
    ERROR : ConnectorRunner.block in exception - <DIR>/streamHandler.rb:171:in `send'
    ERROR : ConnectorRunner.block in exception - <DIR>/rpc/proxy.rb:186:in `route'
    ERROR : ConnectorRunner.block in exception - <DIR>/rpc/proxy.rb:149:in `call'
    ERROR : ConnectorRunner.block in exception - <DIR>/rpc/driver.rb:151:in `call'
  8. Contact Rally Support if stumped:
    If you still cannot determine the root cause of an issue, then please email the entire log file and configuration file to Rally Support.

Tips

  1. Mapping Rally Projects:
    If you are copying issues from JIRA to Rally using the <RallyReferenceFieldHandler> with Projects, you may see a "Could not find Rally Project with name ..." error in the log file if the connector user does not have "Editor" permissions to that project in Rally.
  2. Mapping Release/Iterations with Multiple Projects:
    If you are using a <RallyReferenceHandler> to map Releases/Iterations with the same name and multiple projects, you may receive an error if the Release/Iteration you are updating on the Defect references a different Project than the given Defect is assigned. This happens because the connector only returns the FIRST Release/Iteration with the matching name in Rally so it could have a reference to a Release/Iteration in a different project.
  3. Mapping Rally ScheduleState to a Jira custom State field
    You may want to get the ScheduleState from Rally (Defined, In-Progress, Completed, Accepted) to go to Jira. This can be achieved if you create a custom dropdown field in Jira that has the same values as Rally. In Jira - create a custom Select-List field named 'Rally Schedule State' with the values: Defined, In-Progress, Completed, Accepted. With the dropdown values as an exact match, you will not need a field handler. Simply map:
    <Field><Rally>ScheduleState</Rally><Other>RallySceduleState</Other></Field>
    If you wish to make sure that the Schedule State only goes from Rally to Jira, you just need to add a Direction mapping in the row:
    <Field><Rally>ScheduleState</Rally><Other>RallySceduleState</Other><Direction>TO_OTHER</Direction></Field>
  4. Why are changesets not displaying in Rally?
    Verify your Workspace administrator has selected the Enable Build and Changeset option on the Edit Workspace configuration pop-up and verify there are no unexpected messages in the Rally_Connector_Error.log file. No errors are written to the console.
  5. How does Rally authenticate your system, and how does your system authenticate Rally?
    JIRA is an on-premises-based software bundle that runs behind the firewall. Outgoing communication from the connector runs over HTTPS/SSL to reach out to both Rally and JIRA systems. This security setting is dependent on SSL being available on both target systems.
  6. For SSL protocol, what are the cryptography algorithms configured? What version of SSL/TLS is used? Examples: SHA1, MD5, RSA, AES, 3DES, RC4.
    The Rally ALM production endpoint supports up to TLS 1.2/SSL3. Additionally, Rally ALM supports multiple ciphers up to 512 bits.
  7. What is the Firewall port used for this connector?
    This connector is an outbound connector that does not listen for inbound traffic, the connector reaches out to port 443 on target systems.
  8. Where does the SSL connector terminate in your system? Which zone it is? How does the SSL private key is managed/protected?
    The connector runs as a client-based connector and does not have a termination point for inbound traffic.

Appendix A - Configuring a custom workflow

In order to support updates from Rally to JIRA in the case where a custom JIRA defect workflow has been defined, the Rally Connector for JIRA allows you to describe the custom workflow in an XML file. Using this workflow definition, the connector can transition a JIRA issue through the workflow until its Status matches the State of a Rally defect.

As an example, consider the default workflow for the JIRA issue type of Bug pictured below. Assume there is a defect in Rally DE1 that was initially created in JIRA (as issue TST-1), marked in JIRA as Resolved (Fixed), and some time later copied to Rally, where it was assigned a State of Fixed.

Subsequently, a developer discovers that the defect is not fixed after all, and updates its State to Open. Since in the JIRA workflow there is no transition from the Resolved status to the In Progress status (to match the Rally state Open), the issue must go through the Reopen and Start Progress transitions to get to the desired status.

workflow

The XML file (workflow.xml) that describes the default JIRA defect workflow is shown below:

<Workflow>
        <Step RallyState="Submitted" JiraStatusName="Open">
                <Transition JiraStatusName="In Progress">
                        <Action ID="301" Name="Stop Progress"/>
                </Transition>
                <Transition JiraStatusName="Resolved">
                        <Action ID="3" Name="Reopen Issue"/>
                        <Action ID="4" Name="Start Progress"/>
                        <Action ID="301" Name="Stop Progress"/>
                </Transition>
                <Transition JiraStatusName="Closed">
                        <Action ID="3" Name="Reopen Issue"/>
                        <Action ID="4" Name="Start Progress"/>
                        <Action ID="301" Name="Stop Progress"/>
                </Transition>
                <Transition JiraStatusName="Reopened">
                        <Action ID="4" Name="Start Progress"/>
                        <Action ID="301" Name="Stop Progress"/>
                </Transition>
        </Step>

        <Step RallyState="Open" JiraStatusName="In Progress">
                <Transition JiraStatusName="Open">
                        <Action ID="4" Name="Start Progress"/>
                </Transition>
                <Transition JiraStatusName="Reopened">
                        <Action ID="4" Name="Start Progress"/>
                </Transition>
                <Transition JiraStatusName="Resolved">
                        <Action ID="3" Name="Reopen Issue"/>
                        <Action ID="4" Name="Start Progress"/>
                </Transition>
                <Transition JiraStatusName="Closed">
                        <Action ID="3" Name="Reopen Issue"/>
                        <Action ID="4" Name="Start Progress"/>
                </Transition>
        </Step>

        <Step RallyState="Fixed" JiraStatusName="Resolved">
                <Transition JiraStatusName="Open">
                        <Action ID="5" Name="Resolve Issue">
                                <Field>resolution</Field>
                        </Action>
                </Transition>
                <Transition JiraStatusName="In Progress">
                        <Action ID="5" Name="Resolve Issue">
                                <Field>resolution</Field>
                        </Action>
                </Transition>
                <Transition JiraStatusName="Reopened">
                        <Action ID="5" Name="Resolve Issue">
                                <Field>resolution</Field>
                        </Action>
                </Transition>
                <Transition JiraStatusName="Closed">
                        <Action ID="3" Name="Reopen Issue"/>
                        <Action ID="5" Name="Resolve Issue">
                                <Field>resolution</Field>
                        </Action>
                </Transition>
        </Step>

        <Step RallyState="Closed" JiraStatusName="Closed">
                <Transition JiraStatusName="Open">
                        <Action ID="2" Name="Close Issue">
                                <Field>resolution</Field>
                        </Action>
                </Transition>
                <Transition JiraStatusName="In Progress">
                        <Action ID="2" Name="Close Issue">
                                <Field>resolution</Field>
                        </Action>
                </Transition>
                <Transition JiraStatusName="Reopened">
                        <Action ID="2" Name="Close Issue">
                                <Field>resolution</Field>
                        </Action>
                </Transition>
                <Transition JiraStatusName="Resolved">
                        <Action ID="701" Name="Close Issue"/>
                </Transition>
        </Step>

        <Step RallyState="Reopened" JiraStatusName="Reopened">
                <Transition JiraStatusName="Open">
                        <Action ID="4" Name="Start Progress"/>
                        <Action ID="5" Name="Resolve Issue">
                                <Field>resolution</Field>
                        </Action>
                        <Action ID="3" Name="Reopen Issue"/>
                </Transition>
                <Transition JiraStatusName="In Progress">
                        <Action ID="5" Name="Resolve Issue">
                                <Field>resolution</Field>
                </Action>
                        <Action ID="3" Name="Reopen Issue"/>
                </Transition>
                <Transition JiraStatusName="Resolved">
                        <Action ID="3" Name="Reopen Issue"/>
                </Transition>
                <Transition JiraStatusName="Closed">
                        <Action ID="3" Name="Reopen Issue"/>
                </Transition>
        </Step>
</Workflow>

The process for creating the XML workflow specification is as follows(refer to the default workflow XML above as an example):

  1. Identify the steps in your JIRA custom workflow.
    In JIRA, click on the Administrator tab and select Workflows under the Global Settings section in the navigation pane on the left. Find the custom workflow and click on the Steps link in the Operations column to display the View Workflow Steps screen. The <Step> sections in workflow.xml correspond directly with the Steps in JIRA.

    Note: We have found that the process of creating the custom workflow XML is much easier if you create a diagram similar to the one above showing the JIRA steps/statuses, corresponding Rally states, and the transitions between them, including status and action IDs.

  2. Create Rally states for each JIRA status.
    For the Linked Status in each JIRA Step, find or create a corresponding State in Rally. To create new states in Rally, follow a procedure similar to that described under the Set up Rally states and resolutions section.
  3. Create <Step> blocks for each state/status.
    In a new file, create the beginning and ending XML tags:
    <Workflow>
    </Workflow>

    Then within these tags, create <Step></Step> blocks for each pair of corresponding Rally and JIRA state/statuses. The values of the <Step> tag should look like this:

    <Step RallyState="Reopened" JiraStatusName="Reopened">
  4. Create <Transition> blocks for each <Step>.
    Inside each <Step> block, create <Transition></Transition> blocks for each of the other state/status pairs. Each <Transition> under a <Step> describes how to get from another state/status to the one identified in the <Step> block you are working on. For example, under the Reopened step from the example above, there is a transition that describes how to get to Reopened from JIRA status Open:
    <Step RallyState="Reopened" JiraStatusName="Reopened">
    <Transition JiraStatusName="Open">

    Again, the status names can be found on the View Workflow Steps screen in JIRA. For a custom workflow with N states, each <Step> block should contain N-1 <Transition> blocks in order to give the connector enough information to successfully update JIRA status with any arbitrary state change in Rally. It is not necessary to specify a transition from a state/status to itself.

  5. Define <Action> blocks for each <Transition>.
    Inside each <Transition> block, create <Action></Action> blocks for each action needed to progress the defect through the workflow from the status identified in the JiraStatusName value of the <Transition> block to the status identified in the JiraStatus value of the enclosing <Step> block. Continuing with our example, to get from status Open to status Reopened, we need three Actions - Start Progress, Resolve, and Reopen. The corresponding XML looks like this:
    <Step RallyState="Reopened" JiraStatusName="Reopened">
    <Transition JiraStatusName="Open">
    <Action ID="4" Name="Start Progress"/>
    <Action ID="5" Name="Resolve Issue">
    <Field>resolution</Field>
    </Action>
    <Action ID="3" Name="Reopen Issue"/>
    </Transition>
    </Step>

    As usual, the action IDs can be found on the JIRA View Workflow Steps page, in the Transitions column. As noted above, a diagram of the custom workflow is indispensable in this part of the process.

  6. Define any fields that must be filled in for an <Action>.
    Notice in the example above that the Resolve Issue action has a element which indicates that the Resolution field should be supplied to JIRA. The value of the Resolution field is the value of Resolution in the Rally defect, after any transformations specified by an <OtherEnumFieldHandler> for Resolution (if the Resolution lists in Rally and JIRA do not match exactly). If clicking on a link under Available Workflow Actions in the JIRA user interface would result in a JIRA screen requiring the user to fill in a field in order to complete the action, you should mimic that process by providing the fields and values here.
English

Feedback

Please send us your feedback regarding our help site. For feedback regarding the Rally product, click here to open a support case or click here to submit a new feature request
English
By submitting this form, you accept the Mollom privacy policy.
© 2014 Rally Software Development Corp | Legal