readEvents Documentation

Purpose

This node fetch events from a user's Outlook Calendar over a specified time range. It enables the user to query specific events based on their topics, and it allows for customizable result limits. This functionality is crucial for applications that require integration with calendar data, such as event management tools or scheduling applications.

Settings

1. calendarId

• Input Type: String
• Description: This setting specifies the calendar from which to read events. If a specific calendar ID is provided, the component will fetch events from that calendar. If it is not provided, the logic defaults to the user's default calendar. Changing this setting allows the user to target specific calendar resources.
• Default Value: User's default calendar (null if not specified).

2. timeRangeDays

• Input Type: Numeric
• Description: This setting defines the number of days around the current date for which events will be fetched. The logic calculates the range from the current date backwards and forwards based on this value. Increasing the time range allows the component to pull a more extensive set of events, while decreasing it narrows the focus to a shorter period.
• Default Value: 30 days.

3. query

• Input Type: String
• Description: This setting allows for a free-text search within event subjects. Any events that match the search string will be returned. This is particularly useful for filtering events based on keywords or topics. Leaving this field blank retrieves all events within the specified range.
• Default Value: An empty string ('').

4. maxResults

• Input Type: Numeric
• Description: This setting limits the maximum number of events returned by the node. It can accept a value between 1 and 250, inclusive. This allows users to control the amount of data retrieved, which can be useful in reducing latency or managing bandwidth in applications. Setting this too low might not capture all relevant events, while setting it too high may cause performance issues.
• Default Value: 50.

How It Works

The node operates asynchronously and follows these general steps:

1. It establishes a connection to the Outlook Calendar integration using a secure connection.
2. It retrieves configuration settings and user inputs, defining values for calendarId, timeRangeDays, query, and maxResults.
3. It calculates two datetime values (timeMin and timeMax) based on the current date and the specified timeRangeDays.
4. It calls the listEvents method of the integration which fetches events from the specified calendar within the calculated time window, applying any search query if provided.
5. It processes the returned event data, mapping it to a structured format suitable for output.
6. Finally, it returns the events along with metadata about the query, including the total number of results found.

Expected Data

This node expects inputs as defined in the settings section. Additionally, the output will contain an array of event objects, each structured with the following properties:

• id: Unique identifier for the event.
• summary: Title or subject of the event.
• start: Start time of the event in ISO format.
• end: End time of the event in ISO format.
• location: Location of the event.
• attendees: List of attendees for the event.

The output is structured in the following manner:

{
    "output1": {
        "data": [
            {
                "id": "event_id",
                "summary": "Event Title",
                "start": "2023-10-01T10:00:00Z",
                "end": "2023-10-01T11:00:00Z",
                "location": "Conference Room",
                "attendees": ["email@example.com"]
            }
        ],
        "metadata": {
            "calendarId": "calendar_id",
            "timeMin": "start_date",
            "timeMax": "end_date",
            "query": "search_term",
            "totalResults": 1
        }
    }
}

Use Cases & Examples

Use Cases

1. Corporate Event Management: A business application can use the readEvents component to pull all relevant events for the upcoming month to evaluate scheduling conflicts and availability of resources such as conference rooms.
2. Personal Assistant Applications: Personal scheduling tools may integrate this functionality to help users plan their week by displaying all events related to specified keywords (e.g., "meeting", "appointment") that fall within the next 15 days.
3. Analytics Dashboards: Team leaders can leverage this logic to generate reports on the number of events scheduled over a specified period to monitor team engagement and resource allocation.

Example Configuration

Use Case: A corporate application that checks for all meetings scheduled for the next two weeks to avoid overlap when planning new meetings.

Sample Configuration:

{
    "inputs": {
        "calendarId": "user_calendar_id",
        "timeRangeDays": 14,
        "query": "meeting",
        "maxResults": 100
    },
    "config": {
        "calendarId": null,
        "timeRangeDays": 30,
        "query": "",
        "maxResults": 50
    }
}

Explanation: In this configuration:

• calendarId is set to a specific user calendar ID to ensure accurate event fetching.
• timeRangeDays is set to 14, ensuring coverage for the next two weeks.
• query filters results to include only events that contain "meeting" in the title.
• maxResults is set to 100, accommodating for a possible high volume of scheduled meetings during that time.