Add-AipServiceTemplate
Creates a protection template for Azure Information Protection.
Syntax
Add-AipServiceTemplate
-Descriptions <Hashtable>
-Names <Hashtable>
[-RightsDefinitions <System.Collections.Generic.List`1[Microsoft.RightsManagementServices.Online.Admin.TemplateRightsDefinition]>]
[-ContentExpirationOption <ContentExpirationType>]
[-ContentExpirationDate <DateTime>]
[-ContentValidityDuration <Int32>]
[-LicenseValidityDuration <Int32>]
[-Status <TemplateStatus>]
[-ScopedIdentities <System.Collections.Generic.List`1[System.String]>]
[-EnableInLegacyApps <Boolean>]
[<CommonParameters>] Description
The Add-AipServiceTemplate cmdlet creates a protection template for Azure Information Protection with the specified name, description, and policy, and sets the status of the template to archived or published.
The same configuration actions can also be done in the Azure portal.
Important
Before you use this cmdlet, you must first create a rights definition object that specifies the rights that you want to grant and to whom, by using the New-AipServiceRightsDefinition cmdlet.
You can store a maximum of 500 custom templates (published or archived) in Azure. If you can't add new templates because you have reached this limit as a result of keeping many archived templates, consider exporting them to save the information locally and then removing these templates in Azure.
For more information about protection templates, including how to configure them in the Azure portal, see Configuring and managing templates for Azure Information Protection.
Using the Azure Information Protection unified labeling client?
The Azure Information Protection unified labeling client uses protection templates indirectly. If you have the unified labeling client, we recommend that you use label-based cmdlets instead of modifying your protection templates directly.
For more information, see Create and publish sensitivity labels in the Microsoft 365 documentation.
Examples
Example 1: Create a departmental template for confidential content
PS C:\> $names = @{}
PS C:\> $names[1033] = "New Launch - Confidential content"
PS C:\> $names[1034] = " Nuevo Lanzamiento - Contenido confidencial"
PS C:\> $descriptions = @{}
PS C:\> $descriptions[1033] = "This content is confidential for people working on the New Launch project and should not be shared externally"
PS C:\> $descriptions[1034] = "Este contenido es confidencial para empleados trabajando en el proyecto Nuevo Lanzamiento y no debe ser compartido fuera de la organización"
PS C:\> $r1 = New-AipServiceRightsDefinition -EmailAddress marketing@contoso.com -Rights "VIEW","EXPORT"
PS C:\> $r2 = New-AipServiceRightsDefinition -EmailAddress engineering@contoso.com -Rights "VIEW","DOCEDIT"
PS C:\> Add-AipServiceTemplate -Names $names -Descriptions $Descriptions -LicenseValidityDuration 5 -RightsDefinitions $r1, $r2 -ScopedIdentities engineering@contoso.com -Status PublishedThis example creates a departmental template for engineers when they are working on the New Launch project. The template is named New Launch - Confidential Content and has names and descriptions in English and in Spanish. It grants View and Export rights to the marketing department (lets them view and save to a non-protected file) by using the marketing@contoso.com group, and View and DocEdit rights (lets them view and edit the contents but not save the changes) to the engineering department by using the engineering@contoso.com group.
Parameters
-ContentExpirationDate
Specifies the date on which content protected with the template expires.
Use this parameter only if the ContentExpirationOption parameter is set to OnDate.
| Type: | DateTime |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ContentExpirationOption
Specifies the type of content expiration for content protected with the template.
The acceptable values for this parameter are:
Never. Indicates that content is available indefinitely.
OnDate. Indicates that content expires at a certain fixed date.
AfterDays. Indicates that content is available for the indicated number of days after it is protected.
| Type: | ContentExpirationType |
| Accepted values: | Never, OnDate, AfterDays |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ContentValidityDuration
Specifies the number of days from the first day of protection after which content protected with the template expires.
Use this parameter only if the ContentExpirationOption parameter is set to AfterDays.
| Type: | Int32 |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Descriptions
Specifies a list of descriptions for the template.
Create names and descriptions for multiple locale IDs by using the hash-table syntax in Windows PowerShell. There must be at least one name/description pair. The locale IDs for names and descriptions must match each other. If a locale ID is specified, its value must contain a non-empty string.
$descriptions = @{}
$descriptions[1033] = "This content is confidential and should not be shared externally"
$descriptions[1034] = "Este contenido es confidencial y no debe ser compartido fuera de la organización"
| Type: | Hashtable |
| Position: | Named |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-EnableInLegacyApps
Determines the behavior of a departmental template in applications that do not support departmental templates (see the ScopedIdentities parameter).
If set to True and the template is a departmental template, all users trying to protect content from an application that does not support departmental templates will see the template and therefore be able to select it, regardless of whether the users are members of the template's target scope or not.
If set to False, no users see and therefore cannot select the template in applications that do not support departmental templates, even if the users are members of the template's target scope.
This setting has no effect on templates that are not departmental templates and also has no effect on applications that natively support departmental templates.
Note: This parameter is functionally the equivalent of the Show this template to all users when the applications do not support user identity check box if you configured APPLICATION COMPATIBILITY in the Azure classic portal. The classic portal is now retired and there is no equivalent setting in the Azure portal.
The Azure Information Protection client supports departmental templates whereas Outlook on the web and Exchange ActiveSync are examples of applications that do not currently support departmental templates. For these Exchange applications (and all other applications that cannot support departmental templates), you must decide whether all users can select a departmental template from the list of available templates, or no users can select a departmental template from the list.
This setting does not affect whether a user can access content that is protected by a departmental template; it only affects the ability for a user to select the template itself.
If you have applications that do not support departmental templates by default, you can use a custom RMS template download script or other tools to deploy these templates to the local RMS client folder. Then, these applications will correctly display the departmental templates.
From a client computer that has downloaded all the templates, you can copy and then paste the template files to other computers.
| Type: | Boolean |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-LicenseValidityDuration
Specifies the validity period of use licenses for content that is protected with this template.
The value is specified as the number of days that content is available offline after a use license is acquired (0-9999). During this period users can re-open content they previously accessed without requiring an Internet network connection.
Reducing this value gives more control to document owners by helping ensure that content that has been revoked or for which the policy has changed cannot be accessed for too long after these changes.
Increasing this value gives more freedom to users to access the content without requiring an Internet network connection.
To specify unlimited access, use -1. To specify that a use license must be obtained each time the protected content is accessed and that content is available only with an Internet connection, specify 0.
Each organization has a maximum use license validity time, which is 30 days by default and can be configured by using the Set-AipServiceMaxUseLicenseValidityTime. The value that you specify for the LicenseValidityDuration parameter must be lower than that value.
When there are different values for the use license validity time, for example, one value for the tenant and one for the template, Azure Information Protection uses the most restrictive value.
| Type: | Int32 |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Names
Specifies a list of names for the template.
Do not include any of the following characters in the name because not all services and applications that use Azure Information Protection can support these characters: < > % & / ? ; + \ : #
Create names and descriptions for multiple locale IDs by using the hash-table syntax in Windows PowerShell. There must be at least one name/description pair.The locale IDs for names and descriptions must match each other. If a locale ID is specified, its value must contain a non-empty string.
$names = @{}
$names[1033] = "Confidential content"
$names[1034] = "Contenido confidencial"
| Type: | Hashtable |
| Position: | Named |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-RightsDefinitions
Specifies a list of rights definition objects that are specified by using the New-AipServiceRightsDefinition cmdlet.
These rights definition objects express the rights to grant individual users or groups to content that is protected by applying the template.
Rights definition objects contain the email address for the identity and the rights to assign to it.
| Type: | System.Collections.Generic.List`1[Microsoft.RightsManagementServices.Online.Admin.TemplateRightsDefinition] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ScopedIdentities
Lists the users by email address (account or group) that can see and therefore select departmental templates from applications.
For the specified users to see the templates, the application must support departmental templates or the EnableInLegacyApps parameter must be set to True.
| Type: | System.Collections.Generic.List`1[System.String] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Status
Specifies the status of the template.
Allowed values are Archived and Published.
Archived templates are available to consume previously protected content but are not visible to users.
Published templates are distributed to users and made available to protect content.
| Type: | TemplateStatus |
| Accepted values: | Archived, Published |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
Inputs
System.String[],System.String[],System.String[],System.string,System.DateTime,System.int,System.int
-Names $Names ; One or more names for the template, in various languages to present to users depending on their system locale.
[-Descriptions $Descriptions] ; One or more descriptions for the template, in various languages to present to users depending on their system locale.
[-RightsDefinitions {$r1,$r2,...}] ; A list of rights definitions in the form of Rights Definition objects.
[-ContentExpirationOption ContentExpirationType.Never|OnDate|AfterDays] ; The type of content expiration for content protected with the template.
[-ContentExpirationDate DateTime] ; The date or time when the content expires, if ContentExpirationOption is set to OnDate.
[-ContentValidityDuration int] ; The number of days for which content is available after it is protected if ContentExpirationOption is set to AfterDays.
[-LicenseValidityDuration int] ; The number of days for which content is available online until it expires (0-9999). To specify unlimited access, use -1. To specify that a license must be obtained for each use and that content is available only online, use 0.
[-Status TemplateStatus.Archived|Published] ; The status of the template. Archived templates are available to consume previously protected content but are not presented to users. Published templates are distributed to users and made available for protecting content.
Create names and descriptions for multiple locale IDs by using the hash-table syntax in Windows PowerShell. There must be at least one name/description pair. The locale IDs for names and descriptions must match each other. If a locale ID is specified, its value must contain a non-empty string.
$names = @{}
$names[1033] = "Confidential content"
$names[1034] = "Contenido confidencial"
$descriptions = @{}
$descriptions[1033] = "This content is confidential and should not be shared externally"
$descriptions[1034] = "Este contenido es confidencial y no debe ser compartido fuera de la organización"
The rights are specified as a list of rights definition objects that contain the email address for the identity and the rights to assign to it.