Page tree
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 6 Next »

Interaction Studio supports ingesting promotions into the catalog to leverage for both rules based & ML driven cross channel decisioning. In order to update or add an asset to an existing promotion, ALL data about the promotion must be included in the ETL even if the values are not changing. When the ETL runs, it will replace any existing data with the data in the ETL file. Files should be sorted by promotion Id. Interaction Studio provides the ability to sort the file in the gear configuration screen if needed. Promotions are configured on the Catalog Setup screen where you can connect related catalog objects and custom attributes to the promotion.

This Article Explains

This article details the requirements and schema of the promotion ETL and provides a sample file structure and download.

Sections in this Article

Requirements and Schema

  • Prior to uploading a promotion ETL, confirm that promotions are enabled in your catalog set-up and that the appropriate related catalog objects & attributes are applied to that promotion (related catalog objects and attributes can be added to a promotion from this same catalog set-up screen in the same way that you would apply custom attributes/related catalog objects to a product, blog, or article)
    • NOTE: If you try to pass in data associated to a related catalog object or attribute that is NOT configured, the data will not be applied/stored against the promotion. Attributes & related catalog objects MUST be configured in advance of loading data.
  • As mentioned in the overview, files should be sorted by promotion Id. File sorting can be performed either prior to delivery to Interaction Studio (client responsibility) or sorting can be enabled for the Promotion ETL in the Gear Configuration screen by marking the Promotion ETL Sort Before Grouping option. If the file is not sorted (either upon delivery or by enabling sorting) then the data will fail to load. The file must be sorted and resubmitted to be processed properly.
  • To add multiple assets to a single promotion, simply include multiple lines with the same promotion id. Each line item requires ALL promotion information, not just the asset details.
    • Example: If a promotion has 3 assets associated to it, you will need to copy the promotion information on 3 rows in the ETL file. The only information that will differ between rows is the asset information
  • If you are updating a promotion (eligibility criteria, description, URL, etc.) you must include ALL values associated to that promotion even if not every value is changing.
    • NOTE: If you are not sure of the promotion id for an existing promotion, simply navigate to the promotion list screen, hover over one of the column headers and click the three-dots icon, hover over the columns option, and check-off the ID box to add the column to the display
  • When constructing your promotion ETL file, it is important to note that if you include a column header in your file, any current values associated to a promotion being updated will be replaced by the contents of the file. If a column row is left blank for a promotion, any current values associated to that promotion that map to the blank row will be deleted. If you do not wish to update or edit an existing promotion value, make sure the column header for that attribute or related catalog object is not included in your feed file.
  • If you are updating a promotion (eligibility criteria, description, URL, etc.) that has multiple assets associated, you must include a line-item for each asset that includes that same update. A Promotion's assets are fully replaced with each ETL run, meaning only the assets in the most recent file will exist on the promotion.


File Format

File Name Format: promotion-YYYY-MM-DD_HH-MM-SS.csv

Requirements and Schema

See the Sample File section below for further clarification.


IMPORTANT NOTE

If you want a promotion to be eligible to appear on the web via the Einstein Decisions Global template, you must include an asset with a contentZone/tag that matches one of the web content zones defined in your sitemap.


Field Name

Minimum Requirements

Example Values

Max Length

Interaction Studio Data Type

Required Fields



idRequired. Promotion Ids are unique identifiers for a promotion. If a promotion already exists with the id of a promotion provided in an ETL file, it will be updated with the information included in the ETL. offer12345255String
attribute:nameRequired. Represents the name of the promotion and must contain at least one alphanumeric character.Winter Savings, Big Savings Event1023String
attribute:urlRequired. RFC-3986 Complete URLs that represent the destination to send the user upon click.https://www.northerntrailoutfitters.com/default/shoes1023String
asset:imageUrlRequired. Fully-qualified URL for an assets image. You can only have ONE asset image link per row in the ETL. If you are associating multiple assets to a single promotion, you will need to have multiple rows for that promotion. On each row, you will need to include ALL information pertinent to that promotion with the only difference between the rows being the data related to the assets.https://www.northerntrailoutfitters.com/dw/image/v2/BDPX_PRD/on/demandware.static/-/Library-Sites-NTO-SFRASharedLibrary/default/dw3984b9da/images/category/footwear-category-1680-400.jpg1023String
asset:contentZones

