Skip to main content

Formulas templates management

Updated over a week ago

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

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

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

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, or INT.

    • 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

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

  • 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.

Did this answer your question?