.png)
Microsoft Graph Integration Guide
Connect Microsoft 365, Microsoft Entra, Windows, and selected Microsoft services with enterprise applications through Microsoft Graph REST APIs and change notifications.
Microsoft Graph integration options at a glance
Microsoft Graph provides a unified REST API at graph.microsoft.com for Microsoft 365, Microsoft Entra, Windows, and selected Microsoft services. Martini can consume Graph REST endpoints using OAuth 2.0 bearer tokens with delegated or application permissions, then orchestrate workflows for users, groups, messages, events, sites, files, and other documented resources. Selected resources support change notifications through expiring subscriptions, while delta queries can support incremental synchronization where available. JSON batching, pagination, file and attachment resources, and OData query options support larger integration workloads. Martini can also expose an HTTPS API to receive Graph notifications and route transformed data to applications, databases, queues, or other APIs.
| Integration point | Supported by Microsoft Graph? | Common use cases | How Martini supports it |
|---|---|---|---|
| REST APIs | Yes | Microsoft Graph exposes Users, Groups, Messages, Events, DriveItems, Sites, Teams, channels, chats, and other Microsoft service resources through graph.microsoft.com. OData query options, JSON payloads, pagination, and resource-specific permissions support targeted retrieval and updates. | Martini can consume Microsoft Graph REST endpoints, generate reusable workflow logic around the API calls, map JSON payloads, and expose downstream APIs for normalized data. |
| Webhooks / outbound callbacks | Yes | Graph change notifications can call an HTTPS notification URL for selected resources and change types. Subscriptions require validation, have expiration limits, and may include lifecycle notifications or resource data in selected scenarios. | Martini can expose an API endpoint to receive notifications, validate and deduplicate them, retrieve the current resource when necessary, and route the result through a workflow. |
| Delta queries | Limited | Selected Microsoft Graph resources support delta queries that return an initial collection and an opaque delta link for subsequent changes. Support and behavior vary by resource. | Martini can persist next links and delta links, schedule incremental retrieval, process tombstones, and initiate a controlled full synchronization when a token is no longer valid. |
| Bulk / async / batch APIs | Limited | Microsoft Graph supports JSON batching, generally allowing up to 20 requests per batch, and selected asynchronous operations. Batching is not a universal bulk API. | Martini can group compatible requests, control concurrency, process individual batch results, and apply bounded retry handling for transient failures. |
| File / attachment APIs | Yes | DriveItem resources support OneDrive and SharePoint files and folders, while attachment resources support documented message, event, and post attachments. Large files may require upload sessions. | Martini can transfer binary content separately from JSON metadata, preserve filenames and identifiers, and orchestrate upload, download, transformation, and archival workflows. |
| Authentication | Yes | Microsoft Graph uses Microsoft identity platform OAuth 2.0 bearer tokens with delegated or application permissions. Authorization code, client credentials, on-behalf-of, and supported managed identity scenarios are available. | Martini can securely use configured OAuth 2.0 credentials and environment secrets when calling Graph, while workflows can separate authentication failures from business and transport errors. |
| JSON APIs and OData queries | Yes | Graph REST requests and responses use JSON and commonly support resource-specific OData options such as $select, $filter, $expand, $orderby, and $top where documented. | Martini can construct focused requests, parse JSON, map nested structures, validate data, and apply resource-specific query rules. |
| Database access | Not applicable | Microsoft Graph is an application and directory API rather than a general SQL database or unrestricted analytics interface. | Martini can persist synchronized Graph data in a separately managed database when required, but it does not use Graph as a database connection. |
How Microsoft Graph exposes data and business events
Microsoft Graph REST APIs
Microsoft Graph is primarily a unified REST API using resource paths under graph.microsoft.com, JSON payloads, OAuth 2.0 bearer tokens, OData query options, and resource-specific permissions. It exposes documented Microsoft 365, Microsoft Entra, Windows, and selected service resources.
Martini implementation pattern
Martini implementation pattern: configure secure OAuth 2.0 access, call the required Graph resource from a workflow, follow returned pagination links, map the JSON response into a canonical model, apply business rules, and write to the target API, database, file store, or queue.
Implementation sequence
Microsoft Graph change notifications
Microsoft Graph can send change notifications to an HTTPS endpoint for selected resources and operations. Notifications are resource-specific, subscriptions expire, and delivery may be delayed, duplicated, or accompanied by lifecycle behavior.
Martini implementation pattern
Martini implementation pattern: expose a Martini API for subscription validation and notification delivery, verify the request, treat the notification as a trigger, retrieve the current Graph resource when the payload contains only a reference, and route the normalized result downstream.
Implementation sequence
Microsoft Graph delta queries
Selected Graph resources support delta queries. An initial synchronization follows next links and returns an opaque delta link that can be used for later change retrieval; deleted resources may be represented as tombstones.
Martini implementation pattern
Martini implementation pattern: run an initial scheduled workflow, persist progress and the returned delta link securely, use the link for subsequent runs, process additions, updates, and deletions, and restart from a full synchronization when the token is invalid.
Implementation sequence
Microsoft Graph files and attachments
Microsoft Graph exposes OneDrive and SharePoint DriveItems plus documented attachments for messages, events, and posts. File metadata and binary content may require different requests, and large files can require upload sessions.
Martini implementation pattern
Martini implementation pattern: retrieve metadata and content through Graph REST resources, preserve source identifiers and ETags, transform metadata separately from binary data, and orchestrate destination upload or archival with retry and conflict handling.
Implementation sequence
Microsoft Graph JSON batching
Microsoft Graph supports JSON batching for compatible requests, generally allowing up to 20 requests in a batch. Batching does not provide universal bulk semantics and individual operations can have separate results.
Martini implementation pattern
Martini implementation pattern: group compatible calls, submit controlled batches, inspect each operation result, retry only eligible failures, and preserve correlation between each Graph request and its downstream write.
Implementation sequence
Common Microsoft Graph integration patterns
Pattern 1: Synchronize Microsoft Entra users to an identity repository
When to use this pattern
Use this pattern when an organization needs a controlled copy of Microsoft Entra user data in Workday, an internal identity repository, or another operational system. A scheduled full synchronization can be combined with delta queries where the selected resource supports them.
Integration direction
Example Mapping
| Microsoft Graph Field | Canonical Field | Target Field |
|---|---|---|
| id | externalUserId | graph_user_id |
| userPrincipalName | loginName | user_name |
| displayName | fullName | display_name |
| accountEnabled | active | is_active |
Martini implementation pattern
A scheduled Martini workflow authenticates with application permissions, retrieves Users with focused OData queries, follows pagination or a stored delta link, validates required attributes, and applies lifecycle rules before writing the database. Stable Graph IDs and a processing key make updates idempotent; throttling and transient failures use bounded retries while permission errors are surfaced for remediation.
Martini capabilities used
- scheduled workflows
- API consumption
- pagination and checkpoint handling
- data mapping
- business rules
- error handling
Pattern 2: Process Microsoft Graph change notifications
When to use this pattern
Use this pattern for selected Graph resources where near-real-time notification is preferable to frequent polling. It is suitable for changes to documented resources such as Messages, Events, Users, Groups, or DriveItems, subject to resource-specific notification coverage.
Integration direction
Example Mapping
| Microsoft Graph Field | Canonical Field | Target Field |
|---|---|---|
| subscription.resource | sourceResource | source_type |
| resourceData.id | sourceId | external_reference |
| changeType | changeAction | event_action |
| subscriptionId | subscriptionReference | integration_subscription_id |
Martini implementation pattern
A Martini API receives Graph validation requests and notifications. The workflow authenticates and deduplicates each notification, retrieves the current resource when necessary, maps it to a ServiceNow incident or request model, and applies routing rules. A separate scheduled workflow renews subscriptions and triggers reconciliation after lifecycle failures or suspected missed delivery.
Martini capabilities used
- API exposure
- webhook reception
- workflow orchestration
- data mapping
- deduplication
- scheduled workflows
- retry handling
Pattern 3: Route Outlook messages and attachments to a support workflow
When to use this pattern
Use this pattern when selected Outlook messages should create or update support work in Zendesk, ServiceNow, or another application. Filtering can be based on mailbox, folder, sender, subject, or received time, subject to Graph query support and permissions.
Integration direction
Example Mapping
| Microsoft Graph Field | Canonical Field | Target Field |
|---|---|---|
| id | sourceMessageId | external_message_id |
| subject | caseSubject | subject |
| from.emailAddress.address | requesterEmail | requester_email |
| hasAttachments | attachmentPresent | has_attachments |
Martini implementation pattern
Martini retrieves or receives eligible Messages, applies sender and subject rules, fetches Attachments when required, and transforms message content into the Zendesk target model. A durable source message identifier prevents duplicate tickets, while attachment size and binary transfer errors are isolated from message metadata processing.
Martini capabilities used
- API consumption
- JSON handling
- file and attachment handling
- mapping and transformation
- business rules
- idempotency
- error handling
Pattern 4: Synchronize SharePoint documents with a signing workflow
When to use this pattern
Use this pattern when SharePoint or OneDrive documents must be sent to DocuSign or another repository and status must be reflected in the originating workflow. The design should account for ETags, conflicts, and large-file upload behavior.
Integration direction
Example Mapping
| Microsoft Graph Field | Canonical Field | Target Field |
|---|---|---|
| id | sourceDocumentId | external_document_id |
| name | fileName | document_name |
| eTag | versionTag | source_version |
| lastModifiedDateTime | modifiedAt | source_modified_at |
Martini implementation pattern
A scheduled or notification-driven workflow retrieves DriveItem metadata and content, validates document eligibility, sends the file to DocuSign, and records the signing envelope reference. Callback or status data is received through a Martini API, correlated to the source DriveItem, and written back to the selected Microsoft 365 workflow with conflict and retry controls.
Martini capabilities used
- workflow orchestration
- API consumption
- file handling
- data mapping
- business rules
- API exposure
- correlation and retry handling
Applications commonly integrated with Microsoft Graph
Microsoft Graph is commonly used as an access layer for Microsoft 365 and Microsoft Entra data in broader enterprise workflows. The exact scope depends on the permissions granted and the Graph resources selected; Martini can orchestrate these flows without requiring a dedicated Microsoft Graph connector.
| Application | Scenario | Direction | Martini Pattern |
|---|---|---|---|
| Salesforce | Synchronize selected Microsoft Entra users, Outlook messages, calendar events, or collaboration data with customer and sales processes. | Microsoft Graph → Martini → Salesforce | Consume the relevant Graph REST resources with application or delegated permissions, normalize users, messages, or events into a canonical model, apply filtering and duplicate controls, and call Salesforce APIs from a Martini workflow. |
| ServiceNow | Create or update ServiceNow incidents, requests, or employee-related records from Microsoft 365 and Entra activity, or notify Teams users about ServiceNow changes. | Microsoft Graph → Martini → ServiceNow | Receive selected Graph notifications or run a scheduled retrieval workflow, enrich the payload by retrieving the current resource, map it to ServiceNow fields, and use retryable API calls with durable correlation identifiers. |
| Workday | Reconcile Workday workers with Microsoft Entra Users, groups, and lifecycle-related identity data. | Workday → Martini → Microsoft Graph | Retrieve worker changes from Workday or schedule a reconciliation, map worker attributes to Graph Users and group operations, apply provisioning rules, and record source and target identifiers for idempotent updates. |
| SAP S/4HANA | Coordinate identity-related actions, approvals, documents, and business notifications between SAP processes and Microsoft 365 services. | SAP S/4HANA → Martini → Microsoft Graph | Expose or consume APIs on both sides, transform SAP business events into Graph messages, events, or files where appropriate, and route response and error outcomes through a Martini workflow. |
| Jira | Connect Microsoft Teams collaboration, user identities, notifications, and issue-related workflows with Jira processes. | Microsoft Graph → Martini → Jira | Use Graph resources and Jira APIs independently, correlate users and issue references in Martini, apply routing rules, and deliver only the selected notifications or collaboration content to Jira. |
| DocuSign | Send documents from Microsoft 365 content stores for signature and return signature status to collaboration or document workflows. | Microsoft Graph → Martini → DocuSign | Retrieve SharePoint or OneDrive DriveItems and metadata, pass supported document content to DocuSign, receive status callbacks through a Martini API, and update the originating Graph workflow with controlled retries. |
| Zendesk | Route selected Outlook messages or service interactions into support workflows while preserving user and message context. | Microsoft Graph → Martini → Zendesk | Use Graph message retrieval or selected change notifications as the trigger, extract and normalize message and attachment data, create or update Zendesk objects, and persist message identifiers to prevent duplicate tickets. |
| NetSuite | Exchange approval, document, notification, and selected user-context data between Microsoft 365 workflows and financial or operational processes. | NetSuite → Martini → Microsoft Graph | Orchestrate NetSuite and Graph REST calls, transform documents or notification payloads, enforce business rules around approval and access, and isolate transient API failures from permanent validation errors. |
How to build a Microsoft Graph integration in Martini
Objective
Establish the Microsoft Graph integration with the least-privileged permissions required for the selected resources and operations.
Instructions in Martini
- Configure the Microsoft identity platform application and required delegated or application permissions.
- Select the appropriate authorization approach, such as client credentials for background workflows or delegated access for user-context operations.
- Store client secrets, certificates, tokens, and environment-specific values in protected Martini configuration.
Objective
Select a trigger that matches the consistency and latency requirements of the integration.
Instructions in Martini
- Use a Martini scheduler for full or incremental synchronization.
- Expose a Martini API for selected Microsoft Graph change notifications.
- Use a workflow trigger or downstream API request when another system initiates the process.
Objective
Call the required Microsoft Graph resources and handle resource-specific response behavior.
Instructions in Martini
- Consume the documented Graph REST endpoint with an OAuth 2.0 bearer token.
- Follow @odata.nextLink values and persist progress for large collections.
- Use delta links only for resources that document delta-query support.
- Retrieve files and attachments separately from their JSON metadata when required.
Objective
Coordinate retrieval, enrichment, routing, and target-system operations in a maintainable Martini workflow.
Instructions in Martini
- Separate notification receipt from resource retrieval and downstream processing where appropriate.
- Use correlation identifiers such as Graph resource IDs, subscription IDs, and ETags.
- Route different resource types or business outcomes through explicit workflow branches.
Objective
Convert Microsoft Graph JSON and binary resource data into the target system's canonical and application-specific models.
Instructions in Martini
- Map actual Graph objects such as Users, Messages, Events, DriveItems, or Groups to canonical fields.
- Normalize timestamps, identifiers, nested properties, filenames, and attachment metadata.
- Validate required values and preserve source identifiers for reconciliation.
Objective
Enforce authorization boundaries, filtering, lifecycle, and duplicate-processing rules before writing to another system.
Instructions in Martini
- Filter resources using documented Graph query options where appropriate.
- Apply rules for active users, eligible messages, permitted files, or supported notification types.
- Use stable identifiers and processing keys to make writes idempotent.
Common Microsoft Graph data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| Users | Synchronize Microsoft Entra user profiles, directory attributes, and selected lifecycle information. | Workday, Salesforce, ServiceNow, identity repositories, SQL databases | Martini retrieves Users with narrow permissions and selected fields, follows pagination or delta links where supported, validates attributes, and maps stable Graph identifiers to the target model. |
| Groups | Coordinate Microsoft 365 groups, security groups, memberships, and access-related workflows. | Workday, ServiceNow, identity repositories, Jira | Martini applies membership and provisioning rules, records source identifiers, handles authorization failures separately, and makes updates idempotent. |
| Messages | Process Outlook email, folders, sender information, message metadata, and selected mail workflows. | Salesforce, Zendesk, ServiceNow, archives, databases | Martini filters messages by documented query criteria, retrieves required fields and attachments, maps content to the destination schema, and stores a durable processing key. |
| Events | Synchronize Outlook calendar events, attendees, schedules, and selected notification workflows. | Salesforce, ServiceNow, scheduling applications, databases | Martini normalizes time zones and identifiers, applies event-routing rules, handles updates and cancellations, and prevents duplicate downstream writes. |
| DriveItems | Synchronize files and folders in OneDrive and SharePoint document libraries. | DocuSign, archives, document repositories, SAP S/4HANA | Martini tracks DriveItem identifiers, ETags, paths, and modification timestamps, transfers binary content separately, and uses upload sessions or delta queries where appropriate. |
| Subscriptions | Register and manage change-notification subscriptions for selected Microsoft Graph resources. | Martini APIs, workflow stores, monitoring systems | Martini stores subscription identifiers and expiration times, renews subscriptions on a schedule, handles validation and lifecycle notifications, and initiates reconciliation after missed delivery. |
Authentication and security considerations
OAuth 2.0 and Microsoft Entra permissions
Microsoft Graph uses Microsoft identity platform OAuth 2.0 bearer tokens. Martini can call Graph with delegated permissions for user-context operations or application permissions for background services, subject to tenant administrator consent and resource-specific authorization requirements.
Least privilege and consent
Permissions should be limited to the resources and operations required by the workflow. Mail, files, groups, Teams, and directory resources have different permission models, and Conditional Access or other Microsoft Entra policies may affect token issuance and use.
Secret protection
- Store client secrets, certificates, refresh tokens, and environment values in protected Martini secrets or configuration.
- Use separate credentials and permission scopes for development, testing, and production where appropriate.
- Do not embed credentials or long-lived tokens in workflow definitions or payload mappings.
Operational considerations for Microsoft Graph integrations
Throttling and retries
Microsoft Graph can return HTTP 429 responses and transient 5xx or network failures. Honor Retry-After when present, use bounded exponential backoff, and avoid unbounded parallelism or unnecessary polling.
Pagination and incremental state
Follow @odata.nextLink values as returned and persist progress for large collections. For supported resources, store opaque @odata.deltaLink values securely and be prepared to perform a new full synchronization if a token becomes invalid.
Notifications and idempotency
Graph change notifications can be duplicated, delayed, or missed. Subscriptions expire and require renewal. Use stable resource identifiers, ETags, subscription identifiers, and durable processing keys, and reconcile after outages or lifecycle events.
Versions and testing
Use the v1.0 endpoint for production when it provides the required capability. Treat beta features as changeable, and test permissions, pagination, notification validation, file sizes, resource-specific query behavior, and failure recovery before deployment.
Why use Martini instead of scripts or point-to-point integrations?
Orchestrate more than an API call
Scripts often combine authentication, pagination, mapping, retries, and business rules in a single implementation. Martini separates these concerns into workflows and reusable integration assets that can be monitored and maintained as requirements change.
Coordinate event and scheduled processing
Martini can expose an API for selected Microsoft Graph notifications while using scheduled workflows for subscription renewal, delta synchronization, reconciliation, and batch processing.
Apply consistent data controls
Mapping, validation, routing, idempotency, error handling, and environment-specific secrets can be applied consistently across Graph resources and target systems rather than duplicated across point-to-point scripts.
Preserve integration flexibility
Because Microsoft Graph is consumed through standards-based REST and OAuth 2.0 mechanisms, Martini can combine Graph calls with other APIs, databases, files, and messaging systems without requiring a dedicated vendor connector.
Frequently asked questions
Microsoft Graph can be integrated through its unified REST API using OAuth 2.0 bearer tokens, JSON payloads, OData queries, pagination, and resource-specific permissions. Selected resources also support change notifications, delta queries, JSON batching, and file or attachment operations. Martini can orchestrate these calls, receive selected notifications through an exposed API, transform the data, and route it to enterprise applications, databases, files, or queues.
Yes. Martini can integrate with Microsoft Graph by consuming its REST APIs with Microsoft identity platform OAuth 2.0 access tokens. It can also expose an API to receive Microsoft Graph change notifications for selected resources and use workflows to retrieve, transform, and route the current resource.
No. A dedicated Microsoft Graph connector is not required. Martini can use Microsoft Graph's documented REST endpoints, OAuth 2.0 authentication, selected change notifications, delta queries, JSON batching, and file resources through workflows and APIs.
Lonti does not charge an additional per-connector or per-vendor fee to integrate Microsoft Graph. Integrations are subject to the provisioned capacity of the Martini environment. Separate costs may apply from Microsoft, Azure, cloud infrastructure, or other third-party systems based on subscription, usage, and deployment model.
Use the Microsoft Graph REST API as the primary integration method, with application or delegated permissions selected for the operating model. Use change notifications for supported near-real-time scenarios, delta queries for supported incremental synchronization, JSON batching for compatible request groups, and DriveItem or attachment resources for document and file workflows.
For selected resources, Microsoft Graph can send change notifications to an HTTPS endpoint. Martini can expose an API to receive validation requests and notifications, retrieve the current resource when necessary, and route it through a workflow. Coverage is resource-specific, subscriptions expire, and the design must handle duplicate, delayed, or missed notifications.
A Martini workflow can perform a scheduled full synchronization by following Graph pagination links, or use delta queries where the selected resource supports them. The workflow persists progress and opaque delta links, processes additions, updates, and deletions, and can reconcile from a new full synchronization if a delta link becomes invalid.
Martini workflows can distinguish authorization and validation failures from transient network, throttling, and server errors. For HTTP 429 responses, the implementation should honor Retry-After when supplied and use bounded exponential backoff. Stable Graph IDs, ETags, timestamps, subscription identifiers, and application processing keys support idempotency and duplicate notification handling.
Related Martini documentation
Build your Microsoft Graph integration with Martini
Use Martini to connect Microsoft Graph REST APIs and selected change notifications with enterprise workflows, applications, databases, and file systems through secure, maintainable integration assets.