RPM-GreenHopper-Installation-User-Guide

RPM GreenHopper Connector

Connector Overview

The RPM GreenHopper connector is a program meant to copy your issues over to CA Agile Central and keep the data in them up to date so that your portfolio information can be rolled up properly in RPM. The connector is installed on a computer that can connect to both CA Agile Central and Jira over https. Both connections use the standard REST based APIs for querying, creating and updating items. This connector supports JIRA 5.2+.

Contents

Connector Overview

Connector Downloads

System Setup (Connectors)

Jira Setup

CA Agile Central Setup

Configuring the Connector

Running the Connector

Debug/Troubleshoot

Use Case

XML Reference

General Requirements

  • Jira 5.2 or greater
  • A computer where the connector will run (Windows, Mac, Linux)
  • Recommended System Specs any OS - 1 CPU, 2GB RAM, 1GB Disk space free for connector

The basic workflow to get started is to:

  1. Install the connector on a specific computer
  2. Log into both CA Agile Central and Jira to make necessary configuration changes including making custom fields required by the connector.
  3. Run a utility to setup a corresponding set of users in CA Agile Central to those already in Jira
  4. Run a utility to setup a corresponding set of projects in CA Agile Central to those in Jira
  5. Configure the connector
  6. Run an initial load to move the Jira issues to CA Agile Central
  7. Schedule the connector to run and copy new issues for ongoing updates from Jira to CA Agile Central

Overview of features

The RPM GreenHopper Connector runs 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 two services to keep the objects in GreenHopper up to date in CA Agile Central.

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

Back to Contents

System Setup (Connectors)

The RPM GreenHopper connector can run on Windows, Mac or Linux.

Pre-installation checklist

  1. Access to a test environment/installation of JIRA
  2. CA Agile Central administrator privileges are needed for setup, but only user access is needed to run the connector
  3. Proxy server details if the machine used to run the connector uses a proxy server to connect to CA Agile Central or JIRA
  4. A JIRA user with Administrator privileges
  5. Create users in the two systems for the connector to use when copying Stories to CA Agile Central:
    • Create a User in Jira/Greenhopper and note the username and password
    • Create a CA Agile Central User and note the username and password

Installation for Windows

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

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

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

Installation for Linux and Mac

The connector for Linux or Mac requires Ruby 1.9.2-p290 or greater. 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)

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

Jira Setup

Configuring Jira for using the connector. Making the custom fields and making the workflow.xml

Create an External ID field in JIRA

In the JIRA system, a custom field is required 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 being up to 14 digits in length.

FOR JIRA 5: As a JIRA administrator perform these steps:

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

Create a CrosslinkUrlField in JIRA

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

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

Migrate your Jira Users and Projects

There is a specific utility to help you migrate your Jira Projects and Users to RPM. This will allow you to have a mirror of your project list in RPM and allow the owners of stories to appear appropriately in RPM. The documentation for the utility can be found here: rpm-greenhopper-users-projects-import-tool

Back to Contents

CA Agile Central Setup

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. Click on Work Products & Fields and ensure the Work Product Type selected is Defect or User Story (whatever work item you are mapping).
  5. Click ActionsNew Field.
  6. Enter a Name of JiraKey, Display Name of JiraKey (name and display name must match), and type of String. Note: you can choose a different name (like JiraID) for the custom field in 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 bring up the corresponding JIRA issue in a browser. The <CrosslinkUrlField> XML element in the <CA Agile CentralConnection> section of the configuration file is where to specify the name of the custom field in CA Agile Central which will contain this link (URL). Use the same sort of process in CA Agile Central as you used for the JIRAKey field above.

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

Connector Configuration

Configuration file syntax

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

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

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\CA Agile CentralConnectorforJira) 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.

