Outlook Calendar Integration Documentation

Overview

The Outlook Calendar Integration allows users to interact with their Outlook calendars using the Microsoft Graph Calendar API. This integration enables functionalities such as listing calendars, creating events, updating events, and deleting events. It is designed to extend the capabilities of the Vantage analytics and data platform by leveraging calendar data, thus providing users the ability to manage their schedules more effectively within the Vantage environment.

Purpose

This integration is particularly useful for organizations or developers who utilize Outlook for their scheduling needs and want to incorporate this functionality into data-driven applications.

Settings

Detailed Explanation of Settings

1. apiUrl:

   • Input Type: String
   • Description: Sets the endpoint for the Microsoft Graph API which is essential for sending requests to interact with the calendar data.
   • Effect: This URL must remain unchanged unless the API version changes; it directly influences all API requests.
   • Default Value: https://graph.microsoft.com/v1.0

2. tokenUrl:

   • Input Type: String
   • Description: Specifies where to request OAuth tokens for API access, central to authentication steps.
   • Effect: Changing this URL incorrectly will result in authentication failures.
   • Default Value: https://login.microsoftonline.com/common/oauth2/v2.0/token

3. serviceId:

   • Input Type: String
   • Description: Acts as a unique identifier for this integration service, allowing tracking and differentiation from other integrations.
   • Effect: Modifications can help in managing or monitoring client requests but don't affect functionality directly.
   • Default Value: Not set

4. clientId:

   • Input Type: String
   • Description: Serves as the public identifier to access Microsoft services and APIs.
   • Effect: Incorrect client ID will prevent authorization and subsequent access to the calendar data.
   • Default Value: Not set

5. credentialId:

   • Input Type: String
   • Description: Links to a specific set of credentials needed to authenticate and request tokens from the Microsoft API.
   • Effect: Non-existence will halt any request operations until credentials are properly configured.
   • Default Value: Not set

6. _accessToken:

   • Input Type: String (private)
   • Description: Stores the current access token necessary for sending authenticated requests to the Microsoft Graph API.
   • Effect: If empty or expired, it will trigger a refresh of the token or lead to authentication errors.
   • Default Value: null

7. _tokenExpiry:

   • Input Type: Date (private)
   • Description: Records the time at which the access token will expire, facilitating better token management.
   • Effect: Ensures token renewal occurs before expiration, thereby maintaining continuous access.
   • Default Value: null

How It Works

The Outlook Calendar Integration works by using OAuth 2.0 for authentication. It initially retrieves access tokens from Microsoft, allowing secure API requests. The integration consists of various methods that interface directly with the Microsoft Graph API, enabling users to perform actions related to calendar management.

• Authentication: Automatically handles token retrieval and refreshing. If a token is expired or invalid, it attempts to refresh the token using a stored refresh token.
• Data Retrieval: Users can list calendars, list events, get details for specific events, and create new calendars or events through structured API calls.
• Data Manipulation: Users can also update existing events or delete them based on specified identifiers.

Data Expectations

The integration interacts with calendar and event data in the format specified by the Microsoft Graph API. For instance, when creating an event, the event data must include:

• subject (string): Required title of the event.
• start and end (object with dateTime and timeZone strings): Required bounds of the event timing.

It also expects proper handling of optional parameters like color for calendars and properties for online meetings in event data.

Use Cases & Examples

Use Cases

1. Automated Meeting Scheduling: Organizations can create scripts or applications that automatically schedule meetings based on data events using this integration, thereby reducing manual effort.

2. Event Reporting: Businesses can pull calendar events and cross-reference them with analytics data. This helps in understanding the impact of calendar events on project milestones or deliverables.

3. Resource Management: Teams can use integration to analyze scheduling conflicts or busy times, optimizing the allocation of resources or availability of employees.

Example Configuration

Use Case: Automated Meeting Scheduling

Scenario: A company wants to automatically create a meeting for their project kick-off event when a new project is added to their system.

Sample Configuration Data:

In this scenario, when a new project is created, the application could invoke the following method to create an event:

const outlookIntegration = new OutlookCalendarIntegration(encryptedRecord, serviceId, clientId, credentialId);

// Event data for the new project kick-off meeting
const eventData = {
    subject: "Kick-off Meeting for Project XYZ",
    start: {
        dateTime: "2023-11-01T10:00:00",
        timeZone: "UTC"
    },
    end: {
        dateTime: "2023-11-01T11:00:00",
        timeZone: "UTC"
    },
    location: {
        displayName: "Conference Room A"
    },
};

async function createKickoffMeeting() {
    try {
        const createdEvent = await outlookIntegration.createEvent(null, eventData, { addTeamsMeeting: true });
        console.log('Meeting created successfully:', createdEvent);
    } catch (error) {
        console.error('Failed to create meeting:', error);
    }
}

createKickoffMeeting();

In the provided example, a meeting titled "Kick-off Meeting for Project XYZ" is created on November 1, 2023, at 10 AM UTC, with a duration of 1 hour. The meeting will be created in the user's default calendar and include Microsoft Teams integration for virtual attendance.