--- title: "Exchange Agent 2023.03.27 - What's Changed" slug: "exchange-agent-20230327-whats-changed" description: "Describes the updates made to the 2023.03.27 version of the RapidIdentity Exchange Agent to accomodate Microsoft's deprecation of serveral PowerShell modules and the associated configuration changes required. " tags: ["What's New", "Administrator", "Exchange Agent", "Microsoft Graph"] updated: 2023-03-30T18:05:40Z published: 2023-03-30T18:05:40Z canonical: "help.rapididentity.com/exchange-agent-20230327-whats-changed" --- > ## Documentation Index > Fetch the complete documentation index at: https://help.rapididentity.com/llms.txt > Use this file to discover all available pages before exploring further. # Exchange Agent 2023.03.27 - What's Changed ## Exchange Agent 2023.03.27 Updates and Impacts The RapidIdentity Exchange Agent has been updated to accommodate Microsoft's impending PowerShell deprecations. > *Click [here](/v1/docs/microsoft-powershell-deprecations) for more information regarding Microsoft's PowerShell deprecations.* *Click [here](/v1/docs/installing-exchange-agent-20230327) for instructions to update the RapidIdentity Exchange Agent to the 2023.03.27 version.* This update changes several Actions in the RapidIdentity Connect Office365 Adapter. **Note:** Several RapidIdentity Connect Office365 Adapter Actions reference the deprecated MSOL service in their names; these Actions have been updated to use the Microsoft Graph API instead. As a result, the following updates are **required.** ### User Actions #### saveOffice365MsolUser - Creates or updates a user - This action previously used Microsoft Online [New-MsolUser](https://learn.microsoft.com/en-us/powershell/module/msonline/new-msoluser?view=azureadps-1.0) to create users and that is replaced by Microsoft Graph [New-MgUser](https://learn.microsoft.com/en-us/powershell/module/microsoft.graph.users/new-mguser?view=graph-powershell-1.0&preserve-view=true) - This action previously used Microsoft Online [Set-MsolUser](https://learn.microsoft.com/en-us/powershell/module/msonline/set-msoluser?view=azureadps-1.0) to update users and that is replaced by Microsoft Graph [Update-MgUser](https://learn.microsoft.com/en-us/powershell/module/microsoft.graph.users/update-mguser?view=graph-powershell-1.0&preserve-view=true) - Creating a user now requires the following fields: - AccountEnabled - This is a new field in Microsoft Graph. The Exchange Agent will set the “AccountEnabled” field to “true” if not specified. - MailNickname - This is a new field in Microsoft Graph. The Exchange Agent will set the “MailNickname” field to the “DisplayName” value if it is not specified. - Password - If you create users without a password, you will need to update your Connect logic to supply a random password. Microsoft Online would automatically generate a random password when creating users without “Password” specified, but this is not the case with Microsoft Graph. - Special consideration should be taken when updating the “DisplayName” for a user (i.e. may also want to consider updating “MailNickname”). - See bullet point above regarding “MailNickname” not being specified on user create --- #### Some User fields have changed names. The Exchange Agent will automatically update the following fields when creating and updating a user: - “FirstName” will be “GivenName” - “LastName” is now “Surname” - “Fax” is now “FaxNumber" - “Office” is now “OfficeLocation” #### License Changes - The “AddLicenses” field will no longer accept an “AccountSkuId”. It will now accept either “SkuId” or “SkuPartNumber”. - The “RemoveLicenses” field will no longer accept an “AccountSkuId”. It will now accept either “SkuId” or “SkuPartNumber” - “SkuPartNumber” can be extracted from “AccountSkuId”. - Given “AccountSkuId=tp01n:DEVELOPERPACK_E5”, “SkuPartNumber=DEVELOPERPACK_E5” (i.e. everything after the colon in “AccountSkuId”). - The “LicenseOptions” field will no longer accept an “AccountSkuId” in its JSON objects. Instead, it will accept “SkuId” or “SkuPartNumber”. - “LicenseOptions” are used for disabling specific plans within a license (e.g. “[{“SkuId”:”SkuId1”,”DisabledPlans”:[“YAMMER_ENTERPRISE”]}]”) #### getOffice365MsolUsers - Retrieves a list of users with optional max results and filter - This action previously used Microsoft Online [Get-MsolUser](https://learn.microsoft.com/en-us/powershell/module/msonline/get-msoluser?view=azureadps-1.0) to retrieve users and that is replaced by Microsoft Graph [Get-MgUser](https://learn.microsoft.com/en-us/powershell/module/microsoft.graph.users/get-mguser?view=graph-powershell-1.0&preserve-view=true) - Filter changes - Careful consideration should be taken when updating Connect action sets utilizing the optional filter parameter. Microsoft provides [documentation](https://learn.microsoft.com/en-us/graph/filter-query-parameter?tabs=powershell) for using filters. An example filter object passed to getOffice365MsolUsers would be: ``` Old Way ------- filter = createRecord(true) setRecordFieldValue(filter, 'SearchString', 'Mi') New Way ------- filter = createRecord(true) setRecordFieldValue(filter, 'Filter', 'startsWith(DisplayName, "Mi")') ``` #### getOffice365MsolUser - Retrieves a specific user by unique identifier - This action previously used Microsoft Online [Get-MsolUser](https://learn.microsoft.com/en-us/powershell/module/msonline/get-msoluser?view=azureadps-1.0) to retrieve users and that is replaced by Microsoft Graph [Get-MgUser](https://learn.microsoft.com/en-us/powershell/module/microsoft.graph.users/get-mguser?view=graph-powershell-1.0&preserve-view=true) - The “Identity”/”UserPrincipalName” field was used as the unique identifier for Microsoft Online, but the “Id” field is used by Microsoft Graph. The Exchange Agent will automatically handle this change when retrieving a specific user (i.e. A user can be found by providing either “UserPrincipalName” or “Id”). - The “Identity” field will no longer be returned on the user objects. If the value is needed in Connect logic, utilize “UserPrincipalName” or “Id” instead. - The “Id” field is now returned by user objects and should be used to reference users #### deleteOffice365MsolUser - Deletes a specific user by unique identifier - This action previously used Microsoft Online [Remove-MsolUser](https://learn.microsoft.com/en-us/powershell/module/msonline/remove-msoluser?view=azureadps-1.0) to delete users and that is replaced by Microsoft Graph [Remove-MgUser](https://learn.microsoft.com/en-us/powershell/module/microsoft.graph.users/remove-mguser?view=graph-powershell-1.0&preserve-view=true) - The “Identity”/”UserPrincipalName” field was used as the unique identifier for Microsoft Online, but the “Id” field is used by Microsoft Graph. The Exchange Agent will automatically handle this change when deleting a specific user (i.e. A user can be deleted by providing either “UserPrincipalName” or “Id”). ### Groups #### saveOffice365MsolGroup - Creates or updates a user - This action previously used Microsoft Online [New-MsolGroup](https://learn.microsoft.com/en-us/powershell/module/msonline/new-msolgroup?view=azureadps-1.0) to create groups and that is replaced by Microsoft Graph [New-MgGroup](https://learn.microsoft.com/en-us/powershell/module/microsoft.graph.groups/new-mggroup?view=graph-powershell-1.0&preserve-view=true) - This action previously used Microsoft Online [Set-MsolGroup](https://learn.microsoft.com/en-us/powershell/module/msonline/set-msolgroup?view=azureadps-1.0) to update groups and that is replaced by Microsoft Graph [Update-MgGroup](https://learn.microsoft.com/en-us/powershell/module/microsoft.graph.groups/update-mggroup?view=graph-powershell-1.0&preserve-view=true) - Creating a group now requires the following fields: - DisplayName - It’s unlikely that groups were being created without the “DisplayName” field, but it was not required with Microsoft Online and is required by Microsoft Graph - MailNickname - This is a new field in Microsoft Graph. The Exchange Agent will set the “MailNickname” field to the “DisplayName” value if it is not specified. - MailEnabled - This is a new field in Microsoft Graph. The Exchange Agent will set the “MailEnabled” field to “false” if not specified. - SecurityEnabled - This is a new field in Microsoft Graph. The Exchange Agent will set the “MailEnabled” field to “true” if not specified. - Special consideration should be taken when updating the “DisplayName” for a group (i.e. may also want to consider updating “MailNickname”). - See bullet point above regarding “MailNickname” not being specified on group create #### getOffice365MsolGroups - Retrieves a list of groups with optional max results and filter - This action previously used Microsoft Online [Get-MsolGroup](https://learn.microsoft.com/en-us/powershell/module/msonline/get-msolgroup?view=azureadps-1.0) to retrieve groups and that is replaced by Microsoft Graph [Get-MgGroup](https://learn.microsoft.com/en-us/powershell/module/microsoft.graph.groups/get-mggroup?view=graph-powershell-1.0&preserve-view=true) - The “Identity” field will no longer be returned on the group objects. If the value is needed in Connect logic, utilize “DisplayName” or “Id” instead. - The “Id” field is now returned by group objects and should be used to reference groups - Filter changes - Careful consideration should be taken when updating Connect action sets utilizing the optional filter parameter. Microsoft provides [documentation](https://learn.microsoft.com/en-us/graph/filter-query-parameter?tabs=powershell) for using filters. An example filter object passed to getOffice365MsolGroups would be: ``` Old Way ------- filter = createRecord(true) setRecordFieldValue(filter, 'SearchString', 'Administrator') New Way ------- filter = createRecord(true) setRecordFieldValue(filter, 'Filter', 'DisplayName eq Administrator') ``` #### getOffice365MsolGroup - Retrieves a specific group by unique identifier - This action previously used Microsoft Online [Get-MsolGroup](https://learn.microsoft.com/en-us/powershell/module/msonline/get-msolgroup?view=azureadps-1.0) to retrieve groups and that is replaced by Microsoft Graph [Get-MgGroup](https://learn.microsoft.com/en-us/powershell/module/microsoft.graph.groups/get-mggroup?view=graph-powershell-1.0&preserve-view=true) - The “Identity”/”DisplayName” field was used as the unique identifier for Microsoft Online, but the “Id” field is used by Microsoft Graph. The Exchange Agent will automatically handle this change when retrieving a specific group (i.e. A group can be found by providing either “DisplayName” or “Id”). - The “Identity” field will no longer be returned on the group objects. If the value is needed in Connect logic, utilize “DisplayName” or “Id” instead. - The “Id” field is now returned by group objects and should be used to reference groups #### deleteOffice365MsolGroup - Deletes a specific group by unique identifier - This action previously used Microsoft Online [Remove-MsolGroup](https://learn.microsoft.com/en-us/powershell/module/msonline/remove-msolgroup?view=azureadps-1.0) to delete groups and that is replaced by Microsoft Graph [Remove-MgGroup](https://learn.microsoft.com/en-us/powershell/module/microsoft.graph.groups/remove-mggroup?view=graph-powershell-1.0) - The “Identity”/”DisplayName” field was used as the unique identifier for Microsoft Online, but the “Id” field is used by Microsoft Graph. The Exchange Agent will automatically handle this change when deleting a specific group (i.e. A group can be deleted by providing either “DisplayName” or “Id”). #### addOffice365MsolGroupMember - Adds a specific user as a member of a specific group - This action previously used Microsoft Online [Add-MsolGroupMember](https://learn.microsoft.com/en-us/powershell/module/msonline/add-msolgroupmember?view=azureadps-1.0) to add group members and that is replaced by Microsoft Graph [New-MgGroupMember](https://learn.microsoft.com/en-us/powershell/module/microsoft.graph.groups/new-mggroupmember?view=graph-powershell-1.0&preserve-view=true) #### deleteOffice365MsolGroupMember - Removes a specific user as a member of a specific group - This action previously used Microsoft Online [Remove-MsolGroupMember](https://learn.microsoft.com/en-us/powershell/module/msonline/remove-msolgroupmember?view=azureadps-1.0) to remove group members and that is replaced by Microsoft Graph [Remove-MgGroupMemberByRef](https://learn.microsoft.com/en-us/powershell/module/microsoft.graph.groups/remove-mggroupmemberbyref?view=graph-powershell-1.0&preserve-view=true) ### Roles #### getOffice365MsolRoles - Retrieves a list of roles - This action previously used Microsoft Online [Get-MsolRole](https://learn.microsoft.com/en-us/powershell/module/msonline/get-msolrole?view=azureadps-1.0) to retrieve roles and that is replaced by Microsoft Graph [Get-MgDirectoryRole](https://learn.microsoft.com/en-us/powershell/module/microsoft.graph.identity.directorymanagement/get-mgdirectoryrole?view=graph-powershell-1.0&preserve-view=true) - You may find that not all roles returned from Get-MsolRole are returned by Get-MgDirectoryRole. If this is the case, look at the “Import MsolRoles to MgDirectoryRoles” section below. #### getOffice365MsolRole - Retrieves a specific role by unique identifier - This action previously used Microsoft Online [Get-MsolRole](https://learn.microsoft.com/en-us/powershell/module/msonline/get-msolrole?view=azureadps-1.0) to retrieve roles and that is replaced by Microsoft Graph [Get-MgDirectoryRole](https://learn.microsoft.com/en-us/powershell/module/microsoft.graph.identity.directorymanagement/get-mgdirectoryrole?view=graph-powershell-1.0&preserve-view=true) - You may find that not all roles returned from Get-MsolRole are returned by Get-MgDirectoryRole. If this is the case, look at the “Import MsolRoles to MgDirectoryRoles” section below. #### addOffice365MsolRoleMember - Adds a specific user as a member of a specific role - This action previously used Microsoft Online [Add-MsolRoleMember](https://learn.microsoft.com/en-us/powershell/module/msonline/add-msolrolemember?view=azureadps-1.0) to add role members and that is replaced by Microsoft Graph [New-MgDirectoryRoleMemberByRef](https://learn.microsoft.com/en-us/powershell/module/microsoft.graph.identity.directorymanagement/new-mgdirectoryrolememberbyref?view=graph-powershell-1.0&preserve-view=true) #### deleteOffice365MsolRoleMember - Removes a specific user as a member of a specific role - This action previously used Microsoft Online [Remove-MsolRoleMember](https://learn.microsoft.com/en-us/powershell/module/msonline/remove-msolgroupmember?view=azureadps-1.0) to remove role members and that is replaced by Microsoft Graph [Remove-MgDirectoryRoleMemberByRef](https://learn.microsoft.com/en-us/powershell/module/microsoft.graph.groups/remove-mggroupmemberbyref?view=graph-powershell-1.0&preserve-view=true) ### Import MsolRoles to MgDirectoryRoles This PowerShell script provides an example of how to import MSOL roles into Microsoft Graph. Run this in an Administrator PowerShell on the Windows machine where the Exchange Agent is installed with the appropriate credentials. ``` > $user = "admin_user@domain.onmicrosoft.com" > $password = ConvertTo-SecureString 'password123' -AsPlainText -Force > $basicCred = New-Object System.Management.Automation.PsCredential($user,$password) > Connect-MsolService -Credential $basicCred > $appId = "" > $tenantId = "" > $certThumbprint = "" > $certPath = 'Cert:\LocalMachine\My\' + $certThumbprint > $cert = Get-ChildItem -Path $certPath > Connect-MgGraph -ClientId $appId -TenantId $tenantId -Certificate $cert > Get-MsolRole | ForEach-Object { $template = (Get-MgDirectoryRoleTemplate -DirectoryRoleTemplateId $_.ObjectId) if ($template -ne $null) { $filter = "RoleTemplateId eq '" + $template.Id + "'" $role = Get-MgDirectoryRole -Filter $filter if ($role -eq $null) { New-MgDirectoryRole -RoleTemplateId $role.Id } } } ``` ## Related - [Installing Exchange Agent 2023.03.27](/installing-exchange-agent-20230327.md) - [Microsoft PowerShell Deprecations](/microsoft-powershell-deprecations.md)