🔍 Code Extractor

A collection class for managing Microsoft Planner Plan entities, providing methods to create and manage multiple PlannerPlan objects within a Microsoft Graph API context.

Purpose

PlannerPlanCollection serves as a container and factory for PlannerPlan entities in the Microsoft Graph API. It extends EntityCollection to provide specialized functionality for creating new planner plans associated with Microsoft 365 Groups. The class handles the API communication for plan creation, including proper payload formatting and deferred execution when group information needs to be loaded asynchronously.

Source Code

class PlannerPlanCollection(EntityCollection[PlannerPlan]):
    def __init__(self, context, resource_path=None):
        super(PlannerPlanCollection, self).__init__(context, PlannerPlan, resource_path)

    def add(self, title, container):
        # type: (str, str|Group) -> PlannerPlan
        """Creates a new plannerPlan.
        :param str title: Plan title
        :param str or Group container: Identifies the container of the plan.
        """
        return_type = PlannerPlan(self.context)
        self.add_child(return_type)

        def _add(owner_id):
            # type: (str) -> None
            payload = {
                "title": title,
                "container": {
                    "url": "https://graph.microsoft.com/v1.0/groups/{0}".format(
                        owner_id
                    )
                },
            }
            qry = CreateEntityQuery(self, payload, return_type)
            self.context.add_query(qry)

        if isinstance(container, Group):

            def _owner_loaded():
                _add(container.id)

            container.ensure_property("id", _owner_loaded)
        else:
            _add(container)

        return return_type

Parameters

Parameter Details

context: The API context object that manages authentication, request execution, and communication with the Microsoft Graph API. This is required for all API operations and is passed to child PlannerPlan entities.

resource_path: Optional string representing the API endpoint path for this collection. If not provided, defaults to the standard path for planner plan collections. Used to construct the full URL for API requests.

Return Value

The constructor returns an instance of PlannerPlanCollection. The add() method returns a PlannerPlan object that will be populated with data after the API request completes. The returned PlannerPlan is immediately added to the collection but may not have all properties loaded until the query executes.

Class Interface

Methods

Attributes

Dependencies

• office365
• office365.directory.groups.group
• office365.entity_collection
• office365.planner.plans.plan
• office365.runtime.queries.create_entity

Required Imports

from office365.directory.groups.group import Group
from office365.entity_collection import EntityCollection
from office365.planner.plans.plan import PlannerPlan
from office365.runtime.queries.create_entity import CreateEntityQuery

Usage Example

from office365.graph_client import GraphClient
from office365.directory.groups.group import Group

# Initialize Graph client with credentials
client = GraphClient(credentials)

# Get the planner plans collection
plans_collection = client.planner.plans

# Create a new plan using group ID string
new_plan = plans_collection.add(
    title="Q1 Marketing Campaign",
    container="12345678-1234-1234-1234-123456789abc"
)
client.execute_query()
print(f"Created plan: {new_plan.id}")

# Or create a plan using a Group object
group = client.groups.get_by_id("group-id")
new_plan2 = plans_collection.add(
    title="Q2 Product Launch",
    container=group
)
client.execute_query()
print(f"Created plan: {new_plan2.id}")

Best Practices

• Always call execute_query() on the context after adding plans to trigger the actual API request
• When using a Group object as container, ensure the group's ID property is loaded before the query executes (the class handles this automatically)
• The add() method returns a PlannerPlan object immediately, but its properties won't be populated until execute_query() completes
• Use the container parameter with either a string group ID or a Group object - both are supported
• Handle potential API errors when execute_query() is called, as network or permission issues may occur
• The collection automatically manages child entities, so added plans are tracked within the collection
• Ensure the authenticated user has appropriate permissions to create plans in the specified group

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• class PlannerGroup 77.6% similar

  PlannerGroup is a class that provides access to Microsoft Planner resources associated with a group, specifically enabling retrieval of planner plans owned by the group.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/planner/group.py

• class Planner 74.5% similar

  The Planner class is a singleton entry point for accessing Microsoft Planner resources, providing access to buckets, tasks, and plans assigned to a user.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/planner/planner.py

• class PlannerPlan 73.1% similar

  The plannerPlan resource represents a plan in Microsoft 365. A plan can be owned by a group and contains a collection of plannerTasks. It can also have a collection of plannerBuckets. Each plan object has a details object that can contain more information about the plan. For more information about the relationships between groups, plans, and tasks, see Planner.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/planner/plans/plan.py

• class PlannerChecklistItems 70.4% similar

  A specialized collection class that manages checklist items for Microsoft Planner tasks, inheriting from ClientValueCollection to provide collection operations for PlannerChecklistItem objects.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/planner/tasks/check_list_items.py

• class PlannerPlanContainer 70.1% similar

  A container class representing a plannerPlan resource that manages authorization rules and lifecycle of Microsoft Planner plans.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/planner/plans/container.py