Configure the Integration

As a
Clarity
Administrator, configure the integration between
Clarity
and
Rally
to enable Project Managers to associate a
Clarity
project with
Rally
.
2
Verify Prerequisites
To integrate with
Rally
, complete the following requirements:
  • Install the Agile Add-in Content:
    1. Navigate to
      Administration
      ,
      Studio
      ,
      Content Add-Ins
      in
      Classic PPM
      .
    2. Search for
      Agile Addin
      . If you do not find the add-in, contact your administrator to install the add-in. For information on installing the add-in, see Add-Ins and Integrations.
      If you are a SaaS customer, create a support ticket to request the Agile add-in installation. During the Agile add-in installation, attributes are created in the Project and Task objects. The new attributes are protected and you cannot add, modify, or delete them from the data warehouse.
    3. Click
      Agile Addin
      and check the
      Status
      field.
      If the Status field shows
      Installed
      , exit this procedure and move to the next prerequisite. If the Status field shows
      Upgrade Ready
      , continue with the next step.
    4. Click the
      Items
      tab. Select
      Upgrade Ready
      in the
      Status
      field and click
      Filter
      The list of content items that are ready to be upgraded is displayed.
    5. Do one of the following:
      • If you do not have custom configurations for the
        Project
        Properties - General
        and
        Project Properties - Settings
        views, select all the content items in the list and click
        Install
        .
      • If you have custom configurations for the
        Project Properties - General
        and
        Project Properties - Settings
        views, follow these steps:
        1. Exclude the following content items and install the rest of the items in the list:
          • Project Properties - General
          • Project Agile Integration Settings
          Do NOT install the above content items. If you install them, your custom configurations for the corresponding Project Properties pages will be lost permanently and cannot be retrieved.
        2. Manually configure the above project properties views in
          Classic PPM
          Studio. See Project Views section for information on the changes that you need to configure.
    6. Wait for the selected items to install.
  • Enable REST API:
    The Synchronize Agile Central job uses the
    Clarity
    REST APIs to synchronize data between
    Clarity
    and
    Rally
    :
    • Navigate to
      Administration
      ,
      General Settings
      ,
      System Options
      in
      Classic PPM
      .
    • Search for the
      REST API Status
      option and ensure that it is
      Enabled
      .
Configure Integration Attributes
The integration attributes define the
Rally
system that you want to integrate with, the connection parameters, and the data that you want to synchronize between the two systems.
Follow these steps
:
  1. Click
    Administration
    ,
    General Settings
    ,
    Integrations
    .
  2. Click
    New
    .
  3. Update the following fields:
    • Integration Name and Integration ID:
      Defines a name and ID for the integration. You can create multiple integrations between
      Clarity
      and
      Rally
      with different settings - for example, to connect to different workspaces, use different integration types and integration directions. Hence, provide a meaningful name to easily identify it later.
    • Integration URL:
      Specifies the
      Rally
      URL that you want to integrate with.
    • Integration Instance:
      Defines the integration instance to connect to such as a
      Rally
      workspace ID. The Synchronize Agile Central job uses this ID to synchronize
      Clarity
      projects with
      Rally
      investments or portfolio items. For information about fetching the Workspace ID, see the Get the
      Rally
      Workspace ID
      section.
    • Referrer URL
      Defines the identity provider URL to use for the timesheet integration with
      Rally
      . The value in this field is used only if you are not using the same URL as the
      Integration URL
      field. See Configure SSO for
      Clarity
      Timesheet Integration with
      Rally
      .
    • Authentication Type
      • Basic:
        Select this authentication method for legacy integrations with
        Rally
        On-Premise (no longer supported). Provide a username and password to use for authentication. When using this authentication type, do not specify an API key. Though you can use basic authentication with
        Rally
        SaaS, we recommend that you use the API key authentication for secure access.
      • API Key:
        Select this authentication method to integrate with
        Rally
        On Demand. Provide the
        Rally
        API Key that maps to the integration record. To create this key, see Create a
        Rally
         API Key
        . We recommend that you create a unique API Key for each Integration record in
        Clarity
        . The API Key is associated with a
        Rally
        user that has the required privileges to update the
        Rally
        workspace. Whenever you synchronize information from
        Clarity
        to
        Rally
        , the updates appear for the
        Rally
        user that is associated with the API Key. Even though the username and password fields appear, values are not needed when using this authentication type.
  4. (Optional) To connect to
    Rally
    using a proxy server in a
    Clarity
    on-premise environment, specify the following proxy server information. If you are accessing
    Rally
    through a non-authenticated proxy, provide the proxy server and port details only. If you are accessing
    Rally
    through an authenticated proxy, also provide the proxy username and password. After defining the proxy server information, restart the
    Clarity
    app and bg services.
    • Proxy Server:
      Defines the name of the proxy server. Provide the full URL starting with http or https.
    • Proxy Port:
      Defines the port for the proxy server.
    • Proxy User Name:
      Defines the user name for connecting to the proxy server.
    • Proxy Password:
      Defines the password for connecting to the proxy server.
      If you do not have the proxy server information, contact your network administrator. If the connection to
      Rally
      is unsuccessful, review the proxy server logs to make sure the IP address is allowed.
  5. Click
    Save
    .
    The Agile Central tab appears. The tab appears only if the Agile add-in is installed.
  6. Click the
    Agile Central
    tab. For
    Integration Type
    , select one of the following options based on your decision in the planning phase:
    • Select
      Portfolio Item
      to integrate
      Clarity
      projects with
      Rally
      portfolio items and click
      Save
      . The
      Integration Policy
      tab appears.
      image2018-11-20_17-36-5.png
    • Select
      Investment
      to integrate a
      Clarity
      project with
      Rally
      investments and click
      Save
      . The
      Portfolio Item Hierarchy
      tab appears.
      image2018-11-20_17-35-46.png
      For more information about the integration types, see Determine the Integration Type.
  7. Create the following defaults for tasks:
    • Task Open for Time Entry:
      Specifies that the tasks created in
      Clarity
      are open for time entry. If you do not select this option, the default setting from the task object definition takes effect.
    • Task Cost Type:
      Defines the default cost type value to use when a task is created in
      Clarity
      . The default value is used only for task creation, not for updates.
    • Task Charge Code:
      Defines the default charge code value to use when a task is created in
      Clarity
      .
    When a parent
    Clarity
    task has actuals, assignments, or both, the integration cannot add a child task under this parent. Instead, the integration adds the child task without a parent. The behavior complies with the rule that summary tasks in
    Clarity
    cannot have actuals or assignments. The situation applies when synchronizing user stories or portfolio hierarchy items from
    Rally
    to
    Clarity
    tasks.
  8. Click
    Save
    .
  9. Depending on the type of integration you create, complete one of the following tasks:
    1. To integrate with
      Rally
      investments, complete the steps described in the section.
    2. To integrate with
      Rally
      portfolio items, complete the steps described in the section.
