EIF Connectors

CA Agile Central's Enterprise Integration Framework (EIF) connectors provide a way to integrate your system with CA Agile Central.

EIF connectors are configurable and extensible and have the following functionality:

  • Custom mapping of work items
    • Supports most work item types
    • Work item filtering
  • Field mapping
    • Map any field to any field
    • Choose field transfer direction
    • Choose which services to runF
    • Default field values
    • User mapping
    • Dropdown field mapping
  • Choose which services to run
  • Choose the schedule to run
  • CA Agile Central project handling
    • Choose which CA Agile Central project to copy work items to
    • Map multiple CA Agile Central projects
  • Extensibility
    • Field mapping
    • Pre and post processing
    • Ability to create your own connector

CA Agile Central’s Extensible Integrations Framework (EIF) connectors includes:

Connector Feature Comparison

The table below details the similarities and differences between EIF connectors.

Feature HP ALM ClearQuest TFS JIRA Bugzilla
Sync user stories X X X X X
Sync defects X X X X X
Sync test cases X X X    
Sync tasks     X    
Copy story hierarchy X   X X  
Copy test runs/results to CA Agile Central test results object X        
Link work items X   X X  

Getting Started

When integrating two systems, start simple. Here are some questions to ask yourself before mapping out an integration:

  • What problem am I trying to solve?
    • For example: "we currently have all of our bugs in system X. We now have a team working and defining stories in CA Agile Central. It would be nice to have defects from system X in CA Agile Central so that the team can prioritize and schedule those defects."
    • If your current option is to have a person export and import defects, then the EIF connectors can definitely help your team solve this problem.
  • What is a small subset of artifacts that I can try moving to the other system?
    • Select a small team and subset of defects from the other system to start with the connector.
    • Once you know what team and subset of artifacts you want to move, you can start to look at what the minimum set of information you would want to map would be.
    • You could start with something as simple as Name, Description, Owner and then figure out what CA Agile Central projects those artifacts would go to.

For more help, the CA Agile Central Integrations FAQ and Best Practices page contains sample configuration files, information on debugging, and many more details on how to manage and troubleshoot connector integrations.

Connector Synchronization

Debugging Create and Update Services

Service Name in Config Service Detail Service Configuration
UPDATE_RALLYFIELDS_AND_OTHER 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. In your config.xml, locate the tag (usually at the bottom of your config file). Inside of the tag, list UPDATE_RALLYFIELDS_AND_OTHER and remove the UPDATE_RALLY_TO_OTHER and UPDATE_OTHER_TO_RALLY service(s).

There is an optional new service, called UPDATE_RALLY_FIELDS_AND_OTHER, that has the following benefits:

  • Reduces overwrites caused by conflicts.
  • Pushes only recent field changes in CA Agile Central to HP ALM.
  • Looks for changes in ALM and writes update back to CA Agile Central.

EIF connectors use a polling mechanism to determine the changes that need to be synchronized. The connector does not have real-time synchronization. The administrator can set the interval between connector runs, with a recommended minimum time limit of 10 minutes between syncs. A separate XML configuration file is typically needed for each project in the third-party tool that you are integrating with.

Note: We recommend careful consideration regarding workflows between CA Agile Central and third party tool with which you are integrating. Other workflows can be supported within the constraints of the connector design:

  • The connectors have limited built-in support for user story hierarchies and linking between objects, such as defects to story.
  • The level of built-in support varies by the third-party tool.
  • The CA Agile Central object model is different from other tools so careful consideration is needed when replicating linking and hierarchies.
  • Implementation of test cases and results varies by third-party tool.

Steps For Success

