Manage JIRA entities from within PPM

You can manage a JIRA entity from within PPM.

Overview

When a PPM request type is mapped to an entity type (such as task and bug) and a JIRA project:

  • If 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 JIRA project.
  • Changes in the request or the agile entity are synced between PPM and JIRA.

This allows both PPM and JIRA users to work on requests, defects, tasks, and so on.

Back to top

Map PPM request types to JIRA entity types

If a PPM request type is mapped to a JIRA entity type, when you create a request of the request type in PPM, an entity of the mapped entity type is created in JIRA. You can map the same PPM request type with different JIRA entity types that are managed in different JIRA projects.

To map a qualified PPM request type to a JIRA entity 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 entity type.

    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 entity 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 entity of the mapped entity 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 entity 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. Add field mappings to enable the request type mapping.

    Field mappings work in the following way:

    • When you create a request in PPM, the values in the request fields are auto-filled in the mapped JIRA entity fields.
    • When you update a field in the PPM request or JIRA entity, 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 entity 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 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 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.
  6. To enable the request type mapping, click in the Request Type Mapping line.
  7. (Optional) If you want to receive email notifications when the request type mapping error occurs or the mapping creates or updates agile entities in JIRA, 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 JIRA entity by creating a PPM request

To create a JIRA entity by creating a PPM request:

  1. Make sure the JIRA entity type is mapped with a PPM request type, and the mapping is enabled.
  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.

    Agile Instance Name Select the JIRA instance where the mapping is created.
    Agile Project

    Select the agile project where you want the JIRA entity to be created.

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

    Agile Entity Type Select the entity type that the JIRA entity belongs to.
    Sync Flag
    • If yes, the PPM request would trigger creating a mapped agile entity 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 no, the PPM request does not trigger creating a mapped agile entity in JIRA.

      If you change sync flag to no after the PPM request successfully creates a mapped agile entity in JIRA, the value changes of mapped fields are not synced between PPM and JIRA.

    Agile Entity ID

    Not editable when creating or update the request.

    It shows link of the JIRA entity after the request is submitted and moved to a certain workflow step where the mapped agile entity is created in JIRA.

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

  4. Provide other request information.
  5. 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 agile project in JIRA. You can click the link in the Agile Entity ID field to open the entity 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 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 JIRA entity creation failure, PPM would give a default value to the required JIRA entity field when creating the entity.

Back to top

How changes are synced between PPM and JIRA

When you create a request of a request type that is mapped with a JIRA entity type, and set the request field Sync Flag to Yes, the value changes that happen in mapped fields are synced between PPM and JIRA as follows:

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

Back to top

View event logs

Event logs keep records of:

  • Whether a PPM request or a JIRA 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,

  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