MSEndpointMgr

PowerShell Module for Microsoft Planner

Recently I fall in love with Microsoft Graph. 🙂 I was honored invited to MMSMOA talk about Intune Graph with David Falkus and Timmy Andersson. We talked about what is Microsoft Graph, how to start use it and how to use Intune Graph PowerShell SDK. Last week,  Tom Degreef asked if there is PowerShell Module for Microsoft Planner. So I did some research, and got an idea that how about make my own PowerShell module for Microsoft Planner using Microsoft Graph. I have never upload anything to PowerShell Gallery, this will full fill my bucket list as well. 🙂

You can find the module directly from PowerShell Gallery and my Github

Let’s break down some details of this module.

Authentication

The module is using Native Application that hosted in my own tenant by default, it uses permission Group.Read.All, Group.ReadWrite.All, User.Read and User.ReadBasic.All, these are the minimum permission requirement to create Planner plans, buckets and tasks. But, I would really hope you use own application for this module, because it will give you more control of those permissions, or if you wants to add more actions in your scripts. Here are the steps how to create this native app.

  1. Go to your Azure Portal, Click on Azure Active Directory, click on App registrations, then New registration

  2. Input a name example Planner PowerShell. Supported account types choose organizational directory only. You can also use any organizational directory,  if you manage multiple tenants and wants use this app to all your tenants.
    Redirect URI, choose Public client (mobile & desktop), and value as urn:ietf:wg:oauth:2.0:oob

  3. After registered this app, go to Authentication, change Default client type from to Yes, so that this will be  a public native client

  4. Click on API permissions, choose Microsoft Graph, then add Delegated permissions: Group.Read.All, Group.ReadWrite.All, User.Read and User.ReadBasic.All

  5. (Optional but also necessary) Grant admin consent. This is very much depend on your own environment and usage. Without admin consent, normal users aren’t able to run this application. If you are the only admin who use this app, then you don’t need grant consent to others. But if you want another non-admin person use this module, you should grant admin consent. Because this is using delegated permission, the required permissions will be a combination of 1) what the user has permissions to do and 2) what the application has permissions to do. (Read the details from this blog https://developer.microsoft.com/en-us/graph/blogs/30daysmsgraph-day-11-azure-ad-application-permissions/ )

    NOTE:

    • if you want to use connect-planner -Credential , you must use Grant admin consent
    • if you are using MFA, then you cannot use connect-planner -Credential, because it won’t popup MFA authentication window

Update Planner Module environment

After register your own app, copy it’s application client ID to your note.

Then install the PlannerModule, and update the module to use your own application instead of the default one.

How to use this module

At first, this module is not 100% ready, there is no delete function yet, it can create plans, buckets, tasks, assign tasks to users, add checklist, add labels, assign labels, add descriptions, create Office 365 groups, add user to Office 365 groups.  It doesn’t handle “for each” objects, only the Invoke-AssignPlannerTask can add multiple array.

Here are some examples.

Hope you like this module. If you would like to contribute this module, please make poll request in my GitHub

Sandy Zeng

Sandy is an Enterprise Mobility MVP since 2018. She is an experienced Information Technology Specialist for over 10 years. Skilled in Microsoft Endpoint Manager (ConfigMgr and Intune), Windows 10 and security. Sandy's interests are mostly related to Microsoft Technologies, she has passions learning new skill sets to improve her professional career and also as her hobbies. She uses her expertise to help customers achieve their goals and solve their issues.

Sandy founded the https://sandyzeng.com blog and is now a blogger on MSEndPointMgr.

15 comments

  • Hi Sandy, thanks for making the effort, but it does not seem to work.

    So, is your idea, that this client id has to be changed each time, I open a PowerShell console?

    When I only open a console and run ‘connect-planner’, I get a login screen and after login I get a complain because of wrong app-id.

    When I run
    ‘Update-PlannerModuleEnvironment -ClientId [my app id]’
    And after that I run connect-planner, it does not even open a login screen, I just get the error message:

    Get-PlannerAuthToken : Authorization Access Token is null, please re-run authentication…
    At C:\Program Files\WindowsPowerShell\Modules\PlannerModule\1.0.2.5\PlannerModule.psm1:1487 char:28
    + $Script:authToken = Get-PlannerAuthToken
    + ~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo : NotSpecified: (:) [Write-Error], WriteErrorException
    + FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException,Get-PlannerAuthToken

    Maybe you did not everywhere fix the name of the PlannerModuelEnvironment?

    Also, in the code sample below, the following:

    Connect-Planner -$Credential

    is wrong, it should be

    Connect-Planner -Credential $Cred

    🙁

    • Yes, it’s meant to use your own app id, so that you can have control of what permission you want to use. It won’t work anymore without using your own app ID, because the original app I was using is from my own tenant, and I deleted my app recently. After you use Update-PlannerModuleEnvironment -ClientId “your app id”, you can use Connect-Planner -ForceInteractive, it will re-run authentication. I will update those examples in my blog, thanks.

  • my script is failing 5/10 times when I run it always on this
    Add-PlannerTaskDescription : Request to https://graph.microsoft.com/beta/planner/tasks/aSyzGFG5T0-n7EfHHQsHm5YAKix6/Details failed with HTTP Status BadRequest Bad Request
    At \\DAT2-S-AS-01\SCRIPTS\FUNCTIONS\ITAUTOMATIONFunctionsV1.psm1:1499 char:19
    + … try { Add-PlannerTaskDescription -TaskID $global:PlannerPlanTas …
    + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo : NotSpecified: (:) [Write-Error], WriteErrorException
    + FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException,Add-PlannerTaskDescription

  • I already have an existin Office 365 group which I would like to re-use as “host” for the PlannerPlan. But all the GET-commands seems to fail, when I try to use them – for example
    get-plannerplanslist

    I need to figure out the PlannerPLan ID, so I can continue

    Alternative I have tried to have the script create a new Planner Plan, but it fails with ‘bad request’
    New-PlannerPlanToGroup -PlanName $PlanName -GroupID $GroupID
    New-PlannerPlanToGroup : BadRequest Bad Request
    At line:1 char:1
    + New-PlannerPlanToGroup -PlanName $PlanName -GroupID $GroupID
    + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo : NotSpecified: (:) [Write-Error], WriteErrorException
    + FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException,New-PlannerPlanToGroup

  • Is it possible to setup access with a client secret? I would like to automate adding some items to planner.

    • Hello Paul,

      Good question! The module doesn’t support use client secret, because according to Microsoft Graph document (https://docs.microsoft.com/en-us/graph/api/planner-post-plans?view=graph-rest-beta&tabs=http), planner Graph API doesn’t support application permissions, which means it need to use credential for authentication, cannot just use client secret. But I am not 100% sure about it since you are asking, because I can see there is application permission for “Group.ReadWrite.All” available in Azure application API permission, so I can’t say for sure if it’s possible or not without testing more.

      Regards, Sandy

      • Hello,

        I currently use Graph to create groups (see connect code below) and would now like to be able to create a stand alone planner from the group.
        My App is registered for GraphAPI with the following permissions:
        Directory.ReadAll
        Group.ReadWriteAll
        User.ReadWriteAll

        I have downloaded your module from PSGallery and have updated the planner env with my clientID.
        Each time I try Connect-Planner -ForceNonInteractive True I receive the following:
        Get-PlannerAuthToken : Cannot find an overload for “AcquireTokenAsync” and the argument count: “4”.

        Can you please let me know how I can connect to planner and what code I need to use to create a planner from the group I have created.

      • Code to connect to Graph
        $ReqTokenBody = @{
        Grant_Type = “client_credentials”
        Scope = “https://graph.microsoft.com/.default”
        client_Id = $clientID
        Client_Secret = $clientSecret
        }

        $TokenResponse = Invoke-RestMethod -Uri “https://login.microsoftonline.com/$TenantName/oauth2/v2.0/token” -Method POST -Body $ReqTokenBody
        $accessToken = $TokenResponse.access_token

      • Hello, Planner graph API is not support application permission, so I don’t think it will work with client secret. Can you try uninstall AzureAD module, then reinstall AzureAD module?

    • I don’t have documentation of this PowerShell module, but the script is also on github as I mentioned in my blog post. If you don’t want install the module from powershell gallery, you can get it from github and modified it for your own usage.

  • Dear Sandy,

    there is a typo in this function: “Update-PlannerModuelEnvironment”. I think the real name should be “Update-PlannerModuleEnvironment”. Would you mind to correct this? of course you have to update the description here since it uses that wrong name.

    Thanks
    Dieter

    • Hello Dieter, another person also pointed out there is typo in function, but I didn’t want to remove the old function name, because I can’t know if anyone is using it already or not. If I change/delete that function, it might break other people’s script. I will properly add the correct one and update description in the old one.

      Thanks
      Sandy

  • Thanks for this! Great module. I only miss the -Credential argument on Connect-Planner to skip the manual login. Or is there another way around that?

    • Hello Jonas, I just publish a newer version 1.0.2.1, that will allow you use Connect-Planner -$Credential. Example:

      $Cred = Get-Credential
      Connect-Planner -$Credential

      thanks,
      Sandy

Sponsors