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.

Knowledge Base

eTool API

Overview

Prerequisites:

Instructions for the eTool Administrator:

Instructions for Third Parties:

Validate and Obtain a New Token:

API Post Request

POST GETACCESSTOKENFROMREFRESHTOKEN

Overview:

Mandatory Parameters

Output

API Functions / Methods

GET GETDESIGNS

Overview:

GET GETMODULES

Overview:

GET GETINDICATORS

Overview:

GET GETIMPACTDESIGNDETAILS

Overview:

Mandatory Parameters

Example Calls and Responses

GET GETIMPACTGROUPDETAILS (TBA)

Overview:

Mandatory Parameters

Example Calls and Responses

Throttling:

Leave A Comment? Click here to cancel reply.