Rally Connector for JIRA 5 and 6 Installation & User Guide

Print this topicEmail this topic

Connector downloads:


Note: This documentation applies to JIRA version 5.2 or newer. If you are using JIRA version 4.4 or older, please refer to the JIRA 4 Installation and User Guide.

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 the JIRA 5 REST API. Most fields between the two systems can be synchronized. This connector supports JIRA version 5.2 or greater.

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.

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 five 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
  • Update Rally work items and JIRA issues

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

An alternative update service, UPDATE_RALLYFIELDS_AND_OTHER, first searches Rally for updates and pushes only the changed fields to the JIRA system. It then searches the JIRA system for updated artifacts, and pushes all mapped fields of those artifacts into the Rally system.

This reduces the chances of data overwrites. The only scenario where an overwrite might occur is if a change is made in Rally and a change is made in JIRA (in reference to two artifacts previously associated together). In this scenario, first any mapped field in Rally, which has been modified, is copied to JIRA (potentially overwriting a previously modified mapped field in JIRA), then all mapped fields are copied from JIRA to Rally.

This installation and user guide includes:

The Rally connector supports synchronizing top-level JIRA issues (bug, new feature, improvement, task, or a 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. This guide discusses some of the trade-offs to be considered and some potential approaches.

The remainder of this guide assumes mapping the Rally defect work item type to a JIRA bug issue type. If you are mapping another JIRA issue type, you will need to have a modified jira-rest_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.

Basic installation steps

  1. Install the connector (run the installer or extract the zip).
  2. Make configuration changes in Rally and in JIRA.
  3. Edit the jira-rest_config.xml to reflect your environment.
  4. Run rally2_jira-rest_connector to start the connector.

System setup

  • The following people will be involved in getting fields set up 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.
  • Consider the process you want to set up between Rally and JIRA:
    • What problem are you trying to solve?
    • Where do objects start and end their lifecycle?
  • Which fields need updated? Identify a test project in JIRA to use for testing.
  • Identify a test Rally workspace and project to use for testing.
  • Decide on which computer the connector will run.

The Rally Integrations FAQ and Best Practices contains some useful information for connector setup.

Software and hardware requirements

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

  • A Rally subscription
  • Windows XP, Windows 7, or Windows 2003/2008/2012 Server
  • Linux
  • Ruby 2.0.0-p247 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 5.2 or greater.
  • Note: The Jira connector does not support LDAP
  • Note: By default, JIRA 5.x does not allow issues without an assignee to be created through the API. There are several ways to work around this behavior, including:
    • Turn on Allow Unassigned Issues in JIRA, under System → 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 <JiraRestConnection> section as follows:
      <Config>
              ....
              <JiraRestConnection>
                      ....
                      <FieldDefaults>
                              <Field><Name>Assignee</Name><Default>someuser</Default></Field>
                      </FieldDefaults>
                      ....

Install the connector

Pre-installation checklist

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

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:

  1. From Start, right-click on Computer, then select Properties.
  2. Click Advanced system settings.
  3. On System Properties, click Environment Variables.
  4. On Environment Variables, click New under System Variables.
  5. On New System Variables, enter http_proxy in the Variable name: field, then enter your proxy's full HTTP Url in the Variable value: field (for example, http://www-cache:8000).
  6. Click OK (three 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 open 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):

  • field_handlers—A folder for custom field handers
  • jira-rest_config.xml—Sample configuration file
  • jira_issue_workflow.xml—Sample configuration file for JIRA Bug workflow steps
  • jira_workflow.xml—Sample configuration file for JIRA workflow steps
  • rally2_jira-rest_connector.exe—Executable to run the connector
  • startjira.bat—Batch file that automatically runs the connector and shows the log file (useful for testing)
  • unins000.dat—Uninstall utilities
  • unins000.exe—Uninstall utilities
  • 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-master-bbb.zip locally on your machine (such as C:\rally for Windows or /Users/username/Downloads/ on a MAC).
  2. Change the directory to the root of the connector installation:
    cd RallyConnectorforJira-Ruby-4.x.x-y-z
  3. Run the installation shell script:
    ./install.sh
    Sample output for revision 4.4.13-maintenance-92 on a MAC:
    $ ./install.sh
    installing gem: ./rallyeif-wrk-0.5.6.gem
    Fetching: mini_portile-0.5.3.gem (100%)
    Successfully installed mini_portile-0.5.3
    Fetching: nokogiri-1.6.1.gem (100%)
    Building native extensions.  This could take a while...
    Successfully installed nokogiri-1.6.1
    Fetching: httpclient-2.4.0.gem (100%)
    Successfully installed httpclient-2.4.0
    Fetching: rally_api-1.1.2.gem (100%)
    Successfully installed rally_api-1.1.2
    Successfully installed rallyeif-wrk-0.5.6
    5 gems installed
    installing gem: ./rally_jest-1.2.9.gem
    Fetching: multipart-post-1.2.0.gem (100%)
    Successfully installed multipart-post-1.2.0
    Fetching: faraday-0.8.8.gem (100%)
    Successfully installed faraday-0.8.8
    Successfully installed rally_jest-1.2.9
    3 gems installed
    installing gem: ./rallyeif-jira-4.4.13.gem
    Fetching: xml-simple-1.1.2.gem (100%)
    Successfully installed xml-simple-1.1.2
    Successfully installed ClothRed-0.5.0
    Fetching: sanitize-2.0.6.gem (100%)
    Successfully installed sanitize-2.0.6
    Successfully installed rallyeif-jira-4.4.13
    4 gems installed
  4. If you are using a proxy, you will need to set an environment variable PROXY with the proxyhost:portnumber prior to running the install.sh script. For example:
    export PROXY=host17:8080

JIRA setup

The JIRA connector user (as specified in the configuration file) does not need to be part of the jira-admin group, but they must have permissions for the following eleven operations:

  1. Add Comments
  2. Assign Issues
  3. Assignable User
  4. Browse Projects
  5. Close Issues
  6. Create Attachments
  7. Create Issues
  8. Edit Issues
  9. Modify Reporter
  10. Resolve Issues
  11. Schedule Issues

Note:

  • JIRA's configuration can become quite complex. We have found that it is good to use JIRA's Permission Helper button to check that all is correct. All eleven of the above permission must show a green check mark in the Permission Helper before using the connector.
  • As a secondary test, log in to your JIRA instance as the connector user. Try to edit an existing Issue. If this is not allowed, then mostly likely the permissions are not correct for the connector to run.

To modify the permissions on a project (the following instructions were developed on a JIRA 6.2 SaaS instance):

  1. Log in to JIRA with an account which has appropriate privileges.
  2. Select your desired project under the Projects tab.
  3. Select Administration under the project name (instead of Overview).
  4. Click Permissions in the left column.
  5. Edit the permissions.

In most cases, a JIRA user in the jira-developers group has the above permissions. If one of the above permission is absent, the log file will likely show something like:

 INFO : JiraRestConnection.connect - Using RallyJest version 1.1.19
DEBUG : RallyJest::JiraComm.block in execute_request - issuing a GET request for endpoint:
                /rest/api/2/serverInfo
DEBUG : RallyJest::JiraComm.execute_request - {
                "baseUrl":"http://jira.jpkole.org:8080","version":"5.2.9","versionNumbers":[5,2,9],
                "buildNumber":852,"buildDate":"2013-03-12T00:00:00.000-0400",
                "serverTime":"2013-10-17T10:37:05.815-0400",
                "scmInfo":"31363faa193505dadf581a01e480744edf4ac0de",
                "serverTitle":"GMS Issue Tracker"}
 INFO : JiraRestConnection.connect - Connected to JIRA at http://jira.jpkole.org:8080, (version 5.2.9)
DEBUG : RallyJest::JiraComm.block in execute_request - issuing a GET request for endpoint:
                /rest/api/2//mypermissions?projectKey=JPKOLE
DEBUG : RallyJest::JiraComm.execute_request - {
                "permissions":{
                        "EDIT_ISSUE":{"id":"12","key":"EDIT_ISSUE",
                                "name":"Edit Issues","description":"Ability to edit issues.",
                                "havePermission":true},
                        "VIEW_VERSION_CONTROL":{"id":"29","key":"VIEW_VERSION_CONTROL",
                                "name":"View Issue Source Tab",
                                "description":"Allows users to view related source code commits ....",
                                "havePermission":true},
                        "MODIFY_REPORTER":{"id":"30","key":"MODIFY_REPORTER",
                                "name":"Modify Reporter",
                                "description":"Ability to modify the reporter when creating or ....",
                                "havePermission":false},
                        ....}}
ERROR : JiraRestConnection.initialize - JIRA Permissions incorrect for Modify Reporter
 INFO : JiraRestConnection.disconnect - Disconnected from JIRA

Determine how to handle Closed issues in JIRA

By default, JIRA does not allow an issue (bug) with a status of Closed, to be updated. When an issue is first copied from JIRA to Rally (the COPY_JIRA_TO_RALLY service), the connector needs to record the ObjectID of the newly created Rally defect into the RallyID custom field of the originating JIRA issue. However, if the issue is closed, the update will fail and the RallyID custom field in JIRA will remain empty on that issue. 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. There are at least two ways to handle this:

  • Ignore closed JIRA issues:

    Adding a <CopySelector> tag in your configuration file within the <JiraRestConnection> section will prevent the connector from trying to copy closed JIRA issues to Rally. For example:

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

  • Change the configuration in JIRA:

    Configure JIRA to allow for the updating of Closed issues. Follow the Atlassian instructions allow editing of closed issues to enable the modification of closed issues in JIRA.

Create an External ID field in JIRA

In the JIRA system, you must create a custom field 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 up to 14 digits in length.

You may need to contact your JIRA administrator to perform the following steps (created using a JIRA 6.2-OD-03 instance):

  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 in the upper-right of the screen.
  3. On the Select a Field Type page, select Standard in the left pane, then select Number Field in the right pane.
  4. Click Next.
  5. On the Configure Number Field page:
    1. Enter RallyID for the Name.
    2. Enter Must default to -1" for the Description.
    3. Click Create.
  6. On the Associate field RallyID to screens page, select ALL of the available screens. Typically, there are at least 3 (Default Screen, Resolve Issue Screen, and Workflow Screen), but there may be more.
  7. Click Update.

    The Custom Fields page should display with your newly created custom field displayed in the list.


  8. Under the gear icon to the right of your new custom field name, select Configure.
  9. On the Configure Custom Field: RallyID page, click Edit Configuration.
  10. On the Modify configuration scheme context page:
    1. In the Choose applicable issue types section, select Any issue type (or a specific, top-level issue such as sub-task, technical task, bug, epic, improvement, new feature, story, task, and so on)
    2. In the Choose applicable context section, select Global context (or choose a specific project after selecting Apply to issues under selected projects).
    3. Click Modify at the bottom of screen.
  11. On the Configure Custom Field: RallyID page, click Edit Default Value.
  12. On the Set Custom Field Defaults page, enter -1 in the box next to RallyID, then click Set Default.

Create a CrosslinkUrlField in JIRA

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

  • We suggest a field name of RallyLink or RallyURL
  • Must be a URL Field or Free Text type of field
  • This field name will be used in the <CrosslinkUrlField> element within the <JiraRestConnection> section of the configuration file

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 (the value of the <User> element in the <JiraRestConnection> section of the configuration file) 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 use 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 the Start Progress transition. Under the Only assignee can execute this transition, click Delete.
  4. Repeat step 3 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.

Rally setup

Rally accesses fields from their Display Name, not their Name. Spaces and underscores are removed, for example, Example Field becomes ExampleField.

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. In the sidebar, click Fields and ensure the Work Item Type selected is Defect or User Story (whichever 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 a CrosslinkUrlField in Rally

It can be useful to have a clickable link in the Rally artifact which will open the corresponding JIRA issue in a browser window. 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 clickable link (URL). Use the same sort of process in Rally as you used for the JIRAKey field above.

  • The first character of the field name must be upper case
  • It is helpful to make the Name and Display Name identical
  • We suggest a field name of JIRALink
  • The field type must be String or Text (not Web Link)
  • This field name will be used in the <CrosslinkUrlField> element within the <RallyConnection> section of the configuration file

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. Select the workspace that you wish to map to JIRA. This will take you to the workspace's detail page.
  4. From the sidebar, click Fields and ensure the Work Item Type selected is Defect (or whichever 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. Go to Setup → Workspaces & Projects.
  3. Select the workspace that you wish to map to JIRA. This will take you to the workspace's detail page.
  4. From the sidebar, click Fields and ensure the Work Item Type selected is Defect or User Story (whichever work item you are mapping).
  5. Note: By default, only defects have State and Resolution fields. If you want to use these fields with user stories, you must create custom fields for that work item type.

  6. Find the Resolution field and click its edit icon at the far right.
  7. Edit the list of resolutions to make them match the corresponding list in JIRA.
  8. Click Save & Close.

You can edit the list of resolutions in JIRA 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.

Connector configuration

There are two approaches to creating the configuration file for the Jira Connector:

  1. Use the Rally Integration Configurator to generate the file with basic settings and mappings, then edit the file manually as needed.
    • Follow the Rally Integrations Configurator instructions.
    • Edit the generated file according to the syntax details below.
  2. Create the file manually
    • Create the file manually according to the syntax details below.

Configuration file syntax

Each major section is surrounded by a tag to delineate that section:

  • RallyConnection
    Defines the connection information for Rally, including Rally URL, user, password, and so on.
  • JiraRestConnection
    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.
Beginning with version 3.0.0 of the JiraRestConnector, all JIRA fields mentioned in the configuration file (such as jira-rest_config.xml) must be in terms of the JIRA display name, identical to what is shown in the JIRA GUI on the issue create, edit, and resolution panels.

Edit the configuration file

A sample configuration file, jira-rest_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-rest_config.xml in case you need to reference a valid configuration file later.

Edit jira-rest_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>

    <JiraRestConnection>
        <Url>http://jiraserver:port</Url>
        <User>jirauser</User>
        <Password>jirapassword</Password>
        <ProxyURL>proxy_host:port</ProxyURL>
        <ProxyUser>proxy_user_name</ProxyUser>
        <ProxyPassword>proxy_password</ProxyPassword>
        <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>
    </JiraRestConnection>

    <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, ensure that you can connect to JIRA and Rally in a test environment. Once you validate this is set up 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, the following setup defines a mapping between the Rally fields Name, Description, and Priority, to the Headline, Description, and Priority fields in the other system (respectively). On a create or update, the connector will only work with fields specified in this <FieldMapping> section.

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

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 or updated between the two systems and you may see an error in the log file. For example, the connector will post an error for a particular work item if you try to send a string to a custom field of type integer in Rally.

If you are mapping a drop-down value field, the connector assumes the drop-down values match. Otherwise, the connector will generate an error that the value was not found in the list. If your drop-down values are different between the two systems, see Map Drop-Down Values.

Other multiple value fields

JIRA has several fields that can have multiple values that are not as restrictive as State or Resolution fields. Affects Versions, Fix Versions and Components fields in JIRA can be bidirectionally mapped with Rally fields, as long as enumfieldhandler is used to handle disparate values (see Field Directionality). 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.

Field handlers

Map drop-down values
Map user names
Map reference fields from Rally

Multiple configuration files

If you want to do any of the following, setting up multiple configuration files may be a good idea:

  • Map to more than one workspace in Rally
  • Map multiple artifact types
  • Map to multiple containers (such as domains or projects in Quality Center or ClearQuest databases) in the other system

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

For Windows:
    rally2_jira-rest_connector.exe  config_workspaceA.xml  config_workspaceB.xml

For Linux:
    rally2_jira-rest_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-rest_connector.exe  config_workspaceA.xml  config_workspaceB.xml  15

For Linux:
    rally2_jira-rest_connector.rb  config_workspaceA.xml  config_workspaceB.xml  15

XML tags

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://). 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 or update work items in Rally. user@company.com
<Password>
Required
Password for user to make the Web Services requests to create or 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 and 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 or 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. JiraID
<SuppressDeprecationWarning /> Changes the WARN message about Rally WSAPI version deprecation in the logfile to an INFO message.  
<CrosslinkUrlField> Rally custom field (of type string) 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 ANDed 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 ANDed together.
<UpdateSelector>Release != alpha</UpdateSelector>
<FieldDefaults>
   <Field>
      <Name>F1</Name>
      <Default>V1</Default>
   </Field>
   [....]
</FieldDefaults>
Used when the destination system has a required field, but the field is not going to be mapped in the configuration file. This will cause field F1 to be set to value of V1. See more information Map Required Fields.
</RallyConnection>
Required
Closing parent tag for this section.  

Tip: Avoid 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 <JiraRestConnection> section:

Tag Name Description Sample Values
     
<JiraRestConnection>
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
The JIRA username
(must have permissions for the following operations: Browse Projects, Create Issues, Edit Issues, Schedule Issues, Assign Issues, Assignable User, Resolve Issues, Close Issues, Modify Reporter, Add Comments, Create Attachments. In most cases, a JIRA user in the jira-developers group has these permissions).
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
<ProxyURL> JIRA field if using a proxy. proxy_host:port
<ProxyUser> JIRA field that may be used depending on the setup of the proxy authentication. proxy_user_name
<ProxyPassword> JIRA field that may be used depending on the setup of the proxy authentication. proxy_password
<ArtifactType>
Required
JIRA issue type for the issues you want to create or update in JIRA. Bug, Task, Initiative, Defect, User Story, ...
<IDField> JIRA field used to store the unique ID of an issue, defaults to key. The ID field can also be used as the value for this tag. Using the value of ID ensures that the connector can locate an issue even if the project for the issue is changed. When an issue is moved to another project in JIRA the key value will change but the ID value does not. key
<ExternalIDField>
Required
JIRA custom field (Number Field type) that stores the unique ID for a Rally work item. For more information, refer to Create an External ID field in JIRA. RallyID
<ExternalEndUserIDField> A custom field in JIRA of type "Text Field (single line)" which will be used to store the FormattedID of the Rally work item (such as DExx). RallyFormattedID
<CrosslinkUrlField> JIRA custom field (URL Field or Free Text types) 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 ANDed 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 ANDed together.
<UpdateSelector>Release != alpha</UpdateSelector>
<WorkflowFile>
   filename
</WorkflowFile>
The relative pathname, from the current working directory, to the workflow XML file. See Configure JIRA workflow and Configure a custom workflow. ../../JIRA/jira_workflow.xml
<FieldDefaults>
   <Field>
      <Name>F1</Name>
      <Default>V1</Default>
   </Field>
   [....]
</FieldDefaults>
Used when the destination system has a required field, but the field is not going to be mapped in the configuration file. This will cause field F1 to be set to value of V1. See more information in Map Required Fields.
<OpenTimeout>
   seconds
</OpenTimeout>
Maximum time in seconds for which the connector will wait in an attempt to open a connection to the JIRA server. Maximum value permitted is 999. 180, 60
<ReadTimeout>
   seconds
</ReadTimeout>
Maximum time in seconds for which the connector will wait to receive a read block of information from the JIRA server. Maximum value permitted is 999. 60, 180
</JiraRestConnection>
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
</FieldMapping>

Used to specify what fields are to be mapped between the two systems.

See Field Mapping.
<RallyFieldHandlers> (opening tag)  
   <RallyConcatFieldHandler>
      <FieldName>
         Dest-fieldname
      </FieldName>
      <ConcatFields>
         <Field>Src-fieldname1</Field>
         <Field>Src-fieldname2</Field>
         <Field>.....</Field>
      </ConcatFields>
   </RallyConcatFieldHandler>
Using the contents of Dest-fieldname as the initial string, appends each additional Src-fieldnameN to Dest-fieldname, using HTML break tags (<br />) to separate each additional field value.

Some custom field


Description
some other field
.....
   <RallyDateTimeFieldHandler>
      <FieldName>F1</FieldName>
      <DateTimeFormat>S1</...>
   </RallyDateTimeFieldHandler>
Bi-directional.
Rally to Other: Convert the Rally ISO date in field F1 into a date string formatted as specified by the string S1 (as per Ruby's DateTime.strftime function) and store this new date string into the field F1 is mapped to.

CreationDate (being mapped to Due Date)
%Y-%m-%d
   <RallyEnumFieldHandler>
      ....
   </RallyEnumFieldHandler>
Allows for the mapping of non-alike, drop-down values between the two systems. See Map Drop-Down Values.
   <RallyReferenceFieldHandler>
      <FieldName>
         name-of-field
      </FieldName>
      <ReferencedFieldLookupID>
         name-of-field
      </ReferencedFieldLookupID>
   </RallyReferenceFieldHandler>
Used to map a field from an object.

User,Owner,Tester


Name,FormattedID
   <RallyCSVUserMappingFieldHandler>
      <FieldName>
         name-of-field
      </FieldName>
      <FileName>
         name-of-file
      </FileName>
   </RallyCSVUserMappingFieldHandler>
Specifies the name of a field being mapped (name-of-field) and a CSV file where user mappings are stored (name-of-file). The CSV file is used to lookup and transform usernames based on the mappings specified within. See a more detailed explanation on the FAQ page or an example XML file.

SubmittedBy


MyUserMappings.csv
   <RallyKeyword2TagFieldHandler>
      <Type>
         type-value
      </Type>
      <Delimiter>
         some-character
      </Delimiter>
   </RallyKeyword2TagFieldHandler>
Specifies the mapping of Rally Tags to JIRA labels. See example configuration file at JIRArest-Labels-to-Tags.pxml.

string


,
</RallyFieldHandlers> (closing tag)  
<OtherFieldHandlers> (opening tag)  
   <OtherEnumFieldHandler>
      ....
   <OtherEnumFieldHandler>
Allows a user to map non-alike, drop-down values between the two systems. See Map Drop-Down Values.
   <OtherConditionalEnumFieldHandler>
      ....
   </OtherConditionalEnumFieldHandler>
Very similar to the <OtherEnumFieldHandler> except with this one only the exceptions need to be declared. Corresponding entries in the pull-down lists of both system which are identical, need not be declared.  
   <OtherConcatFieldHandler>
      <FieldName>
         Dest-field
      </FieldName>
      <ConcatFields>
         <Field>Src-field1</Field>
         <Field>Src-field2</Field>
         <Field>.....</Field>
      </ConcatFields>
   </OtherConcatFieldHandler>
Using the contents of Dest-field as the initial string, appends each additional Src-fieldN to Dest-field, using HTML break tags (<br />) to separate each additional field value.

Some custom field


Description
Some other custom field
.....
   <JiraNewlineFieldHandler>
      <FieldName>
         Description
      </FieldName>
   </JiraNewlineFieldHandler>
Used to declare the JIRA 'Description' field is to be processed, having newlines converted. Currently, only the 'Description' field is supported.
   <JiraUserToEmailFieldHandler>
      <FieldName>
         name-of-field
      </FieldName>
   </JiraUserToEmailFieldHandler>


Used to declare the JIRA field to be used for finding an email address. See example below.
(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 synced with JIRA comments, they should never be modified in JIRA. It will cause a recursive copy, back-and-forth between the two systems, with the discussions and comments growing with each iteration. This occurs because the connector compares the two sets of discussions and comments. 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. At that point the discussions and comments between the two system will be out of sync again, and this loop will continue indefinitely. See Jira-config-RallyJiraCommentLinker.pxml for an 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 or 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, Warning, Info, Debug
<Services>
Required

Use the copy services to initially reflect items between systems, then use the update services to keep those reflected items up to date.

The alternative update service searches Rally first for updates and pushes only the recently changed fields to the other system. It then searches the other system for updates and pushes all mapped fields into Rally. This allows changes done in both systems to not cause overwrites of old data.

Copy services:

COPY_JIRA_TO_RALLY
COPY_RALLY_TO_JIRA

Update services:

UPDATE_JIRA_TO_RALLY
UPDATE_RALLY_TO_JIRA

Alternative update service:

UPDATE_RALLYFIELDS_AND_OTHER (may not be used in conjunction with the other update services)

See FAQ for more information.

The Emailer feature with NO Authorization: <Emailer>
   <LogLevel>value</LogLevel>
   <SendEmailFrom>value</SendEmailFrom>
   <SendEmailTo>value</SendEmailTo>
   <SMTPServer>value</SMTPServer>
   <SMTPPort>value</SMTPPort>
</Emailer>

Opening tag for this feature.
(see note below)
Which logfile messages to email.



Closing tag for this feature.

See example.
Error or Warning
monitor@acme.com
monitor@acme.com
smtp.acme.com
587
The Emailer feature with Authorization:
<Emailer>
   <LogLevel>value</LogLevel>
   <SendEmailFrom>value</SendEmailFrom>
   <SendEmailTo>value</SendEmailTo>
   <SMTPServer>value</SMTPServer>
   <SMTPPort>value</SMTPPort>
   <SMTPDomain>value</SMTPDomain>
   <SMTPUser>value</SMTPUser>
   <SMTPPassword>value</SMTPPassword>
   <SMTPSec>value</SMTPSec>
</Emailer>

Opening tag for this feature.
(see note below)
Which logfile messages to email.







Closing tag for this feature.

See example.
Error or Warning
monitor@acme.com
monitor@acme.com
smtp.acme.com
587
Domain.com
Username@Domain.com
Password
tls or ssl
Note on the above <Emailer> feature: Versions of the connector prior to 3.2.0 used the sub-tag <Level> instead of <LogLevel> in the Emailer block. While we recommend against it, you can still use the <Level> sub-tag but you must invoke the connector with the --run-on-validation-failure or -r flag in order for the connector to work. We recommend that you update your configuration file to use the <LogLevel> to gain the benefit of running the XML configuration file validation.
</ConnectorRunner>
Required
Closing parent tag for this section.  

Run the connector

The connector accepts these command-line flags:

$ rally2_jira-rest_connector.rb  -h
Usage: rally2_jira-rest_connector.rb <options> <config_filename> <interval_in_minutes>

where <options> are:
                           --version, -v:   Prints the revision number of the connector.
                          --precheck, -p:   Precheck, the connector will run in preview mode.
         --run-on-validation-failure, -r:   Will ignore results of XSD Schema validation and run connector.
                 --log-file-size, -s <n>:   Set the size limit for a log file to <n> megabytes.
                 --max-log-files, -m <n>:   Set the maximum number of log files in log file rotation to <n>.
                              --help, -h:   Print this Usage message.

where <config_filename>
  File system reference to an XML file specifying the connector configuration.  Usual extension is '.xml'.

where <interval_in_minutes>
  The interval, in minutes, for which the connector will run after executing command the first time.
  -1 will only run the connector once and will exit afterwards.

Once the jira-rest_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-rest_connector.exe  jira-rest_config.xml  -1

For Linux:
    rally2_jira-rest_connector.rb  jira-rest_config.xml  -1

The -1 (interval value in the examples above specify to run the connector to process each service named in the <Connector><Services> once and then exit.

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-rest_connector.exe  jira-rest_config.xml  10

For Linux:
    rally2_jira-rest_connector.rb  jira-rest_config.xml  10

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

Modify the logging parameters

The connector logs messages as it is processing into a file named rallylog.log in the current working directory. By default, the maximum size of a log file is 5 MB and the log rotation is limited to 10 files. You can adjust the maximum size of the log file and adjust the maximum count of log files in the log rotation by specifying command line arguments as follows:

The -s <integer> option pair can be used to specify the maximum size of the log file in MB increments (up to 100 MB). This can also be expressed as log-file-size <integer>.

The -m <integer> option pair can be used to specify the maximum number of files in the log file rotation scheme. This can also be expressed as --max-log-files <integer>.

Example: To set the log file max size to 50 MB and the maximum log file rotation count to 20 files for a single invocation of the connector:

rally2_jira_connector.rb -s 50 -m 20 xxx_config.xml -1

OR

rally2_jira_connector.rb --log-file-size 50 --max-log-files 20 xxx_config.xml -1

Configure 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, and updates its Rally 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 Issue and Start Progress transitions to get to the desired status.

 

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.
    1. In JIRA, click on the Administrator tab and select Workflows under the Global Settings section in the navigation pane on the left.
    2. 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.

    3. 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 in Set Up Rally States and Resolutions.


  3. Create <Step> blocks for each state/status.

    In a new file, create the beginning and ending XML tags:

    <Workflow>
    </Workflow>

    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> 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> 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 JiraStatusName value of the enclosing <Step> block

    Continuing with this example, to get from status Open to status Reopened, you 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>

    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 you to fill in a field in order to complete the action, you should mimic that process by providing the fields and values here.

Best practices

Use the <JiraUserToEmailFieldHandler>

Here is an example:

      <Config>
      ....
      <Connector>
        <FieldMapping>
          <Field>
            <Rally>Name</Rally>
            <Other>Summary</Other>
          </Field>
          <Field>
            <Rally>Owner</Rally>
            <Other>Reporter</Other>
          </Field>
          .... </FieldMapping>
        <OtherFieldHandlers>
          <JiraUserToEmailFieldHandler>
            <FieldName>Reporter</FieldName>
          </JiraUserToEmailFieldHandler>
        </OtherFieldHandlers>
      </Connector>
      ....
     

Mapping

  • Map the JIRA Sprint field

    You can map the this field, but due to limitations in Atlassian's JIRA REST API implementation, the connector can only support the mapping in the JIRA-to-Rally direction. Also, note that the value which displays in the target Rally field will be the JIRA Sprint field ID value, not the JIRA Sprint field label value. In the future, if Atlassian adjusts their REST API for JIRA to offer support for setting and updating JIRA Sprint field values correctly under most conditions, bidirectional support for the Sprint field should be possible.

    An example specifying the supported directionality for the Sprint field:

    <Config>
            ....
            <Connector>
                    <FieldMapping>
                            ....
                            <Field>
                                    <Rally>Iteration</Rally>
                                    <Other>Sprint</Other>
                                    <Direction>TO_RALLY</Direction>
                            </Field>
                            ....
                    </FieldMapping>
  • Map 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.

  • Note: RallyReferenceFieldHandlers are for the most part deprecated. Prior to the 4.4.2 release, if multiple projects were specified in the config file Release or Iteration value was sometimes mapped incorrectly. By relocating some logic, that issue has been addressed as well as being able to handle the most common Rally Reference fields (Project, Release, Iteration) automatically without needing explicit notation in the configuration file. If the connector detects that are using a RallyReferenceFieldHandler for one of those aforementioned fields, the connector will emit a deprecation warning message into the log file and will not register the field handler as that logic is now handled automatically. The are some edge cases where the use of RallyReferenceFieldHandler may be necessary, for fields such as Parent, Child, WorkProject, Owner and other similar fields.

Known limitations of the JIRA connector

  • LDAP not supported
    The JIRA connector does not support LDAP.
  • Artifact hierarchy
    Artifact hierarchy is not maintained when copying/updating artifacts between Rally and JIRA.

Troubleshoot the connector

  • 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.


  • 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.


  • Custom field precaution (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. This field is often referred to as the ExternalID. Precautions:

    • This custom field must be defined as a type Number Field (not a string) and must be defined with a default value of -1 (minus 1).
    • Old JIRA items that existed before this custom field was created will not have the default value of -1 (as required), but instead it will be NULL. Because of this, the JIRA query (performed by the connector) 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 change operation in JIRA (typically found under Tools → Bulk Change after doing a search and filter) to set the value of the ExternalID custom field to a -1 for items whose current value is NULL.

  • Custom field precaution (general)

    When defining a JIRA custom field (for example, to receive some field from Rally), the valid screens must be declared during this process. It is best to select ALL screens for the field.

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

    ERROR : JiraRestConnection.initialize - Unrecognized field Severity, cannot continue
  • Unrecognized field

    When copying an artifact from Rally to JIRA, the following sample error can occur if:

    • A non-mapped field (such as a custom field like RallyLink or RallyFormattedID) is required, but not defined
    • The custom field exists, but it is not visible to the specified <Project>
      INFO : RallyConnection.find_new -   Found 1 new defects in Rally
      INFO : Connector.copy_to_other - Copy DE442 to JIRA
     DEBUG : Connector.block in map_fields_to_other -   Mapping Name(Test) - to - Summary(Test)
            ....
      WARN : JiraRestConnection.initialize - Unable to create new JIRA Bug,
                    Unrecognized field |RallyField|,
                    unable to accurately realize postable data for this field in |create| mode
            ....
       ANY : ConnectorRunner.process_service - Finished Service COPY_RALLY_TO_JIRA

  • Field not found

    When copying an artifact from Jira to Rally, the following sample error can occur if:

    • A mapped field (such as a custom field) is not visible on all screens
    DEBUG : RallyEIF::WRK::Connector.block in validate - RallyConnection field_mapping target "TestDateDeployment" existence validated
    ERROR : RallyEIF::WRK::Connector.block in validate - FieldMapping: Other field "CustomDate Deploy" not found
    ERROR : RallyEIF::WRK::ConnectorRunner.initialize - Invalid Configuration

  • Mismatched external identifier

    This error can occur whenever artifacts are cloned or duplicated in either Rally or JIRA. If the artifact has already been copied to the other system, then the <ExternalIDField> has been given a value. When an artifact is cloned, the value in this field is carried to the new artifact. And then there will be two artifacts with the same value in this field.

    This error also can occur when two different XML tags are incorrectly using the same custom field name (JiraID in the following example):

    <Config>
            <RallyConnection>
                    <Url>rally1.rallydev.com</Url>
                    .....
                    <ExternalIDField>JiraID</ExternalIDField>
                    <CrosslinkUrlField>JiraID</CrosslinkUrlField>
            </RallyConnection>
            .....
    The error message returned was:
     DEBUG : RallyJest::JiraProxy.makeAnIssueInstance - Attempting to obtain a JiraIssue instance for RIT-37
     DEBUG : RallyJest::JiraProxy.makeAnIssueInstance - Obtained JiraIssue for RIT-37
      WARN : Connector.update_other - JIRA Bug RIT-37 matched to Rally defect DE27 has mismatched external identifier in Rally item
       ANY : ConnectorRunner.process_service - Finished Service UPDATE_RALLY_TO_JIRA
  • SOAP errors returned by the connector

    When using a version of the JIRA connector prior version 3.2.0, running against a version of JIRA which is 5.2 (or greater), it is quite common to see SOAP errors. This typically happens because the JIRA interface is now REST as opposed to SOAP. The newest version of the Rally-JIRA connector supports this new REST interface. A SOAP error returned by the connector might look as follows:

       ANY : ConnectorRunner.process_service - Starting Service COPY_JIRA_TO_RALLY
      INFO : JiraConnection.find_new - find_new query: type=1 and project = "P1" and RallyID = -1 and Status != Open
     DEBUG : Finding method getIssuesFromJqlSearch
     ERROR : JiraConnection.rescue in find_new - Trying to find_new via query: 'type=1 and project = "P1" and RallyID = -1 and Status != Open' resulted in SOAP::EmptyResponseError
     ERROR : JiraConnection.initialize - SOAP::EmptyResponseError
     ERROR : ConnectorRunner.exception - Message SOAP::EmptyResponseError
     ERROR : ConnectorRunner.exception - Stack Trace
    ....
  • Rally is not populated with JIRA artifact's URL

    When creating a clickable link in the Rally artifact (back to the JIRA artifact), if the custom field in Rally is not be completed, en sure the Type on the custom field is string or text, and not web link (see Create a CrosslinkUrlField in Rally).

  • Changesets do not display in Rally

    Verify your workspace administrator has selected the Enable Build and Changeset option on the Edit Workspace detail page and verify there are no unexpected messages in the Rally_Connector_Error.log file. No errors are written to the console.

  • Contact Rally Support

    Log in to the Rally Success Community for support of this and all of our connectors. The Rally Success Community is your one stop shop for self service and support.

Revision history

  • 4.5.3-master-148 --- 07-Mar-2015
    • Enhancements:
      • Updated to use Rally WSAPI v2.0.
      • Added a RallyBooleanFieldHandler.
      • Updated faraday gem to 0.9.0.
    • Fixes:
      • Fixed issue in YetiEmailer where header item had leading spaces not accepted by some email servers.
  • 4.4.13-maintenance-92 --- 22-Jan-2015 
    • Enhancements:
      • Support added for a RallyReferenceAttributeLookupFieldHandler intended to be used primarily with Release and Iteration fields where the attribute used for the lookup is other than the 'Name'.
      • This release is likely to be the last for the 4.4.x line that uses Rally WSAPI 1.43.
  • 4.4.12-maintenance-88 --- 02-Dec-2014
    • Fixes:
      • Corrects an issue with copying attachments to Rally ALM.
  • 4.4.11-maintenance-86 --- 18-Nov-2014
    • Fixes:
      • Fixed incorrect Rally/JIRA comment comparison problem from JIRA 6.0 to 6.4 behavior change that caused comments to be copied multiple times.
      • Fixed defect of not recognizing standard JIRA system date field (CreatedDate) in a CopySelector entry.
      • Fixed defect of retrieving only up to 50 users for each starting letter, now has a max of 1000 items per first letter of user name.
      • Fixed packaging defect for Linux/Mac builds where multiple versions per gem may have been included (although gemspec prevented use of non-specified versions).
  • 4.4.10-master-140 --- 16-Oct-2014
    • Enhancements:
      • Modified rallyeif-wrk core dependency on rally_api to 1.1.2 (that depends on httpclient 2.4.0) to address SSLv3 security issue.
      • Added support for command line arguments to specify log file max size and file count.
      • Added configurable communication timeouts for JIRA.
      • Added better formatting for JIRA field schema output in debug mode.
  • 4.4.4-master-132 --- 18-Sep-2014
    • Enhancements:
      • Improved semantic comparison of Rally boolean values to strings ('true' / 'false') should result in fewer unnecessary updates
      • Improved semantic comparison of Rally decimal values to integers/strings (1.0 should equal 1 or "1") should result in fewer unnecessary updates.
      • Improved comparison of Rally User to user identifier from JIRA should result in fewer unnecessary updates.
  • 4.4.3-master-131 --- 29-Aug-2014
    • Enhancements:
      • Modifications to make parsing RevisionHistory Revision records more robust, especially the Notes field.
  • 4.4.2-master-128 --- 07-Jul-2014
    • Enhancements/Fixes:
      • Common Rally Reference fields (Project, Release, Iteration) no longer need to have a RallyReferenceFieldHandler configured in the Connector - RallyFieldHandlers section of the config file.
      • Mapping of Rally Reference fields such as Release and Iteration is fully project scoped to ensure that if the DisplayName of multiple Release items is identical, the artifact contains the link to the item associated with the Project setting in the artifact.
  • 4.3.0-master-89 --- 15-Jan-2014
    • Enhancements/Fixes:
      • Upgrade from Ruby 1.9.2-p290 to Ruby 2.0.0-p247
      • Performance improvement gained by using rally_api rather than rally_rest_api
      • Added more build tests
      • Added <SuppressDeprecationWarning> XML tag
      • Connector could not successfully map CreationDate to Due Date (DE18781)
      • Connector did not complain when it could not link a Bug to a Defect already copied to Rally (DE17873)
      • Connector would validate only the first config file on command line (DE17492)
      • Upgrade to version 1.42 of the WSAPI
      • Note: For the 4.3.0 version of this connector, any custom code (such as a custom field handler) will require modifications. A working example (using the QC connector) can be found here.

        Previous method for doing requires:
        require 'yeti/field_handlers/other_field_handler'
        require 'rexml/document'

        class MyCustomFieldHandler < ....FieldHandler
          ....
        end
        New way of doing requires:
        require 'rallyeif/wrk/field_handlers/field_handler'

        module RallyEIF
          module WRK
            module FieldHandlers

              class MyCustomFieldHandler < ....FieldHandler
                # See example code in installation directory:
                # ./field_handlers/my_custom_field_handler.rb
              end
            end
          end
        end
  • 3.3.1-master-1012 --- 23-Aug-2013
    • Enhancements/Fixes:
      • Allow updating of Closed issues in JIRA with Changed setting. Caveat: If the JIRA Change is not made, the connector will crash out and stop the services
      • Updated version numbers
      • Rewrote version output method
      • Now uses Ruby's time for current time rather then the JIRA server time
      • Version information is printed stdout (by -v) as well as rallylog.log
      • Fixed: Only first configuration file on command line was validated
      • Several small improvements in error messaging
  • 3.2.0-master-1002 --- 31-May-2013
    • Enhancements/Fixes:
      • Updated rally_api gem to 0.9.14
      • Updated faraday gem to 0.8.7
      • Updated rally_jest.gem to 1.1.10
      • Added support for communicating with JIRA through a Proxy with settings in the JiraRestConnection section of the config file
      • Changed Emailer sub-tag of Level to LogLevel
      • Dropped support for JiraHtmlFieldHandler for Description field
      • Versions 3.2.0 and greater are compatible with JIRA 5.2 or greater.
  • 3.0.1-48 --- 03-Apr-2013
    • Enhancements/Fixes:
      • Added install.sh to ease installation and ensure gem installation sequence
      • Check for appropriate version of JIRA (must be 5.2 or better)
      • Rewrite of the existing JIRA connector to use the JIRA 5 REST API
      • Updated rally_api gem to 0.7.6
      • Introduced faraday gem 0.8.4
      • Dropped requirement of jira4r and soap4r gems
      • Field names for JIRA specified in the config file must use JIRA Display Name format
      • Dropped requirement to use <JiraCollectionFieldHandler> for JIRA Affects Versions, Fix Versions and Components fields
      • Affects Versions, Fix Versions and Components fields in JIRA can be bidirectionally mapped with Rally fields
      • JIRA connection section in configuration file is now called <JiraRestConnection> instead of <JiraConnection>
    • Known issues/limitations:
      • Versions 3.0.0 and greater are not compatible with JIRA 4.x
English

Feedback

Need more help? The Rally Success Community is your one-stop shop for self-service and support. To submit feedback or cases to Rally Support, find answers, and collaborate with others, please join us at rallydev.force.com/answers.
© 2015 Rally Software Development Corp | Legal