Clarity Connections - Rally Integrations

ccppmop1593
Organizations can use the new and improved
Clarity
-Rally integration to ensure data flows seamlessly between the two applications.
The new and improved
Clarity
-Rally integration is:
  • Easily extensible and configurable: You can map objects and attributes between
    Clarity
    and Rally to ensure the integration meets your specific requirements.
  • Simple to maintain: The integration can be set up and maintained by
    Clarity
    administrators who have basic Classic PPM knowledge.
  • Validated and Supported by Broadcom: You don’t need to perform regression testing after every release.
Let’s review some key steps you need to perform to leverage this integration.
  1. Complete the relevant prerequisites to configure the integration.
  2. Create an Integration Object to integrate
    Clarity
    with a specific Rally instance.
  3. Create an Integration Mapping.
  4. Run the Import Integration Mapping job, to fetch all Rally portfolio item type objects and their associated attributes.
  5. Define valid Object mappings.
  6. Define valid Lookup Mappings.
  7. Define valid Field mappings.
  8. Specify a
    Clarity
    Investment that would map to an Object in Rally.
  9. Execute the Synchronized Mapped Information job to synchronize data between
    Clarity
    and Rally.
  10. Review the staging tables to understand the changes made in Rally and
    Clarity
    .
Review each of these steps in detail.
2
Integration Prerequisites
You need to complete the following steps before you configure the new
Clarity
-Rally integration.
  1. Assign the Integration Mapping - Navigate access right to the administrators who will configure the
    Clarity
    -Rally integration. Users with the Integration Mapping - Navigate right will be able to view and access the Integrations tile on the Administration page. To learn more about this access right, see Access Rights documentation.
  2. Ensure the latest version of the PMO-Accelerator content add-in is installed. With the latest version of the PMO-Accelerator installed,
    Clarity
    will include the ‘Rally Object ID’ and the ‘Integration Mapping’ attributes for configuration in Projects, Ideas, and Custom Investments.
Creating an Integration Object in Classic PPM
You can configure the new
Clarity
-Rally integration by creating an integration object. You create an integration object from the Integrations page in Classic PPM, which is the one-stop shop to define and maintain all integration information.
Linked
The key pieces of information you need to create an integration object are:
  • Integration URL
  • Integration Instance
  • Integration API Key
  • Proxy port
Follow these steps:
  1. Log in to Classic PPM.
  2. Click
    Administration
    ,
    General Settings
    ,
    Integrations
    .
  3. Click
    New
    .
  4. Complete the following fields and click
    Save
    .
Field Name
Description
Areas
The software application or business area of the vendor (for example, Agile).
Vendor
The company name with which
Clarity
is integrating (for example, Rally).
Supplier
The company name that is implementing the integration (for example, Broadcom).
Integration URL
The URL for the integration instance (for example, the Rally instance URL).
Integration API Key
The key that is used to access and retrieve data from Rally
Integration Instance
The Rally workspace ID
Create an Integration Mapping in
Clarity
After creating an Integration Object, create an Integration Mapping.
Linked
Follow these steps:
  1. Log into
    Clarity
    .
  2. Click
    Administration
    and select the
    Integrations
    tab to open the Integrations page.
  3. Click Add Row and enter the name of the integration mapping.
    In this release, you cannot use special characters while specifying the Integration Mapping name. If you use a special character such as "&" the Synchronize Mapped Information job will complete with an error and the Import Staging Tables job would fail.
  4. In the Integration column, select the relevant integration object.
  5. The Integration Mapping is now available.
Run the Import Integration Mapping Job in Classic PPM
The Import integration mapping job in Classic PPM enables
Clarity
to retrieve the portfolio item type objects and supported attributes from the configured Rally workspace. It also fetches the Milestones, Investment Categories, State, and Project lookups from Rally. Once imported, the objects and fields are available in the Rally Objects tab in
Clarity
.
Follow these steps:
  1. Log into
    Clarity
    .
  2. Click
    Home
    ,
    Reports and Jobs
    ,
    Jobs
    to open the Jobs tab.
  3. Ensure you have selected
    Available Jobs
    in the drop-down list and open the
    Import Integration Mappings
    job.
  4. Select the relevant Integration Mapping and click
    Submit
    to run the integration immediately. You can also schedule this job to run at a later date.
