Skip to main content

purview retentionevent add

Create a retention event

Usage​

m365 purview retentionevent add [options]

Options​

-n, --displayName <displayName>

The display name of the event.

-e, --eventTypeName [eventTypeName]

Name of the event type associated with the event. Specify either eventTypeId or eventTypeName but not both.

-i, --eventTypeId [eventTypeId]

Id of the event type associated with the event. Specify either eventTypeId or eventTypeName but not both.

-d, --description [description]

A description for the event.

--triggerDateTime [triggerDateTime]

Optional time when the event should be triggered.

-a, --assetIds [assetIds]

The Asset IDs for items in SharePoint and OneDrive that are related to this event. Only items that have labels associated with the event type you chose will be retained. Specify assetIds and/or keywords, but at least one.

-k, --keywords [keywords]

The keywords for items in Exchange that are related to this event. Only items that have labels associated with the event type you chose will be retained. Specify assetIds and/or keywords, but at least one.

-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 an API that is currently in preview and is subject to change once the API reached general availability.

Examples​

Create a retention event to start retention at the end of 2022 for all employee documents that have been labeled and have the Asset ID EmployeeNr1234.

m365 purview retentionevent add --displayName 'Employee information expiration' --description 'Employee documents expired due to offboarding' --eventTypeName 'CustomRetentionTime' --triggerDateTime '2022-12-31' --assetIds 'ComplianceAssetId:EmployeeNr1234'

Response​

{
  "displayName": "Event display name",
  "description": "Event description",
  "eventTriggerDateTime": "2023-04-02T15:47:54Z",
  "lastStatusUpdateDateTime": "0001-01-01T00:00:00Z",
  "createdDateTime": "2023-02-20T18:53:05Z",
  "lastModifiedDateTime": "2023-02-20T18:53:05Z",
  "id": "9f5c1a04-8f7a-4bff-e400-08db1373b324",
  "eventQueries": [
    {
      "queryType": "files",
      "query": "filesQuery,filesQuery1"
    },
    {
      "queryType": "messages",
      "query": "messagesQuery,messagesQuery1"
    }
  ],
  "eventStatus": {
    "error": null,
    "status": "pending"
  },
  "eventPropagationResults": [],
  "createdBy": {
    "user": {
      "id": null,
      "displayName": "John Doe"
    }
  },
  "lastModifiedBy": {
    "user": {
      "id": null,
      "displayName": "John Doe"
    }
  }
}

More information​

This command is part of a series of commands that have to do with event-based retention. Event-based retention is about starting a retention period when a specific event occurs, instead of the moment a document was labeled or created.

Read more on event-based retention here

CTRL + M