eTool API

Overview

eTool has API access for third parties, enabling them to retrieve impact data from an organisation’s project portfolio. The eTool API employs an OAuth 2.0 JWT one-time use refresh token mechanism.  

The following data can be shared:

  • Designs
  • Modules
  • Indicators
  • Impact design details

Prerequisites:

  • Only active organisation subscribers with a valid hot seat can access the API functionality.
  • To create an API refresh token from within eTool, the user must have admin privileges at the organisational level.
  • The third party must have an API platform that supports OAuth 2.0-based authentication and authorisation via JWT tokens.

Instructions for the eTool Administrator:

The initial refresh token is obtainable from the API Keys within the Organisation tab. To create a new refresh token: 

  • Select “New Refresh Token” from the Organisation tab
  • In the “Create New Token” window, give the new token a name or description that will make it easy to identify later on. It’s recommended to use a consistent naming convention, such as the name of the integration, consultant or third party involved 
  • Set the refresh expiry time to a large number, such as 10000 hours (why) 
  • Set the Access Token Expiry Time to a small number, such as 24 hours (why) 
  • Select “Close” and eTool will generate the new tokens
  • Click “Copy” and save the token details ready to share with the third-party
  • Confirm success by checking the box and selecting “Close”.

Note:

  • eTool does not keep refresh tokens for security purposes.
  • After the initial use, the refresh token becomes invalid and a new one is generated.
  • Refresh tokens cannot be shared or reused.

Instructions for Third Parties:

Ensure your API platform supports OAuth 2.0-based authentication. 

Validate and Obtain a New Token:

For added security, this API employs token rotation. During the set-up, the original refresh token is used to obtain a new access token. Once the refresh token is used, it becomes invalid and cannot be reused or shared. The access token however can be used many times until it expires. 

Autherntication API

The authorisation of the impact result data follows the authorisation for the logged-in user to view the design’s information.

Design Authorisation

API Post Request

To initiate the process, use the following post request:

An access token is retrievable from the POST call to GenerateAccessTokenFromRefreshToken.

POST GETACCESSTOKENFROMREFRESHTOKEN

Overview:

URL

https://www.etoollcd.com/Api/Shared/GenerateAccessFromRefreshToken

Methods Supported

POST

Description

Allows you to get a new refresh token and access token.

Mandatory Parameters

RefreshToken

For the first access token, use refresh token previously retrieved from the organisation page. Then use the rotated refresh token which is the output of this call.

Output

Token

New access token, which is valid for the duration specified during the refresh token creation.

RefreshToken

New rotated refresh token, please save this for the next call. 

 

API Functions / Methods

At this stage, there are only four functions/methods for calling the eTool API which is to get results.  We will likely expand on the available functions/methods in the future.  

GET GETDESIGNS

Overview:

URL

https://www.etoollcd.com/extapi/getdesigns

Methods Supported

GET

Description

Allows you to retrieve all designs in your organisation.

 

GET GETMODULES

Overview:

URL

https://www.etoollcd.com/extapi/getmodules

Methods Supported

GET

Description

Allows you to retrieve all modules.

 

GET GETINDICATORS

Overview:

URL

https://www.etoollcd.com/extapi/getindicators

Methods Supported

GET

Description

Allows you to retrieve all indicators.

 

GET GETIMPACTDESIGNDETAILS

Overview:

URL

https://www.etoollcd.com/extapi/getimpactdesigndetails?indicatorId=<IndicatorID>&aggregator=<aggregator>&groupFields=<groupFields>&<optional parameters>

Methods Supported

GET

Description

Allows you to retrieve impact results from all designs in your organisation, based on the grouping fields and optional filters.

Mandatory Parameters

indicatorId

Indicator Id for impact. You can get the list of indicators from GETINDICATORS() call.

aggregator

Sum / Average / Min / Max

groupFields

