Docs Portal

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:

Request ResponseCopy1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  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):

Request ResponseCopy1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  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

Request ResponseCopy1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
  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:

Copy1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "__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.

Copy

1
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.

Copy1
2
3
4
5
6
{
  "__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.

Floors

Copy1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
{
  {
    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

Copy1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
  {
    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

Copy1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
  {
    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

Copy1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
  {
    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

Copy1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
    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.

Request ResponseCopy1
2
3
4
5
6
7
8
9
{
  connectors(filter: {id: {eq: "your-connector-Id"}}) {
    logs {
      timestamp
      level
      message
    }
  }
}