Integrate PPM requests with Azure DevOps work items

You can use the integration between PPM requests and Azure DevOps work items to manage Azure DevOps work items using PPM. This enables both PPM and Azure DevOps users to work on epics and features.

Overview

When a PPM request type is mapped to an work item type (such as task and bug) and an Azure DevOps project, you can establish a mapping between a PPM request and an Azure DevOps work item. 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, a work item of the mapped type is automatically created in the mapped Azure DevOps project.
  • For any work item that is created or already exists in the mapped Azure DevOps 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.
  • You can link a PPM request to an existing Azure DevOps work item.

After the mapping is established between a PPM request and an Azure DevOps work item, changes in the request or the work item are synced between PPM and Azure DevOps. This allows both PPM and Azure DevOps users to work on requests, epics, and features.

Back to top

Map PPM request types to DevOps work item types

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

To map a qualified PPM request type to an Azure DevOps work item type:

  1. Add an Azure DevOps instance. See Add an Azure DevOps agile instance.

  2. On the Request Mapping tab of the instance, click the Add button next to Request Type Mapping.

  3. Establish a mapping between a PPM request type and an Azure DevOps work item type.

    Field Description
    PPM Request Type

    Select a PPM request type to map.

    The PPM request type must be a qualified request type. For details, see Qualified request types.

    Agile Project

    Select an Azure DevOps project where a mapped Azure DevOps work item is created.
    Agile Entity Type

    Select an Azure DevOps work item type to map to the PPM request type.

    For example, if you select Task, when you create a request of the request type in PPM, a task is created in the Azure DevOps project.

    Mapping Status

    Whether the mapping is enabled or not.

    You can enable a request type mapping only after you set up field mappings for it.
  4. Click Save.

  5. 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 work item is automatically created in the mapped Azure DevOps project. For details, see Create a mapped Azure DevOps work item by creating a PPM request.

    This option is selected by default.

    Agile entity -> New PPM request

    For any work item that is created or already exists in Azure DevOps , 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. For details, see Sync Azure DevOps work items to PPM as requests.

    Caution:

    If you already have a large number of existing Azure DevOps work items of the mapped Azure DevOps work item type, be cautious of enabling this sync direction, because PPM creates a mapped PPM request for each of these Azure DevOps work items.

    PPM request -> Existing Agile entity

    You can map a PPM request to an existing work item in the mapped Azure DevOps project.

    For details, see Link a PPM request to an existing Azure DevOps work item.

  6. Add field mappings to enable the request type mapping.

    Field mappings work in the following way:

    • When you create a request in PPM, the mapped Azure DevOps work item fields are auto-filled with the values of the request fields.
    • When you create a work item in Azure DevOps , the mapped PPM request fields are auto-filled with the values of the work item fields.

    • When you update a mapped field in the PPM request or Azure DevOps work item, the field value is synced from PPM to Azure DevOps , or from Azure DevOps to PPM, or bi-directionally, depending on how sync direction is set for the field mapping.

    To add a field mapping:

    1. Click the Add button next to Field Mapping.

    2. Add mappings between PPM request fields and Azure DevOps work item fields.

      PPM Request Field

      Select a PPM request field to map.
      Agile Entity Field

      Select an Azure DevOps work item 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 Azure DevOps field.
      • From Agile to PPM. The value of the Azure DevOps 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 Azure DevOps server are synched. Otherwise, changes done in Azure DevOps might override changes done in PPM even when the changes in PPM are done after the changes in Azure DevOps .
    3. Click Save.
    4. Repeat these steps add other field mappings.

  7. Click in the Request Type Mapping line to enable the request type mapping.

  8. (Optional) If you want to receive email notifications when the request type mapping error occurs or the mapping creates or updates entities in Azure DevOps 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.

Back to top

Create a mapped Azure DevOps work item by creating a PPM request

When you create and move a request to a certain workflow step in PPM, a mapped work item is automatically created in Azure DevOps .

To create a mapped Azure DevOps work item by creating a PPM request:

  1. Prerequisites:

    • Make sure the Azure DevOps work item 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.
    • 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.
  2. From the PPM menu, select Create > Request, and click the mapped PPM request type.

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

    Field Description
    Agile Instance Name

    The instance where a corresponding work item is created in Azure DevOps.
    Agile Project

    The agile project in Azure DevOps where the corresponding work item is created.

    Note: Make sure the agile project you select has the Azure DevOps work item type that the request type is mapped with. Otherwise, creating a request will not create a corresponding Azure DevOps work item.

    Agile Entity Type

    The type for the corresponding work item.

    Sync Flag

    Sync flag:

    • Yes. Create a corresponding work item in Azure DevOps, and sync the value changes of mapped fields between PPM and Azure DevOps. For details about what values are synced, see Value sync.

    • No. Do not create a work item in Azure DevOps.

      Note: If you change sync flag to No after a corresponding work item is successfully created in Azure DevOps, the value changes of the mapped fields are not synced between PPM and Azure DevOps.

    Do not edit these fields after creating the request, otherwise, the sync between the request and the Azure DevOps work item may fail.

  4. Provide other request information.

  5. Submit the request.

    When the request moves to the workflow step where the ksc_create_agile_requirement special command is added, a corresponding work item is created in the target Azure DevOps project. A link to the mapped work item is listed in the Agile Entity ID field, which links directly to the work item in Azure DevOps.