After the job is successfully executed, perform the following steps to view the various portfolio item type objects from Rally.
Linked
  1. Log into
    Clarity
    .
  2. Click Administration and select the
    Integrations
    tab to open the Integrations page.
  3. Open the relevant integration mapping and select Rally Objects to view the various objects imported from Rally.
Define Object Mappings in
Clarity
Linked
You can map selected
Clarity
investments (Projects, Ideas, and Custom Investments) to selected Rally Portfolio items.
Consider an example where an organization has finalized its strategy and used Custom Investments in
Clarity
to create Themes, Business Epics, and Business Outcomes. These investments can be mapped to Themes, Epics, and Capabilities in Rally. If the organization has created individual projects in
Clarity
, they can also map them to a relevant portfolio item type such as a project in Rally.
Follow these steps:
  1. Log into
    Clarity
    .
  2. Click
    Administration
    and select the
    Integrations
    tab to open the Integrations page.
  3. Open the relevant integration mapping and navigate to the
    Object Mappings
    tab.
  4. Click the Add Row icon and enter the following details
    1. Name: Provide the name of the object mapping
    2. Rally Object: Select the Rally object that you want to map to the
      Clarity
      investment
    3. Direction: Select
      Clarity
      to Rally. In this release, the integration enables you to create and update an instance of a portfolio item type in Rally, associated with an investment in
      Clarity
      . That means you will be to create a feature in Rally associated with an investment in
      Clarity
      . However, if you create a feature or any other portfolio item type instance in Rally, the integration will not allow you to create an investment in
      Clarity
      .
After you define your Object Mapping, you are now ready to map lookups between
Clarity
and Rally. The Lookup Mapping helps you ensure lookups are synchronized between
Clarity
and Rally.
Create Lookup Mappings
Linked
The Import Integration Mappings job fetches the Milestones, Investment Categories, Date, and Project lookups from Rally and stores them in Clarity. These (4) dynamic lookups are now available as a part of the PMO Accelerator add-in and will be available to you when you install this add-in.
You can now perform the following actions to map lookups:
  • Leverage existing Rally Lookups imported into Clarity: Create custom attributes in Clarity that leverage the Rally Investment Categories, Rally Milestones, Rally Projects, and Rally States lookups. You can then use field mappings to map these custom attributes to the relevant lookups in Rally. For example, you can create a Clarity Project Milestone field that leverages the Rally Milestone lookup. You can then leverage Field Mappings to map the Clarity Project Milestone field to the Rally Milestone field in Rally.
  • Use the Lookup Mapping tab to configure other lookups: You can use the Lookup Mapping tab to map lookup values in Clarity with Lookup values in Rally enabling data synchronization control. For example, you can map the Investment Category lookup in Rally to the Cost Type lookup in Clarity. You can then define the field mapping to ensure these lookups are updated when their values are updated in Clarity or Rally.
Follow these steps to map the values of lookups in Clarity and Rally:
  1. Log into
    Clarity
    .
  2. Click
    Administration
    and select the
    Integrations
    tile to open the Integrations page.
  3. Open the relevant integration mapping and select the Lookup Mapping tab.
  4. Click
    New Mapping
    and enter the following details
    • Select the relevant Clarity lookup.
    • Select the target Rally lookup.
    • Enter the Name of the lookup mapping.
  5. Click
    Create
    to save the new mapping.
  6. Select the mapping and click
    DETAILS
    to open the Details Panel.
  7. Click the
    Clarity to Rally
    tab and select the target Rally values for associated Clarity values.
  8. Click the
    Rally to Clarity
    tab and select the target Clarity values for associated Rally values.
  9. After the mapping is complete, close the details panel.
