Readme for Micro Focus Connect Pivotal Connector 23.4

Refer to the Micro Focus Community and Micro Focus Connect User Guide for further configuration instructions. Pivotal Connector for Micro Focus Connect (pivotal connector) lets you synchronize Pivotal assets. This readme describes how to configure pivotal connector.

Copyright

Copyright 2018 - 2023 Open Text.

The only warranties for products and services of Open Text and its affiliates and licensors ("Open Text") are as may be set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. Open Text shall not be liable for technical or editorial errors or omissions contained herein. The information contained herein is subject to change without notice.

Except as specifically indicated otherwise, this document contains confidential information and a valid license is required for possession, use or copying. If this work is provided to the U.S. Government, consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license.

Contents
  Installation and Upgrade Information Technical Notes
Prerequisites Known Issues Need assistance with the product?

Prerequisites

This section lists prequisites required to successfully install, configure, and run pivotal Connector.

Micro Focus Connect Requirements

This connector requires at least build 23.4 of Micro Focus Connect and can be configured using the Micro Focus Connect UI. You can download the latest version of Micro Focus Connect from the Micro Focus SupportLine (http://supportline.microfocus.com) navigating to the latest Micro Focus Connect installation.

Required Libraries

The following are required to run the Pivotal Connector (and may not be already installed). For further configuration instructions, see the Micro Focus Connect Release Notes.

  1. Create a Connector directory. For example: C:\Program Files\Micro Focus\Connect\AppData\connectors\mfcConnectorPivotal
    • NOTE: If this is being installed into an existing connector directory, you must remove the existing mfc*.jars
  2. Copy the following libraries (and the provided Connector jar) into the connector directory you created.

Once you have collected the required JAR files, copy them to your Micro Focus Connect root directory.

 

Top

Installation and Upgrade Information

Go to https://supportline.microfocus.com/productdoc.aspx to obtain download.
The following information contains notes regarding installation, but does not replace the entire process.

Configuration Overview

The process for configuring Pivotal Connector involves the following steps:

  1. Create key and link fields in AccuRev and Pivotal for the assets you plan to synchronize.
  2. Merge Connect.xml.sample with the Connect.xml that is checked in to your StarFlow Extensions project.
  3. Review default Pivtoal data source configuration settings in Micro Focus Connect and customize as needed.
  4. Find the internal name for AccuRevIssueKey and AccuRevIssueLink user fields.
  5. Review default Pivotal connection configuration settings in Micro Focus Connect and customize as needed.
  6. Specify the key values for asset types.

Each of these steps is described in the following sections.

Step 1. Create Key and Link Fields

In order to configure Pivotal Connector, you must:

These procedures are described in the following sections. For all of them, refer to your product documentation if you need additional information.

About AccuRev Issue Key and Issue Link Fields

As mentioned earlier in this section, Micro Focus Hub includes key and link fields to use to map AccuRevPivotal assets to those in AccuRev -- ExternalID and ExternalURL, respectively. There is no need to create additional fields in Micro Focus Hub for this purpose.

Creating Issue Key and Issue Link Fields in PIVOTAL

To create issue key and issue link fields in PIVOTAL:

  1. Log in to PIVOTAL and open the project you will be synchronizing with AccuRev.
  2. In the ALM main window, click Tools > Customize.

    3. The Project Customization window appears.

  3. Click the Project Entities link.

    4. The Project Entities page opens.

  4. Expand the folder for the entity for which you wish to create the issue key and issue link fields -- Defect, for example -- and then click the User Fields folder.
  5. Click the New Field button.
  6. On the Settings tab, complete the following fields to create the issue key field:
    • Name - Must be AccuRevIssueKey.
    • Label - The name you want to display in the PIVOTAL GUI.
    • Type - String.
    • Length - 255.
  7. Click the Save button.
  8. Repeat steps 5 - 7 to add the issue link field for the same asset chosen in step 4. Use AccuRevIssueLink for the Name and whatever you like for the Label field. All other fields can use the same values as those for the issue key field.
  9. Repeat steps 4 - 8 for the remaining asset types you plan to map (Requirement, Test, and Release-Cycle, for example).

Enable History for Assets in PIVOTAL

The last step in this stage of the Pivotal Connnector configuration process is to enable the History setting for the fields in the asset types you plan to map to AccuRev.

  1. Log in to Pivotal and open the project you will be synchronizing with AccuRev.
  2. In the ALM main window, click Tools > Customize,

    3. The Project Customization window appears.

  3. Click the Project Entities link.

    4. The Project Entities page opens.

  4. Expand the System Fields folder for the first asset type you are mapping -- Defect, for example.
  5. On the Settings tab, check the History field for each system field you are mapping -- Description, Name, and so on.
  6. Click the Save button.
  7. Repeat steps 4 - 6 for the remaining asset types you plan to map (Requirement, Test, and Release-Cycle, for example).

Step 2. Merge Connect.xml.sample with Connect.xml

In addition to this readme, the Pivotal Connector package includes a configuration file called Connect.xml.sample. This XML file contains default settings to help streamline the Pivotal Connector configuration process in Micro Focus Connect. You use this stage of the configuration process to incorporate values for default settings in your system's Connect.xml file:

  1. Using the AccuRev CPC, check out the Connect.xml that is checked in to the StarFlow Extensions\Connect directory of the StarFlow Extensions project.
  2. Open Connect.xml for editing.
  3. Open the Connect.xml.sample file in your Pivotal Connector package.
  4. Copy the entire Pivotal <DataSource> element from Connect.xml.sample and paste it in the appropriate location in Connect.xml.
  5. Repeat this process for the entire Pivotal <Synchronization> element.
  6. Save your changes to Connect.xml and check it back in to your StarFlow Extensions project.
  7. Finally, open the local.properties file in your Micro Focus Connect install directory and update these values:
    • url= path to the Connect.xml file that is in the StarFlow Extensions\Connect directory where you installed AccuRev (c:\Program Files\Micro Focus\CM Hub 14.0\Projects\StarFlow Extensions\Connect\, for example)
    • user_directory= path to the data directory for Micro Focus Connect (c:/Program Files/Micro Focus/Micro Focus Connect/data, for example)

      • Note: The slashes in the user_directory= path must be forward ( / ) slashes.

Step 3. Review and Modify Default Pivotal Data Source Settings

Micro Focus Connect uses the Connect.xml file to configure connectors like the Pivotal Connector. You merged default Pivotal data source and connection configuration settings into your system's Connect.xml file in the previous step. In this stage of the configuration process, you review default Pivotal data source configuration settings and, where necessary, modify them for your installation.

You perform all of the procedures described in this section using Micro Focus Connect.

A Note About Pivotal Data Sources

In Pivotal every project is associated with its own database. Because a Connector data source is likewise associated with a single project, you will need to create multiple data sources for your Pivotal Connector if you are synchronizing multiple projects with AccuRev.

The default Pivotal Connector configuration includes the definition for a single data source. Use the procedure described here to create others as needed. Refer to Using Micro Focus Connect for more information if you need help.

Review the Pivotal Data Source

Use Micro Focus Connect to review the default Pivotal data source that is defined in your Connect.xml. See Using Micro Focus Connect for more information on using the Micro Focus Connect GUI.

  1. On the Micro Focus Connect Dashboard, click the Settings button to display the Settings page.
  2. Click the Data Sources tab to display default settings. Review the following fields and make changes where needed to support your installation:

    3. Pivotal Server Fields

    • Name - A unique name for the Pivotal data source.
    • Product - The data source product name. (Use "PIVOTAL" for the Pivotal Connector.)
    • User - The user name. This user must have access to Pivotal. Consider creating a special "Pivotal Connector" user to make the actions performed by Micro Focus Connect during issue synchronization clearly identifiable in logs and issue history.
    • Password - The password for the user.
    • Server - The name of the Pivotal server.
    • Port - The port to which you connect to the Pivotal server. The default is 8080
    • URL - The URL of the Pivotal server.
    • Protocol - The protocol used to connect to the server. The default is http.
    • Domain - The Pivotal domain associated with the projects you plan to synchronize with AccuRev. The default is DEFAULT.

    Pivotal Database Fields

    • Database Host - The database server name.
    • Database Port - The database server port number. The default is 1433.
    • Database Name - The database name.
    • Database Username - The DB admin username.
    • Database Password - The DB admin password.

    Types

    The Types field lists the Pivotal asset types you plan to synchronize. They are entered in a colon-separated list as follows:

    Defect:Requirement:Release-Cycle:Test

    Parent IDs for Requirement, Release-Cycle, and Test Asset Types

    You need to specify the IDs for the parent objects of Requirement, Release-Cycle, and Test asset types. In the Micro Focus Connect GUI, these fields are:

    • Requirement Parent Folder ID field:

      • Find the value for this field by locating the Req ID field in the Requirements Module window in Pivotal.

    • Cycle Parent Folder ID field:

      1. Open your Pivotal URL in a Web browser, replacing the parameters in italics with values appropriate for your installation:

        2. http://ServerIP:Port/qcbin/rest/domains/DomainName/projects/ProjectName/releases

      2. In the displayed XML document, search for the desired release. (Look for <Field Name="name"><Value>My Release</Value>, for example.
      3. Search for the "id" field associated with that release (<Field Name="id"><Value>1008</Value>, for example.)
      4. Use that value for the Cycle Parent Folder ID field.

    • Test Parent Folder ID field:

      1. Open your Pivotal URL in a Web browser, replacing the parameters in italics with values appropriate for your installation:

        2. http://ServerIP:Port/qcbin/rest/domains/DomainName/projects/ProjectName/test-folders

      2. In the displayed XML document, search for the desired test folder. (Look for <Field Name="name"><Value>My Tests</Value>, for example.
      3. Search for the "id" field associated with that folder (<Field Name="id"><Value>1007</Value>, for example.)
      4. Use that value for the Test Parent Folder ID field.
  3. Click the Connect button.

    4. Micro Focus Hub connects to the Pivotal data source you just defined. Note that the assets are already defined in the Type list.

  4. Save the Pivotal data source before continuing.

Step 4. Finding the Internal Name for AccuRevIssueKey and AccuRevIssueLink User Fields.

In Step 1. Create Key and Link Fields you created issue key and issue link fields in both AccuRev and Pivotal as summarized here:

Issue Key Fields AccuRev Pivotal
ExternalID AccuRevIssueKey
Issue Link Fields AccuRev Pivotal
ExternalURL AccuRevIssueLink

When you created the AccuRevIssueKey and AccuRevIssueLink fields in Pivotal, Pivotal created internal names for these fields. For example, the internal name for the AccuRevIssueKey might be user-05. In this stage of the configuration process, you need to find the internal name for the AccuRevIssueKey and AccuRevIssueLink fields and record them for use later in the Pivotal Connector configuration process.

To find the internal name for AccuRevIssueKey and AccuRevIssueLink user fields:

  1. Open your Pivotal URL in a Web browser, replacing the parameters in italics with values appropriate for your installation:

    2. http://ServerIP:Port/qcbin/rest/domains/DomainName/projects/ProjectName/customization/entities/Component Type/fields

  2. In the document that appears, search for <Field Label>=AccuRevIssueKey" and record the value of the Name attribute. (It will be something like Name="user-05".)
  3. Repeat this step, this time searching for <Field Label>=AccuRevIssueLink". Again, record the value of the Name attribute.
  4. Close the Web browser.

Tip: In the final two steps, you will need enter the internal names for the Pivotal user fields that correspond to the AccuRev fields. Consider creating a table like this to record the Pivotal internal names for easy reference.

AccuRev Pivotal Pivotal Internal Name
ExternalID AccuRevIssueKey user-02 (for example)
ExternalURL AccuRevIssueLink user-04 (for example)

Step 5. Review and Modify the Default Pivotal Connection Settings

In this stage of the configuration process, you use Micro Focus Connect to review default Pivotal connect settings for your Pivotal data source and, where necessary, modify them for your installation. Connection settings include property maps, value maps, and other settings that specify what gets synchronized between the Pivotal and AccuRev systems. See Using Micro Focus Connect for more information on using the Micro Focus Connect GUI.

  1. On the Micro Focus Connect Dashboard, locate the pivotalSync connection and click the Edit button.

    2. The Update Connection window appears. The Data Source tab is selected by default. This tab displays the data source configuration you specified in Step 3. Review and Modify Default Pivotal Data Source Settings.

  2. Click the Next button.

    3. The Types and Properties tab appears. The Enabled Types table displays the Pivotal types and properties that will be synchronized with corresponding types and properties in AccuRev, and the direction in which changes will flow. The default direction is Bi-directional -- changes made in one system will be synchronized in the other, and vice versa. (Note that in the Connect.xml, AccuRev is considered the "source" system and Pivotal is considered the "target" system.)

    Property Mappings

    The following tables list the default property mappings for Release-Cycle, Defect, Requirements, and Test asset types.

    Release-Cycle <--> Sprint Property Mappings

    Pivotal Property AccuRev Agile Property
    name Name
    start-date StartDate
    end-date EndDate
    the value of the internal name that corresponds to the AccuRevIssueKey field you recorded in Step 4. ExternalID
    the value of the internal name that corresponds to the AccuRevIssueLink field you recorded in Step 4. ExternalURL

    Defect <--> Change Request Property Mappings

    Note that you must also create value maps for the Severity and Status properties as described in the Value Maps section that follows this step.

    Pivotal Property AccuRev Agile Property
    name Synopsis
    description Description
    severity Severity
    status Status
    detected-by CreatedUserID
    the value of the internal name that corresponds to the AccuRevIssueKey field you recorded in Step 4. ExternalID
    the value of the internal name that corresponds to the AccuRevIssueLink field you recorded in Step 4. ExternalURL

    Requirement <--> Requirements Property Mappings

    Note that you must also create value maps for the Status properties as described in the Value Maps section in the Value Maps section that follows this step.

    Pivotal Property AccuRev Agile Property
    name Name
    req-comment Description
    status Status
    owner CreatedUserID
    the value of the internal name that corresponds to the AccuRevIssueKey field you recorded in Step 4. ExternalID
    the value of the internal name that corresponds to the AccuRevIssueLink field you recorded in Step 4. ExternalKey

    Test <--> Task Property Mappings

    Pivotal Property AccuRev Agile Property
    name StTaskName
    description RichDescription
    owner CreatedUserID
    the value of the internal name that corresponds to the AccuRevIssueKey field you recorded in Step 4. ExternalID
    the value of the internal name that corresponds to the AccuRevIssueLink field you recorded in Step 4. ExternalURL

    Value Maps

    In this section of the connection configuration, you review the value maps for Defect and Requirement asset types.

  3. On the Types and Properties page, expand the node for the asset type whose value map you wan to review -- either Defect or Requirement.
  4. Locate the property whose values you want to review and click the Value Maps button.

    5. The Value Maps dialog box appears.

  5. Review the value maps for the following properties and, if needed, change them.

    6. Defect -- Severity Value Map

    Pivotal Value AccuRev Agile Value
    1-Low Low
    2-Medium Medium
    3-High High

    Defect -- Status Value Map

    Pivotal Value AccuRev Agile Value
    New New
    Open Open
    Fixed Fixed
    Rejected Cannot Reproduce

    Requirement -- Status Value Map

    Pivotal Value AccuRev Agile Value
    Blocked Submitted
    Failed Rejected
    Passed Accepted
    N/A Draft

    Project Maps

    In this section of the connection configuration, you map the AccuRev and Pivotal projects you want to synchronize.

  6. On the Update Connect window, click the Next button.

    7. The Project tab appears. You should see default values "PIVOTALConnector" and "Test". Unless these happen to be the names of your AccuRev and PIVOTAL projects, you will need to change them.

  7. Locate the row that represents the Pivotal project you are mapping to AccuRev.
  8. For the Pivotal data source (Mapped Source column), click the dropdown control twice and choose the appropriate project from the list that appears.
  9. Do the same for the value in the Micro Focus Hub Project field.
  10. Click Save to save your changes.

Step 6. Setting the Asset Type Keys

In the the final stage of the connection configuration, you review the keys that are used to establish links between records in AccuRev and Pivotal. You perform the following procedure for each asset type you are synchronizing: Release-Cycle, Defect, Requirement, and Test.

  1. On the Types and Properties tab of the Update Connect window, select the asset type whose key you want to review and click the Edit button.

    2. The Edit Type dialog appears.

  2. Click the Advanced tab.
  3. In the Mapped External Type ID Property field, enter the value of the internal name that corresponds to the AccuRevIssueKey field recorded in Step 4. Finding the Internal Name for AccuRevIssueKey and AccuRevIssueLink User Fields.. You should not need to change the value of the Micro Focus Hub External Type ID Property field.
  4. Repeat steps 1 - 3 for the remaining asset types.
  5. Click OK.

Next Steps

Once you have successfully configured the Pivotal Connector, your pivotalSync connection should start running. Refer to the Micro Focus Connect Dashboard for ongoing status information for pivotalSync and any other connections you have configured.

 

Top

Known Issues

Fallback users are not supported

When selecting a fallback user a message will state there are no users.

 

Top

Technical Notes

There are no technical notes for this release.

 

Top

Need assistance with the product?

Get support enables you to open a support incident or to submit a bug. You can also browse many helpful support resources.

 

Top