Batch configuration batch-configuration
Use the batch configuration options in Destination SDK to allow users to customize the exported file names and to configure the export schedule according to their preference.
When you create file-based destinations through Destination SDK, you can configure default file naming and export schedules, or you can give users the option to configure these settings from the Platform UI. For instance, you can configure behaviors such as:
- Including specific information in the file name, such as audience IDs, destination IDs, or custom information.
- Allowing users to customize the file naming from the Platform UI.
- Configure file exports to occur at set time intervals.
- Define what file naming and export schedule customization options the users can see in the Platform UI.
Batch configuration settings are part of the destination configuration for file-based destinations.
To understand where this component fits into an integration created with Destination SDK, see the diagram in the configuration options documentation or see the guide on how to use Destination SDK to configure a file-based destination.
You can configure the file naming and export schedule settings via the /authoring/destinations
endpoint. See the following API reference pages for detailed API call examples where you can configure the components shown in this page.
This article describes all the supported batch configuration options that you can use for your destination, and shows what customers will see in the Platform UI.
Supported integration types supported-integration-types
Refer to the table below for details on which types of integrations support the functionality described on this page.
Supported parameters supported-parameters
The values that you set up here are surfaced in the Schedule audience export step of the file-based destinations activation workflow.
"batchConfig":{
"allowMandatoryFieldSelection":true,
"allowDedupeKeyFieldSelection":true,
"defaultExportMode":"DAILY_FULL_EXPORT",
"allowedExportMode":[
"DAILY_FULL_EXPORT",
"FIRST_FULL_THEN_INCREMENTAL"
],
"allowedScheduleFrequency":[
"DAILY",
"EVERY_3_HOURS",
"EVERY_6_HOURS",
"EVERY_8_HOURS",
"EVERY_12_HOURS",
"ONCE"
],
"defaultFrequency":"DAILY",
"defaultStartTime":"00:00",
"filenameConfig":{
"allowedFilenameAppendOptions":[
"SEGMENT_NAME",
"DESTINATION_INSTANCE_ID",
"DESTINATION_INSTANCE_NAME",
"ORGANIZATION_NAME",
"SANDBOX_NAME",
"DATETIME",
"CUSTOM_TEXT"
],
"defaultFilenameAppendOptions":[
"DATETIME"
],
"defaultFilename":"%DESTINATION%_%SEGMENT_ID%"
},
"segmentGroupingEnabled": true
}
allowMandatoryFieldSelection
true
to allow customers to specify which profile attributes are mandatory. Default value is false
. See Mandatory attributes for more information.allowDedupeKeyFieldSelection
true
to allow customers to specify deduplication keys. Default value is false
. See Deduplication keys for more information.defaultExportMode
Defines the default file export mode. Supported values:
DAILY_FULL_EXPORT
FIRST_FULL_THEN_INCREMENTAL
Default value is DAILY_FULL_EXPORT
. See the batch activation documentation for details about file exports scheduling.
allowedExportModes
Defines the file export modes available to customers. Supported values:
DAILY_FULL_EXPORT
FIRST_FULL_THEN_INCREMENTAL
allowedScheduleFrequency
Defines the file export frequency available to customers. Supported values:
ONCE
EVERY_3_HOURS
EVERY_6_HOURS
EVERY_8_HOURS
EVERY_12_HOURS
DAILY
defaultFrequency
Defines the default file export frequency.Supported values:
ONCE
EVERY_3_HOURS
EVERY_6_HOURS
EVERY_8_HOURS
EVERY_12_HOURS
DAILY
Default value is DAILY
.
defaultStartTime
filenameConfig.allowedFilenameAppendOptions
Required. List of available file name macros for users to choose from. This determines which items are appended to exported file names (audience ID, organization name, date and time of export, and others). When setting defaultFilename
, make sure to avoid duplicating macros.
Supported values:
DESTINATION
SEGMENT_ID
SEGMENT_NAME
DESTINATION_INSTANCE_ID
DESTINATION_INSTANCE_NAME
ORGANIZATION_NAME
SANDBOX_NAME
DATETIME
CUSTOM_TEXT
Regardless of the order in which you define the macros, the Experience Platform UI will always display them in the order presented here.
If defaultFilename
is empty, the allowedFilenameAppendOptions
list must contain at least one macro.
filenameConfig.defaultFilenameAppendOptions
The macros in this list are a subset of the ones defined in
allowedFilenameAppendOptions
.filenameConfig.defaultFilename
Any macro defined by
allowedFilenameAppendOptions
will be appended after the defaultFilename
macros.If
defaultFilename
is empty, you must define at least one macro in allowedFilenameAppendOptions
.segmentGroupingEnabled
Defines whether the activated audiences should be exported in a single file or multiple files, based on audience merge policy. Supported values:
true
: exports one file per merge policy.false
: exports one file per audience, regardless of the merge policy. This is the default behavior. You can achieve the same result by ommitting this paramter entirely.
File name configuration file-name-configuration
Use file name configuration macros to define what the exported file names should include. The macros in the table below describe elements found in the UI in the file name configuration screen.
SEGMENT_ID
macro in your exported file names. Segment IDs are unique, so including them in the file name is the best way to ensure that file names are unique as well.DESTINATION
SEGMENT_ID
SEGMENT_NAME
DESTINATION_INSTANCE_ID
DESTINATION_INSTANCE_NAME
ORGANIZATION_NAME
SANDBOX_NAME
DATETIME
/ TIMESTAMP
DATETIME
and TIMESTAMP
both define when the file was generated, but in different formats.
DATETIME
uses the following format: YYYYMMDD_HHMMSS.TIMESTAMP
uses the 10-digit Unix format.
DATETIME
and TIMESTAMP
are mutually exclusive, and cannot be used simultaneously.
DATETIME
: 20220509_210543TIMESTAMP
: 1652131584
CUSTOM_TEXT
defaultFilename
.TIMESTAMP
MERGE_POLICY_ID
segmentGroupingEnabled:true
.MERGE_POLICY_NAME
segmentGroupingEnabled:true
.File name configuration example
The configuration example below shows the correspondence between the configuration used in the API call and the options shown in the UI.
"filenameConfig":{
"allowedFilenameAppendOptions":[
"CUSTOM_TEXT",
"SEGMENT_ID",
"DATETIME"
],
"defaultFilenameAppendOptions":[
"SEGMENT_ID",
"DATETIME"
],
"defaultFilename": "%DESTINATION%"
}
Next steps next-steps
After reading this article, you should have a better understanding of how you can configure file naming and export schedules for your file-based destinations.
To learn more about the other destination components, see the following articles: