CA Agile Central Connector for JIRA Installation & User Guide

The CA Agile Central JIRA connector can synchronize JIRA bugs with CA Agile Central 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 CA Agile Central connector for JIRA allows customers to use CA Agile Central for Agile lifecycle management while still using JIRA for defect management. The connector provides synchronization capability between JIRA and CA Agile Central through four services, described below.

The CA Agile Central 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 CA Agile Central 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 CA Agile Central 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 CA Agile Central and JIRA:

  • Copy issues created in JIRA to CA Agile Central work items
  • Copy work items created in CA Agile Central to JIRA issues
  • Update CA Agile Central work items based on changes made to JIRA issues
  • Update JIRA issues based on changes made to CA Agile Central work items
  • Update CA Agile Central 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 CA Agile Central 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 CA Agile Central system.

This reduces the chances of data overwrites. The only scenario where an overwrite might occur is if a change is made in CA Agile Central and a change is made in JIRA (in reference to two artifacts previously associated together). In this scenario, first any mapped field in CA Agile Central, 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 CA Agile Central.

This installation and user guide includes:

The CA Agile Central 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 CA Agile Central defect work item type to JIRA bug and CA Agile Central user story work item type to the other JIRA top-level issue types.

It is important to recognize that the data models of CA Agile Central 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 CA Agile Central 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_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 CA Agile Central work item type if your scenario differs from the one presented here.

Connector download

To download the connector, follow the steps here.

Basic installation steps

  1. Install the connector (run the installer or extract the zip).
  2. Make configuration changes in CA Agile Central and in JIRA.
  3. Edit the jira_config.xml to reflect your environment.
  4. Run ca_agile_central2_jira_connector to start the connector.

System setup

  • The following people will be involved in getting fields set up in both CA Agile Central and JIRA:
    • A JIRA administrator user who can create a custom field on JIRA issue types.
    • A CA Agile Central administrator user who can create a custom field on the CA Agile Central artifact you want to synchronize with JIRA.
  • Consider the process you want to set up between CA Agile Central 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 CA Agile Central workspace and project to use for testing.
  • Decide on which computer the connector will run.

The CA Agile Central 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 CA Agile Central connector for JIRA:

  • A CA Agile Central 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 CA Agile Central'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>
                      ....

Install the connector

Pre-installation checklist

  • Access to a test environment installation of JIRA
  • CA Agile Central 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 CA Agile Central 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 CA Agile Central, 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.

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_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
  • ca_agile_central2_jira_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 CAAgileCentralConnectorforJira-Ruby-4.x.y-master-z
  3. Run the installation shell script:
    ./install.sh
    Sample output for revision 4.7.0­master­173 on a MAC:
    $ ./install.sh
    installing gem: ./rallyeif-wrk-1.1.7.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.6.0.1.gem (100%)
    Successfully installed httpclient-2.6.0.1
    Fetching: rally_api-1.2.1.gem (100%)
    Successfully installed rally_api-1.2.1
    Successfully installed rallyeif-wrk-1.1.7
    5 gems installed
    installing gem: ./rally_jest-1.4.3.gem
    Fetching: multipart-post-2.0.0.gem (100%)
    Successfully installed multipart-post-2.0.0
    Fetching: faraday-0.9.0.gem (100%)
    Successfully installed faraday-0.9.0
    Successfully installed rally_jest-1.4.3
    3 gems installed
    installing gem: ./rallyeif-jira-4.7.0.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.7.0
    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 : JiraConnection.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 : JiraConnection.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 : JiraConnection.initialize - JIRA Permissions incorrect for Modify Reporter
 INFO : JiraConnection.disconnect - Disconnected from JIRA

Determine how to handle closed issues in JIRA when using restrictive flow

By default, JIRA 6 does not allow an issue (bug) with a status of Closed, to be updated. When an issue is first copied from JIRA to CA Agile Central (the COPY_JIRA_TO_RALLY service), the connector needs to record the ObjectID of the newly created CA Agile Central 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 CA Agile Central), 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 <JiraConnection> section will prevent the connector from trying to copy closed JIRA issues to CA Agile Central. For example:

    <Config>
            ....
            <JiraConnection>
                    <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.


  • By default, Jira 7 comes with simplified workflow that allows updating an issue (bug) in a final status to be updated. There is no need to use:
    <CopySelector>Status != Done</CopySelector>

