Integrate PPM tasks with ALM Octane projects

The integration between PPM tasks and ALM Octane projects enables project managers, program managers, portfolio managers, or project stakeholders to view real-time status and progress of agile projects that are run in ALM Octane from within PPM projects.

This section details on how to set up and use the integration.

Add an ALM Octane agile instance

An ALM Octane agile instance is an environment where the ALM Octane connector conveys the data from ALM Octane to PPM.

What integrations does an ALM Octane instance support?

When you add an ALM Octane instance, you will see several icons shown next to the instance name. They are indicative of what kind of integrations an ALM Octane instance can support.

Icon	Meaning
TS	The agile instance supports time sheet integration: you can import effort from ALM octane to PPM time sheets.
WP	The agile instance supports work plan integration: you can link an ALM Octane project with a PPM work plan task.
PE	The agile instance supports portfolio epic integration: you can push a PPM portfolio epic to an ALM Octane project for execution.
AD	The agile instance supports agile data integration: the integration can import agile data from ALM Octane to PPM AGILE_DATA tables, and you can create dashboard datasources and portlets to show the agile data in your dashboard page.
RA	The agile instance supports request-agile entity integration: you can manage ALM Octane agile entities through managing mapped requests in PPM.

Add an ALM Octane instance as an administrator

Click the Administration button in the masthead.
From the Administration menu, click Integrations > Agile Tool Integration.
In the Instances area, Octane line, click the Create Instance button +.

In the General tab, provide the required information.

Field (*Required)	Description
*Instance Name	Specify a unique name for the instance. The instance name should not exceed 50 characters. Do not include special characters such as <>.
*Base URL	URL of the ALM Octane server you want to integrate with PPM. Format of the URL: `http(s)://<server_address>`. Do not end the base URL with a slash. If you have customized the ALM Octane server, make sure you include the port number in the URL as well: `http(s)://<server_address>:<port>`
Proxy Host	Host name of the proxy if you have configured a proxy for the PPM server to access the Internet.
Proxy Port	Port of the proxy if you have configured a proxy for the PPM server to access the Internet.
Use Global Proxy	Select this option to use the proxy specified in the `HTTP_PROXY_URL` parameter.
Client ID Client Secret	Client ID and password of the account used to retrieve agile data and portfolio epic from agile projects in ALM Octane. The account information decides which agile projects you can select in the Request Mapping tab.
*Enable " " ALM Octane project mapping in request agile mapping**	Select this option to allow selecting a wildcard ALM Octane project to match all the ALM Octane projects when mapping PPM request types to Octane entity types. This frees you from creating the same request-agile mapping for each ALM Octane project

Click Save.
Click Test Connection to test the connection with the instance.

If a message appears stating that connection failed, click OK on the message, and then resolve the connection issue.

Tip: If the ALM Octane instance uses a self-signed certificate, the error "sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target" may occur.

To resolve this problem, add the self-signed certificate to the cacerts file of the target PPM server JVM, by running the following command: keytool -import -keystore "<JAVA_HOME>/jre/lib/security/cacerts" -storepass <STORE_PASSWORD> -keypass <KEY_PASSWORD> -alias <CERTIFICATE_ALIAS> -file <PATH_TO_FOLDER_WHICH_CONTAINS_CERTIFICATE>/<CERTIFICATE_NAME>

Set PPM project as hybrid project

Only tasks in a hybrid project where only part of the project uses agile methodology can be linked to ALM Octane projects.

To set a PPM project as a hybrid project as a project manager:

Open the project.
In the top right corner of the project overview page, click Settings.
Open the Hybrid Project policy, and select the option Set the current project as a hybrid project.

If the project is already integrated with Microsoft Project using the Microsoft Project plug-in, you can set the project as a hybrid project only when the work plan is fully controlled by PPM.
If you want the costs of external tasks to be calculated and included in the project, select the option Roll up actual cost/actual effort from external tasks.
Click Done.

Link a PPM task with an ALM Octane project

