Walkthrough for AIP labelByCustomProperties Advanced Feature

Published May 24 2021 12:00 PM 1,421 Views

In the Information Protection world there are several technologies customers could choose to deploy. Ultimately, decisions will also be made to migrate away from them to other vendor products. When this happens, customers generally want to maintain a mapping from the older labels to newer labels, ensuring that they can easily apply new labels without the need for additional manual work.


This document will walk through how to leverage the labelByCustomProperties advanced feature for the cmdlet Set-Label included in the Security and Compliance PowerShell. This will enable us to create a mapping from one label to another, and is useful for use cases of moving from another labeling technology to Sensitivity labels, Secure Islands to Sensitivity labels, Sensitivity labels in Commercial tenants to Sensitivity labels in GCCH tenant, and much more.


Please keep in mind that the mapping is limited to labeling only, meaning that protection capabilities cannot be maintained during this mapping. There is also a potential for performance issues regarding its use with labeled emails.


  1. Connect to the Security and Compliance Center (SCC) PowerShell. This enables you to leverage many of the advanced settings for sensitivity labeling. Ensure that the Module ExchangeOnlineManagement is installed. You can either use Windows PowerShell in admin mode and run the following command:





Install-Module -Name ExchangeOnlineManagement






Or https://www.powershellgallery.com/packages/ExchangeOnlineManagement/2.0.5 to manually download the module and then use it. After doing this, go ahead and import the module using the following command:





Import-Module ExchangeOnlineManagement






2. Connect to the PowerShell for your organization. You can specifically use this for organizations in Commercial M365 and M365 GCC:





Connect-IPPSSession -UserPrincipalName navin@contoso.com






Make sure to change the UPN that is tailored for your use case. For other endpoints such as GCCH organizations and more see here


3. Now you will be able to use the advanced settings by leveraging the SCC PowerShell. We will start by demonstrating one mapping of an AIP label in tenant A to an AIP label in tenant B. The example is demonstrated below:



Set-Label -Identity YOURTENANTBLABELNAME -AdvancedSettings @{labelByCustomProperties="description of rule,MSIP_Label_fc45349f-e0b8-4318-8dac-6a12a9c611fd_Enabled,true"}  



The advanced setting key is defined as labelByCustomProperties and the value is entered using the following format:


“Description of rule, Label Property, metadata”


To unpack the example some more, we start by using Set-Label as the command to set up the mapping of one label to another. To create more mappings, you create more instances of this Set-Label command.


For the -Identity parameter, you want to input what the resulting label name should be. I.e. if you were taking a document in Tenant A with “x” label and wanted it to display “y” label in Tenant B, you would want to input “y” for the -Identity parameter.


The -AdvancedSettings parameter has the key and value described earlier but let’s break down the value format further. For “Description of rule” you can input any string that would help you describe the mapping. For “Label Property” this would be the custom metadata property specific to our use case. In the example above we have an MSIP_Label that is indicative of the label from Tenant A which is “x”. Finally, we have the “metadata” and here we used “true” in the example to denote the scenario when this label metadata is present in Tenant B.


Thus, this label essentially allows us to go from one label in a tenant to another label in another tenant. There are other potential permutations of this, but we hope you understand how you can use this for your own use cases moving forward.

1 Comment
Version history
Last update:
‎May 24 2021 09:02 AM
Updated by: