Cost APIs - HxGN Smart Build - Version 5.0 U2 (5.0.2) - Customization & Programming

HxGN Smart Build Insight API Help

Language
English
Product
HxGN Smart Build
Subproduct
Insight
Search by Category
Customization & Programming

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 Insight 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 Insight 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 Insight 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"

}

]

}

]

}

]

}

]

}

Publish project resource types to Smart Build Insight

You can publish a single resource or multiple resource types, and their corresponding resource classification hierarchy using the following end points. This is similar to creating project resources using the Enterprise > Resources > Project tab in the User Interface.

Publish a project resource:

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

Sample request body:

{

"Name": "Test Resource Type",

"Code": "Resource Type Code 1",

"Description": "Test Description",

"UomID": "SQUARE_METER",

"Amount": 111,

"UnitCost": 111,

"CurrencyCode": "INR",

"ResourceClassification_Name": "{{PlumbingClassification}}"

}

Publish multiple project resources:

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

Sample request body:

{

"Items": [

{

"Name": "Test Resource Type 1",

"Code": "Code_{{$guid}}",

"Description": "Test Description",

"UomID": "SQUARE_METER",

"Amount": 111,

"UnitCost": 111,

"CurrencyCode": "INR",

"ResourceClassification_Name": "{{PlumbingClassification}}"

},

{

"Name": "Test Resource Type 2",

"Code": "Code_{{$guid}}",

"Description": "Test Description",

"UomID": "SQUARE_METER",

"Amount": 222,

"UnitCost": 222,

"CurrencyCode": "INR",

"ResourceClassification_Name": "{{PlumbingClassification}}"

},

{

"Name": "Test Resource Type 3",

"Code": "Code_{{$guid}}",

"Description": "Test Description",

"UomID": "SQUARE_METER",

"Amount": 333,

"UnitCost": 333,

"CurrencyCode": "INR",

"ResourceClassification_Name": "{{PlumbingClassification}}"

}

]

}

Publish global resource types to Smart Build Insight

You can publish a single resource or multiple resource types, and their corresponding resource classification hierarchy using the following end points. This is similar to creating project resources using the Enterprise > Resources > Global tab in the User Interface.

Publish a global resource:

POST <BASE_URL>/Tenants('{TenantId}')/ResourceTypes

Sample request body:

{

"Name": "Test Resource Type",

"Code": "Resource Type Code 1",

"Description": "Test Description",

"UomID": "SQUARE_METER",

"Amount": 111,

"UnitCost": 111,

"CurrencyCode": "INR",

"ResourceClassification_Name": "{{PlumbingClassification}}"

}

Publish multiple global resources:

POST <BASE_URL>/TSenants('{TenantId}')/ResourceTypes/Items

Sample request body:

{

"Items": [

{

"Name": "Test Resource Type 1",

"Code": "Code_{{$guid}}",

"Description": "Test Description",

"UomID": "SQUARE_METER",

"Amount": 111,

"UnitCost": 111,

"CurrencyCode": "INR",

"ResourceClassification_Name": "{{PlumbingClassification}}"

},

{

"Name": "Test Resource Type 2",

"Code": "Code_{{$guid}}",

"Description": "Test Description",

"UomID": "SQUARE_METER",

"Amount": 222,

"UnitCost": 222,

"CurrencyCode": "INR",

"ResourceClassification_Name": "{{PlumbingClassification}}"

},

{

"Name": "Test Resource Type 3",

"Code": "Code_{{$guid}}",

"Description": "Test Description",

"UomID": "SQUARE_METER",

"Amount": 333,

"UnitCost": 333,

"CurrencyCode": "INR",

"ResourceClassification_Name": "{{PlumbingClassification}}"

}

]

}

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