List Events (Google Calendar) v1.0.0 Help ​

Lists the details of the events that match the filters from the selected Google calendar.

How can I use this Step? ​

Use this Step to add the details of the events that match specified filters from the selected Google calendar to its output to be used further in the Flow. First, you select an authorization connected to a Google account with permission to access the calendar, then define the calendar ID. After, you define the filters. When this Step is reached during execution, it adds the details of each event that matches the defined filters to the output, and the Flow proceeds down the next exit. The options to select the Flow behavior in case no events are found and to output the events by pages are available.

Warning! In case the number of events that match the filters is too big, the Step may take significant time to execute. Make sure to consider the lifespan of the Flow session in such a case.

Prerequisites ​

In order to use any Step from the Google Calendar toolkit, you must do the following:

1. Create a new or use an existing Google Cloud Project in your Google Cloud Console. To create a new project, follow these instructions.
2. Create an authorization by connecting your OneReach.ai account with the Google Cloud Project. Step-by-step instructions on how to do this can be found in the collapsible group of the respective authorization type modal window.
3. Get permission for the authorized email accounts to make changes and manage sharing in the defined calendar.

Authorization ​

To set up an authorization, do the following:

1. Select the authorization type in the dropdown.
2. Select one of the two options:

• Click the select authorization in current step option to select an authorization from the respective dropdown in this Step. Use this option when you need to:
  • Create a new authorization;
  • Select a previously created authorization manually.
• Select the inherit from previous step option to choose the authorization that was used in the last executed Step of the Google Drive/Calendar toolkits in the Flow. Use this option when you have already created an authorization of the selected authorization type and used it previously in the Flow.

Authorization type ​

The Google Drive and Google Calendar toolkits support two authorization types:

• OAuth 2.0
• Service account

The OAuth 2.0 authorization is used to authenticate as an end user and access user data in your app. It requires your app to request and receive consent from the user.

The service account authorization is used to authenticate as a robot service account or to access resources on behalf of Google Workspace or Cloud Identity users through domain-wide delegation. A service account is a special kind of account used by an application, rather than a person. Read more here.

Create a new authorization ​

To create a new authorization, do the following:

1. Select the authorization type in the respective dropdown.
2. Click the select authorization in current step button.
3. Click the Gear button, then Add, or select to Create new authorization in the dropdown.
4. A modal window for creating a new authorization will pop up. Follow the instructions in the modal's collapsible. When finished, the created authorization name will be added to the list in the dropdown.
5. Select respective authorization name in the select authorization in current step dropdown.

Select authorization in current step ​

The select authorization in current step dropdown lists every authorization added to your OneReach.ai account.

• To choose an authorization, select its name in the dropdown.

The gear button contains options to add a new or delete an existing authorization, as well as to refresh the list of added authorizations.

Click edit to update the fields of a service account authorization. An OAuth 2.0 authorization can be reauthorized.

Warning! If the user created an external app in their OAuth Consent Screen, the created authorization needs to be reauthorized in any Flow once approximately every 7 days.

Inherit from previous step ​

When a Step from the Google Drive/Calendar toolkit is added to the Flow, the user is expected to manually choose the authorization type and then an authorization from the respective dropdowns. If another Step from these toolkits is added to the Flow and their selected authorization types match, the option to inherit from previous step is chosen by default. When selected, it continues to use the same authorization as was defined in the previous Step of the Google Drive/Calendar toolkit without the need to select it manually.

Warning! If the inherit from previous step option is selected, but there is no Step with the matching authorization type in the Flow, the Step results in an error.

Calendar ​

This section is designated to defining the Google calendar that is used for listing events. To set up this section, take one of the following steps:

• Provide its calendar ID.
• Select option to inherit calendar from previous step.

Warning! If the authorized user in the authorization section doesn't own the defined calendar, the calendar owner should provide the following permissions depending on the authorization type:

Type	Email	Permission
OAuth 2.0	Authorized email	Make changes and manage sharing
Service account	Client email	Make changes and manage sharing
Service account	Impersonate email	Make changes to events

This can be done in the share with specific people or groups section of the defined calendar's setting and sharing. See how to share a calendar here.

Calendar ID ​

The calendar ID is a unique identifier of a Google Calendar. To find it in the Google Calendar UI, do the following:

1. Open your Google calendar, then click Main menu.
2. Hover over the calendar name of the requested calendar, then click the ellipsis > settings and sharing.
3. Open the integrate calendar section and copy the calendar ID.

Alternatively, the calendar ID can be provided via the calendarId merge field value of another Step from the Google Calendar toolkit.

Inherit calendar from previous step ​

When a Step from the Google Calendar toolkit is added to the Flow, the user is expected to provide the calendar ID manually. If another Step from the same toolkit is added to the Flow, the option to inherit calendar from previous step is selected by default. When selected, it continues to use the same calendar ID as was defined in the previous Step of the same toolkit without the need to select it manually.

Filters ​

This section is designated to defining the filters that will be used to find necessary events. Set up no, a few or all of the following filters:

• Set the date and time boundaries;
• Provide a search text term;
• Allow to include deleted events that match the filters.

