Favorites, tagging, renaming

This article deals with managing favorites, renamings, and tags for datapoints.

Overview¶

This article deals with creating favorites, renamings, and tags on datapoints as well as modifying and removing them. We start by adding, querying, and removing favorite datapoints. We then cover the concept of datapointkeys, and show how datapoints can be assigned alternate names (renamings). Finally, we cover creating tags, assigning them to datapoints, modifying them and their association with a datapoint, and ultimately removing associations with a datapoint or removing tags completely.

We provide concrete examples on how to use the aedifion HTTP API to create, inspect, modify and delete favorites, renamings, tags and tag assignments to datapoints.

Preliminaries¶

The examples provided in this article partly build on each other. For the sake of brevity, boiler plate code such as imports or variable definitions is only shown once and left out in subsequent examples.

To execute the examples provided in this tutorial, the following is needed:

• A valid login (username and password) to the aedifion.io platform. If you do not have a login yet, please contact us regarding a demo login. The login used in the example will not work!
• A project with datapoints.
• Optionally, a working installation of Python or Curl.

Favorites¶

Favorites are a way of flagging datapoints that you frequently view. They are, e.g., used in the frontend to sort the datapoint selector list where they are marked by a star ⭐️. Favorites are scoped to the user, i.e., each user can have different favorites and is not able to see other users' favorites.

Adding a favorite¶

You flag a datapoint as a favorite using the POST /v2/datapoint/favorite endpoint which takes the following parameters:

Note that all parameters are query parameters, i.e., they're added in url-encoded form to the query part of the requested URL (the part following the domain and path separated by a question mark). If you are not aware of the project_id you are authenticated for, check out the Viewing company details tutorial.

import requests

api_url = 'https://api.aedifion.io'
auth_john = ('john.doe@aedifion.com', 'mys3cr3tp4ss0wrd')
project_id = 1
query_params = {
    'project_id': project_id, 
    'dataPointID': 'bacnet100-4120-CO2'
}
r = requests.post(f"{api_url}/v2/datapoint/favorite", 
                  auth=auth_john,
                  params=query_params)
print(r.status_code, r.json())

curl 'https://api.aedifion.io/v2/datapoint/favorite?project_id=1&dataPointID=bacnet100-4120-CO2'
    -X POST
    -u john.doe@aedifion.com:mys3cr3tp4ssw0rd

Posting a favorite creates a relation between you (your user account) and a datapoint. On success, this relation (user, datapoint) is returned in the resource field of the answer.

{
  "operation": "create",
  "resource": {
    "datapoint": {
      "dataPointID": "bacnet100-4120-CO2",
      "hash_id": "Jw0EdgdG",
      "id": 121,
      "project_id": 1
    },
    "user": {
      "company_id": 1,
      "email": "john.doe@aedifion.com",
      "firstName": "John",
      "id": 1,
      "lastName": "Doe"
    }
  },
  "success": true
}

Let's shoot a few more requests and flag the following as favorites, too:

• CO2_within_your_office
• TEMP_within_your_office

You can only flag datapoints as favorites that exist in your project. If you pass a non-existing dataPointID, you will get the following error:

{
  "error":"Datapoint does not exist in project: 'does_not_exist'",
  "operation":"create",
  "success":false
}

Querying favorites¶

What use are favorites when you cannot quickly access them? That's what the GET /v2/project/{project_id}/datapoints/favorites endpoint is there for. It takes the project_id as the single parameter and returns all of the logged-in user's favorites.

r = requests.get(f"{api_url}/v2/project/{project_id}/datapoints/favorites", 
                 auth=auth_john)
print(r.status_code, r.json())

curl 'https://api.aedifion.io/v2/project/1/datapoints/favorites'
    -X GET
    -u john.doe@aedifion.com:mys3cr3tp4ssw0rd

The response is a list of all your favorite datapoints in the specified project.

[
  ...,
  "bacnet100-4120-CO2",
  "CO2_within_your_office",
  "datapoint_within_your_office",
  "TEMP_within_your_office",
  ...
]

Deleting a favorite¶

