microsoft
Potential breaking changes in Graph PowerShell SDK due to change/rename of tags
The following tags are missing from the latest metadata for PowerShell.
users.Actions
users.Functions
deviceManagement.Functions
deviceManagement.Actions.
This means that if you try to slice the metadata using the above tags, the service will respond with a 404. e.g. https://devxapi-func-prod-eastus.azurewebsites.net/$openapi?tags=^users.Functions$&title=Users.Functions&openapiversion=3&style=Powershell&fileName=powershell_v2&graphVersion=v1.0&singularizeOperationIds=true.
Therefore, some paths that were assigned those tags, currently have new tags and this would potentially introduce breaking changes in the SDK.
Below is an example of before and after for one of the paths.
Before
After
The change will occur in terms of grouping of paths. e.g. Paths that used to appear under Users. Actions module are now appearing under Calendar module.
@timayabi2020 this change was occasioned by this PR:https://github.com/microsoft/OpenAPI.NET.OData/pull/586 necessitated by this PowerShell issue: https://github.com/microsoftgraph/msgraph-sdk-powershell/issues/2957 and duplicated OData issue: https://github.com/microsoft/OpenAPI.NET.OData/issues/585 as per your request.
You gave the example of the below tag:
...that needed to be updated to
solutions.backupRestoreRoot
If this isn't what is anticipated, shall we revert the change and resume the old naming convention of {navigationSource}.Functions and {navigationSource}.Actions ?
@timayabi2020 @irvinesunday @Ndiritu
To recap our earlier discussion,
Context
At the moment, Powershell has two modules Bookings and BackupRestore that are separate but would ideally reference paths that are both under the root path segment /solutions. Before the PR at https://github.com/microsoft/OpenAPI.NET.OData/pull/586, all function/actions under a root path would have the same tag (i.esolutions.Actions) so the slicing for paths using tags did not allow for the Action/Function paths for Bookings and BackupRestore separated(so that they can exist in separate modules). What ended up happening is all the functions/actions are placed in the Bookings module.
Current State The change in https://github.com/microsoft/OpenAPI.NET.OData/pull/586 solved this problem, but created another problem in that Powershell still needs the functions/actions separated for some other modules according to the mappings here. https://github.com/microsoftgraph/msgraph-sdk-powershell/blob/dceff1f4232c7bab6e579d2c5db0257ab9626f3b/config/ModulesMapping.jsonc#L42
This also creates another problem in that paths that existed in Users.Actions and Users.Functions are now moving into other documents as their tags are now matching other modules. A good example is the odata Action like CreateUploadSession now moves to the Calendar/Drive module due to the updated tagging. (Generating cmdlet with this would obviously be a breaking change). Furthermore, trying to contain the paths manually or with workarounds would still bring more work down the road with reviewing new paths added to the metadata.
On top of this this surfaced another bug with duplicate operation ids showing up due to the slicing logic which is outlined at https://github.com/microsoftgraph/microsoft-graph-devx-api/issues/2255
Option 1
We can update the changes made in https://github.com/microsoft/OpenAPI.NET.OData/pull/586 to also include a suffix in the Tag(i.e. .Actions or .Functions) so that the actions/function for Bookings would look like solutions.Bookings.*.Actions and for BackupRestore would look like solutions.BackupRestore*.Actions(note the wild card characters).
This would
- enable the powershell mappings to be updated to target the paths more precisely to fix the incorrect mappings.
- enable the user functions/actions to still remain in their current modules by targeting operationIds like
user.*.Actions(note the wildcard character) - enable omission/exclusion of actions/functions using a negated match of the tags like
user.*.Actions
Option 2 (I just realized this later, so I'm putting this here so that you may share thoughts on this too)
Given that tags are a collection/array in openApi, we could potentially add both tags to the operation(previous state of tags plus current state of tags).
This means an action/function in Bookings would have both the solutions.Actions and solutions.Bookings and by applying set theory, you could either include/exclude paths matching specific tags. This would however need testing and validation with the current slicing implementation in devX api.
I believe the way forward from the discussion is for
- @irvinesunday to implement changes in library for option 1
- @timayabi2020 to validate if the changes work with updated mappings
- We deprioritize https://github.com/microsoftgraph/microsoft-graph-devx-api/issues/2255 unless the updated mappings lead to the duplicate operation ids.
Lemme know if anything is missed from this.
