Project Portfolio Management API

  • Release version: Xanadu
  • Updated August 1, 2024
  • 4 minutes to read

    • The Project Portfolio Management API provides endpoints to bulk import cost plans and project tasks.

    The PPM Standard plugin (com.snc.financial_planning_pmo) is required to access this API. The calling user must have the it_project_manager role.

    This API is provided within the now namespace.

    Project Portfolio Management - POST /now/ppm/insert_cost_plans

    Creates cost plans in the Cost Plan [cost_plan] table.

    URL format

    Default URL: /api/now/ppm/insert_cost_plans

    Supported request parameters

    Table 1. Path parameters
    Name Description
    None
    Table 2. Query parameters
    Name Description
    None
    Table 3. Request body parameters (JSON)
    Name Description
    end_fiscal_period Required. Sys_id of the ending fiscal period for the cost plan. Located in the Fiscal Period [fiscal_period] table.

    Data type: String
    name Required. Name of the cost plan.

    Data type: String
    resource_type Required. Sys_id of the resource type. Located in the Resource Type Definition [resource_type_definition] table.

    Data type: String
    start_fiscal_period Required. Sys_id of the starting fiscal period for the cost plan. Located in the Fiscal Period [fiscal_period] table.

    Data type: String
    task Required. Sys_id of the project or demand for the cost plan. Located in the Project [pm_project] or Demand [dmn_demand] table.

    Data type: String
    unit_cost Required. Unit cost for the cost plan.

    Data type: String

    Headers

    The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

    Table 4. Request headers
    Header Description
    Accept Data format of the response body. Only supports application/json.
    Content-Type Data format of the request body. Only supports application/json.
    Table 5. Response headers
    Header Description
    None

    Status codes

    The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

    Table 6. Status codes
    Status code Description
    200 Successful. The request was successfully processed.
    401 Unauthorized. The user credentials are incorrect or have not been passed.

    Response body parameters (JSON)

    Name Description
    result Object containing information about the status of the API request.

    Data type: Object

    "result": {
   "status": "String"
}
    result.status Status of the API request.

    Data type: String

    cURL request

    This example imports two cost plans.

    curl "https://instance.servicenow.com/api/now/ppm/insert_cost_plans" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "[
   {
      "name": "Cost plan 1",
      "resource_type": "3d16eaf79330120064f572edb67ffb04",
      "start_fiscal_period": "ed47e5d90b3010108d9ac74363673a98",
      "end_fiscal_period": "0a47e5d90b3010108d9ac74363673afd",
      "task": "0fc9f992db601810852ca6dc13961951",
      "unit_cost": 1200
   },
   {
      "name": "Cost plan 2",
      "resource_type": "3d16eaf79330120064f572edb67ffb04",
      "start_fiscal_period": "ed47e5d90b3010108d9ac74363673a98",
      "end_fiscal_period": "7947e5d90b3010108d9ac74363673ac9",
      "task": "0fc9f992db601810852ca6dc13961951",
      "unit_cost": 3600
   }
]" \
--user 'username':'password'

    Response body.

    {
   "result": {
      "status": "success"
   }
}

    Project Portfolio Management - POST /now/ppm/insert_project_tasks

    Creates a project and associated project tasks.

    Projects are created in the Project [pm_project] table and project tasks are created in the Project Task [pm_project_task] table.

    URL format

    Default URL: /api/now/ppm/insert_project_tasks

    Supported request parameters

    Table 7. Path parameters
    Name Description
    None
    Table 8. Query parameters
    Name Description
    None
    Table 9. Request body parameters (JSON)
    Name Description
    child_tasks Array of tasks for the project. Each task is an object in the array.

    Data type: Array

    "child_tasks": [
   {
      "child_tasks": [Array],
      "external_id": "String",
      "short_description": "String" 
   }
]
    child_tasks.child_tasks Array of child tasks for the parent task. Each child task is an object in the array. Each child task can have its own array of child tasks.

    Data type: Array

    "child_tasks": [
   {
      "child_tasks": [Array],
      "external_id": "String",
      "short_description": "String" 
   }
]
    child_tasks.external_id Unique identifier of the task from the external system.

    Data type: String
    child_tasks.short_description Short description of the task.

    Data type: String
    end_date End date for the project.

    Data type: String
    external_id Unique identifier of the project from the external system.

    Data type: String
    short_description Short description of the project.

    Data type: String
    start_date Start date for the project.

    Data type: String

    Headers

    The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

    Table 10. Request headers
    Header Description
    Accept Data format of the response body. Only supports application/json.
    Content-Type Data format of the request body. Only supports application/json.
    Table 11. Response headers
    Header Description
    None

    Status codes

    The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

    Table 12. Status codes
    Status code Description
    200 Successful. The request was successfully processed.
    401 Unauthorized. The user credentials are incorrect or have not been passed.

    Response body parameters (JSON)

    Name Description
    result Object containing information about the status of the API request.

    Data type: Object

    "result": {
   "status": "String"
}
    result.status Status of the API request.

    Data type: String

    cURL request

    This example imports a project with two tasks (zpq_T1 and zpq_T2). The first task contains several child tasks, and the second task has dependencies on the child tasks from the first task.

    curl "https://instance.servicenow.com/api/now/ppm/insert_project_tasks" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
   "start_date": "2022-05-18 08:00:00",
   "end_date": "2022-05-18 17:00:00",
   "short_description": "zpq_Project",
   "external_id": "0",
   "child_tasks": [
      {
         "short_description": "zpq_T1",
         "external_id": "1",
         "child_tasks": [
            {
               "external_id": "1.1",
               "short_description": "zpq_T11",
               "child_tasks": [
                  {
                     "external_id": "1.1.1",
                     "short_description": "zpq_T111"
                  }
               ]
            },
            {
               "external_id": "1.2",
               "short_description": "zpq_T12"
            }
         ]
      },
      {
         "short_description": "zpq_T2",
         "external_id": "2",
         "dependencies": [
            {
               "external_id": "1.1",
               "lag": -1,
               "type": "fs"
            },
            {
               "external_id": "1.2",
               "lag": 2,
               "type": "fs"
            }
         ]
      }
   ]
}" \
--user 'username':'password'

    Response body.

    {
   "result": {
      "status": "success"
   }
}