Maybe that datapoint_within_your_office is not that important after all. Removing it from the list of your favorites is a simple matter of calling DELETE /v2/datapoint/favorite with the usual parameters:

query_params = {
    'project_id': project_id,
    'dataPointID': 'datapoint_within_your_office'
}
r = requests.delete(f"{api_url}/v2/datapoint/favorite",
                    auth=auth_john,
                    params=query_params)
print(r.status_code, r.json())

curl 'https://api.aedifion.io/v2/datapoint/favorite?project_id=1&dataPointID=datapoint_within_your_office'
    -X DELETE
    -u john.doe@aedifion.com:mys3cr3tp4ssw0rd

The answer confirms the deletion of the favorite and returns the deleted (user, datapoint) relation similar to the creation of a favorite.

{
  "operation": "delete",
  "resource": {
    "datapoint": {
      "dataPointID": "datapoint_within_your_office",
      "hash_id": "Jw0EdgdG",
      "id": 121,
      "project_id": 1
    },
    "user": {
      "company_id": 1,
      "email": "john.doe@aedifion.com",
      "firstName": "John",
      "id": 1,
      "lastName": "Doe"
    }
  },
  "success": true
}

Renamings¶

A datapoint identifier (dataPointID) is obtained directly and automatically from the component from which the datapoint is read, e.g., from a BACnet device. Thus, the dataPointIDs that are displayed as a datapoint's default name are not necessarily nice to read or even correct.

Renamings provide a way to assign a different name (or even multiple different names) to a datapoint. A renaming always belongs to a datapointkey which bundles related renamings of multiple datapoints. This allows, e.g., to add a translation of datapoint names into different languages (the datapointkey would be the language) or to add standardized datapoint names (the datapointkey would be the name of the standard such as BUDO).

In the following, we demonstrate the renaming flow by the example of translating some datapoints' names to german.

Adding datapointkeys¶

Before we can rename any datapoints, we need to create a datapointkey that bundles the datapoint renamings. A new datapointkey is created through POST /v2/project/{project_id}/datapointkey.

To create the new datapointkey, we pass the project_id in the path of the request and the details of the new datapointkey in the request's body encoded as a JSON object.

new_key = {
    "name": "german",
    "description": "Translation into german language."
}
r = requests.post(f"{api_url}/v2/project/{project_id}/datapointkey", 
                  auth=auth_john,
                  json=new_key)
print(r.status_code, r.json())

curl https://api.aedifion.io/v2/project/1/datapointkey
    -X POST
    -H 'Content-Type: application/json'
    -u john.doe@aedifion.com:mys3cr3tp4ssw0rd
    -d '{
        "description": "Translation into german language.",
        "name": "german"
    }'

The response confirms the creation of the new datapointkey. Note down the id as we will need it later.

{
  "operation": "create",
  "resource": {
    "decription": "Translation into german language.",
    "id": 19,
    "name": "german",
    "project_id": 1
  },
  "success": true
}

Now that we have created a new datapointkey, we can go ahead and rename datapoints w.r.t. this datapointkey.

Adding renamings¶

A renaming of a datapoint is added through the POST /v2/datapoint/renaming endpoint which requires the following parameters:

query_params = {
    "project_id": project_id,
    "dataPointID": "datapoint_within_your_office"
}
renaming = {
    "datapointkey_id": 19,
    "renaming": "datenpunkt_in_deinem_büro"
}
r = requests.post(f"{api_url}/v2/datapoint/renaming", 
                  auth=auth_john,
                  params=query_params,
                  json=renaming)
print(r.status_code, r.json())

curl 'https://api.aedifion.io/v2/datapoint/renaming?project_id=1&dataPointID=datapoint_within_your_office'
    -X POST
    -H 'Content-Type: application/json'
    -u john.doe@aedifion.com:mys3cr3tp4ssw0rd
    -d '{
        "datapointkey_id": 19,
        "renaming": "datenpunkt_in_deinem_büro"
    }'

On success, the response confirms the creation of the renaming.

{
  "operation": "create",
  "resource": {
    "datapointkey_id": 19,
    "id": 16,
    "renaming": "datenpunkt_in_deinem_büro"
  },
  "success": true
}

If the datapoint already has a renaming w.r.t. this datapointkey an error is returned:

{
  "error": "Renaming 16 already renames datapoint 121 for datapointkey 19.",
  "operation": "create",
  "success": false
}

Modifying renamings¶

An existing renaming can be changed using the PUT /v2/datapoint/renaming/{renaming_id} endpoint.

We provide the renaming_id in the path and the updated name in the request's body.

update = {"renaming": "Datenpunkt in deinem Büro"}
renaming_id = 16
r = requests.put(f"{api_url}/v2/datapoint/renaming/{renaming_id}", 
                 auth=auth_john,
                 json=update)
print(r.status_code, r.json())

curl https://api.aedifion.io/datapoint/renaming/16
    -X PUT
    -H 'Content-Type: application/json'
    -u john.doe@aedifion.com:mys3cr3tp4ssw0rd
    -d '{"renaming":"Datenpunkt in deinem Büro"}'

On success, the answer returns the new renaming.

{
  "operation": "update",
  "resource": {
    "datapointkey_id": 19,
    "id": 16,
    "renaming": "Datenpunkt in deinem Büro"
  },
  "success": true
}

Go ahead and also rename CO2_in_your_office to CO2 in deinem Büro.

Querying datapointkeys and renamings¶

Calling GET /v2/project/{project_id}/datapointkeys provides a list of all datapointkeys in the given project.

r = requests.get(f"{api_url}/v2/project/{project_id}/datapointkeys", 
                 auth=auth_john)
print(r.status_code, r.json())

curl 'https://api.aedifion.io/v2/project/1/datapointkeys'
    -X GET
    -u john.doe@aedifion.com:mys3cr3tp4ssw0rd

Verify that your newly created datapointkey is among this list.

[
  ...,
  {
    "decription": "Translation into german language.",
    "id": 19,
    "name": "german",
    "project_id": 4
  },
  ...
]

Calling GET /v2/project/{project_id}/datapoints/renamings with datapointkey_id=19 as a query parameter then returns all available german translations, i.e., renamings under datapointkey 19.

r = requests.get(f"{api_url}/v2/project/{project_id}/datapoints/renamings", 
                 auth=auth_john,
                 params={'datapointkey_id': 19})
print(r.status_code, r.json())

curl 'https://api.aedifion.io/v2/project/1/datapoints/renamings?datapointkey_id=19'
    -X GET
    -u john.doe@aedifion.com:mys3cr3tp4ssw0rd

Verify that the created german translations of the datapoint_within_your_office and CO2_in_your_office datapoints are within the returned list.

[
  ...,
  {
    "dataPointID": "datapoint_within_your_office",
    "renamings": [
      {
        "datapointkey_id": 19,
        "id": 16,
        "renaming": "Datenpunkt in deinem Büro"
      }
    ]
  },
  {
    "dataPointID": "CO2_within_your_office",
    "renamings": [
      {
        "datapointkey_id": 19,
        "id": 17,
        "renaming": "CO2 in deinem Büro"
      }
    ]
  },  
  ...
]

Deleting renamings¶

Calling DELETE /v2/datapoint/renaming/{renaming_id} deletes a renaming. The call only requires the id of the renaming to delete.

r = requests.delete(f"{api_url}/v2/datapoint/renaming/16", 
                    auth=auth_john)
print(r.status_code, r.json())

curl 'https://api.aedifion.io/v2/datapoint/renaming/16'
    -X DELETE
    -u john.doe@aedifion.com:mys3cre3tp4ssw0rd

The response returns the deleted renaming:

{
  "operation": "delete",
  "resource": {
    "datapointkey_id": 19,
    "id": 16,
    "renaming": "Datenpunkt in deinem Büro"
  },
  "success": true
}

Removing renamings one-by-one is tedious. If all renamings for a given datapointkey should be deleted, you can simply delete the datapointkey which will automatically delete all associated renamings with it.

Deleting datapointkeys¶

Calling DELETE /v2/project/{project_id}/datapointkey/{datapointkey_id} deletes a datapointkey together with all associated renamings.

r = requests.delete(f"{api_url}/v2/project/1/datapointkey/19", 
                    auth=auth_john)
