Register a purge interactions API task

Abstract

How to register interaction purge tasks with the xConnect purge Web API.

You can use the xConnect Web API to remove unwanted data from your interactions. To do this, you must register a data purge task.

To register a task:

  • Use the following API:

    <instance>/sitecore/api/datatools/purge/tasks/interactions

    The successful task registration request returns the task ID used for status monitoring, for example:

    {
        "TaskId": "1af9fddd-e7dd-49f1-b5a2-dae757f59fd4"
    }

Parameters

The following table describes the POST parameters that you can send to the Web API to register a purge task:

Important

Combined parameters act as an AND condition. So all the parameters sent to the API filter the data to purge.

Parameter

Optional

Default

Type

Description

BatchSize

Yes

100

Integer

The data extraction batch size of interactions.

The BatchSize system parameter controls the amount of data extracted from the collection database for each cursor read.

Important

Use a small batch size for the purging process to not overload the system too much, and so it can cancel tasks with less impact. Task cancellation is not an immediate process and does not cancel an ongoing batch.

DefaultSplitItemCount

Yes

100

Integer

The interactions data extraction cursor split count.

The DefaultSplitItemCount system parameter controls the split process of interaction data extraction.

ExpiresAfterHours

Yes

24

Integer

The expiration of the task in the final state.

The final task status is either successful or failed and removed from the system after the expiration period.

StartedDaysCutoff

No

-

Nullable Integer

Specifies the number of days since the interaction started. This parameter filters interactions based on its StartDateTime value. The StartDateTime reflects the interaction's starting DateTime.

The StartDateTime value must not violate the configuration setting value for the minimum number of days for the data purge worker. The minimum available value is 180 days by default (see Configure the Cortex Processing Engine for task registration).

StartPercentile

Yes

Null

Nullable Double

The start sampling range value. The range restriction is 0 to 1.

The percentile range specifies the subset of data to extract. Use this parameter to perform the purging in small batches to avoid stressing the system too much.

The data extraction process filters interactions based on the percentile range and the StartedDaysCutoff parameter.

EndPercentile

Yes

Null

Nullable Double

The end sampling range value. The range restriction is 0 to 1.

The percentile range specifies the subset of data to extract. Use this parameter to perform the purging in small batches to avoid stressing the system too much.

The data extraction process filters interactions based on the percentile range and the StartedDaysCutoff parameter.

Conditions

Yes

""

String

List of condition names. Multiple conditions run with the AND logical operator.

The Conditions parameters lets you specify custom condition keys used to identify interactions for purging. You must register custom conditions in the Cortex Processing Engine.

You delimit Conditions IDs with a comma.

The filtering with conditions is performed in-memory, not at the database level. If the interaction passes all the conditions, then the purging tool can purge the interaction.

DeleteIfHasEvents

Yes

{string[0]}

Array of strings

List of existing event names or GUIDs.

This parameter specifies an event list used to identify interactions for purging. The data extraction process filters interactions if it has at least one of the events.

You delimit events with a comma or space symbol.

SkipIfHasEvents

Yes

{string[0]}

Array of strings

List of existing event names or GUIDs.

This parameter specifies an event list used to identify interactions to skip deletion. Interactions remain if it has at least one of the provided events.

You delimit events with a comma or space symbol.

DeleteIfHasChannels

Yes

{string[0]}

Array of strings

List of existing channel names or GUIDs.

This parameter specifies a channel list used to identify interactions for purging. The data extraction process filters interactions if it has at least one of the channels.

You delimit channels with a comma or space symbol.

SkipIfHasChannels

Yes

{string[0]}

Array of strings

List of existing channel names or GUIDs.

This parameter specifies a channel list used to identify interactions to skip deletion. Interactions remain if it has at least one of the provided channels.

You delimit channels with a comma or space symbol.