Some of the key points to remember when you leverage the Lookup Mapping capability are:
  • The Administrator needs to install the new PMO accelerator to ensure that the four new dynamic lookups are available to Clarity users.
  • Administrators need to create dynamic lookups attributes, at either the Clarity Investment, Object, Idea, or Custom Investment levels depending on their requirements.
  • If you are creating a static value lookup or multi-value lookup to leverage the four Rally lookups, you need to use the following lookup parameter mappings:
    • Lookup Parameter: Im_id_constrain and Inv_code_constrain
    • Object Attribute ID: obj_int_mapping and Unique_code
  • When you map the Rally Projects, Milestones, States, or Investment Categories lookup to a Clarity custom lookup, the administrator does not need to use the Lookup Mapping tables, but can directly synchronize the values to the target system.
  • It is recommended the Rally States, Projects, and Investment categories lookups are associated with a
    Clarity
    single-value lookup attribute and the Rally Milestones lookup be associated with a
    Clarity
    multi-value lookup attribute.
  • If a
    Clarity
    parameterized lookup is used for Lookup Mapping, the
    Clarity
    to Rally and Rally to
    Clarity
    lookup options will not be displayed in the DETAILS panel.
  • You can synchronize a single-value Clarity number lookup to a Rally string field. The synchronization will not work if:
    • The
      Clarity
      number lookup is configured as a multi-value lookup.
    • The
      Clarity
      number attribute has a comma.
  • If a
    Clarity
    lookup value is marked inactivate, the following actions are possible:
    • If an inactivate value is mapped to a Rally value, the existing Lookup Mapping configuration will not be modified or updated.
    • If an inactivate value is not mapped to a Rally value, the Clarity value will be removed (deleted) from the existing Lookup Mapping configuration
  • If a Rally lookup value is marked inactivate or deleted,
    Clarity
    will display the (inactivate or deleted) Rally value within the Lookup Mapping configuration pages.
You have now mapped the lookups in Clarity and Rally to support data synchronization between both systems. Next, you need to map fields between Rally and Clarity to ensure the data synchronization is accurate.
Define Field Mappings in
Clarity
Linked
Defined field mappings specify how data is exchanged between
Clarity
investments/fields and Rally portfolio items/fields. Field mappings are always associated with an object mapping. Consider the following object and field mapping techniques:
  • Review the Data Type compatibility table to ensure you are mapping supported field types.
    • The table is available on the Data Type Compatibility tab and can be accessed from the Integrations page.
      Linked
  • Specify the direction of data flow when you define the mapping.
    • You can define a mapping where data flows from a field in
      Clarity
      to a field in Rally
    • You can also define a mapping where data flows from a field in Rally to a field in
      Clarity
      .
    • Bi-directional integration is supported by using the
      Both
      option in the Supported direction column. This means that values in
      Clarity
      and Rally will be synchronized with data changes in either of the systems. The "Both" option can only be used when you use
      Update
      in the Sync Option column.
    • You cannot include the same field in multiple mappings.
  • Select the relevant Sync Option.
Follow these steps:
  1. Log into
    Clarity
    .
  2. Click
    Administration
    and select the
    Integrations
    tab to open the Integrations page.
  3. Open the relevant integration mapping and navigate to the Object Mappings tab.
  4. Select the relevant Object Mapping, click
    DETAILS
    and select the
    Field Mappings
    tab.
  5. Click Expand to open the
    Field Mappings
    window.
  6. Enter the following details:
    1. Direction - Select
      Clarity
      to Rally,  Rally to
      Clarity
      , both depending on your requirement.
    2. Clarity
      Field - Select the relevant
      Clarity
      field. This field is associated with the investment you identified during object mapping.
    3. Rally Field - Select the Rally field to be mapped to the
      Clarity
      field. Ensure you are following the Data type compatibility guidelines while mapping the fields.
    4. Sync Option - Select from the Create, Update, Create and Update options. To learn more about these options, see Execute the Synchronize Mapped Information Job.
  7. When
    Clarity
    validates the field mapping, the Data Type columns are populated and saved.
  8. You will see an error message if:
    1. The fields being mapped are not compatible
    2. Either of the fields has an existing mapping
