Usage
m365 purview retentionlabel set [options]
Description
Update a retention label
Options
| Option |
Description |
-i, --id <id> |
The Id of the retention label. |
--behaviorDuringRetentionPeriod [behaviorDuringRetentionPeriod] |
Specifies how the behavior of a document with this label should be during the retention period. Allowed values: doNotRetain, retain, retainAsRecord, retainAsRegulatoryRecord. |
--actionAfterRetentionPeriod [actionAfterRetentionPeriod] |
Specifies the action to take on a document with this label applied after the retention period. Allowed values: none, delete, startDispositionReview. |
--retentionDuration [retentionDuration] |
The number of days to retain the content. |
-t, --retentionTrigger [retentionTrigger] |
Specifies whether the retention duration is calculated from the content creation date, labeled date, or last modification date. Allowed values: dateLabeled, dateCreated, dateModified, dateOfEvent. |
--defaultRecordBehavior [defaultRecordBehavior] |
Specifies the locked or unlocked state of a record label when it is created. Allowed values: startLocked, startUnlocked. |
--descriptionForUsers [descriptionForUsers] |
The label information for the user |
--descriptionForAdmins [descriptionForAdmins] |
The label information for the admin |
--labelToBeApplied [labelToBeApplied] |
Specifies the replacement label to be applied automatically after the retention period of the current label ends. |
Examples
Update a retention label so that it retains documents as records and deletes them after one year.
m365 purview retentionlabel set --id c37d695e-d581-4ae9-82a0-9364eba4291e --behaviorDuringRetentionPeriod retainAsRecord --actionAfterRetentionPeriod delete --retentionDuration 365
Update a retention label so that it retains documents as regulatory records and starts a disposition review one year after the last modification date.
m365 purview retentionlabel set --id c37d695e-d581-4ae9-82a0-9364eba4291e --behaviorDuringRetentionPeriod retainAsRegulatoryRecord --actionAfterRetentionPeriod startDispositionReview --retentionDuration 365 --retentionTrigger dateModified
Additional Info
The following Graph endpoint can be used:
https://graph.microsoft.com/beta/security/labels/retentionLabels/{id}
More information
Further points of interest:
- The documentation mentions
isInUse, createdBy, createdDateTime, lastModifiedBy and lastModifiedDateTime options. But these can not actually be used. I've submitted an issue to fix the graph documentation on that score.
- The documentation mentions
unknownFutureValue as a possible value for the options retentionTrigger, actionAfterRetentionPeriod, defaultRecordBehavior and behaviorDuringRetentionPeriod. As these are obvious placeholders, I've excluded them here.
labelToBeApplied can probably contain an empty string if not used.- I've excluded
dispositionReviewStages from the option list as the setup for this is as of yet unclear.
- I initially had added a
displayName option to get the retentionlabel by name, but $filter is not implemented as of yet, so I removed it again. I did keep the --newDisplayName named like that, so we can easily add displayName without a breaking change when $filter is supported.
Beta notice
The Graph endpoint that's used is in beta, so we should add a beta notice to the docs.
Azure AD
The command will need the Scope RecordsManagement.ReadWrite.All.
Usage
m365 purview retentionlabel set [options]
Description
Update a retention label
Options
-i, --id <id>--behaviorDuringRetentionPeriod [behaviorDuringRetentionPeriod]doNotRetain,retain,retainAsRecord,retainAsRegulatoryRecord.--actionAfterRetentionPeriod [actionAfterRetentionPeriod]none,delete,startDispositionReview.--retentionDuration [retentionDuration]-t, --retentionTrigger [retentionTrigger]dateLabeled,dateCreated,dateModified,dateOfEvent.--defaultRecordBehavior [defaultRecordBehavior]startLocked,startUnlocked.--descriptionForUsers [descriptionForUsers]--descriptionForAdmins [descriptionForAdmins]--labelToBeApplied [labelToBeApplied]Examples
Update a retention label so that it retains documents as records and deletes them after one year.
m365 purview retentionlabel set --id c37d695e-d581-4ae9-82a0-9364eba4291e --behaviorDuringRetentionPeriod retainAsRecord --actionAfterRetentionPeriod delete --retentionDuration 365Update a retention label so that it retains documents as regulatory records and starts a disposition review one year after the last modification date.
m365 purview retentionlabel set --id c37d695e-d581-4ae9-82a0-9364eba4291e --behaviorDuringRetentionPeriod retainAsRegulatoryRecord --actionAfterRetentionPeriod startDispositionReview --retentionDuration 365 --retentionTrigger dateModifiedAdditional Info
The following Graph endpoint can be used:
https://graph.microsoft.com/beta/security/labels/retentionLabels/{id}
More information
Further points of interest:
isInUse,createdBy,createdDateTime,lastModifiedByandlastModifiedDateTimeoptions. But these can not actually be used. I've submitted an issue to fix the graph documentation on that score.unknownFutureValueas a possible value for the optionsretentionTrigger,actionAfterRetentionPeriod,defaultRecordBehaviorandbehaviorDuringRetentionPeriod. As these are obvious placeholders, I've excluded them here.labelToBeAppliedcan probably contain an empty string if not used.dispositionReviewStagesfrom the option list as the setup for this is as of yet unclear.displayNameoption to get the retentionlabel by name, but$filteris not implemented as of yet, so I removed it again. I did keep the--newDisplayNamenamed like that, so we can easily adddisplayNamewithout a breaking change when$filteris supported.Beta notice
The Graph endpoint that's used is in beta, so we should add a beta notice to the docs.
Azure AD
The command will need the Scope
RecordsManagement.ReadWrite.All.