This section details the API endpoints used to create, list, modify, and delete formula templates within a data structure.
Note : If you're not familiar with this feature, please consult the documentation on formula templates.
Retrieve the list of generic formulas in the data structure
This request returns a list of the various generic formulas present in the data structure.
GET /v2/data-structures/{data_structure_id}/formulas
Scope
This request requires the metadata:read scope.
Parameters
data_structure_id (string, required): ID of the tree. This ID can be retrieved via the
GET v2/data-structures
request or from the response when creating a new tree withPOST v2/data-structures
.
This parameter needs to be added to the URL to build the query string :
/v2/data-structures/{data_structure_id}/formulas
Request example
# Command to list a data structure's formulas
curl -X 'GET' \
'https://xxx.indaba.api.indasuite.io-base.com/v2/data-structures/67337415-6bcb-4c21-b0f5-8253d68b6e80/formulas' \
# ----- Headers -----
-H 'accept: application/json' \
-H 'Authorization: Bearer VOTRE_JETON_JWT'
Responses
example of a valid response (200 ok) :
{
"data": [
{
"id": "9b034dcf-0e5b-4b45-908a-1c07ff7880c1",
"metricTypeId": "0b3f2349-9b17-45d9-b7c4-0b47d0f39960",
"options": "Name",
"label": "DOPEN",
"metricTemplate": "main@DOPEN_{code_site}",
"version": 3,
"formula": {
"formulaTemplate": "if([id_moy]>0 or [id_moy]>0, 1, 0)",
"description": "Formule vérifiant si la diode du site {code_site} est ouverte ou non.",
"schedule": "0 6 * * *",
"timezone": "Europe/Paris",
"resultType": "REAL",
"sourceValidityInSecond": 0
}
}
],
"resultCode": 2010,
"message": "OK"
}
Common errors
Please refer to the list of common errors.
Retrieve generic formulas associated with a type
This request returns a list of the different generic formulas present within a specific type in your data structure.
GET /v2/data-structures/{data_structure_id}/types/{type_id}/formulas
Scope
To perform this request, you must have the metadata:read scope.
Parameters
data_structure_id (string, required): ID of the tree. This ID can be retrieved via the
GET v2/data-structures
request or from the response when creating a new tree withPOST v2/data-structures
.type_id (string, required): ID assigned to the element type.
This ID can be retrieved via the GET request /v2/data-structures/{data_structure_id}/types or following the creation of a new type with Post v2/data-structures/{data_structure_id}/types.
These parameters must be added to the URL to construct the query string :
.../data-structures/{data_structure_id}/types/{type_id}/formulas
Example Request
# Command to list formulas for a specific type
curl -X 'GET' \
'https://xxx.indaba.api.indasuite.io-base.com/v2/data-structures/67337415-6bcb-4c21-b0f5-8253d68b6e80/types/e9910c2b-83e9-4954-a1dd-abca2d833999/formulas' \
# ----- Headers -----
-H 'accept: application/json' \
-H 'Authorization: Bearer VOTRE_JETON_JWT'
Responses
example of a valid response (200 ok) :
{
"data": [
{
"id": "9b034dcf-0e5b-4b45-908a-1c07ff7880c1",
"metricTypeId": "0b3f2349-9b17-45d9-b7c4-0b47d0f39960",
"options": "Name",
"label": "DOPEN",
"metricTemplate": "main@DOPEN_{code_site}",
"version": 3,
"formula": {
"formulaTemplate": "if([id_moy]>0 or [id_moy]>0, 1, 0)",
"description": "Formule vérifiant si la diode du site {code_site} est ouverte ou non.",
"schedule": "0 6 * * *",
"timezone": "Europe/Paris",
"resultType": "REAL",
"sourceValidityInSecond": 0
}
}
],
"resultCode": 2010,
"message": "OK"
}
Common errors
Please refer to the list of common errors.
Create a new formula template
Description
This request allows you to add a new formula template to a specific type within your data structure.
POST /v2/data-structures/{data_structure_id}/types/{type_id}/formulas
Scope
To perform this request, you must have the metadata:admin scope.
Parameters
data_structure_id (string, required): ID of the tree. This ID can be retrieved via the
GET v2/data-structures
request or from the response when creating a new tree withPOST v2/data-structures
.type_id (string, required): ID assigned to the element type.
This ID can be retrieved via the GET request /v2/data-structures/{data_structure_id}/types or following the creation of a new type with Post v2/data-structures/{data_structure_id}/types.
These parameters must be added to the URL to construct the query string:
/v2/data-structures/{data_structure_id}/types/{type_id}/formulas
Request Body
{
"label": "string",
"metricTypeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"options": "Custom",
"formula": {
"resultType": "BOOL",
"schedule": "string",
"sourceValidityInSecond": 0,
"timezone": "string",
"description": "string",
"unit": "string",
"formulaTemplate": "string"
},
"metricTemplate": "string"
}
In the request body, provide the necessary information to create the formula template:
label: The label for the template.
metricTypeId: The ID of the desired "metric" type present in the data structure. The generated formulas (calculated metrics) will be added to the data structure with the "metric" type defined here.
formula:
resultType: The expected result type. Can be
BOOL
,REAL
, orINT
.schedule: The periodicity; a CRON expression is expected.
sourceValidityInSecond: Ensures that the calculation only executes with recent data by blocking the operation if input values are older than the specified duration, thereby guaranteeing result reliability.
Note: Set to
0
to disable this feature.timezone: The timezone.
description
unit: The unit to associate with the generic formulas.
formulaTemplate: The expression of the generic formula.
metricTemplate: The generic name for the formulas (calculated metrics) generated by the template.
Important : You must specify the database where the formulas will be stored. The syntax for this is: [database]@{tree_property}.documentation
Request example
# Command to create a new generic formula within a type
curl -X 'POST' \
'https://xxx.indaba.api.indasuite.io-base.com/v2/data-structures/67337415-6bcb-4c21-b0f5-8253d68b6e80/types/e9910c2b-83e9-4954-a1dd-abca2d833999/formulas' \
# ----- Headers -----
-H 'accept: application/json' \
-H 'Authorization: Bearer VOTRE_JETON_JWT' \
-H 'Content-Type: application/json' \
# ----- Request body -----
-d '
{
"label": "test_import",
"metricTypeId": "0b3f2349-9b17-45d9-b7c4-0b47d0f39960",
"options": "Custom",
"formula": {
"resultType": "REAL",
"schedule": "*/2 * * * *",
"sourceValidityInSecond": 0,
"timezone": "Europe/Paris",
"description": "test_description",
"unit": "C",
"formulaTemplate": "if([id_moy]>0 or [id_moy]>0, 1, 0)"
},
"metricTemplate": "main@{code_site}.val"
}
'
Responses
example of a valid response (200 ok) :
{
"data": {
"id": "b4ba1278-4e91-44b2-b6c5-8ced3d8fc1eb",
"metricTypeId": "0b3f2349-9b17-45d9-b7c4-0b47d0f39960",
"options": "Custom",
"label": "test_import",
"metricTemplate": "main@{code_site}.val",
"version": 1,
"formula": {
"formulaTemplate": "if([id_moy]>0 or [id_moy]>0, 1, 0)",
"description": "test_description",
"unit": "C",
"schedule": "*/2 * * * *",
"timezone": "Europe/Paris",
"resultType": "REAL",
"sourceValidityInSecond": 0
}
},
"resultCode": 2010,
"message": "OK"
}
Common errors
Please refer to the list of common errors.
Update a Generic Formula Template
Description
This request allows you to update an existing formula template for a given type within your data structure.
PUT /v2/data-structures/{data_structure_id}/types/{type_id}/formulas/{template_id}
Scope
To perform this request, you must have the metadata:admin scope.
Parameters
data_structure_id (string, required): ID of the tree. This ID can be retrieved via the
GET v2/data-structures
request or from the response when creating a new tree withPOST v2/data-structures
.type_id (string, required): ID assigned to the element type.
This ID can be retrieved via the GET request /v2/data-structures/{data_structure_id}/types or following the creation of a new type with Post v2/data-structures/{data_structure_id}/types.
template_id (string, mandatory): The ID assigned to the formula template you wish to edit. You can retrieve this ID via the
GET v2/data-structures/{data_structure_id}/types/{type_id}/formulas
request or when the formula template was created.
These parameters must be added to the URL to construct the query string :
/v2/data-structures/{data_structure_id}/types/{type_id}/formulas
Request Body
The request body is identical to creating a new formula template.
{
"label": "string",
"metricTypeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"options": "Custom",
"formula": {
"resultType": "BOOL",
"schedule": "string",
"sourceValidityInSecond": 0,
"timezone": "string",
"description": "string",
"unit": "string",
"formulaTemplate": "string"
},
"metricTemplate": "string"
}
Note : It's not possible to modify the "metricTemplate" field, which represents the generic name of the formulas (calculated metrics) generated by the template.
Example request
# Command to update an existing formula template
curl -X 'PUT' \
'https://xxx.indaba.api.indasuite.io-base.com/v2/data-structures/67337415-6bcb-4c21-b0f5-8253d68b6e80/types/e9910c2b-83e9-4954-a1dd-abca2d833999/formulas/b4ba1278-4e91-44b2-b6c5-8ced3d8fc1eb' \
# ----- Headers -----
-H 'accept: application/json' \
-H 'Authorization: Bearer VOTRE_JETON_JWT' \
-H 'Content-Type: application/json' \
# ----- Body request -----
-d '
{
"label": "test_modif_formulas_template",
"metricTypeId": "b63f4f26-2103-460f-bb89-727c341ccfb6",
"options": "Custom",
"formula": {
"resultType": "INT",
"schedule": "*/3 * * * *",
"sourceValidityInSecond": 60,
"timezone": "Europe/Lisbon",
"description": "modif_description",
"unit": "C",
"formulaTemplate": "[id_moy]*100"
},
"metricTemplate": "main@{code_site}.val"
}
'
Responses
example of a valid response (200 ok) :
{
"data": {
"id": "b4ba1278-4e91-44b2-b6c5-8ced3d8fc1eb",
"metricTypeId": "b63f4f26-2103-460f-bb89-727c341ccfb6",
"options": "Custom",
"label": "test_modif_formulas_template",
"metricTemplate": "main@{code_site}.val",
"version": 2,
"formula": {
"formulaTemplate": "[id_moy]*100",
"description": "modif_description",
"unit": "C",
"schedule": "*/3 * * * *",
"timezone": "Europe/Lisbon",
"resultType": "INT",
"sourceValidityInSecond": 60
}
},
"resultCode": 2010,
"message": "OK"
}
Common errors
Please refer to the list of common errors.
Delete a Generic Formula Template
DELETE /v2/data-structures/{data_structure_id}/types/{type_id}/formulas/{template_id}
Scope
To perform this request, you must have the metadata:admin scope.
Parameters
data_structure_id (string, required): ID of the tree. This ID can be retrieved via the
GET v2/data-structures
request or from the response when creating a new tree withPOST v2/data-structures
.type_id (string, required): ID assigned to the element type.
This ID can be retrieved via the GET request /v2/data-structures/{data_structure_id}/types or following the creation of a new type with Post v2/data-structures/{data_structure_id}/types.
template_id (string, mandatory): The ID assigned to the formula template you wish to edit. You can retrieve this ID via the
GET v2/data-structures/{data_structure_id}/types/{type_id}/formulas
request or when the formula template was created.
delete_metrics (boolean, optional): This indicates whether you want to delete the metrics associated with the template from the data structure. This field can be one of two values:
true
: The metrics associated with the template will be deleted from the data structure.false
(default value): The metrics associated with the template will be kept in the data structure.
These parameters must be added to the URL to construct the query string :
/v2/data-structures/{data_structure_id}/types/{type_id}/formulas?delete_metrics=[true or false]
Example Request
# Command to delete a formula template
curl -X 'DELETE' \
'https://xxx.indaba.api.indasuite.io-base.com/v2/data-structures/f9f16627-460e-4369-b345-a4ee3e94221e/types/88dacd49-2f01-4ca7-944c-6716322cb67e?delete_metrics=false' \
# ----- Headers -----
-H 'accept: application/json' \
-H 'Authorization: Bearer VOTRE_JETON_JWT'
Responses
example of a valid response (200 ok) :
{
"resultCode": 2010,
"message": "OK"
}
Common errors
Please refer to the list of common errors.
Common Errors
You will primarily encounter the following HTTP error codes:
400 Bad Request: Your request is malformed. This may be due to a missing parameter, an incorrect data type, or invalid JSON. The response body will contain an
errors
array detailing the problem.
{
"errors": [
{
"error": "Type_De_L_Erreur",
"message": "Description détaillée de l'erreur spécifique."
}
],
"statusCode": 1050,
"message": "Invalid request"
}
401 Unauthorized: Your authentication token (JWT) is missing, invalid, or expired. You must obtain a new valid token.
403 Forbidden: Your authentication token is valid, but you do not have the necessary rights for this action. This can happen for two reasons:
Your token does not have the required scope (e.g., you are trying to write data without the metrics:write scope).
Your token has the correct scope, but your user (or service account) is not linked to an authorization that grants access to the requested metric.
404 Not Found: The resource you are trying to reach does not exist. This typically occurs if you are using an incorrect ID or requesting a metric that does not exist.