Select
Clarity
Investments to Sync with Rally
Now that you have set up the integration and defined the relevant mappings, you can select which specific
Clarity
investments will sync with Rally. In this release, you can select specific
Clarity
projects, custom investments, and ideas to sync with Rally.
Follow these steps:
  1. Log into
    Clarity
    .
  2. Navigate to the relevant investment page and select the grid layout.
  3. Use the column picker to add the
    Rally Object
    and
    Integration Mapping
    attributes to the grid.
  4. Select the relevant integration mapping that you want to associate with the investment.
After you run the Synchronized Mapped Information job to synchronize the data between
Clarity
and Rally successfully, the Rally Object field will be auto-populated.
Run the Synchronize Mapped Information Job
The Synchronize Mapped Information job in Classic PPM enables administrators to synchronize the mapped information between
Clarity
and Rally. Depending upon the configured direction and Sync Option, the job may perform the following operations:
Direction
Sync Option
Expected Behaviour
Both
Update
The job will:
  1. Synchronize data for mapped objects and fields when data changes are detected in either system.
  2. Populate the respective staging tables.
Clarity
to Rally
Create
If the mapped Object does not exist in Rally, this job:
  1. Creates and populates mapped Rally objects and fields
  2. Populates the To Rally Staging Table
  3. Populates mapped
    Clarity
    Investments with their respective Rally Object ID.
Clarity
to Rally
Create and Update
If the mapped Object does not exist in Rally, this job:
  1. Creates and populates mapped Rally objects and fields
  2. Populates To Rally Staging Table
  3. Updates Rally Objects (and Fields) tables in
    Clarity
    .
In subsequent runs, this job:
  1. Updates mapped Rally objects and fields
  2. Populates To Rally Staging Tables
  3. Updates Rally Objects (and Fields) tables in
    Clarity
    .
Clarity
to Rally
Update
If the mapped Object exists in Rally, this job
  1. Updates mapped Rally objects and fields
  2. Populates the To Rally Staging Tables
  3. Updates Rally Objects (and Fields) tables in
    Clarity
Rally to
Clarity
Create
Not supported
Rally to
Clarity
Create and Update
Not supported
Rally to
Clarity
Update
If the mapped Object exists in
Clarity
, this job
  1. Updates mapped
    Clarity
    objects and fields
  2. Populates the To
    Clarity
    staging table
  3. Updates Rally Objects (and Fields) tables in
    Clarity
Follow these steps:
  1. Log into
    Clarity
    .
  2. Click
    Home
    ,
    Reports and Jobs
    ,
    Jobs
    to open the Jobs tab.
  3. Ensure you have selected Available Jobs in the drop-down list and open the
    Synchronize Mapped Information
    job.
  4. Select the relevant Integration Mapping and click
    Submit
    to run the integration immediately.
After this job is successfully executed,
Clarity
automatically executes the Import Staging Tables job to move the data from the staging table to
Clarity
.
You can schedule the Synchronize Mapped Information to run at regular intervals. However, if you manually trigger the Synchronize Mapped Information job then the scheduled jobs will not execute concurrently.
Review the Staging Table in
Clarity
Linked
Every integration mapping has associated To Rally and To
Clarity
  staging tables in
Clarity
. The staging tables are only accessible to members of the PMO System Admin group. If you want to manually provide access to the staging table, you can use assign the following access rights to a user or group:
  • <Integration Mapping Name> - Create
  • <Integration Mapping Name> - Delete All
  • <Integration Mapping Name> - Edit All
  • <Integration Mapping Name> - View All
  • <Integration Mapping Name> - Xog Access
In this release, you can use the Staging table to:
  • Review all the data that is copied from Rally to
    Clarity
    and
    Clarity
    to Rally after the Synchronize Mapping Information job is successfully executed.
  • Review the Error messages in case the data synchronization fails