Checklist for a successful configuration.

  1. Identify the person on your staff with the requisite background to perform or assist in the installation and configuration who:
    • has experience as an admin/user with the system being integrated with CA Agile Central (eg., has set up and used Git, has set up and used Jira, etc.).
    • has knowledge of your organization's network setup (whether proxies are used, other organization or site specific network idisosyncracies).
    • has recent user level experience on the installation platform (Windows: can use Internet Explorer, command shell; Linux: bash/zsh).
    • is familiar with navigating your platform's filesystem.
    • has seen/used XML files and is comfortable editing XML files.
  2. Find and scan the major sections of the installation and user guide for the connector (links at the top of the page).
  3. After installation, perform the basic configuration:
    • Define the system (data) source of record.
    • Define the work items to exchange and project mapping.
    • Define the direction of data flow for create and update.
    • Define the data set to exchange as well as the business rules.
    • Define the configuration file.
    • Use test or sandbox workspaces and projects to verify the configuration.
  4. Configuration tips:
    • Use the Preview mode as part of establishing that connectivity with CA Agile Central and the target system is successful.
    • Limit the mapped fields to the most basic set (eg., Name, Description) that don't require the use of a *FieldHandler.
    • Defer on specifying FieldDefault values.
    • Defer on using Copy or Update Selectors.
    • Defer on using FieldHandlers.
    • Defer on operations involving Attachments.
    • Specify only one service (eg., COPY_OTHER_TO_RALLY).
  5. Once connectivity with CA Agile Central and the other system have been established, use a "sandbox" CA Agile Central Workspace and similar for the other system.
    • Create a single artifact in the target system (Jira, Bugzilla, HPQC, TFS, etc.).
    • Turn off Preview mode.
    • Add a CopySelector so that only the single artifact you created will be considered.
    • Add any FieldDefault specifiers that will be needed.
  6. If you will be copying attachments, add a RelatedObjectLinker for this purpose.
  7. If you will be mapping fields that require a FieldHandler, add a field that uses a FieldHandler that isn't an *EnumFieldHandler.
  8. Introduce on a field by field basis any fields that will require an *EnumFieldHandler.
  9. Introduce additional services on a step-wise basis.

In addition to the steps for success outline above, it is helpful to start with modifying a configuration file in WorkItem mode. A configuration file instructs the connector on what actions to perform. A sample configuration file was part of the delivered ZIP file and should be in the same directory where you extracted the Ruby gem. For Quality Center, the default configuration file has a name of qc_config.xml. We recommend making a backup copy of the qc_config.xml (and naming it something like qc_config.xml-orig or qc_config-pristine.xml) in case you need to reference a valid configuration file later. You can give your configuration file any name of your choosing. For the purposes of this document, we retain the name of qc_config.xml.

Edit your configuration file (or the default qc_config.xml) and enter the appropriate values between each XML begin and end tag. Then, run WorkItem mode and verify that it works before you add more fields or additional configuration.

Example Configuration Files

Below are some common use cases for configuring the connector.

Test Cases

The qc_config_testcases.xml file example below shows the following:

  • How to create a test case in HP ALM.
  • How to set a custom field value in ALM to “Y” to indicate that the test case should be copied to CA Agile Central .
    • The HP ALM custom field is TS_User_04 in the example file.
  • Link the test case to the CA Agile Central user story, whose formatted ID is entered into a different HP ALM custom field.
    • TS_USER_03 in the example file.
  • The <RallyReferenceFieldHandler> is used to process the formatted id of the story.
<?xml version="1.0"?>
<config>
  <RallyConnection>
    <Url>demo-east.rallydev.com</Url>
    <WorkspaceName>Integrations</WorkspaceName>
    <Projects>
      <Project>Shopping Team</Project>
    </Projects>
    <User>[email protected]</User>
    <Password>encoded-U-m-F-s-b-H-l-P-T-i-E-=-</Password>
    <ArtifactType>TestCase</ArtifactType>
    <ExternalIDField>QCTestID</ExternalIDField>
  </RallyConnection>

  <QCConnection>
    <Url>vmwin2008qc11:8080</Url>
    <Domain>DEMO</Domain>
    <Project>DEMO1</Project>
    <User>sara</User>
    <Password>encoded-c-m-F-s-b-H-l-k-Z-X-Y-=-</Password>
    <ArtifactType>TEST</ArtifactType>
    <IDField>TS_TEST_ID</IDField>
    <ExternalIDField>TS_USER_01</ExternalIDField>
        <ExternalEndUserIDField>TS_USER_02</ExternalEndUserIDField>
    <CopySelectors>
        <CopySelector>TS_USER_04 = Y</CopySelector>
    </CopySelectors>
  </QCConnection>

  <Connector>
    <FieldMapping>
          <Field><Rally>Name</Rally><Other>TS_NAME</Other></Field>
          <Field><Rally>Description</Rally><Other>TS_DESCRIPTION</Other></Field>
          <Field><Rally>WorkProduct</Rally><Other>TS_USER_03</Other></Field>
    </FieldMapping>
        
        <RallyFieldHandlers>
                <RallyReferenceFieldHandler>
                        <FieldName>WorkProduct</FieldName>
                        <ReferencedFieldLookupID>FormattedID</ReferencedFieldLookupID>
                </RallyReferenceFieldHandler>
        </RallyFieldHandlers>

    <OtherFieldHandlers>
        <QCRtfFieldHandler>
           <FieldName>TS_DESCRIPTION</FieldName>
        </QCRtfFieldHandler>
    </OtherFieldHandlers>

        
  </Connector>

  <ConnectorRunner>
    <Preview>false</Preview>
    <LogLevel>Debug</LogLevel>
    <Services>UPDATE_RALLYFIELDS_AND_OTHER , COPY_OTHER_TO_RALLY, COPY_RALLY_TO_OTHER</Services>
  </ConnectorRunner>