Comma separated list of fields by which the aggregate results will be grouped: DesignFunctionName, NestedTemplateName, NestedTemplateId, NestedTemplateQuantity, NestedTemplateUnit, ElementId, CategoryCode, CategoryName, ElementDescription, ElementType, ElementQuantity, ElementUnits, ElementRecurrenceFrequency, ElementProcessName, MaterialWasteFactor, MaterialMass, ProcessID, DisposalName, OpenLoopRecovery, ClosedLoopRecovery, OperationalSource, OperationalDemand, MasterTemplateId, MasterTemplateName, FunctionTypeName, YearOccurence, Module, ModuleDescription, UniqueAssetId, EmissionsScope, CustomFieldProject, CustomFieldStructure, CustomFieldDesign

Leaving the groupFields blank will remove the grouping and list all the granularities, however, data flooding may occur if a large number of groupings is requested for many designs.

Optional Parameters (filters)

designIds

Comma separated designId. You can get the list of designs from GETDESIGNS() call.

nestedTemplateIds

Comma separated nestedTemplateId

categoryIds

Comma separated building element categoryIds

  • 1 = Substructure
  • 8 = Superstructure
  • 44 = Internal finishes
  • 54 = Fittings, furnishings and equipment
  • 64 = Services equipment
  • 132 = Prefabricated buildings and building units
  • 137 = Work to existing building
  • 151 = External works
  • 191 = Facilitating works
  • 211 = Project/design team
  • 1016 = Undefined

disposalNames

Comma separated disposalNames

masterTemplateIds

Comma separated masterTemplateIds

yearOccurences

Comma separated year occurrences in ages, from year 0 onwards.

lifeCycleStages

Comma separated life cycle stage.

modules

Comma separated modules. You can get the list of designs from GETMODULES() call. At this stage the available options for the modules are: 

  • A1A3 = Product Stage
  • A4 = Transport of Equipment and Materials
  • A5 = Construction
  • B1 = General Use
  • B2B3 = Maintenance and Repair
  • B4 = Replacement
  • B5 = Refurbishment
  • B6 = Integrated Operational Energy Use
  • B6+ = Non-integrated Energy
  • B7 = Operational Water Use
  • C1 = Deconstruction and Demolition
  • C2 = Transport of Waste Offsite
  • C3 = Waste Processing
  • C4 = Disposal
  • D1 = Operational Energy Exports
  • D2 = Closed Loop Recycling
  • D3 = Open Loop Recycling
  • D4 = Materials Energy Recovery
  • D5 = Direct Reuse

elementIds

Comma separated elementIds

Example Calls and Responses

1) Retrieving the sum of all impact results grouped by Module

Example Call: https://www.etoollcd.com/extapi/getimpactdesigndetails?indicatorId=1&aggregator=Sum&groupFields=Module

Example Response:

{
  [
    ...
    {
      "Module": "D4",
      "ImpactValue": 10.303008941247342
    },
    {
      "Module": "B6",
      "ImpactValue": 508875.7753625
    }
    ...
  ]
}

 

GET GETIMPACTGROUPDETAILS (TBA)

Overview:

URL

https://www.etoollcd.com/extapi/getimpactgroupdetails?orgid=<orgId>&indicatorId=<IndicatorID>&aggregator=<aggregator>&groupFields=<groupFields>Module,CategoryName&<optional parameters>

Methods Supported

GET

Description

Allows you to retrieve impact results from all designs in your organisation, based on the grouping fields and optional filters.

Mandatory Parameters

orgId

Organisation Id associated with your organisation

indicatorId

Indicator Id for impact.  At this stage the available options for the indicatorID are: 

  • 1 = Global Warming Potential 
  • 3 = Australian Dollar
  • 25 = British Pounds Sterling
  • 26 = Euro
  • 45 = US Dollar
  • 46 = New Zealand Dollar
  • 54 = Material Mass

aggregator

Sum / Average / Min / Max

groupFields

Comma separated list of fields by which the aggregate results will be grouped: DesignName, DesignCertified, DesignFavourite, DesignPurpose, ScenarioTree, ScenarioTitle, ParentScenarioID, DesignFunctionName, NestedTemplateName, NestedTemplateId, NestedTemplateQuantity, NestedTemplateQuantity, ProcessID, DisposalName, CategoryCode, CategoryName, MasterTemplateId, MasterTemplateName, FunctionTypeName, ElementType, YearOccurence, LifeCycleStage, Module, Module Description

