Microsoft
Outlook and Microsoft Office are among the most popular business software
packages and services on the planet, with Outlook.com alone boasting over 400 million users
in 2018. With the Microsoft Graph API, integrating Outlook and its
calendar with your FileMaker solution has never been simpler. In this article
we will walk through how to use the Microsoft Graph API to create events in
Outlook Calendar using FileMaker, streamlining event and scheduling management
in your FileMaker solution by eliminating double data entry.
**Updated February 2022
What You Need
You must have an active Office 365 subscription to use this article's integration, as the Microsoft Graph API does not support Outlook hosted on Exchange Server. Also make sure you have admin access to your Office 365 subscription if you have a business or school user account.
Creating a Microsoft Graph Application
Make sure to create an Azure Active Directory Tenant first if you are using a personal account and not a work or school account. An Azure app must be created to make use of the Graph API. Go to the Azure portal and add an app. Creating one can be done through selecting “App Registrations” from the Manage section on the left of the Azure Active Directory screen. After selecting this, select “New Registration” to create your app. Give the new app a name and select an account type depending on who will be connecting to this application. It is also recommended to add a Redirect URI, as most authentication scenarios will require one.
After creating your app, go to your new App and select the Certificates & Secrets tab under the Manage section and create a new client secret. A client secret will expire after at most two years, so you will eventually have to return to this menu and create a new one before expiration.
Managing App Permissions
Microsoft Graph requires that each user give the app permission to push and pull data between their Outlook Calendar and FileMaker. Before users can give permission, default permissions will need to be set up on the application registration page. This can be accessed via API Permissions under the Manage section of AAD. There are two types of Microsoft Graph permissions: delegated permissions and application permissions. For purpose of this article, delegated permissions will be used to communicate with the Outlook Calendar as a user rather than as an application.
For the Outlook Calendar Integration, the following delegated permissions must be added:
- Calendars.ReadWrite
- Calendars.ReadWrite.Shared
- User.Read
- offline_access
Authenticating with Microsoft Graph
Once the API information has been set up, you will need to authenticate your solution with the Microsoft Graph API to connect to Outlook Calendar. The sample file at the end of this article has the proper calls and web viewers to reference for setting up an initial authentication between Outlook and your new Graph application.
When the user clicks the Connect button, they will be asked to log in to their Outlook account and approve the delegated permissions for the application.
After login, a FileMaker script parses the redirected page's URL for the app’s client ID and authorization codes that will be used for requests to Outlook.
Making Requests and Parsing the Response
Microsoft Graph API supports multiple types of HTTP requests such as POST, GET and DELETE. You can perform all actions by using FileMaker’s native Insert from URL[] script step and providing a valid URL and cURL options including required fields within the JSON body specified by the documentation.
Here is a sample request body to create a calendar event. Note the formatting of theDateTime element, “YYYY-MM-DD”. For more details, refer to Microsoft Graph's properties under the event page.
{
"End" :
{
"DateTime" : "2018-12-12T11:00:00",
"TimeZone" : "Eastern Standard Time"
},
"Start" :
{
"DateTime" : "2018-12-12T10:00:00",
"TimeZone" : "Eastern Standard Time"
},
"Subject" : "Test 123"
}
If a successful request is made, the API will return a JSON-encoded body. You can check for any encountered errors by looking at the following function after the Insert from URL[ ] step:
Get ( LastExternalErrorDetail )
Or through multiple error traps checking dumped response headers, such as:
not IsEmpty ( $responseHeaders ) and PatternCount ( $responseHeaders ; "200" ) = 0
These functions will return 200 on a successful call; else the API encountered an error. If the API call was successful, you'll get a JSON-encoded response body like below with an event ID and a change key that you will need to use when updating events:
{
"@odata.context" : "https://graph.microsoft.com/v1.0/$metadata#users('gmoon%40dbservices.com')/calendar/events/$entity",
"@odata.etag" : "W/\"eyoqZr4V6UOE23scd9kKdQABYJFSxw==\"",
"attendees" : [],
"body" :
{
"content" : "",
"contentType" : "text"
},
"bodyPreview" : "",
"categories" : [],
"changeKey" : "eyoqZr4V6UOE23scd9kKdQABYJFSxw==",
"createdDateTime" : "2018-12-11T18:26:21.48905Z",
"end" :
{
"dateTime" : "2018-12-12T17:00:00.0000000",
"timeZone" : "Eastern Standard Time"
},
"hasAttachments" : false,
"iCalUId" : "040000008200E00074C5B7101A82E00800000000525905047F91D4010000000000000000100000002EF55A9CBBF9F8429AA5DF86AE8FB2CF",
"id" : "AQMkADAwATM3ZmYAZS0wYTI1LWI1N2ItMDACLTAwCgBGAAADVUTIWkB8vk_xO5-ko1YImAcAeyoqAGa_FelDhNt7HHfZCnUAAAIBDQAAAHsqKgBmvhXpQ4Tbexx32Qp1AAFghoJ2AAAA",
"importance" : "normal",
"isAllDay" : false,
"isCancelled" : false,
"isOrganizer" : true,
"isReminderOn" : true,
"lastModifiedDateTime" : "2018-12-11T18:46:23.4155607Z",
"location" :
{
"address" : {},
"coordinates" : {},
"displayName" : "",
"locationType" : "default",
"uniqueIdType" : "unknown"
},
"locations" : [],
"onlineMeetingUrl" : null,
"organizer" :
{
"emailAddress" :
{
"address" : "example@outlook.com",
"name" : "Gayoung Moon"
}
},
"originalEndTimeZone" : "Eastern Standard Time",
"originalStartTimeZone" : "Eastern Standard Time",
"recurrence" : null,
"reminderMinutesBeforeStart" : 15,
"responseRequested" : true,
"responseStatus" :
{
"response" : "organizer",
"time" : "0001-01-01T00:00:00Z"
},
"sensitivity" : "normal",
"seriesMasterId" : null,
"showAs" : "busy",
"start" :
{
"dateTime" : "2018-12-12T16:00:00.0000000",
"timeZone" : "Eastern Standard Time"
},
"subject" : "4 PM Test",
"type" : "singleInstance",
"webLink" : "https://outlook.live.com/owa/?itemid=AQMkADAwATM3ZmYAZS0wYTI1LWI1N2ItMDACLTAwCgBGAAADVUTIWkB8vk%2BxO5%2Fko1YImAcAeyoqAGa%2BFelDhNt7HHfZCnUAAAIBDQAAAHsqKgBmvhXpQ4Tbexx32Qp1AAFghoJ2AAAA&exvsurl=1&path=/calendar/item"
}
Things to Think About
- It's important to note that if permissions on the application registration page are changed, users will need to reauthenticate and allow the application use of those new permissions. The same needs to happen if you delete and regenerate your application password.
- Some users will not have permission to allow application access to their Outlook calendar. Make sure your 365 administrator gives this to each user before attempting to sync calendar events.
- If you want to display a personal calendar in FileMaker via a web viewer, users will need to log in each time that specific layout refreshes. We recommend using a public calendar that anyone can see to avoid the need to constantly log back in.
- You will need to refresh your access token at least once every hour, as the token expires after 60 minutes. We recommend error trapping for HTTP code 401 after a request, refresh the token if there's a 401, and then retry the original request.
Conclusion
The Microsoft Graph API can help streamline event and scheduling workflows by providing the ability to sync your Outlook calendar flawlessly with your FileMaker solution. Contact us if you need help integrating your FileMaker solution with your Outlook Calendar!
Did you know we are an authorized reseller for Claris FileMaker Licensing?
Contact us to discuss upgrading your Claris FileMaker software.
Download the FileMaker Outlook Calendar Integration File
Please complete the form below to download your FREE FileMaker file.