</config>

Test Runs

The example configuration file below is used in conjunction with the testcases config file above to copy test results from HP ALM to CA Agile Central.

<?xml version="1.0"?>
<config>
  <RallyTestResultConnection>
    <Url>demo-west.rallydev.com</Url>
    <WorkspaceName>Integrations</WorkspaceName>
    <Projects>
      <Project>Shopping Team</Project>
    </Projects>
    <User>[email protected]</User>
    <Password>encoded-U-m-F-s-b-H-l-P-T-i-E-=-</Password>
    <ArtifactType>TestCaseResult</ArtifactType>
  </RallyTestResultConnection>

  <QCRunConnection>
    <Url>vmwin2008qc11:8080</Url>
    <Domain>DEMO</Domain>
    <Project>DEMO1</Project>
    <User>sara</User>
    <Password>encoded-c-m-F-s-b-H-l-k-Z-X-Y-=-</Password>
    <ArtifactType>RUN</ArtifactType>
    <IDField>RN_RUN_ID</IDField>
    <ExternalIDField>RN_USER_01</ExternalIDField>
    <ExternalEndUserIDField>RN_USER_02</ExternalEndUserIDField>
    <!-- QC user field on TEST table that stores the unique id for the Rally work item -->
    <TestExternalIDField>TS_USER_01</TestExternalIDField>
    <TestExternalEndUserIDField>TS_USER_02</TestExternalEndUserIDField>
  </QCRunConnection>

  <Connector>
    <FieldMapping>
      <!-- Required fields in Rally: TestCase, Verdict, Date and Build -->
      <!-- Do not remove the following 4 field mappings -->
      <Field><Rally>TestCase</Rally><Other>RN_TEST_ID</Other></Field>
      <Field><Rally>Verdict</Rally><Other>RN_STATUS</Other></Field>
      <Field><Rally>Date</Rally><Other>RN_EXECUTION_DATE</Other></Field>
      <Field><Rally>Build</Rally><Other>RN_RUN_NAME</Other></Field>
    </FieldMapping>
    <RallyFieldHandlers>
      <!-- Required field handler: Determines how to lookup the associated test in Rally -->
      <RallyReferenceFieldHandler>
        <FieldName>TestCase</FieldName>
        <!-- Custom field on Rally test case that stores the unique id for the linked QC test -->
        <ReferencedFieldLookupID>QCTestID</ReferencedFieldLookupID>
      </RallyReferenceFieldHandler>
    </RallyFieldHandlers>
    <OtherFieldHandlers>
      <!-- Required field handler: Determines how to convert QC run date to Rally date -->
      <QCRunDateFieldHandler>
        <FieldName>RN_EXECUTION_DATE</FieldName>
      </QCRunDateFieldHandler>
      <OtherEnumFieldHandler>
        <FieldName>RN_STATUS</FieldName>
        <Mappings>
          <!-- Add additional mappings between Rally verdict and RN_STATUS -->
          <Field><Rally>Fail</Rally><Other>Failed</Other></Field>
          <Field><Rally>Pass</Rally><Other>Passed</Other></Field>
        </Mappings>
      </OtherEnumFieldHandler>
    </OtherFieldHandlers>
  </Connector>

  <ConnectorRunner>
    <Preview>false</Preview>
    <LogLevel>Debug</LogLevel>
    <!--- COPY_OTHER_TO_RALLY is only service supported for runs -->
    <Services>COPY_OTHER_TO_RALLY</Services>
  </ConnectorRunner>
</config>

Defects

The example configuration file below shows how to log defects in ALM and transfer the defects that the team needs to fix to CA Agile Central.

  • This file shows the most common fields that many users want to copy from ALM to CA Agile Central. You can use the field handler to map values of the priority field in ALM to a set of priority fields in CA Agile Central.
  • Tip for setting up: create a custom field in ALM with values Y,N (BG_USER_02) and set the value to “y” if that bug should be copied from ALM to CA Agile Central.