When you link a PPM task with an ALM Octane project, the ALM Octane project entities become external tasks of the hybrid project.

To link a PPM task with an ALM Octane project as a project manager:

Open the hybrid project work plan.
Open a target task.

Tasks that can be linked with an ALM Octane project must meet the following requirements:
- The task is a leaf task.
- The task is not a milestone.
- The task has no manually entered actuals. Tasks with actuals only synced from time sheets can be linked with an ALM Octane project.
- The task is not linked to an RFC in Service Manager.
- If the project is integrated with Microsoft Project using an MSP plug-in or an MPP file, the work plan should be fully controlled by PPM (under the PPM-controlled mode) if you want to map the project tasks to ALM Octane projects.
On the Hybrid Project tab, click Start Mapping.
In step 1, select an ALM Octane instance, and click Next.
In step 2: User Configuration, click the Authenticate access to ALM Octane before selecting a shared space link to log into ALM Octane. If you are in an SSO-enabled environment, this link opens an SSO login page, otherwise, it opens an ALM Octane login page.

Provide the following information, and click Next.

Field (*Required)	Description
*Shared Space	The ALM Octane shared space where your agile project belongs. Note: After you are authenticated to ALM Octane, the Shared Space field may keep loading the values, this is because your ALM Octane site and space require API key authorization for direct REST API access, by enabling the RESTRICT_REST_API_TO_API_KEYS_ONLY parameter. To resolve the problem, disable this parameter.
*Workspace	The ALM Octane workspace where your agile project belongs.
If you want to link the task with an existing release, epic, or feature, fill the following.
*Import Selection	Select what you want to import into PPM. Available options are: One Feature. Imports backlog items of a specific feature. One Epic. Imports backlog items of a specific epic. One Release. Imports backlog items of a specific release.
*Import Selection Details	This field works together with the Import Selection field. If you select One Feature in Import Section, this field displays all available features in the selected workspace. Select a feature. If you select One Epic in Import Selection, this field displays all available epics in the selected workspace. Select an epic. If you select One Release in Import Selection, this field displays all available releases in the selected workspace. Select a release.
If you want to link the task with a new release, fill the following.
Create a New Release	Check this option if you want to create a new release in ALM Octane and link the task with the new release.
*Name	Name of the new release. By default, it is the linked task's name.
Description	Description of the new release.
*Start Date	Release start date.
*End Date	Release end date.
*Scrum or Kanban?	Select the release type Scrum or Kanban.
*Sprint Duration (in Days)	Duration (in days) of each sprint in the new release.
Group by	Select how to group by the imported backlog items: Backlog/Epic/Feature. Imported backlog items are grouped by epic > feature > backlog item. Epics have the prefix [E]. Features have the prefix [F]. Backlog items that do not belong to any epics are not imported. Release/Sprint. Imported backlog items are grouped by release > sprint > backlog item. Backlog items that do not belong to any sprints are not imported. In both cases, PPM creates the summary tasks Stories, Quality Stories, and Defects to further group backlog items: Imported user stories are grouped under the summary tasks Stories. Imported quality stories are grouped under the summary tasks Quality Stories. Imported defects are grouped under the summary tasks Defects.
% Complete for Summary Tasks	Based on what to calculate % complete of summary tasks. % Work Complete. PPM calculates the % complete of a summary task based on the invested hours of the backlog items. % complete of a summary task = Invested hours of all imported backlog items / [Sum of invested hours of all imported backlog items + Sum of remaining hours of all imported backlog items] % Story Points Done. PPM calculates the % complete of a summary task based on the story points of done backlog items. % complete of a summary task = Story points of done imported backlog items / Story points of all imported backlog items % Backlog Items Count Done. PPM calculates the % complete of a summary task based on the number of done backlog items. % complete of a summary task = Number of done imported backlog items / Number of all imported backlog items
How to import effort	Select how the effort in ALM Octane is synced to PPM work plan tasks: Capture Octane tasks effort under Story/Defect owner. Imports effort from ALM Octane to the mapped tasks in PPM work plan, and attributes it to the owner of the Story or Defect to which the task belongs. Capture Octane tasks effort under respective task owner. Imports effort from ALM Octane to the mapped tasks in PPM work plan and attributes it to the owner of the corresponding tasks. Do not import effort from Octane. No effort is imported from Octane to the mapped tasks in the PPM work plan.
Import User Stories Import Defects Import Quality Stories	Select which types of backlog items (user stories, defect, and quality stories) in the specified epic or release are imported.
Show Each Backlog Item as a Task	Whether the backlog items you select to import are added as tasks in PPM. If yes, the imported backlog items are added as leaf tasks under the summary tasks Stories, Quality Stories, or Defects. If no, the imported backlog items are not visible from the work plan but their data is rolled up to the summary tasks Stories, Quality Stories, or Defects.