Warning! All defined filters must be met for an event to be included in the output of the Step.

Note: If no filters are defined, the Step returns all events from the calendar.

Date and time ​

To list events that fall into the date and time boundaries do the following:

1. Select the timezone.
2. Enter the start date and start time.
3. Enter the end date and end time.

See how to set up the timezone, dates and times.

Note: If left empty, these inputs will default to:

Key	Value
Start date	The first date of the calendar.
Start time	00:00
End date	The last date of the calendar.
End time	00:00

Warning! The date and time boundaries are excluded from the filter. The event must partially overlap or completely cover the defined date and time period to be included.

See filter examples.

Timezone ​

The timezone value can be changed in the dropdown or set to the timezone of the user's device via the pin button.

Date ​

The numeric formats yyyy-MM-dd or MM-dd-yyyy are suggested to specify dates. All the formats of start date and end date values are explained in the link under the ? icon. The start date must be earlier or the same as the end date value.

Warning! 12-03-2023 input is interpreted as Dec 3rd, 2023, while 16-03-2023 input is interpreted as Mar 16th, 2023.

Time ​

The numeric formats HH:mm or hh:mm am/pm are suggested to specify time. All the formats of start time and end time values are explained in the link under the ? icon.

See filter examples.

Search text ​

To filter out the events with a text expression:

• Provide the search text in the respective field.

The defined search text input has to exactly match a part of the value found either in the event's title, description, location or guests for the event to be included in the output.

The search text is case insensitive and ignores all special characters, processing them as a single space.

Example: The search text input Meeting #12 is processed as meeting 12. See how the Step processes events that have the following text inputs in the table:

Skips	Includes
New meeting, meeting, 12, meeting 123, meetings 12	New meeting @#$%:;")(12, meeting @12, meeting,12, meeting,#12, meeting 12

See filter examples.

Deleted events ​

By default, the Step applies the filters to events in the defined calendar without including the cancelled events found in its trash bin. To include deleted events that match the filters, turn on the respective toggle.

See filter examples.

Filter examples ​

1. If the inputs are as follows:

   Start date: 2023-09-01
   End date: 2023-10-01
   Search text: vacation

   Start date: 2023-09-01
   End date: 2023-10-01
   Search text: vacation

   The output includes all events that begin, happen or end in September 2023 and have the word vacation in their text inputs, such as title or description.

2. If the inputs are as follows:

   Start date: 2023-05-01
   Start time: 10:00
   End date: 2023-05-05
   End time: 12:00
   Search text: onereach.ai

   Start date: 2023-05-01
   Start time: 10:00
   End date: 2023-05-05
   End time: 12:00
   Search text: onereach.ai

   Only the events that have onereach.ai in their text inputs are selected from the calendar. For example, events with guests whose emails belong to the onereach.ai domain. Out of those events, the following are included in the output:

   • each specific time event that ends after 10:00 am on May 1st, begins before noon of May 5th, 2023, or covers the whole period.
   • each all day event that begins, happens or ends between May 1st and May 5th.

   Note: Specific time events that end at 10:00 on May 1st or begin at 12:00 on May 5th are not included, but all day events that end on May 1st or begin on May 5th are included.

3. If the inputs are as follows:

   Start date: 2023-01-01
   Start time: 00:00
   End date: 2023-01-04
   End time: 00:00
   Include deleted events that match the filters: ON

   Start date: 2023-01-01
   Start time: 00:00
   End date: 2023-01-04
   End time: 00:00
   Include deleted events that match the filters: ON

   The output includes:

   • each existing or deleted specific time event that ends after midnight Dec 31st, 2022, begins before midnight of Jan 4th, 2023, or covers the whole period.
   • each existing or deleted all day event that begins, happens or ends between Jan 1st and Jan 3rd, 2023, included.

   Note: Specific time events that end at 00:00 Dec 31st, 2022 or begin at 00:00 on Jan 4th, 2023 and all day events that end on Dec 31st, 2022 or begin on Jan 4th 2023 are not included.

Conflict handling ​

By default, in case no events match all filters, the Flow will proceed down the not found exit. Select the next or error option in the dropdown to take the Flow down the respective exit.

Note: the not found exit is removed from the Flow tree if a different exit is selected.

Output settings ​

This section is optional and allows to set up the pagination of the output. This can be useful when you expect a big number of matches and wish to process them in batches, each defined by the number of events per page and the next page token.

By default, the Step waits until the Google Calendar API filters through the whole calendar before returning its results in the output. To limit the number of matches with an option to filter the rest later, turn on the limit the output of search results by a single page toggle, then:

1. Define the number of events per page.
2. Optional: provide the next page token.

In this case, the Step will wait until the Google Calendar API either:

• returns a list of events that match the filters whose quantity is equal to the defined number of events per page, and a next page token value;
• filters through the whole calendar and returns all the events that match the filters whose quantity may be less than or equal to the defined number of events per page.

Number of events per page ​

The number of events per page is expected as a positive integer number between 1 and 2500.

Warning! The Google Calendar API may take some time to filter and return a big number of events per page.