<?xml version="1.0"?>
<config>
   <RallyConnection>
      <Url>demo-west.rallydev.com</Url>
      <WorkspaceName>Integrations</WorkspaceName>
      <Projects>
        <Project>Shopping Team</Project>
      </Projects>
      <User>[email protected]</User>
      <Password>encoded-U-m-F-s-b-H-l-P-T-i-E-=-</Password>
      <ArtifactType>Defect</ArtifactType>
      <ExternalIDField>QCDefectID</ExternalIDField>
   </RallyConnection>
        
   <QCConnection>
      <Url>vmwin2008qc11:8080</Url>
      <Domain>DEMO</Domain>
      <Project>DEMO1</Project>
      <User>sara</User>
      <Password>encoded-c-m-F-s-b-H-l-k-Z-X-Y-=-</Password>
      <ArtifactType>BUG</ArtifactType>
      <IDField>BG_BUG_ID</IDField>
      <ExternalIDField>BG_USER_01</ExternalIDField>
      <ExternalEndUserIDField>BG_USER_03</ExternalEndUserIDField> <!-- Rally Formatted ID -->
      <CopySelectors>
        <CopySelector>BG_USER_02 = Y</CopySelector>
      </CopySelectors>
   </QCConnection>

   <Connector>
    <FieldMapping>
        <Field><Rally>Name</Rally>          <Other>BG_SUMMARY</Other></Field>
        <Field><Rally>Description</Rally>   <Other>BG_DESCRIPTION</Other></Field>
    <Field><Rally>Notes</Rally>         <Other>BG_DEV_COMMENTS</Other><Direction>TO_OTHER</Direction></Field>
        <Field><Rally>Severity</Rally>      <Other>BG_SEVERITY</Other></Field>
        <Field><Rally>Priority</Rally>      <Other>BG_PRIORITY</Other></Field>
        <Field><Rally>SubmittedBy</Rally>   <Other>BG_DETECTED_BY</Other></Field>
        <Field><Rally>Owner</Rally>         <Other>BG_RESPONSIBLE</Other></Field>
        <Field><Rally>State</Rally>         <Other>BG_STATUS</Other></Field>
        <Field><Rally>FoundInBuild</Rally>  <Other>BG_DETECTION_VERSION</Other></Field>
        <Field><Rally>TargetBuild</Rally>   <Other>BG_PLANNED_CLOSING_VER</Other></Field>
        
    <!--<Field><Rally>QCAttachments</Rally> <Other>BG_ATTACHMENT</Other><Direction>TO_RALLY</Direction></Field>-->``
    </FieldMapping>
        
                <OtherFieldHandlers>

          <QCRtfFieldHandler>
            <FieldName>BG_DESCRIPTION</FieldName>
          </QCRtfFieldHandler>
        
          <OtherUserFieldHandler>
            <FieldName>BG_DETECTED_BY</FieldName>
            <Domain>acme.com</Domain>
          </OtherUserFieldHandler>
          
          <OtherUserFieldHandler>
            <FieldName>BG_RESPONSIBLE</FieldName>
            <Domain>acme.com</Domain>
          </OtherUserFieldHandler>

         <!-- <QCUrlAttachmentFieldHandler>
           <FieldName>BG_ATTACHMENT</FieldName>
         </QCUrlAttachmentFieldHandler> -->
                        
          <OtherEnumFieldHandler>
            <FieldName>BG_SEVERITY</FieldName>
            <Mappings>
                    <Field><Rally>Cosmetic</Rally>        <Other>Cosmetic</Other></Field>
                    <Field><Rally>Minor Problem</Rally>   <Other>Minor Problem</Other></Field>
                    <Field><Rally>Major Problem</Rally>   <Other>Major Problem</Other></Field>
                    <Field><Rally>Crash/Data Loss</Rally> <Other>Crash/Data Loss</Other></Field>
                    <Field><Rally>None</Rally>            <Other>None</Other></Field>
            </Mappings>

          </OtherEnumFieldHandler>

          <OtherEnumFieldHandler>
            <FieldName>BG_STATUS</FieldName>
            <Mappings>
                    <Field><Rally>Submitted</Rally> <Other>New</Other></Field>
                    <Field><Rally>Open</Rally>      <Other>Open</Other></Field>
                    <Field><Rally>Reopened</Rally>  <Other>Reopen</Other></Field>
                    <Field><Rally>Fixed</Rally>     <Other>Fixed</Other></Field>
                    <Field><Rally>Closed</Rally>    <Other>Closed</Other></Field>
            <Field><Rally>Closed</Rally>    <Other>Rejected</Other></Field>
        </Mappings>
          </OtherEnumFieldHandler>

          <OtherEnumFieldHandler>
            <FieldName>BG_PRIORITY</FieldName>
            <Mappings>
                    <Field><Rally>Resolve Immediately</Rally>  <Other>Resolve Immediately</Other></Field>
                    <Field><Rally>High Attention</Rally>       <Other>High Attention</Other></Field>
                    <Field><Rally>Normal</Rally>               <Other>Normal</Other></Field>
                    <Field><Rally>Low</Rally>                  <Other>Low</Other></Field>
            </Mappings>
          </OtherEnumFieldHandler>
    </OtherFieldHandlers>
  </Connector>
 
  <ConnectorRunner>
        <Preview>false</Preview>
        <LogLevel>Debug</LogLevel>