Required. Content Zones & Tags are eligibility filters applied to an asset that is stored against a promotion. A single asset can have multiple content zones or tags and these are referenced in a campaign to help filter what assets are allowed to be returned in a campaign response. Multiple Content Zones and tags can be added via a bar separated list. 

You ARE NOT allowed to have duplicate content zones or tags on multiple assets that are tied to a single promotion (For example: if one promotion has two associated assets, they cannot share a common content zone or tag. They must be unique across those two assets).

Content Zones and Tags ARE ALLOWED to be duplicated across promotions. (For example: If you have two promotions that each have one associated asset, they can both have the same content zone or tag)

Homepage Hero|Winter Savings|Spring Sale|Back to School1023String
Additional Fields



attribute:publishedOptional. ISO 8601 Date time string for promotion validity start date. The promotion will only be considered "valid" to show to a user between published and expiration dates. If just a published date is provided, a promotion will become eligible to return in a campaign response on that date and remain eligible from that point forward. If no dates are provided (published or expiration) a promotion will be considered evergreen and will always count as an active promotion for campaign response consideration. All dates are stored in UTC time only.

2020-10-15

2020-01-09T11:24:59Z

1023Date
attribute:expirationOptional. ISO 8601 Date time string for promotion validity end date. The promotion will only be considered "valid" to show to a user between published and expiration dates. If only an expiration date is provided, the promotion will become inactive after that date and no longer be eligible to be shown in a campaign response. If no dates are provided (published or expiration) a promotion will be considered evergreen and will always count as an active promotion for campaign response consideration. All dates are stored in UTC time only.

2020-10-15

2020-01-09T11:24:59Z

1023Date
attribute:descriptionOptional. Represents the description of the promotion and must contain at least one alphanumeric character.Great savings are here!

attribute:

Optional. The custom attributes for the promotion. Column titles are the word 'attribute', followed by a colon, followed by the attribute name as configured in the Attributes section of the Catalog Setup > Promotion screen. Attributes are parsed as the data type they are defined as in Attributes.

Supported promotion attributes include string, boolean, date & integer attributes.

attribute:loyaltyTier, attribute:offerType

1023any (string, integer, boolean, date)
relatedCatalogObject:Optional. Additional related catalog objects such as brands, countries, destinations, properties, etc. may be defined and imported with matching column names. Each related catalog object name must match the name of a catalog object type configured in Interaction Studio Catalog Setup. Column titles are the word 'relatedCatalogObject', followed by a colon, followed by the catalog object type name. A promotion can have multiple related catalog objects in separate columns and/or multiple values for the same related catalog object, separated by the pipe character (assuming the related catalog object cardinality on the promotion catalog object type set-up screen is set to "many per item" as opposed to "one per item"). A literal pipe in one of the values is represented as two pipe characters in the feed.

relatedCatalogObject:brand → Nike|Adidas|Reebok

relatedCatalogObject:destination → America

relatedCatalogObject:properties → Hotel1|Hotel2|Hotel3


Related Catalog Objects & Dimensions

For customers leveraging a promotion ETL configured prior to 9/7/2021 that uses "dimension:" instead of the new "relatedCatalogObject:" column header, this ETL configuration will continue to function as is. The "dimension:" column header will update the Related Catalog Object fields on the promotion. No changes to the ETL file are required. It is recommended that any new file leverage the updated nomenclature.

255String
userMatchAttribute:[userAttributeName]

Optional. Promotion eligibility criteria based on exact matches to user attributes can be passed in via the promotion ETL. The user attribute MUST already exist in the system for the eligibility criteria to be applied to the promotion. A promotion can have multiple user attribute match criteria. Multiple criteria are added through multiple columns. To correctly format the column header, simply write userMatchAttribute, followed by a colon, followed by the name of the user attribute.

To correctly format the input for a user attribute, simply follow this structure: true/false (space) bar separated list. If true leads the statement, a user MUST have an attribute that matches at least one of the values in the subsequent bar separated list in order to be eligible to receive the promotion in a campaign response. If false leads the statement, a user CANNOT have a user attribute that matches at least one of the values in the subsequent bar separated list in order to qualify to receive the promotion in a campaign response.