Next page token ​

The next page token is a unique token that can be used to access the next page of this result. If no further results are available, the nextPageToken merge field value will be absent from the output.

To process the first page, leave the next page token empty. To process the next page, use the nextPageToken merge field value of this Step in the respective field of another List Events (Google Calendar) Step.

Advanced settings ​

The Google Calendar API supports other optional event properties that can be used to filter through events or output the result (e.g. define how to order the list or limit the number of guests listed in the output). You can specify these parameters as a JSON expression in the additional query parameters field. See the list of parameters here.

For example, to list events in ascending order by their start time, and list guests in the output only if the respective event has 10 or less, you can use the following structure:

{
  "orderBy": "startTime",
  "maxAttendees": 10
}

{
  "orderBy": "startTime",
  "maxAttendees": 10
}

Merge field settings ​

The output data of the Step will be stored under the name provided in the merge field name. It includes the defined calendar in calendarId, all the data about the each event that matched the defined filters in events and the total number of returned events in eventsQuantity. The nextPageToken property is returned if the calendar has not yet retuned all events that match the filters. See the list of possible properties:

See below an example of the merge field object's structure:

{
  "calendarId": "c_oos5h8kvedslp0k8m2gaie553k@group.calendar.google.com",
  "nextPageToken": "",
  "eventsQuantity": 100,
  "events": [{
      "kind": "calendar#event",
      "etag": "...",
      "id": "...",
      "status": "confirmed",
      "htmlLink": "https://www.google.com/calendar/event?eid=...",
      "created": "YYYY-MM-DDThh:mm:ss.000Z",
      "updated": "YYYY-MM-DDThh:mm:ss.209Z",
      "summary": "...",
      "description": "...",
      "creator": {
        "email": "...@onereach.com"
      },
      "organizer": {
        "email": "c_oos5h8kvedslp0k8m2gaie553k@group.calendar.google.com",
        "displayName": "My calendar",
        "self": true
      },
      "start": {
        "dateTime": "2022-10-05T14:00:00+03:00",
        "timeZone": "GMT+03:00"
      },
      "end": {
        "dateTime": "2022-10-05T19:00:00+03:00",
        "timeZone": "GMT+03:00"
      },
      "iCalUID": "...",
      "sequence": 0,
      "attendees": [{
        "email": "...@gmail.com",
        "responseStatus": "needsAction"
      }],
      "reminders": {
        "useDefault": true
      },
      "eventType": "default"
    },
    {
      "kind": "calendar#event",
      ...
    }
  }]
}

{
  "calendarId": "c_oos5h8kvedslp0k8m2gaie553k@group.calendar.google.com",
  "nextPageToken": "",
  "eventsQuantity": 100,
  "events": [{
      "kind": "calendar#event",
      "etag": "...",
      "id": "...",
      "status": "confirmed",
      "htmlLink": "https://www.google.com/calendar/event?eid=...",
      "created": "YYYY-MM-DDThh:mm:ss.000Z",
      "updated": "YYYY-MM-DDThh:mm:ss.209Z",
      "summary": "...",
      "description": "...",
      "creator": {
        "email": "...@onereach.com"
      },
      "organizer": {
        "email": "c_oos5h8kvedslp0k8m2gaie553k@group.calendar.google.com",
        "displayName": "My calendar",
        "self": true
      },
      "start": {
        "dateTime": "2022-10-05T14:00:00+03:00",
        "timeZone": "GMT+03:00"
      },
      "end": {
        "dateTime": "2022-10-05T19:00:00+03:00",
        "timeZone": "GMT+03:00"
      },
      "iCalUID": "...",
      "sequence": 0,
      "attendees": [{
        "email": "...@gmail.com",
        "responseStatus": "needsAction"
      }],
      "reminders": {
        "useDefault": true
      },
      "eventType": "default"
    },
    {
      "kind": "calendar#event",
      ...
    }
  }]
}

In case no events are found, the merge field value depends on the exit:

• next - {}
• not found - null

Error handling ​

The handle error toggle is enabled by default and adds an error exit to the Step. The Flow proceeds down this exit if any error is encountered during the Step execution, e.g. if the authorization data or the calendar ID is invalid, or you don't have permission to manage the calendar.

If the handle error toggle is disabled, the Step does not handle errors. In this case, if any error occurs during the Step execution, the Flow fails immediately after exceeding the Flow timeout. To prevent the Flow from being suspended and continue handling errors, you can place the Handle Flow Error Step before the main logic of your Flow.

Reporting ​

After the Step completes, it generates a report that includes its execution status and other details. You can customize the report by adjusting the Step's log level and adding tags.

Log level ​

By default, the Step's log level matches that of the Flow. You can change the Step's log level by selecting an appropriate option from the Log level dropdown.

Tags ​

Tags provide a way to classify and search for sessions based on their attributes. To create a new tag, specify its category, label, and value. You can then use tags to filter and group the sessions in the report.

Services dependencies ​

• studio v3.46.1
• authorization Manager v1.3.6

Release notes ​

v1.0.0

• Initial release