import Global from '../../_global.mdx';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# planner roster add

Creates a new Microsoft Planner Roster

## Usage

```sh
m365 planner roster add [options]
```

## Options

<Global />

## Remarks

:::warning

The Roster will be automatically deleted when it doesn't contain a plan 24 hours after its creation. Membership information will be completely erased within 30 days of this deletion.

:::

:::warning

This command is based on an API that is currently in preview and is subject to change once the API reached general availability.

:::

:::info

To be able to create a new Roster, the Planner Roster creation tenant setting should be enabled. Use the [planner tenant settings list](../tenant/tenant-settings-list.mdx) command to check if this setting is enabled for your tenant.

:::

## Permissions

<Tabs>
  <TabItem value="Delegated">

  | Resource        | Permissions     |
  |-----------------|-----------------|
  | Microsoft Graph | Tasks.ReadWrite |

  </TabItem>
  <TabItem value="Application">

  | Resource        | Permissions         |
  |-----------------|---------------------|
  | Microsoft Graph | Tasks.ReadWrite.All |

  </TabItem>
</Tabs>

## Examples

Creates a new Microsoft Planner Roster

```sh
m365 planner roster add
```

## Response

<Tabs>
  <TabItem value="JSON">

  ```json
  {
    "id": "8bc07d47-c06f-41e1-8f00-1c113c8f6067",
    "assignedSensitivityLabel": null
  }
  ```

  </TabItem>
  <TabItem value="Text">

  ```text
  assignedSensitivityLabel: null
  id                      : 8bc07d47-c06f-41e1-8f00-1c113c8f6067
  ```

  </TabItem>
  <TabItem value="CSV">

  ```csv
  id,assignedSensitivityLabel
  8bc07d47-c06f-41e1-8f00-1c113c8f6067,
  ```

  </TabItem>
  <TabItem value="Markdown">

  ```md
  # planner roster add

  Date: 7/2/2023

  ## 8bc07d47-c06f-41e1-8f00-1c113c8f6067

  Property | Value
  ---------|-------
  id | 8bc07d47-c06f-41e1-8f00-1c113c8f6067
  assignedSensitivityLabel | null
  ```

  </TabItem>
</Tabs>

## More information

Rosters are a new type of container for Microsoft Planner plans. This enables users to create a Planner plan without the need to create a new Microsoft 365 group (with a mailbox, SharePoint site, ...). Access to Roster-contained plans is controlled by the members on the Roster. A Planner Roster can contain only 1 plan.
