Cost APIs - HxGN Smart Build - 4.0 U10 (4.0.10) - Help - Hexagon

HxGN Smart Build Insight API Help

Language
English (United States)
Product
HxGN Smart Build
Search by Category
Help

The following list summarizes the actions or operations that can be performed using the cost API endpoints. For more information on schema elements, refer the metadata available at <BASE_URL>/v1/annotations/$metadata.

Retrieve all the resources

You can retrieve the resources, resource types, and their corresponding resource classification hierarchy. This is similar to viewing the resources on the Enterprise > Resources > Global tab or the Project tab in the User Interface.

  • Global Resources - Use the following endpoint to fetch all the resources available in a tenant with the requested ID.

    GET <BASE_URL>/Tenants('{TenantId}')/ResourceTypeTree

  • Project Resources - Use the following endpoint to fetch all the resources available in a project with the requested ID.

    GET <BASE_URL>/Tenants('{TenantId}')/Projects('{ProjectId'})/ResourceTypeTree

Retrieve all the bill of quantities (BOQ) available in a project 

You can retrieve all the entities under the default root BOQ structure node, including all its child BOQ structures and quantity items. This is similar to browsing all the bill of quantities in the Quanitification > Bill of Quantities page in the User Interface.

GET <BASE_URL>/Tenants('{TenantId}')/Projects('{ProjectId}')/BillOfQuantities('{QuantityStructureId}')?$expand=QuantityStructures($expand=QuantityStructures($expand=QuantityItems))

You can further expand the query to drill down the QuantityStructures to the deepest level. You can also expand the query to fetch the quantity items under a specific BOQ structure node. For example, the following endpoint returns the requested quantity item and its additional properties under the second level BOQ structure node.

GET <BASE_URL>/Tenants('{TenantId}')/Projects('{ProjectId'})/BillOfQuantities('{QuantityStructureId}')/
QuantityStructures('{QuantityStructureId}')/QuantityItems('{QuantityItemId}')/AdditionalProperties

Retrieve progress and dates of all the cost items in a project

You can retrieve the progress, start and end dates of all the cost items in the project.

GET <BASE_URL>/Tenants('{TenantId}')/Projects('ProjectId')/ProgressAndDates

Publish KPI data from an external cost system

You can publish cost KPI data such as budget, forecast, actuals, approved and pending change orders to a Smart Build project.

POST <BASE_URL>/Tenants('{TenantId}')/Projects('ProjectId')/CostKPI

Sample request body:

{

"Budget": 50000.50,

"Actuals": 25000.25,

"Forecast": 50005.00,

"plannedPercentComplete": 50.00,

"ChangeOrderPending": 8000.00,

"ChangeOrderApproved": 4000.00,

"ActualPercentComplete": 45.25,

"BudgetDetails": "[{\"key1\" : \"value1\"},{\"key2\" : \"value2\"}]",

"ForecastDetails": "[{\"key1\" : \"value1\"},{\"key2\" : \"value2\"}]",

"ActualsToDateDetails": "[{\"key1\" : \"value1\"},{\"key2\" : \"value2\"}]"

}

If you successfully posted the request, open the Overview page in Smart Build and you should see that the Project Cost widget is updated with KPI data.

Refer the Smart API Explorer documentation for information related to the parameters and their associated data type values used in the API requests.

Publish cost data to a Smart Build project

You must connect the project in external cost system with the project in Smart Build Insight to which you want to publish cost estimate.

Any cost data imported or published from a third-party cost system is first pushed to the staging area and then to the working area after approving the data. This is to ensure that you are not overwriting the data accidentally.

You can publish the entire cost breakdown structure using the following endpoints in the specified order.

  1. Push the data to staging area.

    POST <BASE_URL>/Tenants('{TenantId}')/Projects('ProjectId')/Estimate?staging=true

  2. Approve the data in the staging area.

    POST <BASE_URL>/Tenants('{TenantId}')/Projects('ProjectId')/Estimate?stagingapprove=true

Once the request is approved, go to the Cost Management feature and you should see the cost data published. If you don't see the data immediately, try refreshing the web page.

For example, the following request creates a cost breakdown structure with a parent and child cost items, and the child items have resources, hyperlinks, and custom properties. Also the child item Estimateitem1 is associated with specified BOQ items and CS codes (StructItems).

{

"ExternalSystemId": "ExternalSystemUniqueId",

"Name": "Estimate Name ",

"Phase": "Contract",

"Status": "Final",

"Type": "Budget",

"CurrencyCode": "SEK",

"Description": "Estimate Desc",

"TotalCost": 1400.21,

"TotalLabourCost": 100.12,

"TotalMaterialCost": 1500.09,

"TotalLabourTime": 30.5,

"Remark": "Estimate Remark",

"EstimateItems": [

{

"ExternalSystemId": "ExternalSystemUniqueId",

"Name": "Estimateitem Name",

"Description": "Estimateitem Desc",

"Remark": "Estimateitem Remark",

"Quantity": 20.1,

"UOM": "PIECE",

"TotalCost": 340.32,

"TotalLabourCost": 50.17,

"TotalMaterialCost": 300.15,

"TotalLabourTime": 5.3,

"HyperLinks": [

{

"Name": "Google",

"URL": "https://www.google.com",

"Description": "Google URL"

}

],

"CustomPropertySets": [

{

"name": "Custom Properties",

"key1": "Value1",

"key2": "Value2"

}

],

"EstimateItems": [

{

"ExternalSystemId": "ExternalSystemUniqueId",

"Name": "Estimateitem1",

"Description": "Estimateitem1 Desc",

"Remark": "Estimateitem1 Remark",

"Quantity": 60.1,

"UOM": "PIECE",

"TotalCost": 640.32,

"TotalLabourCost": 60.17,

"TotalMaterialCost": 600.15,

"TotalLabourTime": 6.3,

"HyperLinks": [

{

"Name": "Google",

"URL": "https://www.google.com",

"Description": "Google URL"

}

],

"CustomPropertySets": [

{

"name": "Custom Properties",

"key1": "Value1",

"key2": "Value2"

}

],

"StructItems": [

{

"Id": "62791a31-b631-453f-b263-33bec267d7cf"

},

{

"Id": "88ca3a8d-54ae-40ed-a969-30dab60892f1"

}

],

"BoQItems": [

{

"Id": "d705d994-41d4-4710-bbe9-57d21ee11e4d"

},

{

"Id": "b0bd94ef-b40c-4e47-8340-2436a3a74166"

}

],

"ResourceAssemblies": [

{

"ExternalSystemId": "ExternalSystemUniqueId",

"Name": "Resource Assembly 1",

"Description": "Resource Assembly 1 Desc",

"Sequence": 2,

"Remark": "Resource Assembly 1 Remark",

"Quantity": 20.5,

"UOM": "METER",

"UnitCost": 200.12,

"ResourceItems": [

{

"ExternalSystemId": "ExternalSystemUniqueId",

"Quantity": 2,

"TotalCost": 200,

"Remark": "ResourceItem 1 Remark",

"ResourceTypes": [

{

"Code": "100001"

}

]

}

],

"HyperLinks": [

{

"Name": "Google",

"URL": "https://www.google.com",

"Description": "Google URL"

}

]

}

],

"ResourceItems": [

{

"ExternalSystemId": "ExternalSystemUniqueId",

"Quantity": 2,

"TotalCost": 200,

"Remark": "ResourceItem 1 Remark",

"ResourceTypes": [

{

"Code": "100001"

}

]

}

]

}

]

}

]

}

Refer the Smart API Explorer documentation for information related to the parameters and their associated data type values used in the API requests.