Overview
eTool has API access, enabling third parties 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
API integration requires a certain level of technical expertise. You will need to consult with a qualified IT professional for assistance with integrations. We provide the API as is, and support for it is limited. If you require technical assistance from Cerclos related to API functionality, this falls outside our standard support and incurs additional fees.
Prerequisites:
- Active organisation subscribers with a valid hot seat can access the API functionality.
- You must have admin privileges at the organisational level to create an API refresh token
- The third party must have an API platform supporting OAuth 2.0-based authentication and authorisation via JWT tokens.
Instructions for the eTool Administrator:
To create a new refresh token:
- Navigate to the Organisation tab > Integrations
- Click on the “New Refresh Token Mode” button from the ‘Integrations’ 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
- Set the Access Token Expiry Time to a small number, such as 24 hours
- 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, run 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
|
designIds |
Comma separated designId. You can get the list of designs from GETDESIGNS() call. |
|
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)
|
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.