Data flooding may occur if a large number of groupings is requested for many designs.

Optional Parameters (filters)

designIds

Comma separated designId

nestedTemplateIds

Comma separated nestedTemplateId

categoryIds

Comma separated building element categoryIds

  • 1 = Substructure
  • 8 = Superstructure
  • 44 = Internal finishes
  • 54 = Fittings, furnishings and equipment
  • 64 = Services equipment
  • 132 = Prefabricated buildings and building units
  • 137 = Work to existing building
  • 151 = External works
  • 191 = Facilitating works
  • 211 = Project/design team
  • 1016 = Undefined

disposalIds

Comma separated disposalIds

masterTemplateIds

Comma separated masterTemplateIds

yearOccurenceAges

Comma separated year occurrences in ages, from year 0 onwards.

yearOccurenceDates

Comma separated year occurrences in calendar years (2020, 2021, 2022, etc).

modules

Comma separated modules. At this stage the available options for the modules are: 

  • A1A3 = Product Stage
  • A4 = Transport of Equipment and Materials
  • A5 = Construction
  • B1 = General Use
  • B2B3 = Maintenance and Repair
  • B4 = Replacement
  • B5 = Refurbishment
  • B6 = Integrated Operational Energy Use
  • B6+ = Non-integrated Energy
  • B7 = Operational Water Use
  • C1 = Deconstruction and Demolition
  • C2 = Transport of Waste Offsite
  • C3 = Waste Processing
  • C4 = Disposal
  • D1 = Operational Energy Exports
  • D2 = Closed Loop Recycling
  • D3 = Open Loop Recycling
  • D4 = Materials Energy Recovery
  • D5 = Direct Reuse

elementIds

Comma separated elementIds

designPurposeID

Comma separated design purpose

  • 1 = Target Setting – Business as Usual
  • 2 = Target Setting – Improved
  • 3 = Target Setting – Scenario
  • 4 = Target Setting – Final
  • 5 = LCA – Proposed
  • 6 = LCA – Improved
  • 7 = LCA – Scenario
  • 8 = LCA – Final
  • 9 = LCA – Audit
  • 10 = LCA – Business as Usual
  • 11 = LCA – As Built

isFavourite

Boolean value where 1 signifies that the design is marked as a favourite for that structure (there is only one favourite design per structure, intended to indicate the design team’s favourite design. 0 signifies the design is not marked as a favourite.

isCertified

Boolean value where 1 signifies that the design is certified (independently reviewed). 0 signifies the design is not certified.

Example Calls and Responses

1) Retrieving the sum of all impact results grouped by Module

Example Call: https://www.etoollcd.com/extapi/getimpactgroupdetails?orgid=1&indicatorId=1&aggregator=Sum&groupFields=Module

Example Response:

{
  "Result": [
    ...
    {
      "Module": "D4",
      "ImpactValue": 10.303008941247342
    },
    {
      "Module": "B6",
      "ImpactValue": 508875.7753625
    }
    ...
  ]
}

 

2) Retrieving the average of all impact results grouped by categoryName for module A1A3

Example Call: https://www.etoollcd.com/extapi/getimpactgroupdetails?orgid=12&indicatorId=1&aggregator=Average&groupFields=Module,CategoryName&modules=A1A3

Example Response:

{
  "Result": [
    ...
    {
      "Module": "A1A3",
      "CategoryName": "Civil Engineering Structure",
      "ImpactValue": 19386.449602815534
    },
    {
      "Module": "A1A3",
      "CategoryName": "Balustrades and handrails",
      "ImpactValue": 1549.6984477864078
    }
    ...
  ]
  ,
  "CategoryDictionary": [
    ...
    {
      "CategoryName": 1,
      "ImpactValue": “Substructure”
    },
    {
      "CategoryName": 2,
      "ImpactValue": “Standard foundations”
    }
    ...
  ]
}
Throttling: 

API calls are being processed on a first come first serve basis. There is a limit of 15 seconds applied for each call to assure no calls are bottlenecking the API network.

 

 

 

Leave A Comment?

You must be logged in to post a comment.