Define the Portfolio Item Hierarchy (Investment-Level Integrations Only)
If you are integrating with investments, complete the steps in this section. On the
Portfolio Item Hierarchy
tab, specify the portfolio items and their hierarchy levels or ordinals that you want to associate with
Rally
investments. The integration uses the Ordinal field values as follows:
  • Associates a portfolio item type with a position in the portfolio item hierarchy.
  • Determine the type of work item or portfolio item allowed for parents and children.
The Ordinal field value starts with 0 for the lowest level of portfolio item (such as Feature), and increments by 1 for each portfolio item type as you go up in the hierarchy. As an administrator, you are responsible for creating the portfolio hierarchy data in
Clarity
. For information on getting the ordinal value for each portfolio item type, see the Get the Portfolio Item Type Ordinals section
Follow these steps:
  1. Click
    New
    to create a row for each level in the portfolio item hierarchy that exists in the
    Rally
    workspace.
  2. Enter the portfolio item type name such as epic, initiative, or feature. The value must match exactly the portfolio item type name in the
    Rally
    workspace.
  3. Enter the portfolio item type hierarchy level or ordinal as it is defined in the workspace.
  4. (Optional) Select the
    Create and Sync Portfolio Items
    flag to bring the portfolio item level to
    Clarity
    as a task when the synchronization job runs. Select only the levels that are needed. You can skip levels in the hierarchy.
  5. Proceed to define an Agile Integration Owner.
Define the Integration Policy (For Portfolio Item Integrations Only)
If you are integrating with portfolio items, complete the steps in this section. The documentation reflects a
Rally
portfolio hierarchy that is available and supported by default.
Rally
allows you to configure up to five levels of portfolio items in the portfolio hierarchy. The lowest level is P1 and the highest level is P5. You can map to a maximum of two portfolio items to
Clarity
projects. For example, you can map to feature at the P1 level and initiative at the P2 level. In
Clarity
, the P1 level item is mapped to a task and the P2 level item is mapped to a project.
Keep the following information handy:
Follow these steps
:
  1. On the
    Integration Policy
    tab, specify the following integration policy details:
    • Portfolio Item Type Map (Project):
      Defines the portfolio item type that you want to map to
      Clarity
      projects (for example, initiative). You can map a project to any level in the portfolio hierarchy except the lowest level.
    • Portfolio Item Type Map (Task):
      Defines the portfolio item type that you want to map to
      Clarity
      tasks (for example, feature). The portfolio item type must be at the lowest level. For the following integration directions, the portfolio item type has to be contiguous to the portfolio item type that you defined for the Portfolio Item Type Map (Project) field:
      • Clarity
        to
        Rally
      • Bidirectional
      For the
      Rally
      to
      Clarity
      integration direction, the portfolio item type
      does not
      have to be contiguous to the portfolio item type that you defined for the Portfolio Item Type Map (Project) field. If the value for the Portfolio Item Type Map for both project and task is the same, then only one task is created in
      Clarity
      . The task has the same name as the project and all the details from
      Rally
      are rolled up to that task during synchronization.
      Do not change the value for the
      Portfolio Item Type Map
      fields for projects and tasks after the initial synchronization. Changing either value can break the connection with
      Rally
      .
    • Create and Sync Tasks:
      Specifies whether to synchronize the
      Clarity
      tasks with the
      Rally
      portfolio items.
    • Select the integration direction in the
      Create Direction
      field. For more information about the integration direction, see Determine the Integration Direction.
    • The Create Direction field works with the Synchronize option for tasks in a project that is integrated with
      Rally
      . For each task marked as Synchronize, a corresponding portfolio item is created in
      Rally
      .
    • Create and Sync Team:
      Specifies whether to synchronize the
      Clarity
      project team with the users assigned to
      Rally
      portfolio items.
    • Team Open for Time Entry:
      Specifies whether the team members that are synchronized from 
      Rally
      are open for time entry in
      Clarity
      . Select one of the following options for the integration instance:
      • Yes
        : All the resources that are added to the
        Clarity
        project team from
        Rally
        are open for time entry.
      • No
        : All the resources that are added to the
        Clarity
        project team from
        Rally
        are not open for time entry.
      • Select
        : The Open attribute value on the Team Object is considered for determining whether the resources that are added to the
        Clarity
        project team from
        Rally
        are open for time entry.
    • Specify the
      Default
      Rally
      Owner ID
      and 
      Default
      Rally
      Project ID
      that you fetched from
      Rally
      .
  2. Click
    Save
    .
    The integration configuration is completed.
  3. Proceed to define an Agile Integration Owner.
