MS Planner – Buckets – Get Bucket

Get a Planner bucket by id.

Action details

Property	Value
Action label	MS Planner – Buckets – Get Bucket
Category	CloudTools
Apex class and method	GetMSPlannerBucket.getBucket
Input type	GetMSPlannerBucket.GetMSPlannerBucketInput
Output type	List<MSPlannerBucket>
Authorization	Microsoft 365 connector; delegated or application access depends on the endpoint.
Microsoft Graph request	GET /planner/buckets/{bucketId}

Prerequisites and permissions

Configure a CloudTools Connector with Connector Type set to Microsoft 365. Complete Microsoft sign-in for OAuth Delegated (Authorization Code). For endpoints supporting OAuth Application (Client Credentials), grant the required application permissions and administrator consent. The identity must have access to the target resource. See Creating an Entra ID App and Integration Connectors for setup.

The permission provider declares these alternatives; they are not cumulative requirements. Check the Microsoft reference for endpoint restrictions.

Permission type	Declared alternatives
Delegated	Tasks.Read, Tasks.ReadWrite, Group.Read.All, Group.ReadWrite.All
Application	Tasks.Read.All, Tasks.ReadWrite.All

See the Microsoft operation and permissions reference.

Inputs

Input	Apex field	Type	Required	Description
Bucket Id	bucketId	String	Yes	Planner bucket identifier
Select Query	selectQuery	String	No	OData select query
Expand Query	expandQuery	String	No	OData expand query

Supply one non-null request. This implementation processes only the first request. The global input does not expose connectorId; Flow and subscriber Apex use CloudTools connector selection. Resolve dynamic values before invocation; replacement tokens are not resolved by this action.

Outputs

Returns one MSPlannerBucket inside a list, or an empty list if no response is mapped. Check for an empty list before reading fields. A Microsoft 404 response is treated as an empty result.

Output	Apex field	Type	Description
Id	id	String	Planner bucket identifier
Name	name	String	Planner bucket name
Plan Id	planId	String	Planner plan identifier
Order Hint	orderHint	String	Sort hint used by Planner
OData Type	odataType	String	OData type
OData ETag	odataEtag	String	OData etag
Additional Properties	additionalProperties	List<DynamicObject>	Additional data returned by query

Behavior and limits

Query inputs are forwarded as OData parameters, without checking endpoint support. List responses map only value and do not follow or expose @odata.nextLink; a result may be only the first page.

Use in Flow

Add MS Planner – Buckets – Get Bucket in Flow Builder. Use a Microsoft 365 application connector configured as Set as default for Flow automations only when the endpoint supports application access. Delegated connections are not supported for CloudTools Flow automation. Supply the required values and add fault handling. This action is not a bulk operation.

Use in custom Apex

This subscriber-org example uses the Apptigent namespace. Replace the placeholders and check empty or null results. Arrange connector authorization first, run in a context that permits callouts, and handle exceptions in the caller.

Apptigent.GetMSPlannerBucket.GetMSPlannerBucketInput request =
    new Apptigent.GetMSPlannerBucket.GetMSPlannerBucketInput();
request.bucketId = 'REPLACE_WITH_BUCKET_ID';

List<Apptigent.MSPlannerBucket> results =
    Apptigent.GetMSPlannerBucket.getBucket(
        new List<Apptigent.GetMSPlannerBucket.GetMSPlannerBucketInput>{ request }
    );
System.debug(results);

Use in a Lightning Web Component

Use getMSPlannerBucket from msPlannerConnectorLib through MSPlannerConnectorController. The function accepts a request object and an optional connector record ID as its second argument. That ID takes precedence over request.connectorId. The controller passes the selection through MSPlannerAction; it is not a field on the global invocable input. These c/ imports apply in the same namespace.

plannerActionExample.js

import { LightningElement } from 'lwc';
import { getMSPlannerBucket, MSPlannerObjects } from 'c/msPlannerConnectorLib';

export default class PlannerActionExample extends LightningElement {
    result = null;
    errorMessage = '';
    isRunning = false;
    completed = false;

    async handleRun() {
        if (this.isRunning || this.completed) return;
        this.isRunning = true;
        this.errorMessage = '';
        try {
            const request = MSPlannerObjects.inputs.plan();
            request.bucketId = 'REPLACE_WITH_BUCKET_ID';
            this.result = await getMSPlannerBucket(
                request, 'REPLACE_WITH_CONNECTOR_RECORD_ID'
            );
            this.completed = true;
        } catch (error) {
            this.errorMessage = error.requiresInteractiveAuthorization
                ? 'Sign in to Microsoft for the connector, then try again.'
                : error.message || 'The Planner action failed.';
        } finally {
            this.isRunning = false;
        }
    }
}

plannerActionExample.html

<template>
    <lightning-button label="Run action" onclick={handleRun}
        disabled={isRunning}></lightning-button>
    <p role="alert">{errorMessage}</p>
</template>

The library resolves to one mapped object or null. rawJson serializes the mapped Apex object, not the untouched Graph response. Use getMSPlannerAuthorizationState, beginMSPlannerAuthorization, and createMSPlannerOAuthMessageHandler to arrange delegated sign-in. The library normalizes controller errors but does not automatically sign in or retry.

Reset completed for a new deliberate operation. If a failed mutation has an uncertain outcome, inspect the resource before retrying. An empty update result can represent a successful operation with no response body.

Error handling and troubleshooting

Symptom	What to check
Required fields error	Supply a nonempty request list, a non-null first request, and all required fields.
Authorization or access denied	Check connector selection, sign-in, permissions, administrator consent, and resource access.
Resource not found	Use Microsoft Graph identifiers and retain each task or bucket with its source plan. Check documented 404 behavior.
Concurrency failure	Refresh the exact resource ETag before retrying; details use separate ETags.
Missing fields or items	Check query support, first-page behavior, empty PATCH responses, and model mapping limits.
Operation rejected	Inspect the Microsoft error, supported endpoint and body properties, JSON structure, and If-Match behavior.

See Planner connector introduction.