Microsoft Graph Source Connector

The Microsoft Graph Source connector integrates with the Microsoft Graph API to synchronize room calendar data from Microsoft 365 (Exchange Online) into the Mapped platform. It polls room mailbox calendars for booking events, creating a live view of meeting room usage across your organization.

Use Cases

• Room booking visibility: Surface real-time and upcoming meeting room bookings from Exchange Online into the Mapped graph for occupancy awareness and space analytics.
• Calendar event synchronization: Automatically sync current and future calendar events for mapped conference rooms, keeping the Mapped platform up to date with scheduling changes.
• Historical calendar backfill: On-demand sync of calendar events within a custom date range to populate historical booking data for rooms.

Configuration

Auth Requirements

The connector authenticates to Microsoft Graph using Azure AD OAuth 2.0 Client Credentials flow. An Azure AD App Registration with the appropriate Microsoft Graph API permissions is required.

To obtain the required credentials, follow Microsoft's Graph's instructions to Get access without a user with the permissions described below.

Credential	Description	Required
Tenant ID	Azure AD tenant identifier (directory ID)	Yes
Client ID	Application (client) ID from the Azure AD registration	Yes
Client Secret	Client secret generated for the Azure AD app	Yes

Required Microsoft Graph API Permissions (Application)

Permission	Type	Description
Calendars.Read	Application	Read calendars in all mailboxes
Place.Read.All	Application	Read all company places (rooms)

Credentials are validated on save by authenticating against the Microsoft identity platform. Invalid credentials will be rejected immediately.

Place Mappings

After authentication, the connector fetches the list of rooms from the Microsoft Graph Places API. Each room can be mapped to a Mapped Space entity.

Field	Description	Required
Building Name	Building name (auto-populated from room display name)	Yes
Building Address	Address of the building	No
Floor Name	Floor name	No
Floor Level	Floor level number	No
Space Name	Room display name (auto-populated)	Yes
Space Ref ID	Unique room identifier from Microsoft Graph	Yes

Each room mapping also stores the room email address internally, which is used to query the calendar view for that room's mailbox.

Calendar Sync (Action)

The Calendar Sync action allows manual, on-demand synchronization of calendar events for a specific date range. This is useful for backfilling historical data or re-syncing a particular time window.

• Select a Start Date and End Date (maximum range: 365 days).
• The sync processes all booking events within the specified range for every mapped room.
• Only one Calendar Sync action can run at a time per connector instance.

Polling Schedule

Function	Interval	Description
Current Events	Every 30 minutes	Fetches events that were created or modified since the last successful poll
Future Events	Once per day	Fetches events scheduled within the next 30 days (configurable via futureEventsWindow setting)

Mapped Concepts

Graph Entities

This connector creates the following entities in the Mapped graph:

Microsoft Graph API	Mapped Entity	Description
Room (Place)	Space	A conference room or bookable space
Calendar View Events	SpaceBookingCalendar	A booking calendar associated with a room
Calendar Event	CalendarEvent	An individual booking/meeting event on the calendar

Space

Represents a bookable room from Microsoft 365, created from the Place Mappings configuration.

Key Fields

GraphQL Field	Description
name	Room display name
exactType	Subclass of Space (e.g. Room)
mappingKey	Unique key from place mapping
identities	External identity URN

SpaceBookingCalendar

Represents the booking calendar for a specific room. One calendar is created per mapped room.

Key Fields

GraphQL Field	Description
name	Calendar for {room name}
mappingKey	Derived from the parent Space mapping key
hasCalendarEvent	List of CalendarEvent entities on this calendar
isCalendarOf	The Space this calendar belongs to

CalendarEvent

Represents an individual meeting or booking on a room calendar. Cancelled events are automatically excluded.

Key Fields

GraphQL Field	Description
name	Event subject/title
startTime	Event start time (ISO 8601)
endTime	Event end time (ISO 8601)
hasLocation	The Space where the event takes place
identities	External identity URN based on the iCalUId
mappingKey	Unique key derived from the event's iCalUId

When an event is moved to a different room, the connector automatically updates the hasLocation relationship to reflect the new room assignment.

Sample Code

Query Spaces with their Calendars and Events

{
  spaces{
	    id
	    name
	    exactType
	    hasCalendar {
	      ... on SpaceBookingCalendar {
	        id
	        name
	        hasCalendarEvent {
	          id
	          name
	          startTime
	          endTime
	          hasLocation {
	            id
	            name
	            exactType
	          }
	        }
	      }
	    }
	  }
}

Query CalendarEvents with location

{
  calendarEvents {
	    id
	    name
	    startTime
	    endTime
	    hasLocation {
	      ... on Space {
	        id
	        name
	        exactType
	        floor {
	          name
	        }
	      }
	    }
	    identities {
	      ... on ExternalIdentity {
	        value
	        scope
	      }
	    }
	  }
}

Query a specific Space's booking calendar

{
  spaces(filter: {id: {eq: "your-Space-Id"}}) {
	    id
	    name
	    hasCalendar {
	      ... on SpaceBookingCalendar {
	        id
	        name
	        exactType
	        hasCalendarEvent {
	          id
	          name
	          startTime
	          endTime
	        }
	      }
	    }
	  }
}

Graph Diagrams