Skip to main content

purview retentionlabel add

Create a retention label

Usage

m365 purview retentionlabel add [options]

Options

-n, --displayName <displayName>

The display name of the 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. Defaults to dateLabeled.

--defaultRecordBehavior [defaultRecordBehavior]

Specifies the locked or unlocked state of a record label when it is created. Allowed values: startLocked, startUnlocked, Defaults to startLocked.

--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.

--eventTypeId [eventTypeId]

The Id of the event type that is used to in case of an event-based label. Specify when using retentionTrigger with the value dateOfEvent. Specify either eventTypeId or eventTypeName, but not both.

--eventTypeName [eventTypeName]

The display name of the event type that is used to in case of an event-based label. Specify when using retentionTrigger with the value dateOfEvent. Specify either eventTypeId or eventTypeName, but not both.

-h, --help [help]

Output usage information. Optionally, specify which section of command's help you want to see. Allowed values are options, examples, remarks, response, full. Default is options.

--query [query]

JMESPath query string. See http://jmespath.org/ for more information and examples.

-o, --output [output]

Output type. json, text, csv, md, none. Default json.

--verbose

Runs command with verbose logging.

--debug

Runs command with debug logging.

Remarks

warning

This command is based on a Microsoft Graph API that is currently in preview and is subject to change once the API reached general availability.

Examples

Create a retention label that retains documents and deletes them after one year.

m365 purview retentionlabel add --displayName 'some label' --behaviorDuringRetentionPeriod retain --actionAfterRetentionPeriod delete --retentionDuration 365

Create a retention label that retains documents as records and does not take any action one year after the last modification date.

m365 purview retentionlabel add --displayName 'some label' --behaviorDuringRetentionPeriod retainAsRecord --actionAfterRetentionPeriod none --retentionDuration 365 --retentionTrigger dateModified

Create an event-based retention label that retains documents as records and deletes them one year after a Contract Expiry event date.

m365 purview retentionlabel add --displayName 'some label' --behaviorDuringRetentionPeriod retain --actionAfterRetentionPeriod delete --retentionDuration 365 --retentionTrigger dateOfEvent --eventTypeName "Contract Expiry"

Response

{
"displayName": "some label",
"descriptionForAdmins": "Description for admins",
"descriptionForUsers": "Description for users",
"isInUse": false,
"retentionTrigger": "dateLabeled",
"behaviorDuringRetentionPeriod": "retain",
"actionAfterRetentionPeriod": "delete",
"createdDateTime": "2022-12-21T09:28:37Z",
"lastModifiedDateTime": "2022-12-21T09:28:37Z",
"labelToBeApplied": "another label",
"defaultRecordBehavior": "startLocked",
"id": "f7e05955-210b-4a8e-a5de-3c64cfa6d9be",
"retentionDuration": {
"days": 365
},
"createdBy": {
"user": {
"id": null,
"displayName": "John Doe"
}
},
"lastModifiedBy": {
"user": {
"id": null,
"displayName": "John Doe"
}
},
"dispositionReviewStages": []
}

More information

CTRL + M