Integrate PPM requests with Jira issues

You can use the integration between PPM requests and Jira issues to manage Jira issues using PPM. This enables both PPM and Jira users to work on requests, defects, and tasks.

Overview

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

After the mapping is established between a PPM request and a Jira issue, changes in the request or the issue are synced between PPM and Jira. This allows both PPM and Jira users to work on requests, defects, and tasks.

Back to top

Map PPM request types to Jira issue types

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

To map a qualified PPM request type to a Jira issue type:

  1. Add a Jira instance. See Add a Jira agile instance.

  2. In the Request Mapping tab of the instance, click the add icon next to Request Type Mapping.

  3. Establish a mapping between a PPM request type and a Jira issue type.

    Field Description
    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 a Jira project where a mapped Jira issue is to be created.

    Starting from PPM 10.0.1, you can select the wildcard Jira project: * to indicate all the Jira projects. If you select the wildcard Jira project, when a request of the request type is created in PPM, an issue of the mapped issue type can be created in all Jira projects.

    Note:

    • The wildcard Jira project (*) is available only when it is enabled. For details, see Enable " * " Jira Project Mapping in Request Agile Mapping.
    • If the Jira agile instance is run on Jira cloud, the wildcard Jira project includes all the company-managed projects. It does not include the team-managed projects. Therefore, if you want to map the request type with a team-managed project, select the target team-managed project instead of the wildcard Jira project.
    Agile Entity Type

    Select a Jira issue 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 Jira 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. (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 issue is automatically created in the mapped Jira project. For details, see Create a mapped Jira issue by creating a PPM request.

    This option is selected by default.

    Agile entity -> New PPM request

    For any issue that is created or already exists in Jira, 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 Synchronize Jira issues to PPM as requests.

    Caution:

    If you already have a large number of existing Jira issues of the mapped Jira issue type, be cautious of enabling this sync direction, because PPM creates a mapped PPM request for each of these Jira issues.

    PPM request -> Existing Agile entity

    You can map a PPM request to an existing issue in the mapped Jira project.

    For details, see Link a PPM request to an existing Jira issue.

  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 Jira issue fields are auto-filled with the values of the request fields.
    • (Available in 10.0.3 and later versions) When you create an issue in Jira, the mapped PPM request fields are auto-filled with the values of the issue fields.

    • When you update a mapped field in the PPM request or Jira issue, the field value is synced from PPM to Jira, or from Jira 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 icon next to Field Mapping.

    2. Add mappings between PPM request fields and Jira issue fields.

      For details of supported PPM-Jira field type mappings, see Supported PPM-JIRA field type mappings.

      PPM Request Field

      Select a PPM request field to map.
      Agile Entity Field

      Select a Jira issue 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 Jira field.
      • From Agile to PPM. The value of the Jira 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 Jira server are synched. Otherwise, changes done in Jira might override changes done in PPM even when the changes in PPM are done after the changes in Jira.
    3. Click Save.
    4. Repeat a through c to add other field mappings.
  7. To enable the request type mapping, click in the Request Type Mapping line.

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

    3. Click Save.

    Email notifications provide the same information as event logs. See View event logs.

Back to top

Create a mapped Jira issue by creating a PPM request

When you create and move a request to a certain workflow step in PPM, a mapped issue is automatically created in Jira.

To create a mapped Jira issue by creating a PPM request:

  1. Prerequisites:

    • Make sure the Jira issue 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 Select the Jira instance where the mapping is created.
    Agile Project

    Select the agile project where you want the Jira issue to be created.

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

    Agile Entity Type Select the issue type that the Jira issue belongs to.
    Sync Flag
    • If you select Yes, the PPM request would trigger creating a mapped issue in Jira, and the value changes of mapped fields are synced between PPM and Jira. See How changes are synced between PPM and Jira.

    • If you select No, the PPM request does not trigger creating a mapped issue in Jira.

      If you change sync flag to No after the PPM request successfully creates a mapped issue in Jira, the value changes of mapped fields are not synced between PPM and Jira.

    Do not edit these fields after creating the request, otherwise, the sync between the request and the Jira issue 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, an issue of the selected issue type is created in the selected Jira project. A link to the mapped Jira issue is listed in the Agile Entity ID field. Clicking the link opens the issue in Jira.

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

It might happen that a field is required when creating a Jira issue but the field is not mapped to a PPM request field, or its mapped PPM field is not filled.

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

Back to top

Synchronize Jira issues to PPM as requests

Available in versions: PPM 10.0.3 and later

For any Jira issue that is created or already exists in the mapped Jira 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 Jira issues to PPM as requests:

  1. Prerequisites:

    • Make sure the Jira issue 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 Jira issue types.

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

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

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

Back to top

Link a PPM request to an existing Jira issue

Available in versions: PPM 10.0.3 and later

You can link a PPM request to an existing issue in Jira.

To link a PPM request to an existing Jira issue:

  1. Prerequisites:

    • The Jira issue 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 Map PPM request types to Jira issue types.

  2. Open a target PPM request.

    PPM requests that can be linked to an existing Jira issue 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 Select the Jira instance where the mapping is created.
    Agile Project Select the Jira project where the agile issue is created.
    Agile Entity Type Select the issue type that the Jira issue belongs to.
    Existing Agile Entity

    Select the Jira issue 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
    • If set to Yes, when you save the request, the mapping is created between the PPM request and the selected Jira issue, and the value changes of mapped fields are synced between PPM and Jira. See How changes are synced between PPM and Jira.

    • If set to No, when you save the request, the mapping is not created between the PPM request and the selected Jira issue.

      If you change sync flag to No after the mapping is created between the PPM request and the selected Jira issue, the value changes of mapped fields are not synced between PPM and Jira.

  4. Click Save.

    The mapping is created between the PPM request and the Jira issue.

    The Agile Entity ID field appears in the request's Agile Integration Info section and lists a link to the mapped Jira issue. Clicking the link opens the issue in Jira.

Back to top

How changes are synced between PPM and Jira

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

  • The value changes that happen in PPM request fields are immediately synced to the mapped fields in Jira issue.
  • The value changes that happen in Jira issue 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

Available in versions: PPM 10.0.3 and later

You can unlink a PPM request from its mapped Jira issue.

To unlink a PPM request from its mapped Jira issue:

  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 Jira issue.

    The request and the issue remains in PPM and the Jira project. You can map them to another Jira issue/PPM request.

Back to top

View event logs

Event logs keep records of the following:

  • Whether a PPM request or a Jira issue 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:

  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