What if a field is required in Azure DevOps but its mapped field in PPM request is not filled?

It might happen that a field is required when creating an Azure DevOps work item but the field is not mapped to a PPM request field, or its mapped PPM field is not filled.

In this case, to avoid Azure DevOps work item creation failure, PPM would give a default value to the required Azure DevOps work item field when creating the work item.

Back to top

Sync Azure DevOps work items to PPM as requests

For any Azure DevOps work item that is created or already exists in the mapped Azure DevOps 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 sync Azure DevOps work items to PPM as requests:

  1. Prerequisites:

    • Make sure the Azure DevOps work item 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 Sync direction option.

  2. Enable the External Request Info Sync Service. For details, see PPM background services.

    When the External Request Info Sync Service runs, for any work item of the mapped type created or already existing in the mapped Azure DevOps project that is not yet mapped to a PPM request, a request is automatically created in PPM to map to the Azure DevOps work item.

    The fields in the Agile Integration Info section of the mapped PPM request are automatically filled with the information of the mapped Azure DevOps work item. The Agile Entity ID field lists the link to the mapped Azure DevOps work item. Clicking the link opens the work item in Azure DevOps .

Back to top

Link a PPM request to an existing Azure DevOps work item

You can link a PPM request to an existing work item in Azure DevOps .

To link a PPM request to an existing Azure DevOps work item:

  1. Prerequisites:

    • The Azure DevOps work item type is mapped with a PPM request type, and the mapping is enabled.
    • The PPM request -> Existing Agile entity sync direction is enabled for the mapping. For details, see Sync direction option.

  2. Open a target PPM request.

    PPM requests that can be linked to an existing Azure DevOps work item must meet the following requirements:

    • The request is of the mapped request type.
    • The request is not already linked to an agile entity.

  3. In the Agile Integration Info section, provide the following information:

    Field Description
    Agile Instance Name

    The instance where a corresponding work item is created in Azure DevOps.
    Agile Project

    The agile project in Azure DevOps where the corresponding work item is created.
    Agile Entity Type

    The type for the corresponding work item.

    Existing Agile Entity

    The work item in Azure DevOps to which the PPM request is linked.

    Note: By default, this field is always available as long as the request is not mapped to an agile entity. Administrators can configure whether this field is available or editable when the request is under a specific status. For details, see Configure request field status dependencies.
    Sync Flag

    Sync flag:

    • Yes. Sync the value changes of mapped fields between PPM and Azure DevOps. For details about what values are synced, see Value sync.
    • No. Do not sync the value changes of mapped fields between PPM and Azure DevOps.

  4. Click Save.

    The mapping is created between the PPM request and the Azure DevOps work item.

    A link to the mapped work item is listed in the Agile Entity ID field, which links directly to the work item in Azure DevOps .

Back to top

Value sync

After you establish a mapping between a PPM request with an Azure DevOps work item, and set the request field Sync Flag to Yes, the value changes that happen in the mapped fields are synced between PPM and Azure DevOps as follow:

  • The value changes that happen in PPM request fields are immediately synced to the mapped fields in Azure DevOps work item.
  • The value changes that happen in Azure DevOps work item fields are synced to the mapped fields in PPM request the next time when the External Request Info Sync Service background 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.

Back to top

Remove an entity mapping

You can unlink a PPM request from its mapped Azure DevOps work item.

To unlink a PPM request from its mapped Azure DevOps work item:

  1. Prerequisites:

  2. Open the target request and move the request to the workflow step where the special command ksc_unlink_agile is added, the PPM request is unlinked from its mapped Azure DevOps work item.

    The request and the work item remains in PPM and the Azure DevOps project. You can map them to another Azure DevOps work item or PPM request.

Back to top

View event logs

Event logs keep records of the following:

  • Whether a PPM request or an Azure DevOps work item was created, updated, or deleted.
  • Date and time of an event.
  • Whether an error occurs to an event.
  • Other details.

To view event logs of a request type mapping:

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

Back to top

See also: