Search <book_title>...

Enterprise Vault™ PowerShell Cmdlets

Last Published: 2019-02-06

Product(s): Enterprise Vault (12.4)

Set-EVRetentionPlan

Set-EVRetentionPlan sets or updates the properties of an existing retention plan, such as its description and associated retention category, classification policy, and retention folders.

If you change any of the retention plan settings, you must run the appropriate provisioning task or restart the appropriate archiving task to apply the changes to the target archives. For example, if you have associated the retention plan with the archive of an SMTP target, you must restart the SMTP Archiving task. In Exchange environments, you must restart the Exchange Mailbox Archiving task and also synchronize the mailboxes.

Set-EVRetentionPlan is provided by the snap-in Symantec.EnterpriseVault.PowerShell.AdminAPI.dll.

Syntax

Set-EVRetentionPlan -SiteId <String> -Name <String> [-Description <String>] [-RetentionCategory <String>] [-OverrideRetention [<SwitchParameter>]] [-ClassificationPolicy <String>] [-FolderXmlPath <String>] [-DisableStorageExpiry [<SwitchParameter>]] [<CommonParameters>]

Set-EVRetentionPlan -SiteId <String> -Name <String> [-Description <String>] [-RetentionCategory <String>] [-OverrideRetention [<SwitchParameter>]] [-ClassificationPolicy <String>] [-FolderXml <String>] [-DisableStorageExpiry [<SwitchParameter>]] [<CommonParameters>]

Parameters

Table: Set-EVRetentionPlan parameters

