Meta Data
Metadata is a great way to associate Arcentry component visualizations with their real-world counterparts up in the cloud. It allows you to add any number of key-value pairs, e.g. an AWS Instance ID or ARN, a Docker Image name or a dynamic property such as status: booting to a component.
This meta-information can simply be displayed as a label that's directly linked to its component or it can be used to find and manipulate components via the API.
How do I add Metadata to a component?
You can add Metadata manually via the Metadata-panel that appears at the bottom of the sidebar whenever a component is selected.
It is also possible to set Metadata programmatically when creating or updating an object via the API. To do so, simply include a Metadata key in your properties, e.g.
{
"props": {
"meta": {
"Instance ID": "i-06d7f0be6d177c918",
"Status": "running"
}
}
}
How do I display Metadata in an Arcentry diagram?
To display Metadata as a label next to a component, simply click the checkbox labeled "show meta data next to component"
You can also decide whether you want to display only the values (fields on the right) or also the keys for your Metadata - as well as set rotation, font-size, and alignment.
How do I search or manipulate components based on Metadata?
There are two API Endpoints that let you interact with your document using Metadata: Sending a get request to v1/doc/{docId}/obj/where/{selector} will return a list of objects that match your selector, sending a post request to v1/doc/{docId}/obj/where allows you to set properties for all objects matching a given selector.
Selectors
You can query components based on their Metadata using Selectors. Selectors are simple, JSON formatted arrays with exactly three entries: key, operator and value.
Supported operators are
- "eq" Equals - type-insensitive equality
- "gt" Greater than for numbers and lexical comparison of strings
- "lt" Less than for numbers and lexical comparison of strings
- "co" Contains - checks if a string contains another string
- "no" Not - property doesn't have the given value or doesnt exist
Here are some examples
// A simple selector to retrieve an item by its id
[ "InstanceID", "eq", "i-06d7f0be6d177c918"]
// Here we retrieve all items deployed
// in an eu region, e.g. eu-central-1, eu-west-2 etc.
[ "Region", "co", "eu" ]
// You can also provide arrays of selectors. Selectors are chained with
// AND, meaning that items have to match all criteria to be returned
// Here's e.g. how to get all running processes within a specific VPC
[
[ "vpc", "eq", "vpc-cf01f4e3" ],
[ "status", "eq", "running" ]
]
Using Selectors in URLs
Please note - whenever you use a selector within an URL, e.g. for v1/doc/{docId}/obj/where/{selector} the selector must be URL encoded. This can be achieved using e.g. encodeURI( selector ) in JS/Node, urlencode( $selector ) in PHP, QueryEscape( selector ) in GO or jumping through a few extra hoops in Java