The following list summarizes the actions or operations that can be performed using the schedule API endpoints. For more information on schema elements, refer the metadata available at <BASE_URL>/v1/annotations/$metadata.
Retrieve the schedule from Smart Build Insight to use in another tool
You can retrieve the schedule as well as all the entities under the entered WBS Item ID, such as work packages, work steps, resources, resource types, associated calendars, and classification structures (CS codes). This endpoint fetches a similar result when you publish the schedule to a project management tool from Smart Build Insight.
GET <BASE_URL>/Tenants('{TenantId}')/Projects('ProjectId')/Schedule('{WBSId}')
Retrieve the work packages in a project
This endpoint fetches all the work packages under the second level WBS item with the requested ID. This is similar to viewing the work packages under a WBS item in the Scheduling feature.
GET <BASE_URL>/Tenants('{TenantId}')/Projects('{ProjectId}')/Schedule('{WBSId}')/WBSChildren('{WBSId}')/Workpackages
Retrieve the assigned work packages in a project
This end point fetches all the work packages assigned to you in a project with requested ID. This is similar to viewing the assigned work packages in the My Work Packages feature.
GET <BASE_URL>/Tenants('{TenantId}')/Users('{UserId}')/WorkPackages?ProjectUid=<ProjectId>
You can expand the endpoint to get the work packages along with work steps, calendars, and resource items. For example, the following endpoint fetches the work packages along with work steps and calendars associated to the work packages.
GET <BASE_URL>/Tenants('{TenantId}')/Users('{UserId}')/WorkPackages?ProjectUid=<ProjectId>&$expand=Calendars,WorkSteps
Similarly, you can further expand the endpoint to fetch all the entities associated to the assigned work packages, such as calendars associated to the work packages, work steps and their associated calendars, and resource items.
GET <BASE_URL>/Tenants('{TenantId}')/Users('{UserId}')/WorkPackages?ProjectUid=<ProjectId>&$expand=Calendars,WorkSteps($expand=Calendars,ResourceItems)
Retrieve work steps from the assigned work packages in a project
This end point fetches all the work steps from the work packages assigned to you in a project with requested ID. This is similar to viewing the work steps of an assigned work package in the My Work Packages feature.
GET <BASE_URL>/Tenants('{TenantId}')/Users('{UserId}')/WorkPackages('{WorkPackageId}')/WorkSteps?ProjectUid=<ProjectId>
Retrieve a milestone
This endpoint fetches all the milestones under the second level WBS item with the requested ID. This is similar to viewing the milestones under a WBS item in the Scheduling feature.
GET <BASE_URL>/Tenants('{TenantId}')/Projects('{ProjectId}')/Schedule('{WBSId}')/WBSChildren('{WBSId}')/Workpackages
You need to look for milestone details in the response using Start_Milestone and Finish_Milestone values.
Retrieve CS codes from Smart Build Insight
You can retrieve all the entities in the requested structure item in the project with the requested ID. This produces a similar result when you export a classification structure (CS codes) from Smart Build Insight using the User Interface.
GET <BASE_URL>/Tenants('{TenantId}')/Projects('ProjectId')/StructItems('{StructItemId}')
Retrieve a calendar
You can further expand the endpoints to get entities such as work days, work hours, and work exceptions (holidays and time offs). This is similar to viewing a calendar in the User Interface.
-
Global Calendar - Use the following endpoint to fetch the calendar in a tenant with the requested ID.
GET <BASE_URL>/Tenants('{TenantId}')/Calendar('{CalendarId}')
-
Project Calendar - Use the following endpoint to fetch the calendar in a project with the requested ID.
GET <BASE_URL>/Tenants('{TenantId}')/Projects('ProjectId')/Calendar('{CalendarId}')
The /Calendar and /StructItems endpoints allow the synchronization of the schedule data between Smart Build Insight and your application.
Create a milestone in a project
This endpoint creates a milestone under the second level WBS item with the requested ID. This is similar to creating the milestones under a WBS item in the Scheduling feature.
POST <BASE_URL>/Tenants('{TenantId}')/Projects('{ProjectId}')/Schedule('{WBSId}')/WBSChildren('{WBSId}')/Workpackages
Sample request body for a start milestone:
{
"Name": "Commencement of ground floor",
"Type": "Start_Milestone",
"PlannedStartDate": "2022-10-06T06:00:36.160Z"
}
Sample request body for a finish milestone:
{
"Name": "Completion of ground floor",
"Type": "Finish_Milestone",
"PlannedEndDate": "2022-10-06T06:00:36.160Z"
}
Publish the schedule to a Smart Build Insight project
Any schedule data imported or published from a third-party system is first pushed to the staging area and then to the working area after approval. This is to ensure that you are not overwriting the data accidentally.
You can publish the entire work breakdown structure using the following endpoints in the specified order.
-
Connect the project in external scheduling system with the project in Smart Build Insight, to which you want to publish the schedule.
-
Push the data to staging area.
POST <BASE_URL>/Tenants('{TenantId}')/Projects('{ProjectId}')/Schedule?staging=true
-
Approve the data in the staging area.
POST <BASE_URL>/Tenants('{TenantId}')/Projects('ProjectId')Schedule?stagingapprove=true
Once the request is approved, go to the Scheduling feature and you should see the schedule published. If you don't see the data immediately, try refreshing the web page.
For example, the following request creates a work breakdown structure with a WBS item that has two work packages under it, and each work package has a work step.
{
"Name": "1",
"description": "Test WBS",
"WBSChildren": [
{
"Name": "1.1",
"description": "Test WBS Item",
"WorkPackages": [
{
"Name": "WP1",
"WorkPackageStatus": "Open",
"Purpose": "Inspection",
"WorkEffort": 10,
"PlannedStartDate": "2021-07-13T07:00:00.000Z",
"PlannedEndDate": "2021-07-15T17:00:00.000Z",
"Calendars": [
{
"Id": "07053b78-bc18-4ea6-9a1d-ed33d9f7f910"
}
],
"WorkSteps": [
{
"Name": "ws1",
"PlannedStartDate": "2021-07-14T07:00:00.000Z",
"PlannedEndDate": "2021-07-15T17:00:00.000Z",
"Sequence": 1,
"UpdateProgressBy": "Quantity",
"PlannedQuantityUOM": "PER_FOOT",
"PlannedQuantity": 23.0,
"SyncPlannedQuantityWithAllocatedCostQuantity": false,
"QuantitiesToBeReviewed": false,
"WorkEffort": 105,
"Calendars": [
{
"Id": "07053b78-bc18-4ea6-9a1d-ed33d9f7f910"
}
]
}
]
},
{
"Name": "WP2",
"WorkPackageStatus": "Open",
"Purpose": "Inspection",
"WorkEffort": 10,
"PlannedStartDate": "2021-07-14T07:00:00.000Z",
"PlannedEndDate": "2021-07-15T17:00:00.000Z",
"WorkSteps": [
{
"Name": "ws1",
"PlannedStartDate": "2021-07-14T07:00:00.000Z",
"PlannedEndDate": "2021-07-15T17:00:00.000Z",
"Sequence": 1,
"WorkEffort": 100,
"UpdateProgressBy": "Percentagengchg"
}
]
}
]
}
]
}
Refer the Smart API Explorer documentation for information related to the parameters and their associated data type values used in the API requests.
Update the work package progress
The following endpoint produces a similar result updating the work package using the User Interface. You can further expand the query to drill down the WBSChildren to the deepest level.
PUT <BASE_URL>/Tenants('{TenantId}')/Projects('{ProjectId}')/Schedule('{WBSId}')/WBSChildren('{WBSId}')/WorkPackages('{WorkPackageId}')
Sample request body:
{
"PercentageDone": 5,
"EstimatedStartDate": "2021-07-13T07:00:00.000Z",
"EstimatedEndDate": "2021-07-15T15:00:00.000Z",
}
Update the work step progress
You can update the the progress of a work step by percentage done or installed quantity. The following endpoint produces a similar result updating the work step using the User Interface. You can further expand the query to drill down the WBSChildren to the deepest level.
PUT <BASE_URL>/Tenants('{TenantId}')/Projects('{ProjectId}')/Schedule('{WBSId}')/WBSChildren('{WBSId}')/WorkPackages('{WorkPackageId}')/WorkSteps('{WorkStepId}')
Sample request body to update progress by percentage:
{
"PercentageDone": 5,
"EstimatedStartDate": "2021-07-13T07:00:00.000Z",
"EstimatedEndDate": "2021-07-15T15:00:00.000Z",
}
Sample request body to update progress by installed quantity:
{
"InstalledQuantity": 5,
"EstimatedStartDate": "2021-07-13T07:00:00.000Z",
"EstimatedEndDate": "2021-07-15T15:00:00.000Z",
}
Update the progress of an assigned work package in a project
The following endpoint produces a similar result updating the progress of an assigned work package in a project using the User Interface.
PUT <BASE_URL>Tenants('{TenantId}')/Users('{UserId}')/WorkPackages('{WorkPackageId}')?ProjectUid=<ProjectId>
Sample request body
{
"PercentageDone": 50
}
Update the progress of work step of an assigned work package in a project
The following endpoint produces a similar result updating the progress of a work step of an assigned work package in a project using the User Interface.
PUT <BASE_URL>Tenants('{TenantId}')/Users('{UserId}')/WorkPackages('{WorkPackageId}')/WorkSteps('{WorkStepId}')?ProjectUid=<ProjectId>
Sample request body
{
"PercentageDone": 50
}
Refer the Smart API Explorer documentation for information related to the parameters and their associated data type values used in the API requests.