PPM Express exposes REST API that allows integrating PPM Express with third-party applications.
You can use it to build add-ons for PPM Express or develop integrations between PPM Express and other applications.
Authentication and Authorization
Access to the API is granted via personal tokens. You can create a personal token with the scopes you need on the PPM Express Automation settings page.
You need to insert the following header into each request:
Authorization: Bearer <your-token>
Thus, in order to create a new Project via API, users need to have both: permission to Create Project within PPM Express (People management) and Write Projects scope in the API token.
URL Structure
PPM Express API follows REST principles. You may access resources via URL paths. To use a REST API, your application makes secure HTTP requests.
Our REST API uses JSON as its communication format and the standard HTTP methods: GET, POST, and PATCH. URLs have the following structure:
https://host/@tenant-name/api-version/resource-name
You can get the actual URL for your tenant in the PPM Express Automation menu.
Resources
PPM Express REST API gives the possibility to create, read, and update Projects, Programs, Portfolios, Project Key Dates, Tasks, Ideas, Resources, Resource Plans, and Resource Calendars. As Projects and Ideas are separate entities with multiple sections, only fields from the Details section are available via API.
Besides, it is possible to get information about all fields of any entity (“Fields” feed), and details about the current User and token (“Me” feed). Also, the Resource Plan, Calendars and Calendar Exceptions can be managed via API.
The full list of all resources and methods can be obtained from the interactive API documentation tool (Swagger UI). Besides retrieving all resources, you can try to send a request directly from the browser and check the response.
You can access the Swagger UI depending on the location that your tenant is hosted on. The direct link can be found in your PPM Express tenant in the Automation menu.
Before making any requests, please make sure to authorize your session by clicking the Authorize button and filling it in with your token.
Once authorized, select the desired request and click the “Try it out” button:
You can get the full list of Tasks and Key Dates (created from PPM Express and External systems like Azure DevOps or Jira), but it is possible to edit only items created in PPM Express.
Working with Resource Calendars and Calendar Exceptions is available.
For example, if you need to create a global Calendar Exception, click Post, and provide the tenant name. There are several required fields in PPM Express when creating an Exception (Name, Start date, End date), so they need to be filled in from the API.
Similar actions are available for Resource Calendars of specific resources and set personal settings. You will need to provide the tenant name and the Resource ID to execute actions.
Working with a Resource Plan is available. Select the Resource Planning level in the Entity type to start working with the Resource Plan.
The entity you choose here depends on the Resource Planning level selected on the Tenant Settings page for your PPM Express tenant (Program, Portfolio, or Project level). For example, if the Project level is selected on the tenant level, it should also be selected as the entity type here.
Besides tasks, you can also create sub-tasks using simple POST or bulk create POST requests.
To create a sub-task, you need to indicate the parent task ID ["ParentID"] and/or task ID that is located below the expected sub-task ["insertBeforeId"]. Parameters should be indicated before "attributes":
[
{
"ParentID": "8466d4c0-0204-4949-865c-772e8bf9b11a",
"insertBeforeId": "105268ef-92dc-48dd-bede-78b6bb28bdaf",
"attributes": {
"Name": "Sample Task"
} }
]Requests features
Please take into account that POST and PATCH requests have different structures.
POST request:
{
"attributes": {
"Name": "Sample name",
"Field_1": 123,
"Field_2": "Test string"
}
}PATCH request:
{
"updates": {
“Field_1": 12.5,
"Field_2": "Test string edited"
}
}Unlike PPMX UI, you can pass any attributes when creating a Project here.
Field input formats
Statuses: defines the status category of a Project, Task, Key Date, or Deliverables.
Status categories transcript:
PPM Express value |
API value |
On Track |
0 |
At Risk |
1 |
Critical |
2 |
Done |
10 |
N/A |
-1 |
Project:
“OverallStatus”: 1
Task/Key Date/Deliverable:
“Status”: 0
Status can be updated manually only in case status auto-calculation is disabled.
On update/create you can use string values of status category: "On Track", "At Risk", "Critical", "Done", or "N/A", but when getting the data always a numeric value is displayed.
User and Resource: defines an assignee of a Task or Key Date, manager of a Project, or a custom field of these types. It is required to pass the User/Resource Id, Email, or Name in the request body.
Task/Key Date:
“AssignedTo”: [
{
“search”: “assignee1@gmail.com”
},
“search”: “Anna Doe”
},
{
“id”: “f1dc4b2a-6ca8-449e-b58b-09b9d6c91139”
}
]Tags can be added to all entities and sub-entities.
"Tags": [ "#api_tag1", "#api_tag2" ]
Program/Portfolio. You can add a Project to an existing Program and Portfolio by passing its ID or Name.
Project:
"Portfolio": [
{
"id": "13425407-63ae-4cb4-8104-bb5df22b9437"
},
{
"search": "e-Learning platform"
}
]To get the Program/Portfolio ID, you can open it from PPM Express and copy the ID from the URL:
https://host/@tenant-name/portfolio/portfolioID
Project Progress
Progress transcript:
PPM Express value |
API value |
Not Started |
0 |
Completed |
1 |
In Progress |
2 |
On Hold |
3 |
Canceled |
4 |
“Progress”: 2
Priority, Risk, Cost, Effort, Impact, Revenue, Business Priority: defines Priority of Project and Task, Project and Ideas Cost, Effort, Impact, Risk, Revenue, and all custom fields of Impact type.
Field transcript:
PPM Express value |
API value |
N/A |
0 |
Low |
1 |
Normal |
2 |
Moderate |
3 |
Strong |
4 |
Extreme |
5 |
Group: defines Tasks Group. To change the Group, Group Id or name is required:
"Group": {
"search": "Not Started Tasks"
}Predecessor: defines Task predecessor. To set a Predecessor, its Id or name is required:
"Predecessor": [
{
"id": "499b58c0-d898-40a6-9bbe-b84318e7cfe7"
},
{
"search": "Create QA environment"
}
],Successor’s Start Date is dependent on the Predecessor’s Due Date. In case a Task has a Predecessor, its Start Date can’t be edited.
Baseline: defines Tasks Baseline fields. To set the Task's Baseline, the separate PATCH feed should be used:
https://host/@tenant-name/v1.0/Projects/ProjectID/Tasks/bulk/baseline
Using this request, you can edit Baseline for several tasks within a single Project. Here is an example of the request:
[
{
"taskId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"baseline": {
"startDate": "2024-01-30T15:43:32.580Z",
"dueDate": "2024-01-30T15:43:32.580Z",
"duration": 0,
"effort": 0,
"originalEstimate": 0
}
}
]It is possible to set a Baseline only for our internal PPM Express tasks. If any of the Baseline fields is not indicated in the request, it will be erased in case its value has been already set for the task.
Key Date Type
Type transcript:
PPM Express value |
API value |
Key Date |
0 |
Milestone |
1 |
Release |
2 |
“Type”: 1
Idea’s Stage
Stage transcript:
PPM Express value |
API value |
Draft |
0 |
Proposed |
1 |
Active |
2 |
Selected |
3 |
Not Selected |
4 |
Archived |
5 |
In order to update Idea’s Stage, you will need to use the separate POST request that has the following structure:
{
"Stage": 5
}Please take into account that stages have a strict sequence that must be followed. In case stage shift is not possible, 400 status code will be returned. Please check the Managing Challenges and Ideas article for more details about the Idea stages.