📖 Definition

The List Calendars action in the Microsoft Calendar category allows you to retrieve all calendars associated with a user account, including both their personal calendars and shared calendars. This is particularly useful when you need to access calendar information dynamically without knowing the calendar IDs in advance.

With this action, you can:

• Fetch up to 1,000 calendars in a single run.
• Retrieve both default and shared calendars, along with details like ownership, permissions, and online meeting settings.
• Use the returned calendar information (such as display name, ID, or permissions) in later steps of your flow—for example, to identify the right calendar for creating or updating events.
• Leverage pagination through the Next page token field to handle large sets of calendars seamlessly.

In short, the List Calendars action provides a flexible and efficient way to access calendar metadata, making it easier to design flows that adapt to different users and organizational setups.

---

💡 Example Use Cases

1. Identify the Default Calendar

Quickly retrieve the user’s default calendar to ensure all new events are scheduled in the correct place without manually specifying an ID.

2. Find a Calendar by Name

When the calendar ID is unknown, fetch all calendars and then use a query (e.g., with Query Collection) to match the display name, ensuring you target the right calendar dynamically.

3. Access Shared Calendars

Get a list of calendars shared with the user (e.g., a department calendar or project-specific calendar) and automate event scheduling or updates on them.

4. Check Permissions Before Scheduling

Retrieve calendars to check whether the user has permission to edit, share, or view private items before attempting to add or modify events. This prevents errors in automated workflows.

5. Set Up Switches Based on Calendar Type

Use the calendar data to apply different actions depending on the calendar type—e.g., route tasks to a team’s shared calendar versus a personal one.

6. Audit User Calendars

Retrieve all calendars for a user to create reports (e.g., which calendars are default, which allow online meetings, which are removable) for administrative or compliance purposes.

7. Multi-Calendar Event Creation

For users managing multiple projects or roles, list their calendars and then dynamically choose which calendar should receive the event based on workflow logic.

8. Automated Calendar Sync

Use the calendar metadata (owners, permissions, online meeting providers) to help synchronize or align events between different users’ calendars across teams.

---

📝 Inputs

1. Connection

This is where you set up the link between Zenphi and your Microsoft account. The connection ensures Zenphi can securely access your Microsoft Calendar service on your behalf. You only need to configure this once, and then Zenphi can use it to retrieve calendars, read their details, and interact with them.

---

2. Number of Calendars to Return

This field determines how many calendars will be included in the results.

• Minimum value: 1 – Ensures that at least one calendar is returned.
• Maximum value: 1000 – Useful if the account has many calendars, such as shared departmental calendars or project-specific ones.💡 Example: If you know you only want the first 5 calendars, set this to 5. If you’re building a process that needs to capture all available calendars, set this to a high value like 1000.

---

3. Next Page Token

Calendars are often retrieved in pages when the number of results is too large to return in a single request. This field lets you fetch the next batch of calendars after the first set has been retrieved.

• If this is left blank, Zenphi will start from the first page (default behavior).
• If you provide a token (from a previous output), Zenphi continues from where it left off, allowing you to loop through all calendars until none remain.💡 Practical Use: This is especially useful when handling hundreds of calendars, ensuring you don’t miss any results beyond the initial response.

---

Outputs

1. CalendarsA collection of the user’s own and shared calendars. Use this list to identify which calendar to act on (e.g., list events, create meetings, share permissions).

   • IDThe calendar’s unique identifier (stable token used in all subsequent actions). Example: AAMkAGI2...AAA=. Use this to fetch events or create new ones on this calendar.

   • NameThe human-readable display name shown in Outlook/Teams. Example: Marketing Team, Personal, Room 2F-Blue.

   • Change KeyA version stamp that updates when the calendar’s metadata changes. Compare stored vs. current values to detect changes before updating.

   • Can Edittrue/false indicating whether you can create/update/delete events on this calendar. Gate write actions based on this flag to avoid permission errors.

   • Can Sharetrue/false indicating whether you can share this calendar with others. If false, suppress any “share calendar” automation for this item.

   • Can View Private Itemstrue/false indicating whether private events’ details are visible to you. If false, private events appear as busy blocks only—design your downstream steps accordingly.

   • Is Default Calendartrue/false showing whether this is the user’s primary calendar (the default target for new events). Useful when your flow should “just work” without asking which calendar to use.

   • Is Removabletrue/false indicating whether this calendar can be removed from the mailbox. Use this to hide “delete/remove” options where not allowed.

   • Default Online Meeting ProviderThe conferencing service automatically attached to events created here (e.g., teamsForBusiness, skypeForBusiness, or unknown). If unknown, set meeting provider explicitly in your event-creation step.

   • OwnerWho owns this calendar—helps you distinguish personal vs. shared calendars.

     • Includes: Display Name (e.g., Jane Doe), Email Address (e.g., [email protected]).Use this to filter calendars by owner or to route approvals to the right person.

   • Allowed Online Meeting ProvidersA list of conferencing providers permitted on this calendar (e.g., teamsForBusiness, zoom, webex). If empty or unknown, rely on defaults or prompt the user.

---

2. Next Page TokenA continuation token to retrieve the next set of calendars when results are paginated. If absent, you’ve reached the end. Store and pass this value into the next List Calendars call to iterate through large tenants.

---

3. CountThe number of calendars returned in this response (not the grand total across pages). Use it for reporting, loop bounds, or to validate that your filters (e.g., by name/owner) are working as intended.

---

Example: Finding a Specific Calendar by Display Name

**Scenario:**You are building a workflow that needs to create events in a shared team calendar, but you don’t know the calendar’s ID. You only know the display name, e.g., "Marketing Team".

Steps to implement:

1. Add the “List Calendars” action

   • Connect your Microsoft account.
   • Set Number of calendars to return to a high enough value (e.g., 50) to ensure the target calendar is included.
   • Leave Next page token empty for the first call.

2. Retrieve the list of calendars

   • The action returns a collection of all accessible calendars, including personal and shared ones.

3. Use a “Query Collection” or filter step

   • Apply a filter on the returned calendar list using the display name:
   • This identifies the specific calendar object and retrieves its detailed information.

Key Tip:

• If your organization has many shared calendars, enable pagination using Next Page Token to ensure you don’t miss any calendars.
• Once the ID is retrieved, you can safely store it in a variable for reuse in the workflow, avoiding repeated searches.

---

This example demonstrates a common use case: finding a calendar when only the display name is known. It highlights how to combine the action with filtering to reliably select the correct calendar for further automation steps.