Create an External ID field in JIRA

In the JIRA system, you must create a custom field which will be used to record the CA Agile Central Object ID (OID) of the corresponding CA Agile Central 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, or task)
    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 CA Agile Central 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 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 <JiraConnection> section of the configuration file

Configure JIRA Workflow to allow transitions to be executed by users other than assignees

For example, default (read­-only) JIRA 6 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 <JiraConnection> 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 CA Agile Central. You may see the following error message if you encounter this issue:

ERROR : RallyEIF::WRK::Connector.rescue in copy_to_other - Unable to create a JIRA Bug with these field values: {:Assignee=>"...", :Priority=>"High", :Reporter=>"...", :"Doc Enh Req"=>"No", :Summary=>"...", "RallyID"=>"99999999999", "RallyURL"=>"https://rally1.rallydev.com/slm/#/detail/defect/99999999999"}, undefined method `has_key?' for nil:NilClass

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.

CA Agile Central setup

CA Agile Central 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 CA Agile Central

The External ID custom field in CA Agile Central is used by the connector to record the key of the corresponding JIRA issue.

  1. Log into CA Agile Central 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 CA Agile Central, 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 CA Agile Central

It can be useful to have a clickable link in the CA Agile Central 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 CA Agile Central which will contain this clickable link (URL). Use the same sort of process in CA Agile Central 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 (not-clickable) or Text (clickable). Unfortunately, a field type of "Web Link" does not function properly at this time.
  • This field name will be used in the <CrosslinkUrlField> element within the <RallyConnection> section of the configuration file

Set up CA Agile Central 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 CA Agile Central work items

  1. Log into CA Agile Central 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 CA Agile Central 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 CA Agile Central 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 CA Agile Central Integration Configurator to generate the file with basic settings and mappings, then edit the file manually as needed.
    • Follow the CA Agile Central 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 CA Agile Central, including CA Agile Central URL, user and password or APIKey.
  • Jira Connection
    Defines the connection information for JIRA, including the JIRA URL, user, password, and artifact type.
  • As of the 4.7.x release of the JiraConnectorForAgileCentral, we have deprecated the use of the Rest modifier in JiraRestConnection and with the naming of the connector. Config files that currently use the tag will still work although the preferred tag is now <JiraConnection>. CA Agile Central will support the use of either tag through the life cycle of 4.7.x but the recognition of the <JiraRestConnection> tag will not be supported upon the release of the 4.8.x series.
  • Connector
    Defines the field mapping between the two systems. Generally, strings should be mapped to strings, and integers to integers. In JIRA, field names are generally specified with the first letter capitalized, such as Summary,or 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 JiraConnector, all JIRA fields mentioned in the configuration file (such as jira_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_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>
        <!-- You can use an APIKey in place of User and Password tags -->
        <!-- <APIKey>YourAPIKeyValueGoesHere...</APIKey>-->
        <ArtifactType>Defect</ArtifactType>
        <ExternalIDField>JiraKey</ExternalIDField>
    </RallyConnection>

    <JiraConnection>
        <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>
    </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, ensure that you can connect to JIRA and CA Agile Central 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 CA Agile Central 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 CA Agile Central.

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 CA Agile Central fields, as long as enumfieldhandler is used to handle disparate values (see Field Directionality). In the course of mapping from JIRA to CA Agile Central, if there are multiple values for the field, they will be copied to CA Agile Central (or updated in CA Agile Central) as a string of comma separated values.

Field handlers

Map drop-down values
Map user names
Map reference fields from CA Agile Central

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 CA Agile Central
  • 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 ca_agile_central2_jira_connector.rb script or ca_agile_central2_jira_connector.exe.

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

For Linux:
    ca_agile_central2_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:
    ca_agile_central2_jira_connector.exe  config_workspaceA.xml  config_workspaceB.xml  15

For Linux:
    ca_agile_central2_jira_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 CA Agile Central (excluding the HTTPS prefix, as the connector adds https://). sandbox.rallydev.com
rally1.rallydev.com
myRally.mydomain.com
192.168.23.24
<User>
Required if no APIKey specified
Login name for user to make the Web Services requests to create or update work items in CA Agile Central. user@company.com
<Password>
Required if no APIKey specified
Password for user to make the Web Services requests to create or update work items in CA Agile Central. Note: The first time the connector runs, it will encode the password so it is not saved in plain text. mypassword
<APIKey> CA Agile Central APIKey (from CA Agile Central Application Manager) for the account to be used to access CA Agile Central from the connector. If this is specified, you do not need to supply a username and password. You do not need to whitelist the user associated with the value of the APIKey used as a value. ABC123plmokn43315...
<WorkspaceName>
Required
Workspace in CA Agile Central you want to copy and update work items. My Workspace
MyWorkspace
<Projects>
Required
Contains a list of project tags. Each tag refers to one CA Agile Central project that will be used when finding new CA Agile Central work items to copy to the other system. For updating work items from CA Agile Central to the other system, all projects in <WorkspaceName> are considered. At least one CA Agile Central 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 CA Agile Central. (Defect, defect),
(Story, UserStory, HierarchicalRequirement), TestCase
<ExternalIDField>
Required
CA Agile Central 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 CA Agile Central WSAPI version deprecation in the logfile to an INFO message.  
<CrosslinkUrlField> CA Agile Central custom field of type string (not-clickable) or text (clickable) containing a hyperlink to the corresponding bug in JIRA. JIRALink
<CopySelectors>
   <CopySelector>
      expression
   </CopySelector>
   ....
</CopySelectors>
Criteria to use when finding new CA Agile Central issues to copy to JIRA. An individual expression has the form <field> <relation> <value>, where:
   <field> is the name of a CA Agile Central 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 CA Agile Central that should be updated to JIRA. An individual selector specification has the form <field> <relation> <value>, where
   <field> is the name of a CA Agile Central 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 CA Agile Central 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
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 CA Agile Central 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 CA Agile Central 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 CA Agile Central. RallyURL
<Project>
Required
Specify the JIRA Project Key name which contains the issues to be associated with CA Agile Central 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 CA Agile Central. 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 More Restrictive 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
</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
</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
   <RallyUserFieldHandler>
      <FieldName>
         name-of-object
      </FieldName>
      <ReferencedFieldLookupID>
         name-of-field
      </ReferencedFieldLookupID>
   </RallyUserFieldHandler>
Used to map usernames. See Map user names.

User,Owner,Tester


Name,FormattedID
   <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. Direction: Jira to Agile Central only. TestCase, Parent, TestCaseResult, WorkProduct, TestSet, TestFolder, Requirement

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


,
   <RallyBooleanFieldHandler>
      <FieldName>
         name-of-field
      </FieldName>
      <Mappings>
         <Field><Rally>false</Rally><Other>no</Other></Field>
         <Field><Rally>true</Rally><Other>yes</Other></Field>
      </Mappings>
   </RallyBooleanFieldHandler>
 
</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. This can be used to map the Jira Reporter email field or Jira Assignee email field to the CA Agile Central Owner field when sending information from Jira to CA Agile Central. 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 CA Agile Central (bi-directional). Can be used on any object which supports attachments (in CA Agile Central: tasks, defects, stories, and tests; in JIRA: any issue type with attachments).  
    <RallyJiraCommentLinker /> Used to copy discussions or comments between CA Agile Central and JIRA.
WARNING: There is a known limitation with this feature. Once CA Agile Central 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, CA Agile Central discussions are read-only (once they have been created), so an edited comment in JIRA is copied to CA Agile Central 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 CA Agile Central 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 CA Agile Central. 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.  

Copy and update selectors

In addition to standard copy and update selectors 4.7.0 version of the connector supports selectors that allow subset and range operators using "in", "!in" and "between", and "!between" operators respectively. "In" and "!in" operators are intended to select a subset of allowed values of dropdown fields, for example, Status in Jira or State in Agile Central. Here is an example of Copy and Update Selectors in a section of a config file that limit a copy and update service from HP ALM to AgileCentral to defects with BG_STATUS within a certain subset of allowed values:

<CopySelectors>
<CopySelector>Status in To Do, In Progress</CopySelector>
</CopySelectors> <UpdateSelectors>
<UpdateSelector>Status in To Do, In Progress</UpdateSelector> </UpdateSelectors>

In the example below, the defects are selected using "!in" operator. The returned subset is effectively the same as the subset of defects limited by "in" operator in the example above. Note that when using negation with dropdown fields that allow empty values like Priority, the subset of included work items will contain work items where this field is empty. If inclusion of those items is undesirable, "in" operator should be preferred. Empty field values are not supported by subset selectors.

<CopySelectors>
<CopySelector>Status !in In Review,Done</CopySelector>
</CopySelectors> <UpdateSelectors>
<UpdateSelector>Status !in In Review, Done</UpdateSelector> </UpdateSelectors>

"Between" and "!between" operators select work items where a specific field falls within a certain range, where both ends of the range are included. The range selectors are intended to work with date fields such as Created in Jira or CreationDate in AgileCentral. Here is an example of Copy and Update Selectors in a section of a config file that limit a copy and update service from AgileCentral to HP ALM to stories created within a certain date range:

<CopySelectors>
<CopySelector>CreationDate between 2016­07­05 and 2016­07­06</CopySelector>
</CopySelectors> <UpdateSelectors>
<UpdateSelector>CreationDate between 2016­07­05 and 2016­07­06</UpdateSelector> </UpdateSelectors>

A variation of the range selector that uses "!between" operator will select only stories that were created on either side of the date range:

<CopySelectors>
<CopySelector>CreationDate !between 2016­07­05 and 2016­07­06</CopySelector>
</CopySelectors> <UpdateSelectors>
<UpdateSelector>CreationDate !between 2016­07­05 AND 2016­07­06</UpdateSelector> </UpdateSelectors>

Run the connector

The connector accepts these command-line flags:

$ ca_agile_central2_jira_connector.rb  -h
Usage: ca_agile_central2_jira_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.
                         --cleartext, -c:   Bypass encrypting the credentials if they are already in clear text.

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_config.xml is set up, you can start running the connector. To start the connector, use one of the following command lines:

For Windows:
    ca_agile_central2_jira_connector.exe  jira_config.xml  -1

For Linux:
    ca_agile_central2_jira_connector.rb  jira_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:
    ca_agile_central2_jira_connector.exe  jira_config.xml  10

For Linux:
    ca_agile_central2_jira_connector.rb  jira_config.xml  10

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

Credential Encryption (added May 2015)

As of version 4.6.0 of the Connector, credentials occurring in the *Connection sections of the configuration file that are in clear-text are encrypted after the initial run using that config file. Credentials are identified as any configuration item tag appearing in a *Connection section whose name is '*User', or any '*Password' or 'APIKey'.

Credentials in the Emailer section (SMTPUser and SMTPPassword) will still be encoded. The credential encryption is localized for the installation of the connector and various aspects of the configuration file.

In practice, as long as the installation and execution folders are constant and the key CA Agile Central parameters in the configuration do not change, you are free to modify most of the contents of the configuration file without having to reset the credentials to their clear-text values. However, care must be taken in environments that do not have such stable characteristics to frequently check the log files for any entries that indicate environmental changes have taken place that prevent the connector from decrypting the encrypted values for use in the connector execution.

Note: The -c option can be used to specify leaving the password in clear case (if it is already in clear text) instead of encrypting. The command line for running the connector will be as follows ca_agile_central2_jira_connector.exe -c configfile.xml. The -1 option may still be used at the end of the command if needed.

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:

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

OR

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

Workflows

The connector installation comes with four workflow xml files, which are found in the root of the connector's directory:

jira_issue_workflow.xml
jira_workflow.xml
simplified_issue_workflow.xml
simplified_workflow.xml

<jira_issue_workflow.xml> and simplified_issue_workflow.xml are intended for non­bug issue types. <jira_workflow.xml> and <simplified_workflow.xml> are intended for bugs. <simplified_workflow.xml> and <simplified_issue_workflow.xml> are intended to work in Jira projects that use Jira 7 default Software Simplified Workflow. <jira_workflow.xml> and <jira_issue_workflow.xml> are intended to work in Jira projects that use Jira 6 default Jira Workflow.

Three scenario examples are described:

  • When a Jira project is associated with Software Simplified Workflow, use a simplified workflow file. <WorkflowFile> tag in <JiraConnection> section should reference simplified_workflow.xml if <ArtifactType> is bug, or simplified_issue_workflow.xml if <ArtifactType> is set to any other supported issue type: <WorkflowFile>simplified_workflow.xml</WorkflowFile>
  • When a Jira project is associated with Jira Workflow, use a jira workflow file. <WorkflowFile> tag in <JiraConnection> section should reference jira_workflow.xml if <ArtifactType> is bug, or jira_issue_workflow.xml if <ArtifactType> is set to any other supported issue type: <WorkflowFile>jira_workflow.xml</WorkflowFile>
  • When a Jira project is associated with a custom workflow, you need to create a custom workflow file first, and then reference it in the <WorkflowFile> tag in <JiraConnection> section, like this: <WorkflowFile>my_custom_workflow.xml</WorkflowFile>

Configure A Custom Simplified Workflow

The connector does not work with workflow xml files directly exported from Jira. If your Jira project is not associated with either default "Software Simplified Workflow" or default "Jira Workflow", workflow files that come with the connector cannot be used without customization.

Consider the following example:

Out of box a Jira 7 project is assocaiated with a default "Software Simplified Workflow. Your Jira administrator creates a new custom workflow and associates it with your Jira project. This custom workflow is very similar to the default simplified workflow with one modification: when issue is transitioned to "Done" status the Resolution is no longer automatically set to default "Done" value, but instead the transition to "Done" status now triggers "Resolve Issue Screen" where a user has to select Resolution.

It turns out that the only modification you will need to make to simplified_workflow.xml file, which comes with the connector installation is to add resolution nested inside each tag. Here is the modified simplified_workflow.xml file compatible with this custom workflow:

  <?xml version="1.0"?>
<!­­ Custom Simplfied Workflow­­> <Workflow>
<Step RallyState="Submitted" JiraStatusName="To Do"> <Transition JiraStatusName="In Progress">
<Action ID="11" Name="To Do"/> </Transition>
<Transition JiraStatusName="In Review">
<Action ID="11" Name="To Do"/>
</Transition>
<Transition JiraStatusName="Done">
<Action ID="11" Name="To Do"/> </Transition>
</Step>
<Step RallyState="Open" JiraStatusName="In Progress"> <Transition JiraStatusName="To Do">
<Action ID="21" Name="In Progress"/> </Transition>
<Transition JiraStatusName="In Review">
<Action ID="21" Name="In Progress"/> </Transition>
<Transition JiraStatusName="Done"> <Action ID="21" Name="In Progress"/>
</Transition> </Step>
<Step RallyState="Fixed" JiraStatusName="In Review"> <Transition JiraStatusName="To Do">
<Action ID="31" Name="In Review"/> </Transition>
<Transition JiraStatusName="In Progress">
<Action ID="31" Name="In Review"/> </Transition>
<Transition JiraStatusName="Done">
<Action ID="31" Name="In Review"/> </Transition>
</Step>
<Step RallyState="Closed" JiraStatusName="Done"> <Transition JiraStatusName="To Do">
<Action ID="41" Name="Done"> <Field>resolution</Field>
</Action>
</Transition>
<Transition JiraStatusName="In Progress">
<Action ID="41" Name="Done"> <Field>resolution</Field>
</Action>
</Transition>
<Transition JiraStatusName="In Review">
<Action ID="41" Name="Done"> <Field>resolution</Field>
</Action> </Transition>
</Step> </Workflow>

This customized workflow makes it possible to map Resolution field from CA AgileCentral to Jira during COPY_RALLY_TO_OTHER and UPDATE_RALLY_TO_OTHER service (provided that Resolution is listed in section and individual dropdown values are mapped in section. The is optional if Resolution dropdown values are identical between the two systems). On a related note: unlike the custom workflow example above, the default Software Simplified Workflow does not lend itself for setting Resolution field from CA AgileCentral to Jira during COPY_RALLY_TO_OTHER and UPDATE_RALLY_TO_OTHER service. While it is possible to set Resolution from CA AgileCentral to Jira's project associated with the default Software Simplified Workflow, it will require changes to the Jira project, specifically adding Resolution field to Software Development Bug Screen or/and to Software Development Default Issue Screen. Adding Resolution to those screens makes Resolution a required field for every status transition, no longer limited to transition to the final status. This approach is cumbersome and may be undesirable as far as Jira best practices are concerned.

Configure A More Restrictive Custom Workflow

In order to support updates from CA Agile Central to JIRA in the case where a custom JIRA defect workflow has been defined, the CA Agile Central 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 CA Agile Central defect.

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

Subsequently, a developer discovers that the defect is not fixed, and updates its CA Agile Central state to Open. Since in the JIRA workflow there is no transition from the Resolved status to the In Progress status (to match the CA Agile Central 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 CA Agile Central states, and the transitions between them, including status and action IDs.

  2. Create CA Agile Central states for each JIRA status.

    For the Linked Status in each JIRA step, find or create a corresponding state in CA Agile Central. To create new states in CA Agile Central, follow a procedure similar to that described under in Set Up CA Agile Central 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 CA Agile Central 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 CA Agile Central. 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 CA Agile Central defect, after any transformations specified by an <OtherEnumFieldHandler> for Resolution (if the Resolution lists in CA Agile Central 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

  • Mapping Jira Attachments

    Copy attachments between CA Agile Central and Jira with the  <RallyAttachmentLinker/> option in the configuration file as follows:

    <Config>
        ....
        <Connector>
            ....
            <RelatedObjectLinkers>
                <RallyAttachmentLinker />
            </RelatedObjectLinkers>
            ....

    Note: CA Agile Central attachments are limited to 5 MB. If a Jira attachment is larger than 5 MB, it will not be copied from Jira to CA Agile Central. The  <RallyAttachmentLinker/> supports bi-directional mapping between Jira and CA Agile Central.

    Known issue: DE23963 - If adding attachments to a child project and the connector user only has editor permissions to CA Agile Central, the user must have at least editor permissions to all parent projects of the child project to add an attachment.

  • 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-CA Agile Central direction. Also, note that the value which displays in the target CA Agile Central 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 CA Agile Central projects

    If you are copying issues from JIRA to CA Agile Central using the <RallyReferenceFieldHandler> with projects, you may see a Could not find CA Agile Central Project with name error in the log file if the connector user does not have editor permissions to that project in CA Agile Central.

  • 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 CA Agile Central 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 CA Agile Central 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 CA Agile Central is successful
    • Connecting to the JIRA system is successful
    • Fields in the field mapping exist in CA Agile Central
    • 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.


  • JIRA custom field precaution (ExternalID) field default value

    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 CA Agile Central. This field is often referred to as the ExternalID. Precautions:

    • This JIRA custom field must be defined as a type Number Field (not a string and not text, etc) and must be defined with a default value of -1 (minus 1).
    • Old JIRA items that existed before this JIRA 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 CA Agile Central will not find these items. Should you want to include these existing 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.

  • JIRA custom field precaution (ExternalID) field type

    When the connector searches JIRA for new artifacts, it attempts to find all JIRA artifacts where the custom field "ExternalID" (or whatever you named it) is equal to a "-1". For this reason, the field must be defined as a type "Number Field". If it is defined as a "Text Field (single line)", you'll see an error like:

     ERROR : RallyEIF::WRK::JiraConnection.rescue in find_new - Trying to find_new via query: ....
     ERROR : RallyEIF::WRK::JiraConnection.initialize - ["The operator '=' is not supported by the 'RallyObjectID' field."]
      INFO : RallyEIF::WRK::JiraConnection.disconnect - Disconnected from JIRA

  • Custom field precaution (general)

    When defining a JIRA custom field (for example, to receive some field from CA Agile Central), 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 : JiraConnection.initialize - Unrecognized field Severity, cannot continue
  • Unrecognized field

    When copying an artifact from CA Agile Central 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 CA Agile Central
      INFO : Connector.copy_to_other - Copy DE442 to JIRA
     DEBUG : Connector.block in map_fields_to_other -   Mapping Name(Test) - to - Summary(Test)
            ....
      WARN : JiraConnection.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 CA Agile Central, 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

  • Not a valid field

    Sometimes Projects will not see custom fields if the custom fields existed before the project was created. The following error may occur for this issue:

    ERROR : RallyEIF::WRK::JiraConnection.validate - JIRA ExternalIDField name of "RallyID" is not a valid field name"
    • The fix for this is: Verify that all screens are selected for that custom field

  • Mismatched external identifier

    This error can occur whenever artifacts are cloned or duplicated in either CA Agile Central 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
  • CA Agile Central is not populated with JIRA artifact's URL

    When creating a clickable link in the CA Agile Central artifact (back to the JIRA artifact), if the custom field in CA Agile Central 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 CA Agile Central).

  • EnvironmentalKey ident_vector not valid error

    The following error may be seen in the Jira connector version 4.6.0 and higher. If this error is seen, please re-enter the userid/password for both Jira and CA Agile Central.

            .....
              ERROR : Class.initialize - EnvironmentalKey ident_vector not valid for decryption target value

  • Ruby Certificate Errors on Windows

    The following error may be seen in the Jira connector. This link describes the issue: https://gist.github.com/fnichol/867550

            .....
              C:/Ruby200-p647/lib/ruby/2.0.0/net/http.rb:921:in `connect': SSL_connect
    returned=1 errno=0 state=SSLv3
    read server certificate B: certificate verify failed (OpenSSL::SSL::SSLError)

    This issue was fixed in our test environment using the following steps:

    1. Download this .PEM file

    2. Set a Window's environment variable: set SSL_CERT_FILE=.\cacert.pem

    3. Run the connector

  • Contact CA Agile Central Support

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

