Connectors
The Mapped API allows you to make calls to retrieve information about the installed Connectors in your org. In this guide, we'll walk through how to retrieve basic info like name and ID, as well as how to filter down to see all the things and points associated with a specific Connector.
You can add, update, or remove a connector in the Mapped Console. For guidance on setting up connectors, review our Connector Guides including configuration and code samples for specific connectors.
Viewing Connectors
There's a lot of core information available about your Connectors - name, id, when it was created, the current state of the Connector (like ACTIVE or STOPPED) and so on. In the following example, we'll include all that data, along with information about the type:
{
connectors {
id
name
created
connectorType {
name
description
direction
version
}
state
}
}
The name field listed in the beginning is the name you provides to the Connector when it was originally setup - this is often left as the default, but can be customized in scenarios where a more descriptive name is needed (like "Weather Development" and "Weather Production"). Under connectorType, the name value is what we assigned to the Connector and is not modifiable.
Additional fields under connectorType include description, direction and version. The direction value indicates whether this Connector is SOURCE or DESTINATION focused. SOURCE means data is flowing from the connector to your org - data from sensors, like the humidity level in a room. DESTINATION means the Connector is sending data from your org to somewhere else, like an external data lake. The version will let you know which release of the Connector is installed, as over time we may have multiple releases.
Viewing Things & Points by Connector
When you initially add a Connector, it might not be obvious what types of things and points will be added to your data. You can filter by the Connector id and then include both the things and points fields to retrieve that information, including the latest time series data and even unit information (like Degree Celsius):
{
connectors(filter: { id: { eq: "CONXG1u32osqN7eyzntnrABCD" } }) {
name
things {
id
name
exactType
points {
id
name
exactType
unit {
name
description
}
series(latest: true) {
value {
float64Value
}
}
}
}
}
}
Viewing Contributions from each Connector
The Mapped Graph offers a full picture of data enriched from various connector sources. Each resolved entity -- Buildings, Floors, Zones, Spaces, Things, Points -- in the Mapped Graph will be composed of a contribution from one or more Connectors. These contributions are all unified based on shared identities. Read more about Identities.
You can review each core entity that contributes to an entity in the Graph and the identities tied to those connectors using the hasPropertyContributedFrom endpoint.
Buildings
{
buildings(filter: {id: {eq: "BLDGR8kVnF2yZqPwXb7QJt9Ls3"}}) {
id
name
mappingKey
dateCreated
dateUpdated
hasPropertyContributedFrom {
__typename
... on Building {
id
name
dateCreated
dateUpdated
mappingKey
identities {
... on Identity {
__typename
value
scope
scopeId
}
}
}
}
}
}
The mappingKey of each entity under the hasPropertyContributedFrom indicates the contributing connector. So, from this excerpt of the output in the previous example:
{
"__typename": "Building",
"id": "BLDGGQ4FJbcSfWEmbYq5JqgMW8",
"name": "Intellicare Infirmary",
"dateCreated": "2024-02-07T09:07:08.242Z",
"dateUpdated": "2024-02-07T09:07:08.242Z",
"mappingKey": "msrc://CONGm7R2XvYpLk9QdJt4Hc8ZFa@weatherbit/buildings/Qb3L5Xn9HcRZ2TJ7kV4YmP",
"identities": [
{
"__typename": "ExternalIdentity",
"value": "Pd565whgbaLvjCYQRP2Upn",
"scope": "CONNECTOR",
"scopeId": "CONGm7R2XvYpLk9QdJt4Hc8ZFa"
},
{
"__typename": "PostalAddressIdentity",
"value": "12188 Highway 71, Last Chance, Colorado, 80757, United States",
"scope": "ORG",
"scopeId": "ORG9XvT2Lp8QkJm5ZcR4HyW7Fa"
}
]
}
The mappingKey points to Weatherbit, with connector Id CONGm7R2XvYpLk9QdJt4Hc8ZFa as contributing these various properties.
msrc://CONGm7R2XvYpLk9QdJt4Hc8ZFa@weatherbit/buildings/Qb3L5Xn9HcRZ2TJ7kV4YmP
If you review the example output, you'll notice that each Building contribution has the same org-scoped PostalAddressIdentity value. This identity glues all the contributions together.
{
"__typename": "PostalAddressIdentity",
"value": "12188 Highway 71, Last Chance, Colorado, 80757, United States",
"scope": "ORG",
"scopeId": "ORG9XvT2Lp8QkJm5ZcR4HyW7Fa"
}
Other Entities
The query to view contributions by connector for other entities is shaped similarly to that for Buildings. Check for shared identities under each contribution to confirm entities have unified as desired.
The example queries below can be useful when you have duplicate entities sharing the same name under the same Building, but these filters can be adjusted.
Floors
{
{
buildings(filter: {id: {eq: "BuildingId"}}) {
id
name
floors(filter: {name: {contains: "FloorName"}}) {
id
name
level
exactType
mappingKey
hasPropertyContributedFrom {
__typename
... on Floor {
id
name
level
exactType
mappingKey
identities {
...on Identity {
__typename
value
scope
scopeId
}
}
}
}
}
}
}
}
Spaces
{
{
buildings(filter: {id: {eq: "BuildingId"}}) {
id
name
spaces(filter: {name: {contains: "SpaceName"}}) {
id
name
exactType
mappingKey
hasPropertyContributedFrom {
__typename
... on Space {
id
name
exactType
mappingKey
identities {
...on Identity {
__typename
value
scope
scopeId
}
}
}
}
}
}
}
}
Zones
{
{
buildings(filter: {id: {eq: "BuildingId"}}) {
id
name
zones(filter: {name: {contains: "ZoneName"}}) {
id
name
exactType
mappingKey
hasPropertyContributedFrom {
__typename
... on Zone {
id
name
exactType
mappingKey
identities {
...on Identity {
__typename
value
scope
scopeId
}
}
}
}
}
}
}
}
Things
{
{
buildings(filter: {id: {eq: "BuildingId"}}) {
id
name
things(filter: {name: {contains: "ThingName"}}) {
id
name
exactType
mappingKey
hasPropertyContributedFrom {
__typename
... on Thing {
id
name
exactType
mappingKey
identities {
...on Identity {
__typename
value
scope
scopeId
}
}
}
}
}
}
}
}
Points
{
buildings(filter: {id: {eq: "BuildingId"}}) {
id
name
points(filter: {id: {eq: "PointId"}}) {
id
name
exactType
mappingKey
hasPropertyContributedFrom {
__typename
... on Point {
id
name
exactType
mappingKey
identities {
...on Identity {
__typename
value
scope
scopeId
}
}
}
}
}
}
}
}
Viewing Connector Logs
The logs GraphQL endpoint displays the past 24 hours of logs you can view under each Connector's config in the Mapped Console.
{
connectors(filter:{id:{eq:"your-connector-Id"}}) {
logs {
timestamp
level
message
}
}
}