Configure the Integration
ClarityAdministrator, configure the integration between
Rallyto enable Project Managers to associate a
To integrate with
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:
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.
- Project Properties - General
- Project Agile Integration Settings
- 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.
The integration attributes define the
Configure Integration Attributes
Rallysystem 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.
- 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:
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.
- 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.
- Depending on the type of integration you create, complete one of the following tasks:
If you are integrating with investments, complete the steps in this section. On the
Define the Portfolio Item Hierarchy (Investment-Level Integrations Only)
Portfolio Item Hierarchytab, specify the portfolio items and their hierarchy levels or ordinals that you want to associate with
Rallyinvestments. 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 section
Follow 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.
If you are integrating with portfolio items, complete the steps in this section. The documentation reflects a
Define the Integration Policy (For Portfolio Item Integrations Only)
Rallyportfolio hierarchy that is available and supported by default.
Rallyallows 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
Clarityprojects. 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.
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:
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.
The following procedure applies only to on-premise integrations of
Import the Signed Certificate (On-Premise Only)
RallySaaS. Customers who install
Rallyon-premise have the option to generate their own certificate, purchase a certificate from a third party vendor, or use the
Rallycertificate that is installed by default. On-prem
Clarityare not supported.
Clarityon-premise or SaaS integrations are only supported with
- 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
Rallyjob 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
Define the Agile Integration Owner
Clarityuser as the Agile Integration Owner who can schedule and run the background sync jobs. The jobs synchronize data between
Rallyinvestments, portfolio items, and
Clarityprojects and tasks. The jobs also create investments and other portfolio items in
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)
Depending on the frequency at which you want to synchronize the data between
Schedule Background Jobs
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.
Clarityprojects that have the Synchronize option selected and an Agile System defined in their agile summary. See Jobs Reference for details.