Revision history

  • 4.7.2-master-174 --- 08-Nov-2016
    • Fixes:
      • Adjusted Time Zone conversion so Target Date field in Agile Central maps correctly.
  • 4.7.0­-master­-173 ­­­ --- 23­-Sep-2016
    • Enhancements:
      • Support for JIRA 7
      • Subset and range copy and update selectors
      • Support for timetracking fields, specifically OriginalEstimate and RemainingEstimate.
  • 4.6.5-master-167 --- 24-Nov-2015
    • Enhancements:
      • Detecting duplicate CA Agile Central project names will now create an error log and exit condition.
      • Emailer functionality is now process prioritized to allow alert emails to send even if subsequent configuration validation fails.
      • Enhanced credential value encryption.
  • 4.6.4-master-166 --- 16-Nov-2015
    • Enhancements:
      • Brand redesign.
  • 4.6.2-master-165 --- 14-Aug-2015
    • Fixes:
      • Cleaned up log errors when the pre_copy method called on copy_to_rally can not satisfy the necessary conditions.
      • XML include files containing CA Agile Central Url or Workspace or Project handled properly both before and after credential encryption.
  • 4.6.1-master-158 --- 25-Jun-2015
    • Fixes:
      • Modified JiraConnection checkResultAgainstIntent method called by Connector.copy_to_other to handle Status field correctly.
      • Adjusted XML Schema Definition for Jira REST Connector to allow APIKey entry in RallyConnection section of the configuration file.
  • 4.6.0-master-156 --- 31-May-2015
    • Enhancements:
      • Credentials in the RallyConnection and JiraConnection sections are now encrypted.
  • 4.5.5-master-152 --- 25-April-2015
    • Enhancements:
      • Support for using APIKey in place of CA Agile Central username and password.
      • Better handling of FieldDefaults and values.
      • Better logging of failed attempt to copy/update item from another system to CA Agile Central.
  • 4.5.4-master-149 --- 02-Apr-2015
    • Enhancements:
      • Better logging for create/update operations when error conditions encountered.
      • Better handling of string fields mapped to CA Agile Central Name, Description, Notes that contain non-ASCII characters.
  • 4.5.3-master-148 --- 07-Mar-2015
    • Enhancements:
      • Updated to use CA Agile Central 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 CA Agile Central WSAPI 1.43.
  • 4.4.12-maintenance-88 --- 02-Dec-2014
    • Fixes:
      • Corrects an issue with copying attachments to CA Agile Central 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 JiraConnection 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 <JiraConnection> instead of <JiraConnection>
    • Known issues/limitations:
      • Versions 3.0.0 and greater are not compatible with JIRA 4.x

Feedback

Need more help? The CA Agile Central Community is your one-stop shop for self-service and support. To submit feedback or cases to CA Agile Central Support, find answers, and collaborate with others, please join us in the CA Agile Central Community.