<!--         <Services>UPDATE_RALLY_TO_OTHER, UPDATE_OTHER_TO_RALLY, COPY_OTHER_TO_RALLY</Services>  -->
        <Services>UPDATE_OTHER_TO_RALLY, COPY_OTHER_TO_RALLY</Services>
    </ConnectorRunner>
</config>

WorkItem Mode

A configuration file is used to instruct the connector on what actions to perform. A sample configuration file was part of the delivered ZIP file and should be in the same directory where you extracted the Ruby gem. For Quality Center, the default configuration file has a name of qc_config.xml. We recommend making a backup copy of qc_config.xml (and naming it something like qc_config.xml-orig or qc_config-pristine.xml) in case you need to reference a valid configuration file later. You can give your configuration file any name of your choosing. For the purposes of this document, we retain the name of qc_config.xml.

Edit your configuration file (or the default qc_config.xml) and enter the appropriate values between each XML begin and end tag.

<Config>
        <RallyConnection>
                <Url>rally1.rallydev.com</Url>
                <WorkspaceName>Workspace Name</WorkspaceName>
                <Projects>
                        <Project>Project Name 1</Project>
                </Projects>
                <User>[email protected]</User>
                <Password>password</Password>
<!-- You can use an APIKey in place of User and Password tags -->
        <!-- <APIKey>YourAPIKeyValueGoesHere...</APIKey> -->
                <ArtifactType>Defect</ArtifactType>
                <ExternalIDField>ExternalID</ExternalIDField>
        <!--    <UpdateSelectors>
                        <UpdateSelector>State = Open</UpdateSelector>
                        <UpdateSelector>Priority = High</UpdateSelector>
                </UpdateSelectors>
                <FieldDefaults>
                        <Field><Name>RootCause</Name><Default>Undefined</Default></Field>
                </FieldDefaults>
        -->
        </RallyConnection>

        <QCConnection>
                <Url>server:port</Url>
                <Domain>Domain Name</Domain>
                <Project>Project Name</Project>
                <User>qcusername</User>
                <Password>password</Password>
                <ArtifactType>BUG</ArtifactType>
        <!--    <CopySelectors>
                        <CopySelector>BG_STATUS   = Open</CopySelector>
                        <CopySelector>BG_PRIORITY = High Attention</CopySelector>
                        <CopySelector>RQ_REQ_NAME = (WebExample1 Or WebExample2) </CopySelector>
                </CopySelectors>
        -->
                <IDField>BG_BUG_ID</IDField>
                <ExternalIDField>BG_USER_XX</ExternalIDField>
                <ExternalEndUserIDField>BG_USER_YY</ExternalEndUserIDField>
        </QCConnection>

        <Connector>
                <FieldMapping>
                        <Field><Rally>Name</Rally><Other>BG_SUMMARY</Other></Field>
                </FieldMapping>
        </Connector>

        <ConnectorRunner>
                <Preview>False</Preview>
                <LogLevel>Debug</LogLevel>
                <Services>UPDATE_RALLY_TO_QC,  COPY_QC_TO_RALLY</Services>
        </ConnectorRunner>
</Config>

Each major section is surrounded by a tag (called an XML element) to delineate that section. In the example above, here is a description of each section:

  • RallyConnection

    Defines the connection information for CA Agile Central, including CA Agile Central URL, username and password or APIKey.

  • QCConnection

    Defines the connection information to Quality Center including domain name, project name, artifact type, user, 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.

  • ConnectorRunner

    Specifies parameters related to the services the connector is to run.

 

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.