Download the SampleConfig (right click and save)
<Config>
    <CA Agile CentralConnection>
        <Url>rally1.rallydev.com</Url>
        <WorkspaceName>Workspace Name</WorkspaceName>
        <Projects>
            <Project>Project</Project>
        </Projects>
        <User>user@company.com</User>
        <Password>password</Password>
        <ArtifactType>Story</ArtifactType>
        <ExternalIDField>JiraID</ExternalIDField>
        <CrossLinkURLField>JiraLink</CrossLinkURLField>
    </CA Agile CentralConnection>

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

    <Connector>
        <FieldMapping>
            <Field><CA Agile Central>Name</CA Agile Central><Other>Summary</Other></Field>
            <Field><CA Agile Central>Description</CA Agile Central><Other>Description</Other></Field>
            <Field><CA Agile Central>ScheduleState</CA Agile Central><Other>Status</Other></Field>
            <Field><CA Agile Central>Owner</CA Agile Central><Other>Assignee</Other></Field>
        </FieldMapping>

        <CA Agile CentralFieldHandlers>
            <CA Agile CentralTruncateFieldHandler>
                <FieldName>Description</FieldName>
            </CA Agile CentralTruncateFieldHandler>
            <CA Agile CentralUserFieldHandler>
                <Fieldame>Owner</Fieldame>
                <ReferencedFieldLookupID>EmailAddress</ReferencedFieldLookupID>
            </CA Agile CentralUserFieldHandler>
        </CA Agile CentralFieldHandlers>

        <OtherFieldHandlers>
            <OtherEnumFieldHandler>
                <FieldName>Status</FieldName>
                <Mappings>
                    <Field><CA Agile Central>Defined</CA Agile Central>    <Other>Open</Other></Field>
                    <Field><CA Agile Central>Defined</CA Agile Central>    <Other>Reopened</Other></Field>
                    <Field><CA Agile Central>In-Progress</CA Agile Central><Other>In Progress</Other></Field>
                    <Field><CA Agile Central>Completed</CA Agile Central>  <Other>Resolved</Other></Field>
                    <Field><CA Agile Central>Accepted</CA Agile Central>   <Other>Closed</Other></Field>
                </Mappings>
            </OtherEnumFieldHandler>
        </OtherFieldHandlers>
    </Connector>

    <ConnectorRunner>
        <Preview>false</Preview>
        <Services>COPY_JIRA_TO_RALLY,  UPDATE_JIRA_TO_RALLY</Services>
    </ConnectorRunner>
</Config>
Back to Contents

Running the connector

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

For Windows:
    rally2_jira_connector.exe  jira_config.xml -1

For Linux:
    ruby  rally2_jira_connector.rb  jira_config.xml -1

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.

We recommend using the Windows task scheduler or cron (for Linux or Mac OS) to schedule running the connector every 30 minutes. Notes on setting up that configuration can be found here: Running as a scheduled Task

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

Multiple configuration files

If you want to map to more than one workspace in CA Agile Central, or if you want to map multiple artifact types, or if you need to map to multiple containers (such as projects in Jira) in the other system, setting up multiple configuration files may make sense.

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

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

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

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

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

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

For Linux:
    ruby  rally2_jira_connector.rb  config_workspaceA.xml  config_workspaceB.xml  10
Back to Contents

Debug/Troubleshooting

Determine how to handle Closed issues in JIRA

By default, JIRA does not allow issues with a status of Closed to be updated. When issues are first copied from JIRA to CA Agile Central (the COPY_JIRA_TO_RALLY service), the connector needs to update the CA Agile CentralID custom field in each issue with the object id of the corresponding CA Agile Central defect. If the issue is closed, the update will fail, and the CA Agile CentralID will remain empty. 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. For this reason, we recommend including a <CopySelectors> section in your configuration file within the <JiraRestConnection> section. For example:

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

This will prevent the connector from trying to copy closed Jira issues to CA Agile Central.

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

Working with a proxy server

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

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

Troubleshooting the connector


XML Reference

Configuration file syntax

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

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

Definitions of the XML tags in the config file

Jira Installation guide notes on field mapping

Jira Installation guide notes on working with a custom workflow

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.