Skip to main content

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​

AttributeValue
typeconnectorEntitiesChangelog
source//com.mapped/org/{orgId}/connectors/{connectorId} (note org, singular)
idUnique 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",
"createdBy": "[email protected]"
},
"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": []
}
}
}
FieldDescription
connectorTypeIdThe type of connector, for example the room-booking system it connects to.
connectorIdThe connector whose entities changed, the same as the last part of source.
sourceTypeThe kind of entity in the source system, as the connector names it: room, employee, accessPoint, and so on. One job covers one sourceType.
commitMessageThe note the user wrote when saving, or "".
job.idThe job that applied the change. Every part of one changelog has the same job.id.
job.nameThe job's name.
job.createdAtWhen the user saved the change.
job.completedAtWhen the change was applied to the graph.
job.createdByThe email of the user who saved the change, or "" when it was not a user.
part.index, part.totalWhich part this is, starting at 1, and how many parts the changelog has. See Large Changes.
entities.deletedEntities removed from the graph.
entities.addedEntities added to the graph.
entities.updatedEntities 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:

FieldDescription
refIdThe entity's ID in the source system.
mappingKeyThe key that ties the source entity to the graph. Treat it as an opaque string.
mappedIdThe 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.
baseTypeWhat the entity is in Mapped terms: SITE, BUILDING, SUB_BUILDING, FLOOR, SPACE, ZONE, or THING.
exactTypeThe 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.completedAt to apply the older one first.

  • Reconcile by querying the connector's places and things in the graph, which always hold the current state.