Confirm the user configuration and click Submit.

A one-to-one mapping is established, and the mapping information is displayed under the PPM task.

The ALM Octane logo is added in front of the PPM task, indicating that it is linked to an ALM Octane project.

Synchronize agile data into PPM

After the PPM task is linked with an agile project, you wait for the background service to synchronize the agile project work items (external tasks) into PPM. Alternatively, you can click the agile icon in the front of the linked task to trigger immediate running of the service.

The data control of external tasks depends on whether the project enables Time Management to track actuals.

When the project enables Time Management

Schedule information of external data is controlled in agile and synched to PPM

For data mapping between PPM and agile, see Data mapping between Octane and PPM.

Exceptions

If an external task has time logged in PPM but was deleted in agile, PPM still keeps the task in the work plan, adds the prefix [Deleted in Agile] in the task name, and change the task status to Cancelled. This is to make sure time spent on the task is included in cost calculation and the task is no longer possible to be added into time sheets.
If an external task owner has logged time in PPM but was removed in agile, PPM keeps the previous resource and adds the new resource for the task.

Actual information of external data is tracked in PPM using time sheets

Actual information of external data is tracked in PPM using time sheets.

Every time when the background service External Work Plan Sync runs, PPM checks whether there is time logged on the external tasks.

If yes, PPM does not import actual data including actual effort, and actual start/finish date from agile to PPM. Instead, the PM-TM sync background service will sync these actual data with time sheet data.
If no, PPM imports status and actual start/finish date from agile to PPM, but does not import actual effort. This way, you can see consistent task status in agile and in PPM.

When the project does not enable Time Management

Both scheduled and actual information of external tasks are controlled in agile and synched to PPM by the background service External Work Plan Sync.

For task data mapping between agile and PPM, see the following table.

Data mapping between Octane and PPM
Data in PPM	Data in ALM Octane
Task name	Epic name/feature name/backlog item name
Schedule start	If a backlog item's creation time is within the sprint period, it is the backlog item's creation time. Otherwise, it is sprint's start time.
Schedule finish	Sprint's finish time
Actual start	If user story’s status is not ready or complete percent is greater than 0, It is user story’s schedule start time. Otherwise, it is empty.
Actual finish	When the task is completed, actual finish is Octane work item last modified time. But if the task ends before actual start, it is task scheduled finish, which is the sprint finish date if sprint is defined, or the same day as scheduled start if sprint is not defined.
Scheduled effort	Estimated hours
Percent complete	For summary tasks, see % Complete of Summary Tasks. For leaf tasks, if the backlog item is done, it is 100%; if the backlog item is not done, its % complete is calculated by the same method as its summary task.
Status In Planning In Progress Completed	New In Progress or In Testing Done

Unlink ALM Octane project from PPM task

You can unlink an ALM Octane project from a task.

To unlink an ALM Octane project from a PPM task:

Go to the Hybrid Project tab of the Task Details page for the linked task.
Next to the ALM Octane instance information, click Unlink.

A warning message pops up.
Click OK.

The link between the ALM Octane project and PPM task is cancelled immediately.