Import the Signed Certificate (On-Premise Only)
The following procedure applies only to on-premise integrations of
Clarity
with
Rally
 SaaS. Customers who install
Rally
on-premise have the option to generate their own certificate, purchase a certificate from a third party vendor, or use the
Rally
certificate that is installed by default. On-prem
Rally
integrations with
Clarity
are not supported.
Clarity
on-premise or SaaS integrations are only supported with
Rally
 SaaS edition.
  1. If you obtain your signed certificate from a third-party vendor, import it to the
    Rally
    on-premise console. See
    Rally
    Control Panel
    .
  2. Import the same certificate into the JDK/JRE path for your
    Clarity
    environment:
    1. Navigate to the JDK/JRE file location in the
      bin
      directory on your
      Clarity
      environment.
    2. Go to
      cacerts
      and insert the signed certificate with the following command:
      keytool -import -keystore cacerts -alas <adcert> -file <certificate.cer> -keyalg RSA -trustcacerts -storepass changeit
  3. Restart services for both
    Rally
    and
    Clarity
    .
If the Synchronize
Rally
job fails with handshake SSL errors, verify both systems are using the same certificate. If the job fails due to an invalid workspace ID or configuration value, verify all the integration property values and enter them again. Complete the remaining setup tasks on this page and run the Synchronize
Rally
job again.
Define the Agile Integration Owner
Define a
Clarity
user as the Agile Integration Owner who can schedule and run the background sync jobs. The jobs synchronize data between
Rally
investments, portfolio items, and
Clarity
projects and tasks. The jobs also create investments and other portfolio items in
Rally
based on
Clarity
projects.
Assign the required access rights to the Agile Integration Owner so they can update the project and associated team and tasks. If the agile summary pages for the project and tasks are secured, assign the secure subpage rights to the Agile Integration Owner.
Follow these steps:
  1. In
    Classic PPM
    , click
    Administration
    ,
    Project Management
    ,
    Settings
    .
  2. Select a user as an Agile Integration Owner (for example, admin) and save.
  3. Assign the following global access rights to the integration owner:
    • API - Access
    • Projects - Navigate
    • Resource - Navigate
    • Project - Edit Management
      (for specific projects, or for all projects)
  4. Assign the following access rights to the integration owner for investment type integrations:
    • Agile Central Investment - Create
    • Agile Central Investment - Edit All
  5. Assign the following access rights to the integration owner for portfolio item type integrations:
    • Portfolio Item Type - Create
    • Portfolio Item Type - Edit All
    • Portfolio Item Type - View All
    • Portfolio Item Type - XOG Access
  6. Depending on what data you are pulling from
    Rally
    to send to
    Clarity
    , assign the following additional rights:
    • Resource - View
      (for specific resources, or for all resources)
    • Resource - Hard Book
      (for specific resources, or for all resources)
Schedule Background Jobs
Depending on the frequency at which you want to synchronize the data between
Clarity
and
Rally
, set up the following jobs to run at scheduled intervals. For information on scheduling jobs, see Run or Schedule a Job.
  • Create Agile Central Investments:
    Run this job to create investments in
    Rally
    using information from the
    Clarity
    project. Use the job for integrating with
    Rally
    investments.
  • Synchronize Agile Central:
    Run this job to synchronize
    projects with
    Rally
    portfolio items and investments. Use the job for integrating with
    Rally
    investments and portfolio items.
The jobs read through all
Clarity
projects that have the Synchronize option selected and an Agile System defined in their agile summary. See Jobs Reference for details.
Next Step: