Connector Entity Events
Some connectors bring in connector entities: rows from the source system, such as rooms, floors, buildings, employees, or access points, that you review in the Console and then save to the graph. Each save runs as a job. When the job finishes, Mapped publishes a changelog event that lists every entity the job added, updated, or deleted, so you can keep your own systems in step without re-reading the whole connector.
Event
| Attribute | Value |
|---|---|
type | connectorEntitiesChangelog |
source | //com.mapped/org/{orgId}/connectors/{connectorId} (note org, singular) |
id | Unique per event (a UUID). Each part of a large changelog has its own id. |
Payload
The payload has a single member, connectorEntitiesChangelog:
{
"connectorEntitiesChangelog": {
"connectorTypeId": "CTYP4k2Ry8eZcQxP7Uo3XnMVa",
"connectorId": "CON8NnmVKfa2Eq6BpBJ6Wz9hT",
"sourceType": "room",
"commitMessage": "Add the third-floor meeting rooms",
"job": {
"id": "JOB6qT1xV8Lr3KaPm2Ze9YcWd",
"name": "Merge room entities",
"createdAt": "2026-11-19T16:58:41.207Z",
"completedAt": "2026-11-19T16:59:02.884Z",
},
"part": { "index": 1, "total": 1 },
"entities": {
"deleted": [
{
"refId": "rm-2117",
"mappingKey": "msrc://CON8NnmVKfa2Eq6BpBJ6Wz9hT@CTYP4k2Ry8eZcQxP7Uo3XnMVa/room/rm-2117",
"mappedId": "SPC3sVb7hJ5xWkN2qLm8RtYcQ",
"baseType": "SPACE",
"exactType": "ROOM"
}
],
"added": [
{
"refId": "rm-3104",
"mappingKey": "msrc://CON8NnmVKfa2Eq6BpBJ6Wz9hT@CTYP4k2Ry8eZcQxP7Uo3XnMVa/room/rm-3104",
"mappedId": "SPC9aFk2LmQ7yTnB4vXc1RzDf",
"baseType": "SPACE",
"exactType": "CONFERENCE_ROOM"
}
],
"updated": []
}
}
}
| Field | Description |
|---|---|
connectorTypeId | The type of connector, for example the room-booking system it connects to. |
connectorId | The connector whose entities changed, the same as the last part of source. |
sourceType | The kind of entity in the source system, as the connector names it: room, employee, accessPoint, and so on. One job covers one sourceType. |
commitMessage | The note the user wrote when saving, or "". |
job.id | The job that applied the change. Every part of one changelog has the same job.id. |
job.name | The job's name. |
job.createdAt | When the user saved the change. |
job.completedAt | When the change was applied to the graph. |
job.createdBy | The email of the user who saved the change, or "" when it was not a user. |
part.index, part.total | Which part this is, starting at 1, and how many parts the changelog has. See Large Changes. |
entities.deleted | Entities removed from the graph. |
entities.added | Entities added to the graph. |
entities.updated | Entities already in the graph whose values changed. |
All of these fields are always present: unknown text is "" and an empty list is [].
Each entity in the three lists identifies the entity; it does not carry its values:
| Field | Description |
|---|---|
refId | The entity's ID in the source system. |
mappingKey | The key that ties the source entity to the graph. Treat it as an opaque string. |
mappedId | The ID of the entity in the Mapped graph, for example a SPC… or BLDG… ID. It is "" when the graph had not assigned the ID yet when the event was sent; the entity is still created, so query the graph again a little later to find its ID. For a deleted entity it is the ID the entity had before it was removed. |
baseType | What the entity is in Mapped terms: SITE, BUILDING, SUB_BUILDING, FLOOR, SPACE, ZONE, or THING. |
exactType | The entity's precise ontology type, as a constant such as ROOM or CONFERENCE_ROOM. Left out when the connector doesn't say. |
To get the values of an added or updated entity, query it by its mappedId, for example with
spaces or things.
When It Is Sent
Once for each job that changes the graph, after the change has been applied. It is not sent when:
- The job had nothing to change.
- The job failed. No change was applied, so there is nothing to report.
Large Changes
A job can change tens of thousands of entities, which is too much for one request. Mapped then splits the changelog
into parts of under 1 MB each and sends each part as its own event. Every part repeats the same header
(connectorId, sourceType, job, and so on) with its own part.index; the entities are spread across the parts in
the order deleted, then added, then updated, so one part can hold entities from two lists.
To rebuild the whole changelog, group the parts by job.id and wait until you have part.total distinct
part.index values. Parts can arrive in any order, so don't assume part 1 comes first. A part can also go missing:
if some parts have not arrived after a reasonable wait, process what you have and reconcile the rest.
Using It
-
Subscribe on the type, and add the source to limit it to one connector:
@.type == 'connectorEntitiesChangelog' && @.source =~ /\/connectors\/CON8NnmVKfa2Eq6BpBJ6Wz9hT$/ -
Apply changes in job order. Two jobs for the same connector can arrive out of order; use
job.completedAtto apply the older one first. -
Reconcile by querying the connector's places and things in the graph, which always hold the current state.