Skip to main content

Formulas templates management

Updated over a month 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?