PPM Express offers two ways how the connection can be added for Planner: with a regular user account (limited access to Planner plans), or with Admin consent to grant access for the whole tenant.
In order to have full access for data synchronization between PPM Express and your Microsoft Office 365 Planner environment you need the following:
- Grant PPM Express application Global Admin consent that is provided by your Tenant Global Administrator during the first connection configuration.
- Have Office 365 Planner Account that will be used for connection. The account should meet the requirements described below in the section 'Requirements for Microsoft Planner account used for connection (Connection Account)'.
In this article, we describe how to provide a Global Admin consent to the PPM Express application. Also, we will review the requirements that your Office 365 Planner account used for connection should meet, and will provide some recommendations to make sure that your connection is set up properly with the minimum permissions required for the application to work correctly.
Why Global Administrator Consent is required
When you establish your first Planner or O365 Group connection, PPM Express Office 365 Sync app is added to Azure Enterprise Apps.
Before adding connection for the first time, Office 365 tenant Global Administrator consent (Admin Consent) is required to grant PPM Express app permissions to access Office 365. Admin Consent should be granted to PPM Express only once. When the consent is granted by Global Admin, any other Planner Account (that meets the requirements described below in the section 'Requirements for Microsoft Planner account used for connection (Connection Account)') can be used to add more connections within the same Office 365 tenant.
Admin Consent procedure is required because PPM Express needs to access data in Microsoft Graph to synchronize data from Planner.
The final set of Microsoft Graph permissions required by PPM Express is the following:
- Directory.AccessAsUser.All
- Group.ReadWrite.All
- User.Read
- User.Read.All
- User.ReadBasic.All
The following access rights require Admin Consent, which is provided by Tenant Global Administrator.
Please find more details on access review permissions in the Microsoft Graph permissions reference article.
If the connection is added using a regular account, no admin consent is granted, only those plans where the connection account is added as a member will be available for importing/linking. Also, the user must open the plan selected for linking in Planner at least once, otherwise, this plan will not appear in the list of available ones in PPM Express. This is an API limitation.
The Planner groups are not available and it is not possible to create a new plan from PPM Express with this connection type.
The following permissions are required:
- Tasks.Read
- Team.ReadBasic
- All Channel.ReadBasic
- All ChannelMessage.Send
Where Admin Consent is granted
Admin Consent should be granted to PPM Express application before adding your first Planner or Office 365 connection. This can be done while configuring connections in PPM Express. Please refer to this article on how to import your first project from Planner and the process of adding your first connection.
Alternatively, it is possible to grant consent to PPM Express Office 365 Sync app in Azure Enterprise Apps (Azure portal -> Enterprise App-> PPM Express). If you cannot find the app in Azure Enterprise Apps, use this URL replacing the {tenant-id} with your tenant ID:
https://login.microsoftonline.com/{tenant-id}/adminconsent?client_id=c5ad89ea-1cd6-406e-81c9-4480a9854172 (the grant consent window will be opened at once).
It is necessary to grant admin consent for both the PPM Express apps:
- PPM Express Sign-In
- PPM Express Office 365 Sync.
Requirements for Microsoft Planner account used for connection (Connection Account)
When Admin Consent is granted to PPM Express app, you can add a connection with any Office 365 account within the same tenant that meets the following requirements:
- Has access to read existing Planner plans. Required permissions are listed here.
- Has access to create new Planner plans. Required permissions are listed here.
- Has access to read users list. Required permissions are listed here.
- Has access to manage groups membership. Required permissions are listed here.
- Has any type of Office 365 license.
It is recommended that all plans synchronized to PPM Express are shared with the Connection Account. When the plan is shared with the Connection Account this plan is added to the API and thus can be synchronized to PPM Express. For this purpose Connection Account should open each plan that needs to be synchronized at least once.
It is also possible to share the plan while linking PPM Express project and Planner plan if the Connection Account is a member of the plan but has not opened it yet. For this purpose in the Configure Connections window click on the 'Select plan's group' link and select a Group first. Then select a Plan you would like to link your PPM Express project to.
Data that PPM Express can connect to when the connection with Admin consent is established
When the connection is established between PPM Express and Office 365 Planner, PPM Express will get the following permissions:
- Read data from Plans in Microsoft Office 365 Planner that are accessible by a Connection Account (read permissions);
- Create Plans in PPM Express and connect Plans to a plan group in Microsoft Office 365 Planner (write permissions);
- Read data Office 365 groups that are accessible by a Connection Account;
- Create new Office 365 groups.
In Office 365 Planner, when you create a plan, an Office 365 group is created to support your plan. In the same way, PPM Express gets “read” or “write” permissions to your Office 365 groups depending on whether you connect already existing plans or create new plans in PPM Express.
Please note that PPM Express will be able to access and allow you to import ONLY the Plans that are accessible by Office 365 Account used for connection. If Office 365 Account used for connection does not have access to some Plans in your Office 365 environment, this Plan will NOT be available for Projects import in PPM Express.
Data that PPM Express users can have access to when the connection with Admin consent is established
When data from Planner plan is synchronized to PPM Express project, PPM Express users can review the data synchronized from Planner, according to their permissions set in the People Management section by PPM Express Administrator.
Data synchronized from Planner to PPM Express cannot be edited within PPM Express, it is available for viewing only.
How many Planner connections can we add to PPM Express?
The number of Connection Accounts is not limited in PPM Express. It depends on how you would like to manage connections. But in order not to be confused with Connections and the Plans they have access to we recommend using one Connection Account that has access to all Plans that might be synchronized with PPM Express.
Recommendations
PPM Express uses the minimum permissions required for the application to work correctly with Planner connection. We do not recommend removing any of the permissions required as it will greatly affect PPM Express functionality in the projects connected to Planner.
Office 365 Global Admin account can be used only for providing Admin Consent which is obligatory application permission. As soon as Microsoft provides the ability to add new permissions for groups and teams that users can consent to, PPM Express will promptly adjust account requirements on our side.
As a Connection Account, you can either use somebody’s personal Office 365 account (e.g. account of your Project Manager/Portfolio Manager/ PMO) or create a separate service account. The account used for connection should match the requirements listed in this article.
If you have any additional questions, please contact us at support@ppm.express to request the FAQ Document for Connection Account Requirements for Microsoft Planner.