One common question I run into is the “description” of a group object. Because of some… inconsistencies between “legacy” Exchange schema and the Graph, people seem to have trouble understanding how to update the description of a group object within Microsoft 365. In an attempt to address this, Microsoft has introduced a new parameter for Set-Group and (some, but not all) related cmdlets. Let’s see what this brings…
The story so far
One can argue that things were actually quite simple in the “old” Exchange way. Relevant object types (groups in our scenario) had the Notes property, exposed both in the UI and via PowerShell, which was used to enter a free-form description. Notes is a string property, although it does accept multi-line input (not the same thing as being multi-valued property, but more on that later). The screenshot below illustrates how this looks like for a “traditional” distribution list object in the “classic” EAC (actually, a mail-enabled security group, but same story):
Once Office 365 Groups were introduced, the lines between ExODS and Azure AD started blurring. After all, we had an object that is authored in Azure AD, yet behaves both like a mailbox and a distribution group. One could create such a group within the Azure AD portal or via the Graph API, and give it a “description” therein. However, no matching “description” property existed in ExODS, thus the value is mapped to the Notes property instead. So whereas the UI bits in “classic” EAC will show a Description, the actual property used in ExODS is still Notes, as illustrated below:
Get-UnifiedGroup firstgroup_471b526b-a084-46c0-a649-986c4e2cb89d | select Name,Notes Name Notes ---- ----- firstgroup_471b526b-a084-46c0-a649-986c4e2cb89d First group Get-Group firstgroup_471b526b-a084-46c0-a649-986c4e2cb89d | select Name,Notes Name Notes ---- ----- firstgroup_471b526b-a084-46c0-a649-986c4e2cb89d First group
OK, so instead of Notes, the UI showed a Description, big deal. You were encouraged to manage such objects from the Office 365 Admin center and the underlying APIs anyway, where the property does have the Description moniker. As things progressed however, the same approach started to apply to other group object types, and not necessarily ones that Azure AD was the source of truth for. The shiny Microsoft 365 Admin Center and the Modern EAC both showcase the Description field, even for objects such as “traditional” Distribution groups or Mail-enabled security groups, for which the underlying property is still the Notes one, and is still authored within ExODS. Thus the confusion that some users experience when having to update a “description” for a given object.
One last example to illustrate where this confusion stems from. Consider the same group object we looked at in the first screenshot, but now displayed within the Microsoft 365 Admin Center. As noted above, you can expect to see a Description property therein, yet the value of the Notes property is surfaced, much like the behavior with Microsoft 365 Group objects. However, the mail-enabled security group object we’re currently looking at is authored in ExODS!
Exchange Online gets a Description parameter
OK, so we now understand what’s a bit confusing about this experience. The good news is, it looks like Microsoft is trying to address this, by means of introducing a Description property, and the corresponding parameter, for (some) group objects. The corresponding commit to the documentation is dated early March, although the change itself has likely been around longer. Effectively, we now have two parameters basically serving the same purpose, but still treated a bit differently. As an example, you can run the Set-Group cmdlet with both –Notes and –Description parameters, and provide different values:
Set-Group DG -Description "aaaa" -Notes "bbbb"
Get-Group DG | select Name,Description,Notes
Name Description Notes
---- ----------- -----
DG {aaaa} bbbb
Let’s see how the corresponding changes are reflected in the UI. The “classic” EAC continues to use the Notes value, as shown on the first screenshot below, so no changes therein. If you try to find the Description property and its value anywhere in the classic EAC UI, you will be disappointed. On the other hand, the new EAC is happy to display the exact opposite behavior – only the Description value is surfaced, with Notes sent to oblivion:
And the Microsoft 365 Admin Center shows the exact same behavior as the new EAC, with only the Description property exposed:
One can of course make the argument that the M365 Admin center doesn’t particularly care about Exchange objects and their attributes, and there is some truth to this. Instead, it uses the representation of the object within Azure AD, which in turn has its own schema. Graph, being the prime method to query Azure AD objects nowadays, reveals:
OK, so I think by now is clear that those two attributes are different. In their attempt to unify the experience and alleviate confusion, Microsoft is moving in a direction where the Description property is given a preference over the Notes one, even for Exchange-authored objects. The expected behavior is to always use the Description property going forward. If you have objects for which the Description property is not populated, but the Notes property is supported and has a non-null value, you can expect to see it represented in the UI instead. To better visualize the expected behavior, consider the output below and compare it to the screenshots above:
Updating Group’s description
Enough illustrating! Let’s now talk about the cmdlets/parameters and how updates to the Description property are handled in the UI. Buckle up, as things are about to go wild…
As mentioned already, a handful of Exchange Online cmdlets now feature a –Description parameter. Most notably, the Set-Group cmdlet, which was traditionally used to update the –Notes property. In addition, the New-DistributionGroup/Set-DistributionGroup cmdlet also feature the –Description parameter, but only the New-DistributionGroup cmdlet supports the –Notes one. Interestingly, the set of *-UnifiedGroup cmdlets do not support –Description, and only leverage the –Notes parameter. We will see how this becomes an issue in a bit.
In turn, most Get– group cmdlets now return a Description property in the output. Lastly, the set of *-DynamicDistributionGroup cmdlets also do not have support for –Description parameter. While it’s a shame that not all cmdlets support –Description, in general we can use the all-encompassing Set-Group cmdlet as a workaround. Said cmdlet can be used to update both the Notes and Description properties of all Group object types, apart from Dynamic DGs. And yes, this also includes Microsoft 365 Groups, for example:
Set-Group new_1716eb09-ea49-4549-a979-0d14ba61b222 -Description aaa -Notes bbb
Get-UnifiedGroup new_1716eb09-ea49-4549-a979-0d14ba61b222 | select Name,Description,Notes
Name Description Notes
---- ----------- -----
new_1716eb09-ea49-4549-a979-0d14ba61b222 {aaa} bbb
Unfortunately, this is where the good news stop, at least when Microsoft 365 Group object are concerned (the example above). While Exchange Online will happily accept the new values for both the Notes and Description properties, no immediate “signal” is sent to the Graph. Thus, looking at corresponding object properties in the modern EAC, Microsoft 365 AC or Graph API, you will not see the change reflected. At least not until the once-a-day backup sync process is triggered, I suppose? So far, my tests seem to indicate that even after a day the change is not picked up, which is quite a red flag.
Luckily, updates to other group types are processed as expected. Things start to go downhill once you try to update the Description property via the UI though. As we established above, both the modern EAC and M365 AC will display the Description value, and fallback to surfacing the Notes value if Description is null. One would expect the corresponding property to be updated if you make a change via the UI, but the observed behavior is wildly erratic.
Let’s start with a simple example, a Distribution group with null values for both Description/Notes. Performing the update via the M365 AC results in a “substrate” call to ExODS to update the Description value for the corresponding object. So far so good, and more or less what we can expect, given that Description is given preference within the UI. The resulting change can quickly be confirmed on Exchange side via PowerShell:
Get-Group bhmyu | fl Name,Description,NotesName : bhmyu
Description : {NOT
NULL}
Notes :
And yes, there is a newline between “NOT” and “NULL”, as I took the opportunity to also test how multi-line strings are handled. Interestingly, the Graph explorer fails to visualize them and shows the value as “NOTNULL”, whereas the EAC/M365 AC correctly represent it. The audit log trail correctly represents the value as “NOT\nNULL” too, so we’re all good. Here’s also the “substrate” execution of the Set-Group cmdlet, as taken from the audit log:
(Search-UnifiedAuditLog -EndDate (Get-Date) -StartDate (Get-Date).AddDays(-1) -Operations Set-Group -ObjectIds bhmyu).AuditData | ConvertFrom-Json
CreationTime : 2022-09-28T10:07:12
Operation : Set-Group
UserType : 2
Workload : Exchange
ClientIP : [2603:1020:800:2::45]:11578
ObjectId : bhmyu
UserId : vasil@michev.info
AppId : 00000006-0000-0ff1-ce00-000000000000
Parameters : {@{Name=Identity; Value=EURPR03A001.prod.outlook.com/Microsoft Exchange Hosted Organizations/michev.onmicrosoft.com/bhmyu}, @{Name=BypassSecurityGroupManagerCheck;
Value=True}, @{Name=Description; Value=NOT
NULL}}
We’re not as good when it comes to other scenarios though. Let us now perform the same operation, but this time against a Microsoft 365 Group object. We again start from the M365 AC, and enter some value for the Description field therein. Again, the audit trail reveals that the Description property is being updated, this time by making a direct Graph call. Yet, when we take a look at the corresponding object within ExODS, it’s the Notes property that’s being updated instead:
Get-UnifiedGroup abuse | select Name,Description,Notes
Name Description Notes
---- ----------- -----
abuse_18744c33-db33-421a-817f-7f9f016057e9 {} 11111
The same happens when you perform the operation via the modern EAC. I suppose we can agree that this is the “expected” behavior, as M365 Groups are authored in Azure AD, so changes are written therein first, and a “signal” is sent to ExODS to synchronize the changes. So even though M365 Group objects within ExODS now feature a Description property, the changes are written only to the Notes one, likely for backwards compatibility reasons. Or at least that’s the best excuse I can come up with. And it goes against my initial expectations of “unified” experience across all group types.
But wait, it gets weirder! Let us now try the exact same thing, but this time with an Microsoft 365 Group that already has a Description value populated. In fact, let’s use the “First group” we already showcased above, and stamp a Description on it:
Set-Group firstgroup_471b526b-a084-46c0-a649-986c4e2cb89d -Description "Second group"
Get-Group firstgroup_471b526b-a084-46c0-a649-986c4e2cb89d | select Name,Description,Notes
Name Description Notes
---- ----------- -----
firstgroup_471b526b-a084-46c0-a649-986c4e2cb89d {Second group} First group
Checking the group’s properties via the UI still shows the Notes value, as the change is not immediately pushed to Azure AD, if at all. Now, if you try to update the value from the UI, you will be presented with the following error message:
Note the wording of the error! Looking at the audit trail, you will find a “failure” event corresponding to this operation, with an indication that an attempt was made to update the Description property. However, since we have already set a value for it via Exchange Online PowerShell, it looks like this now results in a conflict. And what’s more interesting, the error message above suggests that ExODS is now the authoritative source?! Go figure!
Just to make sure this is not an isolated instance, I reproduced the issue with another Microsoft 365 Group. The experience was exactly the same, giving us a strong indication that using the –Description parameter against Microsoft 365 Group objects is something you’d likely want to avoid for now. On the other hand, Distribution group objects that have both the Description and Notes values populated seem to be updated just fine from either the UI or PowerShell.
Some additional notes
A side note. With or without the oddities of Microsoft 365 Groups, both the modern EAC and M365 AC UIs suffer from the long-known and mildly irritating issue of Graph wrappers not being able to null-ify a value of a string parameter. In the case of the Description parameter, both UIs will happily show you an “Changes saved” success message, while in reality no actual change is made and the original Description value is preserved. In all fairness though, this is a widespread issue across multiple admin interfaces, so we cannot blame it on Groups only.
Another interesting observation is that the Description property seems to be implemented not as System.String, but instead as Deserialized.Microsoft.Exchange.Data.MultiValuedProperty object, hinting that it accepts multiple entries. You might also have noticed the curly brackets around its value in the output example above. As expected though, this is not really the case, and trying to add multiple values will always result in an error:
Yet, over at Azure AD side, the change actually succeeds, as evident from the audit log entry:
CreationTime : 2022-09-28T14:39:23
Operation : Update group.
RecordType : 8
ResultStatus : Success
UserType : 4
Workload : AzureActiveDirectory
ObjectId : Group_9e629d33-d655-440c-89af-15738e59e667
UserId : ServicePrincipal_addc2e3e-7486-4761-8a3c-8d0f28e530e6
ModifiedProperties : {@{Name=Description; NewValue=[
"test;test2"
]; OldValue=[
"test"
]}, @{Name=Included Updated Properties; NewValue=Description; OldValue=}, @{Name=TargetId.GroupType; NewValue=; OldValue=}}
Actor : {@{ID=Microsoft Substrate Management; Type=1}, @{ID=98db8bd6-0cc0-4e67-9de5-f187f1cd1b41; Type=2}, @{ID=ServicePrincipal_addc2e3e-7486-4761-8a3c-8d0f28e530e6;
Type=2}, @{ID=addc2e3e-7486-4761-8a3c-8d0f28e530e6; Type=2}, @{ID=ServicePrincipal; Type=2}}
Target : {@{ID=Group_9e629d33-d655-440c-89af-15738e59e667; Type=2}, @{ID=9e629d33-d655-440c-89af-15738e59e667; Type=2}, @{ID=Group; Type=2}, @{ID=USG; Type=1}}
So after a while, the writeback process kicks in and ExODS also gets the updated value, as shown with the last line on the screenshot above. To top it off, it simply concatenates the input to a semicolon-separated string, in yet another overlooked detail of the implementation…
Now, with all the findings above, I am a bit reluctant to share this small bit of code. The idea here was that we can use this short one-liner to populate the Description value across all supported object types, based on the current value of the Notes property. In doing so, one could then put the Notes property to rest and start working with Description, going forward. Alas, I’m afraid at this point doing so will likely create more issues than it will solve. So keep the below handy for such a time where all the issues have been fleshed out!
Get-Group -Filter {Notes -ne $null} | ? {$_.RecipientTypeDetails -ne "RoleGroup" -and (!$_.Description -or ($_.Description -ne $_.Notes))}  | % { Set-Group $_.Name -Description $_.Notes }
If you do decide to use this, do yourself a favor and exclude Microsoft 365 Group objects!
In summary
The takeaway from this article is that Microsoft introduced the –Description parameter a while back, and said parameter is now available for Set-Group, Set-DistributionGroup and New-DistributionGroup cmdlets. Since the “modern” UI bits have long ago started using Description even when the corresponding attribute value was taken from the Notes property, my hopes were that some unification effort has been made here. Some tests quickly reveal a number of issues with the current implementation, at least when it comes to Microsoft 365 Group objects, opening more questions than it answers and doubling the confusion. So for the time being, be informed that the –Description parameter is a thing, but be careful when using it!