print(r.status_code, r.json())

curl 'https://api.aedifion.io/v2/project/1/datapointkey/19'
    -X DELETE
    -u john.doe@aedifion.com:mys3cr3tp4ssw0rd

The response returns the deleted datapointkey:

{
  "operation": "delete",
  "resource": {
    "decription": "Translation into german language.",
    "id": 19,
    "name": "german",
    "project_id": 1
  },
  "success": true
}

Tags¶

Tags are a way to annotate your datapoints. aedifion's tags are labels consisting of a key-value pair. For example, if you have a set of datapoints located inside your office, you can tag them with the key-value pair ('location', 'Office A113'). Subsequently, the tagged datapoints can be easily accessed by the API. Tags are strictly project-scoped, i.e, they are shared within a project and can be assigned to multiple datapoints of that project but are never shared across different projects.

aedifion also provides automatically created tags, e.g., datapoint properties read from the BA system or results of different AI algorithms.

We will cover all relevant API endpoints by the example of annotating datapoints with the office location.

Types of tags¶

Tags are inherently only a key-value pair with an additional unique numeric id for easy access. The following tag represents a location information.

{
  "id": 42,
  "key": "location",
  "value": "Office A113"
}

A tag can be assigned to multiple datapoints. All tag assignments have a source. The source denotes the origin of the assignment and can assume multiple values. A few examples are denoted here:

• user: The tag has been assigned by a user. Any tag assigned through the API is designated a user generated tag assignment.
• ai: The tag has been assigned by an artificial intelligence (ai).
• bacnet: The tag assignment has been derived from BACnet meta data.
• system: The tag has been created by amalgamation of different sources. This is used to e.g. create a definitive unit for each datapoint.

In the following, we will often use the terms tag and tag assignment synonymously since the difference rather lies in the implementation than in the concept.

{
  "id": 42,
  "key": "location",
  "protected": false,
  "source": "user",
  "value": "Office A113"
}

{
  "confirmed": true,
  "id": 43,
  "key": "description",
  "protected": true,
  "source": "bacnet",
  "value": "Temperature sensor in Room 1.113"
}

{
  "confirmed": false,
  "id": 44,
  "key": "L4_type",
  "probability": 0.9,
  "protected": true,
  "source": "ai",
  "value": "/temperature/gaseous/indoor"
}

{
  "id": 45,
  "key": "units",
  "protected": true,
  "source": "system",
  "value": "degrees-celsius"
}

Adding tags¶

The API allows to create tags as key-value pairs. Subsequently, you can assign this tag to a datapoint. We want to create the tag ('location', 'Office A113') to some of our datapoints. To this end, we use the POST /v2/project/{project_id}/tag which takes the following parameters:

project_id is a path parameter, i.e., it is entered directly in the requests path while the parameters key and value must be encoded as a valid JSON and sent in the body of the request.

project_id = 1
newtag = {
    'key': 'location', 
    'value': 'Office A113'
}
r = requests.post(f"{api_url}/v2/project/{project_id}/tag", 
                  auth=auth_john,
                  json=newtag)
print(r.status_code, r.json())

curl https://api.aedifion.io/v2/project/1/tag
    -X POST
    -u john.doe@aedifion.com:mys3cr3tp4ss0wrd
    -d @newtag.json 
    -H "Content-Type: application/json"

We get the following JSON-formatted response from the API which states that the tag has been successfully created as indicated by the return code: 201 (Created).

{
  "success": true,
  "operation": "create",
  "resource": {
    "id": 42,
    "key": "location",
    "value": "Office A113"
  }
}

Go ahead and create the same tag, i.e., same key and value, a second time. Note how this will not produce an error but instead return the already existing tag and change return code to 200 (OK).

For now, our newly created tag is not assigned to any datapoint. Let's now assign this tag to an existing datapoint. For this we have to use the POST /v2/datapoint/tag endpoint which requires the following parameters:

Note that all parameters are query parameters, i.e., they're added in url-encoded form to the query part of the requested URL (the part following the domain and path separated by a question mark).

project_id = 1
dataPointID = 'datapoint_within_your_office'
tag_id = 42
r = requests.post(f"{api_url}/v2/datapoint/tag", 
                  auth=auth_john,
                  params={'project_id': project_id,
                          'dataPointID': dataPointID,
                          'tag_id': tag_id})
print(r.status_code, r.json())

We get the following response from the API which indicates a successful assignment of the tag to the datapoint. Since an assignment is a relation between two entities, it returns both entities, the datapoint and the assigned tag, in the resource field. Note that "source": "user" was added automatically.

{
  "operation": "create",
  "resource": {
    "datapoint": {
      "dataPointID": "datapoint_within_your_office",
      "hash_id": "ABCD1234",
      "project_id": 1
    },
    "tag": {
      "id": 42,
      "key": "location",
      "protected": false,
      "source": "user",
      "value": "Office A113"
    }
  },
  "success": true
}

Listing tags¶

Since we just created the tag we knew the required tag_id to assign it to a datapoint. If you want to assign a previously created tag but you do not know the tag_id, you can get an overview of all possible key-value pairs in combination with their IDs (tag_id) by using the GET /v2/project/{project_id}/tags endpoint with the following parameters:

For this method we need a GET request. Therefore, we use requests.get.

project_id = 1
r = requests.get(f"{api_url}/v2/project/{project_id}/tags", 
                 auth=auth_john,
                 params={'key': 'location'})
print(r.status_code, r.json())

curl 'https://api.aedifion.io/v2/project/1/tags'
    -X GET
    -u john.doe@aedifion.com:mys3cr3tp4ss0wrd
    -d key=location
    -H "Content-Type: application/json"

Since we provided the optional key parameter only the tags with the key "location" are returned:

[
  {
    "id": 42,
    "key": "location",
    "value": "Office A113"
  },
  {
    "id": 43,
    "key": "location",
    "value": "Office A114"
  }
]

Modifying tags¶

With the aedifion API you can either modify the tag directly (i.e. the key or the value) or the tag assignment (i.e. the confirmed status). The first method affects all assignments the user has made. This method is conceived e.g. for fixing typos in the tags. The second method is to verify the tag assignment (set the confirmed status).

For example if your company decides to rename the offices (e.g. from A113 to B113), you do not need to recreate all the tags, you can just modify them. To modify the key and/or the value of the tag use the API endpoint PUT /v2/project/{project_id}/tag/{tag_id}. It requires the following parameters:

Let us now rename the created tag to the new Office name. We have to provide the project_id, tag_id, and the new value.

project_id = 1
tag_id = 42
r = requests.put(f"{api_url}/v2/project/{project_id}/tag/{tag_id}",
                 auth=auth_john,
                 json={"value": "Office B113"})
print(r.status_code, r.json())

curl https://api.aedifion.io/v2/project/1/tag/42
    -X PUT
    -u john.doe@aedifion.com:mys3cr3tp4ss0wrd
    -d @updatetag.json 
    -H "Content-Type: application/json" 

As a response the client gets a 200 status code. This depends on whether the API edited the tag in-place or had to create a new tag. The latter case might have happened if for example the BACnet logger has assigned the same tag to another datapoint. In this case all user-made assignments are updated to use the new tag_id.

{
  "operation": "update",
  "resource": {
    "id": 42,
    "key": "location",
    "value": "Office B113"
  },
  "success": true
}

{
  "operation": "update",
  "resource": {
    "id": 43,
    "key": "location",
    "value": "Office B113"
  },
  "success": true
}

Modifying tag assignments¶

You can also modify the tag assignment to a datapoint (here: confirm or reject the assignment). This is especially useful for automatically generated tags (e.g. from BACnet or from machine learning). Modifying these will help find faulty datapoints and improve our machine learning systems. For this we use the endpoint PUT /v2/datapoint/tag/{tag_id} with the following parameters:

With this method we can now confirm our created tag as an example.

project_id = 1
tag_id = 42
r = requests.put(f"{api_url}/v2/datapoint/tag/{tag_id}", 
                 auth=auth_john,
                 params = {
                    "dataPointID": "datapoint_within_your_office",
                    "project_id": project_id,
                 },
                 json={'confirmed': 'true'})
print(r.status_code, r.json())

curl 'https://api.aedifion.io/v2/datapoint/tag/42?
    dataPointID=datapoint_within_your_office&project_id=1'
    -X PUT
    -u john.doe@aedifion.com:mys3cr3tp4ss0wrd
    -d @confirmedtag.json 
    -H "Content-Type: application/json" 

The response for this API method returns the modified tag associated with this datapoint. If a tag is assigned by multiple sources (e.g. "user" and "bacnet") to this datapoint, all of these assignments are modified. Note, that the "confirmed" parameter is now set to true.

{
  "operation": "update",
  "resource": [
    {
      "confirmed": true,
      "id": 42,
      "key": "location",
      "protected": false,
      "source": "user",
      "value": "B113"
    }
  ],
  "success": true
}

Filtering datapoints by tag¶

You can retrieve all datapoints corresponding to different tags. You must provide a tag key. Optional parameters are the tag value, the assigning source, or the confirmed status. The API call returns a list of all datapoints conforming with all those filters combined with the relevant tags.

This method is intended for fast retrieval of datapoints with tags assigned to it. For example one could get the list of all datapoints with a unit assigned to it (key='unit') which are unconfirmed (confirmed='unconfirmed'). The returned tag assignments can now be easily confirmed or rejected to improve finding faulty datapoints or the machine learning system.

The relevant API endpoint is GET /v2/project/{project_id}/datapoints/byTag and the parameters are as follows:

Let us now query for confirmation status, all datapoints we assigned a location tag. Since we just confirmed the assignment before, we should get returned the just assigned tag to the datapoint.

project_id = 1
r = requests.get(f"{api_url}/v2/project/{project_id}/datapoints/byTag", 
                 auth=auth_john,
                 params={
                    'key': 'location',
                    'confirmed': 'unconfirmed',
                 })
print(r.status_code, r.json())

curl 'https://api.aedifion.io/v2/project/1/datapoints/byTag?key=location'
    -X GET
    -u john.doe@aedifion.com:mys3cr3tp4ss0wrd
    -H "Content-Type: application/json" 

We get the following list as result:

[
  {
    "dataPointID": "datapoint_within_your_office",
    "tags": [
      {
        "confirmed": true,
        "id": 42,
        "key": "location",
        "protected": false,
        "source": "user",
        "value": "Office B113"
      }
    ]
  }
]

Deleting tag assignments¶

The aedifion API allows you to delete tag assignments (remove tag from a datapoint) or to delete a tag entirely. You cannot delete a tag assignment which is protected. Also you cannot delete a tag completely from a project which has protected assignments or is assigned by another source as user (e.g. BACnet).

Let us now delete the assignment of the created location tag from the datapoint. For this we need the API endpoint DELETE /v2/datapoint/tag/{tag_id}. The parameters are as follows:

project_id = 1
tag_id = 42
r = requests.delete(f"{api_url}/v2/datapoint/tag/{tag_id}", 
                    auth=auth_john,
                    params = {
                        'dataPointID': 'datapoint_within_your_office',
                        'project_id': project_id,
                    })
print(r.status_code, r.json())

curl 'https://api.aedifion.io/v2/datapoint/tag/42?
    dataPointID=datapoint_within_your_office&project_id=1'
    -X DELETE
    -u john.doe@aedifion.com:mys3cr3tp4ss0wrd
    -H "Content-Type: application/json"

The result returns the tag and the datapoint from which the assignment was deleted.

{
  "operation": "delete",
  "resource": {
    "datapoint": {
      "dataPointID": "datapoint_within_your_office",
      "project_id": 1
    },
    "tag": {
      "id": 42,
      "key": "location",
      "value": "Office B113"
    }
  },
  "success": true
}

The tag itself still exists in the system but it is no longer assigned to the datapoint.

Deleting Tags¶

If you want to delete the tag completely including all its assignments then you can use the following API method DELETE /v2/project/{project_id}/tag/{tag_id}.

The parameters for the API endpoint are the following:

project_id = 1
tag_id = 42
r = requests.delete(f"{api_url}/v2/project/{project_id}/tag/{tag_id}", 
                    auth=auth_john)
print(r.status_code, r.json())

curl https://api.aedifion.io/v2/project/1/tag/42
    -X DELETE
    -u john.doe@aedifion.com:mys3cr3tp4ss0wrd
    -H "Content-Type: application/json"

When the operation is successful the deleted tag is returned.

{
  "operation": "delete",
  "resource": {
    "id": 42,
    "key": "location",
    "value": "Office B113"
  },
  "success": true
}

System Tags¶

System tags are automatically created tags which combine multiple other tags to provide a single source of truth. Currently, the only tags available as system tag, are tags with the key units or type. These tags are combined by using the tag from the BA system, the AI and tags from users. As the BA system can be configured incorrectly and the AI algorithm is inherently a statistical process, the units tags from those sources might be wrong. The system tags are automatically set, such that it has the highest confidence of being correct. Therefore, this tag will be used both in the frontend for better display of timeseries and in analyses for the components. In the future we might add additional system tags with different keys.

Units¶

The unit is an essential property of a datapoint. aedifion provides you with a collection of units applicable to the most datapoints used in BA systems. The collection can be viewed when querying the endpoint /v2/labels/definitions. This endpoint can be queried without any authentication and will provide you with a collection of predefined classes. Available classes are the id values from objects without any children (leaf nodes). If you provide the locale parameter, the names and descriptions are localized in the given language. Available languages can be obtained by querying the endpoint /v2/labels/systems. The classes for units are the ones both the system tag and the ai tags use.

project_id = 1
tag_id = 42
r = requests.get(f"{api_url}/v2/labels/definitions", params={
    'locale': 'en',
  })
print(r.json())

curl https://api.aedifion.io/v2/labels/definitions?locale=en
    -H "Content-Type: application/json"

The system tag with key=units is automatically updated whenever another tag with key=units is changed. In that case all tags assigned to that datapoint with key=unit are compared and the most probable value is selected and written to the system tag. Each ai tag has a dedicated probability assigned to it, each tag from a BA system is assigned a probability of 0.85 and each user tag is assigned a probability of 1.0. Therefore, if you want to override the current system tag, just assign a tag with key=units and the desired value from the endpoint /v2/labels/definitions. This will trigger the update mechanism and assign the specified system tag to the datapoint.

Example¶

Let us give an example on how this could look like for a single datapoint named bacnet47-returnTemperature. Initially this datapoint will be discovered by our Edge Device which then transfers observations of the datapoint to the aedifion platform. There is currently neither metadata, AI results nor user tags available. No system tag has been set.

After the Edge Device has performed a metadata scan, it can transfer the metadata to our platform. The platform organizes this metadata and assigns tags to the datapoint. Here, the BACnet system contains the (faulty) unit squareMeters. Therefore, a tag is created and assigned to the datapoint

{
  "id": 200,
  "key": "units",
  "protected": true,
  "source": "bacnet",
  "value": "squareMeters"
}

Now the system tag is updated. Since there are no other tags present, the assigned tag with source=bacnet is the one with the highest priority. A tag is created and assigned to the datapoint

{
  "id": 201,
  "key": "units",
  "protected": true,
  "source": "system",
  "value": "square-meters"
}

Now the AI algorithm analyses the datapoint, detects the temperature and assigns an AI tag to this datapoint.

{
  "id": 202,
  "key": "units",
  "probability": 0.925,
  "source": "ai",
  "value": "degrees-celsius"
}

The update of the system tag is initiated. There are now two tags with key=units assigned to the datapoint. As the ai tag's probability is higher than the predefined probability of the BA system of 0.85 the system tag is updated:

{
  "id": 201,
  "key": "units",
  "protected": true,
  "source": "system",
  "value": "degrees-celsius"
}

A user now views this datapoint and recognizes, that the temperature is actually measured in Kelvin. Therefore, the user assigns the respective tag to the datapoint.

{
  "id": 203,
  "key": "units",
  "protected": true,
  "source": "user",
  "value": "kelvin"
}

Since the user tag takes priority over all other assigned tags (probability=1.0), the system tag is updated once more:

{
  "id": 201,
  "key": "units",
  "protected": true,
  "source": "system",
  "value": "kelvin"
}