userMatchAttribute:loyaltyTier → true 1|2|3

userMatchAttribute:MobileAppDownload → false Y

userMatchAttribute:Company → false Salesforce|Tableau|Slack

1023any (string, integer, boolean, date)
exclusionSegments

Optional. Promotion eligibility criteria based on segment exclusion logic. 

The segment id's (not segment names) entered must already exist within the platform. If multiple segment id's are being entered, they should entered as a bar separated list.

If a user is a member of ANY of the segments listed in the segment exclusion criteria, they will not be eligible to see the offer.

exclusionSegments → goXqo|ybkWF|MfYFa


NOTE: To find a segmentId, simply navigate to the segment list screen in the Interaction Studio UI and select the desired segment (do not double-click into the segment detail screen). Once your segment is highlighted, look at the URL for the segmentId= parameter. This will be followed by a string of 5 characters (If you are leveraging a segment brought in from Salesforce CDP, it will start with a c360 prefix and then be followed by a 15 digit ID). This string is the Id for the segment and is what you should leverage in the ETL. The Id's are case sensitive, so should be copy/pasted exactly as listed.

1023String
inclusionSegments

Optional. Promotion eligibility criteria based on segment inclusion logic.

The segment id's (not segment names) entered must already exist within the platform. If multiple segment id's are being entered, they should entered as a bar separated list.

A user needs to be a member of ALL of the segments listed as part of the segment inclusion criteria in order to be eligible to receive the promotion.

NOTE: If a user is a member of segments used in both the inclusion and exclusion criteria, the exclusion logic will take priority and the user will NOT be eligible to receive the promotion.

inclusionSegments → YqO7X|U5t0V|HToYr


NOTE: To find a segmentId, simply navigate to the segment list screen in the Interaction Studio UI and select the desired segment (do not double-click into the segment detail screen). Once your segment is highlighted, look at the URL for the segmentId= parameter. This will be followed by a string of 5 characters (If you are leveraging a segment brought in from Salesforce CDP, it will start with a c360 prefix and then be followed by a 15 digit ID). This string is the Id for the segment and is what you should leverage in the ETL. The Id's are case sensitive, so should be copy/pasted exactly as listed.

1023String

  

Sample File


id

attribute:name

attribute:url

attribute:description

attribute:published

attribute:expiration

asset:contentZones

asset:imageUrl

relatedCatalogObject:brand

userMatchAttribute:loyaltyTier

offer100120% Off Shoeshttps://www.northerntrailoutfitters.com/default/shoes20% offer on shoes2020-10-152021-04-15HomeHeroDesktophttps://www.northerntrailoutfitters.com/dw/image/v2/BDPX_PRD/on/demandware.static/-/Library-Sites-NTO-SFRASharedLibrary/default/dw3984b9da/images/category/footwear-category-1680-400.jpg

offer100120% Off Shoeshttps://www.northerntrailoutfitters.com/default/shoes20% offer on shoes2020-10-152021-04-15HomeHeroMobilehttps://www.northerntrailoutfitters.com/dw/image/v2/BDPX_PRD/on/demandware.static/-/Library-Sites-NTO-SFRASharedLibrary/default/dw9de36c8e/images/category/footwear-subcategory-men-200-200.png

offer1002Nutrition Promotionhttps://www.northerntrailoutfitters.com/default/nutritionNutritional Promotion 20212021-01-172021-06-30HomeHeroDesktop|HomeHeroMobilehttps://www.northerntrailoutfitters.com/dw/image/v2/BDPX_PRD/on/demandware.static/-/Library-Sites-NTO-SFRASharedLibrary/default/dwa91a0c16/images/category/nutrition-category-1680-400.jpgAlpinetrue Gold|Silver
offer1003Electronicshttps://www.northerntrailoutfitters.com/default/electronicsElectronics Promotion 20222022-01-012022-12-31HomeHeroDesktophttps://www.northerntrailoutfitters.com/dw/image/v2/BDPX_PRD/on/demandware.static/-/Library-Sites-NTO-SFRASharedLibrary/default/dw35e8ceb7/images/category/electronics-category-1680-400.jpg
false Bronze

  • No labels