Entity Metadata and Tags
Project Haystack
Project Haystack is an open-source initiative that seeks to standardise semantic tagging, data-modelling, and communication in buildings to unlock the full value of data. By providing a standardised open-source methodology, Project Haystack enables increased interoperability across building disciplines and streamlined data exchange with software applications.
In the Hark Platform, the use of Haystack in the UI is subtle and is visible through the inherent tags. For example, when setting up a Site entity, you can see the default haystack tag 'site':
Haystack will also allow weather data to be linked to the geographical location, which is applied using a Site's latitude and longitude address alongside weather stations setup in the Platform or using weather APIs.
What is a Tag?
A 'tag' is a single value that is either set by default when an entity is created or user input, which is defined by Project Haystack that can be applied in various combinations to define virtually any set of descriptors or relationships for Equipment, systems and associated data in a standardized way. Currently there are over 200 tags!
Tags Use Case
Site Level Energy Data
For example, if you wanted to aggregate the data of all of your electricity 'main' meters, you would need to tag the relevant meters with:
This means that only those meters with the above tags will aggregate data, as opposed to every meter - there could be child meters that would result in duplicating consumption.
What is Metadata?
'Metadata' is a key-value data stored against an entity, similar to attributes in Analytics. Similar to tags, metadata powers various parts of the Explorer hierarchy, depending on what values are entered.
Metadata Use Case
Site Weather Data
Similarly, if you want to utilise Site Weather data, the Platform requires the following metadata at Site level:
'tz' (e.g. GMT)
'geoCoord' (e.g. C(53.7948055,-1.5469567))
The next time the data is regenerated, currently every 4 hours (00:00, 04:00, 08:00, 12:00, 16:00, 20:00, etc.) the weather data will appear in the Platform UI. This can be triggered by a Hark Support user if the data refresh needs to happen within a 4 hour period.
System vs Custom Tags & Metadata
The key to using the Haystack ontology correctly is to ensure that the tags and metadata associated to an entity (whether it be an Equipment or a Site) are correct, as these drive how the data is processed and where it is used, for example in Equipment Overview pages.
It is for this reason that we split tags and metadata into two types:
System - defined by Project Haystack (and Hark). System tags & metadata are limited to a specific list, which we are continually updating. If a user tries to add something as a system tag which has not been defined in this list, they will receive an error and will not be able to save their entity.
Custom - these are defined by the user, and can be anything the user wants. Custom tags help to drive some features in other areas of the Platform, for example the Reporting module's Energy Equipment Report, where users can filter down their Site/Equipment selection through custom tags and metadata.
Each entity has their own tags, which is important to understand when creating your hierarchy. You can understand the specifics in the guides below:
Metadata
Adding Metadata
On the 'Management' tab of any entity, you can add metadata by clicking the "Add Metadata" button this will allow you to add custom and system metadata to your entity.
The tick and error icons will show whether the metadata is valid. If you try to enter system metadata which is not supported, you will receive an error, and you will not be able to save. You can add any value as custom metadata.
Once metadata is added, you can also delete from this list before you save by using the bin icon on the left hand side.
Editing & Removing Metadata
From the Management tab, you can edit a Metadata Item by clicking on the pencil icon at the right hand side of each Metadata Item. To delete a Metadata Icon you can click the bin icon at the left hand side of each Metadata Item.
If you want to select multiple items at once to delete, click "Select" from the top toolbar using the checkbox at the left of each Metadata Item select the Metadata Items you wish to delete and then click "Delete Metadata" that is now shown in the top toolbar.
Tags
Adding & Removing Tags
On the 'Management' tab of any entity, you can add system or custom tags by clicking the pencil icon button to add additional tags or removing existing tags (except System Tags that are required by the Platform).
After clicking the tags pencil icon you will be presented with the Edit Form for that Entity see below Site example:
