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
Rally
, complete the following requirements:
- Install the Agile Add-in Content:
- Navigate toAdministration,Studio,Content Add-InsinClassic PPM.
- Search forAgile 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.
- ClickAgile Addinand check theStatusfield.If the Status field showsInstalled, exit this procedure and move to the next prerequisite. If the Status field showsUpgrade Ready, continue with the next step.
- Click theItemstab. SelectUpgrade Readyin theStatusfield and clickFilterThe list of content items that are ready to be upgraded is displayed.
- Do one of the following:
- If you do not have custom configurations for theProjectProperties - GeneralandProject Properties - Settingsviews, select all the content items in the list and clickInstall.
- If you have custom configurations for theProject Properties - GeneralandProject Properties - Settingsviews, follow these steps:
- 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. - Manually configure the above project properties views inClassic PPMStudio. See Project Views section for information on the changes that you need to configure.
- Wait for the selected items to install.
- Enable REST API:The Synchronize Agile Central job uses theClarityREST APIs to synchronize data betweenClarityandRally:
- Navigate toAdministration,General Settings,System OptionsinClassic PPM.
- Search for theREST API Statusoption and ensure that it isEnabled.
Configure Integration Attributes
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
:
- ClickAdministration,General Settings,Integrations.
- ClickNew.
- Update the following fields:
- Integration Name and Integration ID:Defines a name and ID for the integration. You can create multiple integrations betweenClarityandRallywith 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 theRallyURL that you want to integrate with.
- Integration Instance:Defines the integration instance to connect to such as aRallyworkspace ID. The Synchronize Agile Central job uses this ID to synchronizeClarityprojects withRallyinvestments or portfolio items. For information about fetching the Workspace ID, see the Get theRallyWorkspace ID section.
- Referrer URLDefines the identity provider URL to use for the timesheet integration withRally. The value in this field is used only if you are not using the same URL as theIntegration URLfield. See Configure SSO forClarityTimesheet Integration withRally.
- Authentication Type
- Basic:Select this authentication method for legacy integrations withRallyOn-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 withRallySaaS, we recommend that you use the API key authentication for secure access.
- API Key:Select this authentication method to integrate withRallyOn Demand. Provide theRallyAPI Key that maps to the integration record. To create this key, see Create aRallyAPI Key. We recommend that you create a unique API Key for each Integration record inClarity. The API Key is associated with aRallyuser that has the required privileges to update theRallyworkspace. Whenever you synchronize information fromClaritytoRally, the updates appear for theRallyuser that is associated with the API Key. Even though the username and password fields appear, values are not needed when using this authentication type.
- (Optional) To connect toRallyusing a proxy server in aClarityon-premise environment, specify the following proxy server information. If you are accessingRallythrough a non-authenticated proxy, provide the proxy server and port details only. If you are accessingRallythrough an authenticated proxy, also provide the proxy username and password. After defining the proxy server information, restart theClarityapp 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 toRallyis unsuccessful, review the proxy server logs to make sure the IP address is allowed.
- ClickSave.The Agile Central tab appears. The tab appears only if the Agile add-in is installed.
- Click theAgile Centraltab. ForIntegration Type, select one of the following options based on your decision in the planning phase:
- SelectPortfolio Itemto integrateClarityprojects withRallyportfolio items and clickSave. TheIntegration Policytab appears.
- SelectInvestmentto integrate aClarityproject withRallyinvestments and clickSave. ThePortfolio Item Hierarchytab appears.For more information about the integration types, see Determine the Integration Type.
- Create the following defaults for tasks:
- Task Open for Time Entry:Specifies that the tasks created inClarityare 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 inClarity. 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 inClarity.
When a parentClaritytask 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 inClaritycannot have actuals or assignments. The situation applies when synchronizing user stories or portfolio hierarchy items fromRallytoClaritytasks. - ClickSave.
- Depending on the type of integration you create, complete one of the following tasks:
- To integrate withRallyinvestments, complete the steps described in the section.
- To integrate withRallyportfolio items, complete the steps described in the section.
Define the Portfolio Item Hierarchy (Investment-Level Integrations Only)
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.
Clarity
. For information on getting the ordinal value for each portfolio item type, see the Get the Portfolio Item Type Ordinals sectionFollow these steps:
- ClickNewto create a row for each level in the portfolio item hierarchy that exists in theRallyworkspace.
- Enter the portfolio item type name such as epic, initiative, or feature. The value must match exactly the portfolio item type name in theRallyworkspace.
- Enter the portfolio item type hierarchy level or ordinal as it is defined in the workspace.
- (Optional) Select theCreate and Sync Portfolio Itemsflag to bring the portfolio item level toClarityas a task when the synchronization job runs. Select only the levels that are needed. You can skip levels in the hierarchy.
- Proceed to define an Agile Integration Owner.
Define the Integration Policy (For Portfolio Item Integrations Only)
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
:
- On theIntegration Policytab, specify the following integration policy details:
- Portfolio Item Type Map (Project):Defines the portfolio item type that you want to map toClarityprojects (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 toClaritytasks (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:
- ClaritytoRally
- Bidirectional
RallytoClarityintegration direction, the portfolio item typedoes nothave 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 inClarity. The task has the same name as the project and all the details fromRallyare rolled up to that task during synchronization.Do not change the value for thePortfolio Item Type Mapfields for projects and tasks after the initial synchronization. Changing either value can break the connection withRally. - Create and Sync Tasks:Specifies whether to synchronize theClaritytasks with theRallyportfolio items.
- Select the integration direction in theCreate Directionfield. 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 withRally. For each task marked as Synchronize, a corresponding portfolio item is created inRally.
- Create and Sync Team:Specifies whether to synchronize theClarityproject team with the users assigned toRallyportfolio items.
- Team Open for Time Entry:Specifies whether the team members that are synchronized fromRallyare open for time entry inClarity. Select one of the following options for the integration instance:
- Yes: All the resources that are added to theClarityproject team fromRallyare open for time entry.
- No: All the resources that are added to theClarityproject team fromRallyare 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 theClarityproject team fromRallyare open for time entry.
- Specify theDefaultandRallyOwner IDDefaultthat you fetched fromRallyProject IDRally.
- ClickSave.The integration configuration is completed.
- Proceed to define an Agile Integration Owner.
Import the Signed Certificate (On-Premise Only)
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.
- If you obtain your signed certificate from a third-party vendor, import it to theRallyon-premise console. SeeRallyControl Panel.
- Import the same certificate into the JDK/JRE path for yourClarityenvironment:
- Navigate to the JDK/JRE file location in thebindirectory on yourClarityenvironment.
- Go tocacertsand insert the signed certificate with the following command:keytool -import -keystore cacerts -alas <adcert> -file <certificate.cer> -keyalg RSA -trustcacerts -storepass changeit
- Restart services for bothRallyandClarity.
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
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:
- InClassic PPM, clickAdministration,Project Management,Settings.
- Select a user as an Agile Integration Owner (for example, admin) and save.
- 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)
- Assign the following access rights to the integration owner for investment type integrations:
- Agile Central Investment - Create
- Agile Central Investment - Edit All
- 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
- Depending on what data you are pulling fromRallyto send toClarity, 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
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 inRallyusing information from theClarityproject. Use the job for integrating withRallyinvestments.
- Synchronize Agile Central:Run this job to synchronize projects withRallyportfolio items and investments. Use the job for integrating withRallyinvestments and portfolio items.
Clarity
projects that have the Synchronize option selected and an Agile System defined in their agile summary. See Jobs Reference for details.Next Step: