Manage ALM Octane entities from within PPM

You can use the integration between PPM requests and ALM Octane entities to manage ALM entities using PPM.

Overview

When a PPM request type is mapped to an agile entity type (such as feature and user story) and an ALM Octane project, you can establish a mapping between a PPM request and an ALM Octane entity. For example, depending on the integration configuration:

When you create and move a request of the request type to a certain workflow step in PPM, an entity of the mapped entity type is automatically created in the mapped ALM Octane project.
(Available in 10.0.3 and later versions) For any entity that is created or already exists in the mapped ALM Octane project but not yet mapped to a PPM request, a request of the mapped request type is automatically created in PPM after running the External Request Info Sync Service.

After the mapping is established between a PPM request and an ALM Octane entity, changes in the request or the entity are synced between PPM and ALM Octane. This allows both PPM and ALM Octane users to work on requests, defects, features, and user stories.

Qualified request types

The PPM request type must meet the following requirements before it can be mapped to an entity type and an ALM Octane project.

Requirement Description

Requirement	Description
The request type is enabled.	Make sure the request type is active.
The request header type for the request type includes the field group: Agile Integration Info.	This field group in the PPM request details page contains details of the mapped agile entity. To add the Agile Integration Info field group to a request header type, see Request Header Type Field Groups .
The request type is assigned a workflow, and the workflow contains an execution step that has the following special command added: `ksc_create_agile_requirement [REQ.REQUEST_ID]`	When you create a request of the request type in PPM, and when the request moves to the execution workflow step, the special command triggers the action of creating a mapped agile entity. To assign a workflow to a request type, see Create simple default rules for request types . To add the special command to an execution workflow step: In PPM Workbench, open Configuration > Workflows. Open the target workflow, and go to the Layout tab. Right-click the execution step, and select Edit Source. In the Execution Type field, select Workflow Step Commands. In the Execution section, click New Cmd. In the New Command window, give the command a name, and in the Steps field, type `ksc_create_agile_requirement [REQ.REQUEST_ID]`. Click Add to add the command, and click Save to save the changes to the execution step.

The request type is enabled.

Make sure the request type is active.

The request header type for the request type includes the field group: Agile Integration Info.

This field group in the PPM request details page contains details of the mapped agile entity.

To add the Agile Integration Info field group to a request header type, see Request Header Type Field Groups .

The request type is assigned a workflow, and the workflow contains an execution step that has the following special command added:

ksc_create_agile_requirement [REQ.REQUEST_ID]

When you create a request of the request type in PPM, and when the request moves to the execution workflow step, the special command triggers the action of creating a mapped agile entity.

To assign a workflow to a request type, see Create simple default rules for request types .

To add the special command to an execution workflow step:

In PPM Workbench, open Configuration > Workflows.
Open the target workflow, and go to the Layout tab.
Right-click the execution step, and select Edit Source.
In the Execution Type field, select Workflow Step Commands.
In the Execution section, click New Cmd.
In the New Command window, give the command a name, and in the Steps field, type ksc_create_agile_requirement [REQ.REQUEST_ID].
Click Add to add the command, and click Save to save the changes to the execution step.

Map PPM request types to ALM Octane entity types

Before creating a mapping between a PPM request and an ALM Octane entity, and synchronizing data between PPM and ALM Octane, you need to map a PPM request type to an ALM Octane entity type. You can map the same PPM request type to different ALM Octane entity types that are managed in different ALM Octane projects.

To map a qualified PPM request type to an ALM Octane entity type:

Add an ALM Octane instance. See Add an ALM Octane agile instance.
Make sure the account provided on the General tab has required role to ALM Octane workspace.
- For 10.0.2, if your ALM Octane version is earlier than 16.1.8, both the Space Admin role and the Workspace Admin role are required. If you use ALM Octane 16.1.8 and later versions, the Workspace Admin role is required.
- For 10.0.1 and earlier versions, the Workspace Admin role is required.
For details about roles in ALM Octane, see the ALM Octane documentation.
In the Request Mapping tab of the instance, click the Add button next to Request Type Mapping.

Map a PPM request type to an ALM Octane project and an ALM Octane entity type that is managed in the ALM Octane project.

PPM Request Type	Select a PPM request type to map. The PPM request type must be a qualified request type. See Qualified request types for details.
Agile Project	Select an ALM Octane project (ALM Octane workspace) where a mapped ALM Octane entity is to be created. Starting from PPM 10.0.2, you can select the wildcard ALM Octane project: * to indicate all the ALM Octane projects. If you select the wildcard ALM Octane project, when a request of the request type is created in PPM, an entity of the mapped entity type can be created in all ALM Octane projects. Note: The wildcard ALM Octane project () is available only when it is enabled. For details, see Enable " " ALM Octane project mapping in request agile mapping.
Agile Entity Type	Select an ALM Octane entity type to map to the PPM request type. For example, if you select Feature, when you create a request of the request type in PPM, a feature is created in the ALM Octane project. Starting from PPM 10.0.2, you can map a shared epic to the PPM request. The shared epic is available for selection only when the selected ALM Octane project is associated with a shared space and you have the Space Admin role to that project.
Mapping Status	Whether the mapping is enabled or not. You can only enable a request type mapping after you set up field mappings for it.

(Available in 10.0.3 and later versions) Specify the sync direction for the mapping.

Sync direction option	Description
PPM request -> New Agile entity	When you create and move a request of the request type to a certain workflow step in PPM, an associated agile entity is automatically created in the mapped ALM Octane project. This option is selected by default.
Agile entity -> New PPM request	For any entity that is created or already exists in ALM Octane, and not yet mapped to a PPM request, a PPM request of the mapped request type is automatically created the next time when the External Request Info Sync Service runs. Caution: If you already have a large number of existing agile entities in ALM Octane, be cautious of enabling this sync direction, because PPM creates a mapped PPM request for each of these agile entities.

Sync direction option

Description

PPM request -> New Agile entity

When you create and move a request of the request type to a certain workflow step in PPM, an associated agile entity is automatically created in the mapped ALM Octane project.

This option is selected by default.

Agile entity -> New PPM request

For any entity that is created or already exists in ALM Octane, and not yet mapped to a PPM request, a PPM request of the mapped request type is automatically created the next time when the External Request Info Sync Service runs.

Caution:

If you already have a large number of existing agile entities in ALM Octane, be cautious of enabling this sync direction, because PPM creates a mapped PPM request for each of these agile entities.

Click Save.

Add field mappings to enable the request type mapping.

How field mappings work

When you create a request in PPM, the mapped ALM Octane entity fields are auto-filled with the values in the request fields.
(Available in 10.0.3 and later versions) When you create an entity in ALM Octane, the mapped PPM request fields are auto-filled with the values in the entity fields.
When you update a field in the PPM request or ALM Octane entity, the field value is synced from PPM to ALM Octane, or from ALM Octane to PPM, or bi-directionally, depending on how sync direction is set for the field mapping.

How to add a field mapping

Click the Add button next to Field Mapping.

Add mappings between PPM request fields and ALM Octane entity fields.

For details about the supported PPM-Octane field type mappings, see Supported PPM-Octane field type mappings.

PPM Request Field	Select a PPM request field to map.
Agile Entity Field	Select an ALM Octane entity field to map to the PPM request field.
Sync Direction	From PPM to Agile. The value of the PPM field overrides the value of the mapped ALM Octane field. From Agile to PPM. The value of the ALM Octane field overrides the value of the mapped PPM field. Bi-directional. The value of the field whose last update date is later overrides the value of the other field. Note: Make sure the clocks in the PPM server and ALM Octane server are synched. Otherwise, changes done in ALM Octane might override changes done in PPM even when the changes in PPM are done after the changes in ALM Octane.
Value Mapping	Required only when both fields in a field mapping are list values. You can also map values after saving the field mapping. To map values: Click Map Values. Select a value from the PPM Values column and a value from the Agile System Values, and then select an enabled button to specify the direction of the value mapping. !: Enabled when field mapping sync direction is "From Agile to PPM". If the agile field is filled with the selected value, the corresponding PPM field is auto-filled with the mapped value. ": Enabled when field mapping sync direction is "From PPM to Agile". If the PPM field is filled with the selected value, the corresponding agile field is auto-filled with the mapped value. D: Enabled when field mapping sync direction is "Bi-directional". If the PPM field is filled with the selected value, the corresponding agile field is auto-filled with the mapped value, and vice versa. Click OK.

Click Save.

If you map a PPM field to an unqualified agile field, the field mapping is highlighted in red upon saving. Hover over it to see details about how to correct it.
Repeat these steps to add other field mappings.

Click in the Request Type Mapping line to enable the request type mapping.
(Optional) If you want to receive email notifications when the request type mapping error occurs or the mapping creates or updates entities in ALM Octane or PPM, set up email notifications for the request type mapping.
1. Select the request type mapping, and click in the Request Type Mapping line.
2. Specify when and how often email notifications are sent and sent to whom.
3. Click Save.
Email notifications provide the same information as event logs. See View event logs.

Known issues if you map a PPM request type to an ALM entity type in the wildcard ALM Octane project

If you map one PPM request field to multiple ALM Octane entity fields that are available in different ALM Octane projects and set the sync direction to “Bidirectional” or “From Agile To PPM”, when an ALM entity is created by creating a PPM request, after the synchronization, the value in the mapped PPM request field may be set to empty.
If you add mappings between multiple PPM request fields and ALM Octane entity fields and set the sync direction to “Bidirectional” or “From Agile To PPM”, when an ALM Octane entity is created by creating a PPM request, if a mapped agile field does not exist in the ALM Octane entity, after the synchronization, the value in the mapped PPM request field may be set to empty.
If two or more entity fields in different ALM Octane projects have the same field name, the Agile Entity Field displays only one entity field. Mapping a PPM request field to such an ALM Octane entity field may cause synchronization failure.

Create a mapped ALM Octane entity by creating a PPM request

When you create and move a request to a certain workflow step in PPM, a mapped entity is automatically created in ALM Octane.

To create a mapped ALM Octane entity by creating a PPM request:

Prerequisites:
- Make sure the ALM Octane agile entity type is mapped to a PPM request type and the mapping is enabled.
- The PPM request -> New Agile entity sync direction is enabled for the mapping. For details, see Map PPM request types to ALM Octane entity types.
- Make sure the PPM request type is assigned a workflow, and the workflow contains an execution step that has the ksc_create_agile_requirement special command added. For details, see Add a special command to an execution workflow step.
From the PPM menu, select Create > Request, and click the mapped PPM request type.

In the Create New <PPM_Request_Type> page, Agile Integration Info section, provide the following information.

Agile Instance Name	Select the ALM Octane instance where the mapping is created.
Agile Project	Select the ALM Octane workspace where you want the ALM Octane entity to be created.
Agile Entity Type	Select the entity type that the ALM Octane entity belongs to.
Sync Flag	If set to Yes, the PPM request would trigger creating a mapped agile entity in ALM Octane, and the value changes of mapped fields are synced between PPM and ALM Octane. See How changes are synced between PPM and ALM Octane. If set to No, the PPM request does not trigger creating a mapped agile entity in ALM Octane. If you change sync flag to "No" after the PPM request successfully creates a mapped agile entity in ALM Octane, the value changes of mapped fields are not synced between PPM and ALM Octane.

Do not edit these fields after you create the request, otherwise, the sync between the request and the agile entity may fail.

Provide other request information.
Submit the request.

When the request moves to the workflow step where the special command ksc_create_agile_requirement [REQ.REQUEST_ID] is added, an entity of the selected agile entity type is created in the selected project (workspace) in ALM Octane. You can click the link in the Agile Entity ID field to open the entity in ALM Octane.

What if a field is required in ALM Octane but its mapped field in PPM request is not filled?

It might happen that a field is required when creating an ALM Octane entity but the field is not mapped to a PPM request field, or its mapped PPM field is not filled.

In this case, to avoid ALM Octane entity creation failure, PPM would give a default value to the required ALM Octane entity field when creating the entity.

For example, the Name field is required when creating a user story in ALM Octane. If the mapped PPM field is not filled, the Name field would be auto-filled with the default message "This user story is auto-created by the mapped PPM request <request_id>."

Synchronize ALM Octane entities to PPM as requests

Available in versions: PPM 10.0.3 and later

For any ALM Octane entity that is created or already exists in the mapped ALM Octane project, and is not yet mapped to a PPM request, a PPM request of the mapped request type is automatically created the next time when the External Request Info Sync Service runs.

To synchronize ALM Octane entities to PPM as requests:

Prerequisites:
- Make sure the ALM Octane entity type is mapped to a PPM request type, and the mapping is enabled.
- The Agile entity -> New PPM request sync direction is enabled for the mapping. For details, see Map PPM request types to ALM Octane entity types.
Enable the External Request Info Sync Service. For details, see PPM background services.

When the External Request Info Sync Service runs, for any agile entity of the mapped agile entity type created or already existing in the mapped ALM Octane project that is not yet mapped to a PPM request, a request is automatically created in PPM to map to the ALM Octane entity.

The fields in the Agile Integration Info section of the mapped PPM request are automatically filled with the information of the mapped ALM Octane entity. The Agile Entity ID field lists the link to the mapped ALM Octane entity. Clicking the link opens the agile entity in ALM Octane.

How changes are synced between PPM and ALM Octane

When you create a request of a request type that is mapped to an ALM Octane entity type, and set the request field Sync Flag to Yes, the value changes that happen in mapped fields are synced regularly between PPM and ALM Octane.

The sync happens every time when the background service External Request Info Sync Service runs.
The background service syncs the field value changes according to how the sync direction is set for each field mapping. See Sync Direction.
If a PPM Text field is mapped to an ALM Octane Memo field, and changes are synced from ALM Octane to PPM, a reference record is added in the PPM request to fully display the Memo field information.

View event logs

Event logs keep records of:

Whether a PPM request or an ALM Octane entity was created, updated, or deleted.
Date and time of the event.
Whether an error occurs to an event.
Other details.

To view event logs of a request type mapping:

Select the request type mapping and click .
You can search the log for all the events that are logged for that request type mapping or only for their error events, over the date range you specify.