Follow these steps:
  1. Log into
    Clarity
    .
  2. Click
    Administration
    and select the
    Integrations
    tab to open the Integrations page.
  3. Open the relevant integration mapping and navigate to the To Rally or To
    Clarity
    tabs. You will only see the records in this table if you have the relevant access rights.
  4. Add the relevant columns to the grid layout to review the status of the records that have been processed. Some key columns you can add are:
    1. Job Run ID
    2. Status
    3. Clarity
      Object
    4. Clarity
      Object Name
    5. Rally Object
    6. Rally Object
    7. Name
    8. Error Message
Key Points to Remember
:
  • The administrative user must log out and log in to view the Staging Tables.
  • The staging table data is removed from
    Clarity
    every time the Synchronize Mapped Information job is run.
  • After the Synchronize Mapped Information job is run, the user will be auto-granted access to the To
    Clarity
    and To Rally tables.
  • The Integration Mapping (view, edit, and delete) Global Access rights are automatically added to the PMO System Administrator group. This back-end process enables access to the Staging Tables.
Data Sync Flow for Rally Integration
When you run the Synchronize Mapped Information job after setting up the Rally integration, it checks the associated
Clarity
investments to see if the Rally Object field is updated.
  • The Rally Object field is empty prior to
    Clarity
    creating a new Rally portfolio item. When the sync job is run, the Rally Object field for the relevant investment in
    Clarity
    is updated. The next time you execute the job,
    Clarity
    updates the relevant fields depending on your field mapping. The job also updates the relevant staging tables.
  • If the Rally Object field is not empty,
    Clarity
    directly updates the relevant fields based on the display mapping. The job also updates the relevant staging tables.
Key Points to Consider While Leveraging the Integration
  • Whenever a
    Clarity
    field is updated with the value from a mapped Rally field, the user who runs the Synchronized Mapped Information job is listed in the audit log.
  • Customers can continue to use both the new Rally integration and the Rally Portfolio Item Hierarchy, Investments, or (
    Clarity
    ) Timesheet integrations if warranted.
    • If a customer has configured an "Agile" integration, there is no impact to that existing integration after the upgrade
    • The new jobs (e.g., Import Integration Mappings, Synchronize Mapped Information, & Import Staging Tables) are set as incompatible with the old jobs (e.g., Synchronize Agile Central & Create Agile Central Investments) to prevent them from running simultaneously
  • If the Import Integration Mapping job is not run after creating a new Integration Mappings instance, the
    Clarity
    and Rally Objects will not be available in their respective pull-downs
    • If you create new custom attributes (in either
      Clarity
      or Rally), the Import Integration Mapping job must be run to ensure they are available in the field mapping grid
  • Rally Fields Not Updating
    • If a field in either system is governed by business logic, using that system as the target is not supported
      Linked
  • Synchronize Mapped Information job only returns changes
    • The first time the Synchronize Mapped Information job is run,
      Clarity
      and Rally are in sync
    • Following the job run, a
      Clarity
      user updates the ‘% Complete’ field (which is sourced from Rally)
    • From a performance perspective, the next time the Synchronize Mapped Information job is run, since there has been no change in Rally, the system will not update the
      Clarity
      ‘% Complete’ field and now
      Clarity
      and Rally are no longer in sync
    • The
      Clarity
      ‘% Complete’ field will be synced only when the mapped portfolio item is updated in Rally
    • Until that point, these mapped fields will continue to be out of sync
  • You can use the following options to troubleshoot issues synchronization issues:
    • You can leverage the job log to troubleshoot
      Clarity
      and Rally data exchange.
    • You can review the
      Clarity
      BG logs.
    • You can also check synchronization errors on the staging tables.
    • You can consider logging the following packages for troubleshooting:
      • com.ca.ppm.integrations.jobs
      • com.ca.ppm.integrations.systems
      • com.ca.ppm.integrations.http.client