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.
The authorisation of the impact result data follows the authorisation for the logged-in user to view the design’s information.
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
|
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:
|
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:
|
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
|
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:
|
elementIds |
Comma separated elementIds |
designPurposeID |
Comma separated design purpose
|
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.