Parameter	Description
-SiteId (required)	The ID of the Enterprise Vault site for which to set or update the retention plan details. If you omit this parameter, and the cmdlet cannot determine the ID by looking in the registry, then Set-EVRetentionPlan prompts you to enter the required ID. You can use Get-EVSite to obtain the site ID.
-Name (required)	The name of a specific retention plan whose properties you want to set or update.
-Description	The description to set for the retention plan. The description can contain up to 127 alphanumeric, space, or special characters.
-RetentionCategory	The name of a retention category with which to associate the retention plan.
-OverrideRetention	Add this parameter to override the current retention categories of the affected items with the retention category associated with this plan. Note: Omit this parameter if you have also associated the plan with a classification policy that allows the classification rules to update the retention categories of items. In this case, Enterprise Vault expires the items according to the retention categories that the classification rules apply to them.
-ClassificationPolicy	The name of a classification policy with which to associate the retention plan. If specified, Enterprise Vault sends for classification all the archived items that have this retention plan and tags them according to the rules specified in the classification policy. Note: Classification operates in test mode if you have yet to install a license for the Enterprise Vault retention feature, or the existing license has expired. Instead of applying classification tags and other changes to the archived items, the classification feature generates a report that lists the planned changes.
-FolderXmlPath	The path to an XML file that defines the properties of one or more retention folders. You can create new retention folders and update or delete existing ones. For more information on retention folders and guidelines on how to prepare the required XML file, see the Administrator's Guide. Enterprise Vault comes with a sample XML file, `RetentionFoldersSample.xml`, which you can copy and modify as required. The file is in the `Modules\EnterpriseVault` subfolder of the Enterprise Vault installation folder (for example, `C:\Program Files (x86)\Enterprise Vault\Modules\EnterpriseVault`). If you have associated this retention plan with a classification policy that allows the classification feature to update the retention categories of individual items, the retention folders must have an Expiry setting of Item (not Folder). Type an absolute, relative, or UNC path, and enclose it in quotation marks if it contains space characters.
-FolderXml	This parameter performs the same function as the -FolderXmlPath parameter. However, in this case you define the retention folder properties in an XML string that you append to the parameter, instead of defining them in an external file. You can create new retention folders and update or delete existing ones. Use a backtick character (') to escape the quotation marks in this string.
-DisableStorageExpiry	Add this parameter to disable Storage Expiry in any archive that has retention folder issues.

Examples

Set-EVRetentionPlan -SiteId 13E...localdomain.com -Name "Projects Retention Plan" -Description "Plan created for managing projects" -RetentionCategory "5 years"
Updates the properties of an existing retention plan, "Projects Retention Plan", in the specified Enterprise Vault site. The plan has the description "Plan created for managing projects" and the retention category "5 years".
Set-EVRetentionPlan -Name "Projects Retention Plan" -ClassificationPolicy CP
Updates the classification policy property of the specified retention plan.
Set-EVRetentionPlan -Name "Projects Retention Plan" -ClassificationPolicy CP -OverrideRetention
Sets the override retention flag for the specified retention plan. When items are manually deleted or automatically expired, the retention category that you have set with the plan overrides their current retention categories. However, if the classification policy allows classification to update the retention categories of individual items, it is necessary to omit the -OverrideRetention parameter. Enterprise Vault expires the items according to the retention categories that the classification rules apply to them.
Set-EVRetentionPlan -SiteId 13E9...localdomain.com -Name "Projects Retention Plan" -Description "Plan updated for managing projects" -RetentionCategory "6 years" -OverrideRetention -ClassificationPolicy CP2
Updates the properties of an existing retention plan that is named "Projects Retention Plan" in the specified Enterprise Vault site. The plan has the description "Plan updated for managing projects" and the retention category "6 years".
Set-EVRetentionPlan -SiteId 13E...localdomain.com -Name "Projects Retention Plan" -ClassificationPolicy ''
Removes the previously-applied classification policy so that classification no longer occurs.

Set-EVRetentionPlan -Name "Projects Retention Plan" -FolderXmlPath c:\RetentionFolders.xml -DisableStorageExpiry

Applies the retention folder changes that are defined in the file c:\RetentionFolders.xml to the retention plan "Projects Retention Plan". The command also disables Storage Expiry in any archive that has retention folder issues.

For example, suppose that you originally defined the retention folder settings with the following XML:

<?xml version="1.0" encoding="utf-16"?>
<RetentionFolderRoot>
  <RetentionFolder Name="Inbox" RetentionCategory="1 Year"
    Expiry="Item" Inheritance="ThisFolderOnly" />
  <RetentionFolder Name="Business" RetentionCategory="5 Years"
    Expiry="Item" Inheritance="ThisFolderOnly" />
</RetentionFolderRoot>

To delete the "Inbox" folder, change the retention category for the "Business" folder to "1 Year", and create a new folder "Unit" as a subfolder of the "Business" folder, save the following as c:\RetentionFolders.xml and then submit it with the above command:

<?xml version="1.0" encoding="utf-16"?>
<RetentionFolderRoot>
  <RetentionFolder Name="Business" RetentionCategory="1 Year"
    Expiry="Item" Inheritance="ThisFolderOnly">
    <RetentionFolder Name="Unit" RetentionCategory="5 Years"
      Expiry="Item" Inheritance="ThisFolderAndAllSubfolders" />
  </RetentionFolder>
</RetentionFolderRoot>

You can use the following command to return the retention folder information for the plan:

Get-EVRetentionPlan -Name "New Projects Plan" | select -expand Folders | sort FolderPath | ft -AutoSize

This command produces the following output:

FolderPath       FolderName   RetentionCategory   Expiry                Inheritance
----------       ----------   -----------------   ------                -----------
\Business        Business     1 year              Item               ThisFolderOnly
\Business\Unit   Unit         5 years             Item   ThisFolderAndAllSubfolders

Set-EVRetentionPlan -Name "Projects Retention Plan" -FolderXml "<?xml version='"1.0'" encoding='"utf-16'"?><RetentionFolderRoot><RetentionFolder Name='"Business'" RetentionCategory='"1 Year'" Expiry='"Item'" Inheritance='"ThisFolderOnly'"><RetentionFolder Name='"Unit'" RetentionCategory='"5 Years'" Expiry='"Item'" Inheritance='"ThisFolderAndAllSubfolders'" /></RetentionFolder></RetentionFolderRoot>" -DisableStorageExpiry
Performs the same function as the command in the preceding example. However, the retention folder changes are now defined in the XML string that is appended to the command instead of being defined in an XML file.
Set-EVRetentionPlan -Name "New Projects Plan" -FolderXmlPath C:\RetentionFolders.xml
Applies the retention folder changes that are defined in the file c:\RetentionFolders.xml to the retention plan "Projects Retention Plan". You can use this command to supply alternative names in other languages for the retention folders that you have previously created. For example, suppose that you originally defined the retention folder settings with the following XML:
```
<?xml version="1.0" encoding="utf-16"?>
<RetentionFolderRoot>
	<RetentionFolder Name="Business" RetentionCategory="1 Year"
		Expiry="Item" Inheritance="ThisFolderOnly" />
	<RetentionFolder Name="Unit" RetentionCategory="5 Years"
		Expiry="Item" Inheritance="ThisFolderOnly" />
</RetentionFolderRoot>
```
By saving the following as C:\RetentionFolders.xml and then submitting it with the above command, you can supply alternative folder names for your Danish users:
```
<?xml version="1.0" encoding="utf-16"?>
<RetentionFolderRoot>
  <Languages>
    <Language>DA-DK</Language>
  </Languages>
  <RetentionFolder Name="Business" RetentionCategory="1 Year"
    Expiry="Item" Inheritance="ThisFolderOnly">
    <Name lang="DA-DK">Forretning</Name>
  </RetentionFolder>
  <RetentionFolder Name="Unit" RetentionCategory="5 Years"
    Expiry="Item" Inheritance="ThisFolderOnly">
    <Name lang="DA-DK">Enhed</Name>
  </RetentionFolder>
</RetentionFolderRoot>
```
The <Languages> node specifies the languages in which you want to supply the alternative folder names ("DA-DK" for Danish in this example). Within each <RetentionFolder> node, you can then enter the alternative folder names ("Forretning" for "Business" and "Enhed" for "Unit").
See the Administrator's Guide for more information on supplying alternative names of retention folders in multiple languages.

Output

Table: Set-EVRetentionPlan properties lists the properties that are available.

Table: Set-EVRetentionPlan properties

Name	Type	Description
Name	String	The name of the retention plan.
Description	String	The description of the retention plan.
RetentionCategory	String	The name of the retention category that is associated with the retention plan.
OverrideRetention	SwitchParameter	Whether you have specified the override retention flag for this retention plan.
ClassificationPolicy	String	The name of a classification policy with which the retention plan is associated.
HasFolders	Boolean	Whether the retention plan defines any retention folders. If true, the Folders and FolderXml properties contain information about the retention folders. The Folders property contains the information as tabulated text, which you can format using Format-Table. The FolderXml property contains the information as XML, which you can output to a file.
DisableStorageExpiry	SwitchParameter	Whether you have chosen to disable Storage Expiry in any archive that has retention folder issues.

Related cmdlets