Project Portfolio Management API

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

표 1. Path parameters

Name	Description
None

표 2. Query parameters

Name	Description
None

표 3. Request body parameters (JSON)

Name	Description
end_fiscal_period	Required. Sys_id of the ending fiscal period for the cost plan. Data type: String Table: Fiscal Period [fiscal_period]
name	Required. Name of the cost plan. Data type: String
resource_type	Required. Sys_id of the resource type. Data type: String Table: Resource Type Definition [resource_type_definition]
start_fiscal_period	Required. Sys_id of the starting fiscal period for the cost plan. Data type: String Table: Fiscal Period [fiscal_period]
task	Required. Sys_id of the project or demand for the cost plan. Data type: String Table: Project [pm_project] or Demand [dmn_demand]
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.

표 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.

표 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.

표 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

표 7. Path parameters

Name	Description
None

표 8. Query parameters

Name	Description
None

표 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.

표 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.

표 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.

표 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"
   }
}