New command: planner plan set

[Jwaegebaert]

Usage

planner plan set

Description

Updates a Microsoft Planner plan

Options

Option	Description
-i, --id [id]	ID of the plan. Specify either id or title but not both.
-t, --title [title]	Title of the plan. Specify either id or title but not both.
--ownerGroupId [ownerGroupId]	ID of the group to which the plan belongs. Specify ownerGroupId or ownerGroupName when using title.
--ownerGroupName [ownerGroupName]	Name of the group to which the plan belongs. Specify ownerGroupId or ownerGroupName when using title.
--newTitle [newTitle]	New title of the plan.
--shareWithUserIds [shareWithUserIds]	The comma-separated IDs of the users with whom you want to share the plan. Specify either shareWithUserIds or shareWithUserNames but not both.
--shareWithUserNames [shareWithUserNames]	The comma-separated UPNs of the users with whom you want to share the plan. Specify either shareWithUserIds or shareWithUserNames but not both.

Unknown Options

Option	Description
--category1 [category1]	New label for a category. Define the category key within your option to update the related label. Category 1 to 25 available. e.g. --category4, --category12

In the docs section for this command, we'll reference the category options as unknown options in the remarks section. We'll need to validate the unknown options so that only category1-25 can actually be used.

Examples

Updates a Microsoft Planner plan title to New Title for the plan with id gndWOTSK60GfPQfiDDj43JgACDCb.

m365 planner plan set --id 'gndWOTSK60GfPQfiDDj43JgACDCb' --newTitle 'New Title'

Share a Microsoft Planner plan with title Plan Title that is owned by the group My Group, with the users user1@contoso.com and user2@contoso.com

m365 planner plan set --title 'Plan Title' --ownerGroupName `My Group` --shareWithUserNames `user1@contoso.com,user2@contoso.com`

Updates a Microsoft Planner plan category label with the key 21 to ToDo also the category label with the key 25 to Urgent. This for the plan with id gndWOTSK60GfPQfiDDj43JgACDCb.

m365 planner plan set --id 'gndWOTSK60GfPQfiDDj43JgACDCb' --category21 'ToDo' --category25 'Urgent'

Additional Info

Graph docs:

• https://docs.microsoft.com/graph/api/plannerplan-update?view=graph-rest-1.0&tabs=http
• https://docs.microsoft.com/graph/api/resources/plannerplandetails?view=graph-rest-1.0
• https://docs.microsoft.com/graph/api/resources/plannercategorydescriptions?view=graph-rest-1.0

[Adam-it]

seems well prepared. Good job 👍
@Jwaegebaert were you planning on taking this or should we open it for the community ?

[Jwaegebaert]

Thanks @Adam-it, let's open it up.

[nanddeepn]

Can I work on this?

[martinlingstuyl]

Hi guys,

Of course you can work in it @nanddeepn. I do have a question on the specs though. I personally find the --number option a bit vague. Wouldn't it be a lot clearer if we'd have --key and --label? You'd need to enter the complete category key, like this: category1, category2, etc.

It's slightly more typing, but then we could use autocomplete to let users be able to quickly type the category keys.

[martinlingstuyl]

And maybe, just thinking out loud here:
A category is not an entity within a planner plan as such. It's just a property of the plan.

Wouldn't it be better to name it planner plan set and allow the user to update things like title, owner, sharedWith as well as categoryDescriptions.

For example:

m365 planner plan set --id someid --category1 ToDo --category2 Done

m365 planner plan set --id someid --category1 ToDo --category2 Done --sharedWith adelev@blimped.nl,alexw@blimped.nl

[Jwaegebaert]

That's definitely a good idea @martinlingstuyl. We don't have so many variables to modify within the plan category model, so we can indeed better apply this in a plan set command. Totally agree on that one. Should I update the specs already towards your suggestion?

[martinlingstuyl]

That would be awesome! And then let's see if others have additional good ideas about this.

[Jwaegebaert]

Hey @martinlingstuyl, the specs have been updated. Could you take a look at the option --category#. I'm not sure if this is a correct way to phrase this option.

[martinlingstuyl]

Good question,

We have something a bit like it in the spo field set command, where it's only mentioned in the remarks:
https://pnp.github.io/cli-microsoft365/cmd/spo/field/field-set/#remarks

But maybe in this case we should just use:

--category1 [category1]
New label for a category. Define the category key within your option to update the related label. Category 1 to 25 available. e.g. --category4, --category12

@waldekmastykarz or @garrytrinder have an opinion on this?

[waldekmastykarz]

Since we're talking about 25 options, I'd suggest that we indeed use the ability to pass unknown options to the command, but then in validation use a regex to validate that the specified options are correct and that no truly unknown options (like --foo) are used. Does this make sense?

[martinlingstuyl]

Ok, so @Jwaegebaert, let's add it to the remarks, like with spo field set. Since we don't declare the unknowns a options there as well, let's not do it here either. I'll remove the category option and open it up.

[martinlingstuyl]

Still interested to work on this @nanddeepn?

[nanddeepn]

Hi @martinlingstuyl
Yes, happy to work on this.

Just one question:
In the example, we have not included options shareWithUserIds or shareWithUserNames. Are we considering one of these as mandatory option?

[milanholemans]

Seems duplicate issue of #2531

[Adam-it]

I think the issue #2531 had an PR which was closed to being inactive for very long time.
@pnp/cli-for-microsoft-365-maintainers I think we discussed it some time before and maybe we could just close that old one and retry taking this command again with this new and fresh issue and power and motivation 💪
@plamber I think you were more or less managing this topic 🤔. What do you think ?
thanks @milanholemans for helping keeping the backlog clean 👍👍👍 you rock^2 🤩

[martinlingstuyl]

Indeed, I'd say: let us merge the specs and close the other issue.

[Jwaegebaert]

The specs have been updated to include the suggestions from issue #2531

[Jwaegebaert]

Hey @nanddeepn, are you still interested to work on this new command?

[nanddeepn]

Hi @Jwaegebaert
Yes, I can work on this.

[Jwaegebaert]

Super, all yours @nanddeepn. Thanks for all your hard work!