PPM integration with ServiceNow

You can use the integration between PPM and ServiceNow to manage ServiceNow entities using PPM. This enables both PPM and ServiceNow users to work on requests and incidents.

Note: This feature is not supported if your PPM runs on a Postgre SQL database.

Overview

When a PPM request type is mapped to an entity type in ServiceNow, you can establish a mapping between a PPM request and a ServiceNow entity. For example, depending on the integration configuration:

  • When you create a request of the request type in PPM, and when a certain workflow step in the request is executed, an entity of the mapped entity type is automatically created in the mapped ServiceNow instance.
  • For any entity that is created or already exists in the mapped ServiceNow instance 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 ServiceNow entity.

After the mapping is established between a PPM request and a ServiceNow entity, changes in the request or the entity are synced between PPM and ServiceNow. This allows both PPM and ServiceNow users to work on requests and incidents.

Back to top

Add a ServiceNow instance

A ServiceNow instance is an environment where the ServiceNow connector conveys the data from ServiceNow to PPM.

To add a ServiceNow instance as an administrator:

  1. Click the Administration button in the masthead.

  2. From the Administration menu, click Integrations > Agile Tool Integration.

  3. In the Instances area, ServiceNow San Diego line, click the Create Instance button +.

  4. In the General tab of the instance, provide the required information as described in the table below:

    Field (*Required)

    Description

    *Instance Name

    Specify a unique name for the instance up to 50 characters in length.

    Instance names cannot include special characters.
    *URL of your SNow Server URL of the ServiceNow server you want to integrate with PPM.

    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.
    Authentication Settings for SNow Integration User
    *Username

    Username and password of the account used to retrieve data from ServiceNow.

    Note: Make sure that this account can access the ServiceNow entities or tables to which you want to map PPM requests.

    *Password
  5. Click Save.

  6. 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. To get more information on the connection error, check PPM server log files. For details, see Server log files.

Back to top

Map PPM request types to ServiceNow entity types

Before creating a mapping between a PPM request and a ServiceNow entity, and synchronizing data between PPM and ServiceNow, you need to map a PPM request type to a ServiceNow entity type. You can map the same PPM request type to different ServiceNow entity types.

To map a qualified PPM request type to a ServiceNow entity type:

  1. Add a ServiceNow instance. See Add a ServiceNow instance.

  2. In 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 a ServiceNow entity 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 SNow Instance where a mapped ServiceNow entity is created.
    Agile Entity Type

    Select a ServiceNow entity type to map to the PPM request type.

    For example, if you select Incident, when you create a request of the request type in PPM, an incident is created in ServiceNow.

    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 a request of the request type, when a certain workflow step in PPM is executed, an associated entity is automatically created in the mapped ServiceNow instance. For details, see Create a mapped ServiceNow entity by creating a PPM request.

    This option is selected by default.

    Agile entity -> New PPM request

    For any entity that is created or already exists in ServiceNow, 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 ServiceNow entities to PPM as requests.

    Caution:

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

    PPM request -> Existing Agile entity

    You can map a PPM request to an existing entity in the mapped ServiceNow instance.

    For details, see Link a PPM request to an existing ServiceNow entity.

  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 ServiceNow entity fields are auto-filled with the values of the request fields.
    • When you create an entity in ServiceNow, the mapped PPM request fields are auto-filled with the values of the entity fields.

    • When you update a mapped field in the PPM request or ServiceNow entity, the field value is synced from PPM to ServiceNow, or from ServiceNow 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 ServiceNow entity fields.

      For details of supported PPM-ServiceNow field type mappings, see .

      PPM Request Field

      Select a PPM request field to map.
      Agile Entity Field

      Select a ServiceNow 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 ServiceNow field.
      • From Agile to PPM. The value of the ServiceNow 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 ServiceNow server are synched. Otherwise, changes done in ServiceNow might override changes done in PPM even when the changes in PPM are done after the changes in ServiceNow.
    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 ServiceNow 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 ServiceNow 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 ServiceNow.

To create a mapped ServiceNow entity by creating a PPM request:

  1. Prerequisites:

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

    Select SNow Instance.

    Agile Entity Type Select the entity type that the ServiceNow entity belongs to.
    Sync Flag
    • If you select Yes, a mapped entity is created in ServiceNow, and the value changes of mapped fields are synced between PPM and ServiceNow. See Value sync between PPM and ServiceNow.

    • If you select No, no mapped entity is created in ServiceNow.

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

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

Back to top

Synchronize ServiceNow entities to PPM as requests

For any entity that is created or already exists in the mapped ServiceNow instance, 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 ServiceNow entities to PPM as requests:

  1. Prerequisites:

    • Make sure the ServiceNow 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 ServiceNow entity types.

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

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

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

Back to top

Link a PPM request to an existing ServiceNow entity

You can link a PPM request to an existing entity in ServiceNow.

To link a PPM request to an existing ServiceNow entity:

  1. Prerequisites:

    • The ServiceNow entity 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 ServiceNow entity types.

  2. Open a target PPM request.

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

    Select the ServiceNow entity 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 ServiceNow entity, and the value changes of mapped fields are synced between PPM and ServiceNow. See Value sync between PPM and ServiceNow.

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

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

  4. Click Save.

    The mapping is created between the PPM request and the ServiceNow entity.

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

Back to top

Value sync between PPM and ServiceNow

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

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

To unlink a PPM request from its mapped ServiceNow entity:

  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 ServiceNow entity.

    The request and the entity remains in PPM and ServiceNow. You can map them to another ServiceNow entity or PPM request.

Back to top

View event logs

Event logs keep records of the following:

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