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


DEPRECATED ETL

The Dimension ETL is deprecated as of 9/7/2021. Key information is as follows:

Dimension ETL Replacement:

  • The Catalog Object ETL should be leveraged in place of the Dimension ETL to populate data against blogs, articles, or user created catalog object types
  • The Catalog Object ETL provides the exact same functionality as the Dimension ETL, but reflects the updated platform nomenclature and transition away from the term "dimension"

Customers Currently Using the Dimension ETL:

  • Customers using the Dimension ETL to load in blog, article, or dimension data can continue to leverage existing files.
  • The term dimension is no longer used in the platform interface. Instead of Items and Dimensions, there are simply catalog objects and related catalog objects
  • If a customer using the dimension ETL needs to update their file or creates a new catalog object, we recommend taking the opportunity to transition to the new Catalog Object ETL to populate data
  • If you are transitioning from the Dimension ETL to the Catalog Object ETL, make sure to review the Catalog Object ETL documentation carefully, as column header format does change slightly


-- THE INFORMATION BELOW SHOULD ONLY BE REFERENCED BY CUSTOMERS THAT HAVE AN EXISTING DIMENSION ETL RUNNING. ALL OTHER CUSTOMERS SHOULD LEVERAGE THE CATALOG OBJECT ETL. --


 Interaction Studio supports the ingestion of Articles, Blogs, and Dimensions into the catalog through ETL file feeds. The built-in dimension ETL is leveraged to ingest dimension data, Blog data, and Article data. This article outlines proper file formatting for each.

Dimension Types cannot be created through an ETL feed and must be configured in Catalog Setup prior to importing dimension instances. Once the dimension types have been defined with appropriate custom attributes, instances of the dimension type can be created or updated using this ETLThe built-in system attributes associated with dimension types are defined in the schema section below.

Articles & Blogs may be imported or updated using this ETL. For best results configure custom attributes and dimensions for articles and blogs in Catalog Object Setup to extend the built-in system attributes associated with each item type. While articles and blogs, along with their associated system attributes, can be imported without any prior configuration in Catalog Setup, custom attributes and dimensions must be configured to be supported by this ETL feed. The built-in system attributes associated with each item type are defined in the Requirements and Schema section below.

This Article Explains

This article details the requirements and configuration settings of the Dimension ETL gear for ingesting articles, blogs, and dimensions.  It also provides the file schemas for each item type along with downloadable sample files.

Sections in this Article


Requirements and Schema

Importing Dimensions 

The Dimension ETL supports loading information for multiple Dimension Types (dimensionId) in a single file. It is expected that dimension values are grouped together by Dimension Type when included in the file. If the Dimension values are not provided in consecutive rows, a system administrator can sort the file on the Gear Configuration screen.

Values for id and dimensionId are required for all records, but if other columns have no value, the corresponding dimension attribute will be unset resulting in a null value for that attribute.

Importing Articles and Blogs 

Each article and blog should only appear in a single record of any given file. In the case where there are multiple records with the same article or blog ID, the last complete and valid record in the file will be the one whose data is loaded into the system.

Articles and blogs lacking an attribute value in one of the attribute columns will have any existing value(s) for that attribute removed. This means that if an attribute column is included in the file, all records in the file should have a value for that column, not just the records whose values have changed.


File Naming Conventions

ETL processing will begin when an appropriately named file lands in the 'inbound' directory of your Salesforce SFTP site. The name of the file determines which type of data is loaded. The following file-name convention should be used:

    • dimension-YYYY-MM-DD_HH-MM-SS.csv.[zip|gz|pgp|gpg] for adding or updating instances of existing dimension types.

    • blog-YYYY-MM-DD_HH-MM-SS.csv.[zip|gz|pgp|gpg] for adding or updating blog posts.

    • article-YYYY-MM-DD_HH-MM-SS.csv.[zip|gz|pgp|gpg] for adding or updating articles.


File Formats

Dimension ETL

Field Name

Minimum Requirements

Example Values

Max Length

Interaction Studio Data Type

idRequired. A dimension instance Id must exactly match the id captured by the web SDK sitemap. A specific id value is only expected once per file feed.  When an id appears multiple times in the same feed file, the content of the last row with the id will overwrite any previous updates and load into the catalog.prod1237723255String
dimensionId

Required. Dimension Id must be one of the dimension types configured in the Catalog Object Setup screen.

SaleStatus
Brand
255String
attribute:<attribute name>The custom attributes for this dimension. Column titles are the word attribute followed by a colon, followed by the attribute name as configured in the attributes portion of Catalog Setup > Dimension in Interaction Studio.  Attributes are parsed as the data type defined in the catalog (See Catalog Setup).

attribute:fit. loose

attribute:length long

1023any
dimension:<dimension name>Dimensions may have additional dimensions associated with them. Column titles are the word dimension followed by colon, followed by the dimension name. Each dimension name must match one configured in Catalog Setup in Integration Studio. A dimension can have multiple dimensions in separate columns. A dimension can have multiple values for the same dimension, separated by the pipe character. 

dimension:Color  Blue|Yellow

dimension:Materia  Leather

1023String
System Fields



attribute:nameRepresents the name of the dimension and must contain at least one alphanumeric character.

Sale

Regular Price

1023String
attribute:urlRFC-3986 Complete URLs that represent the canonical dimension display page for this dimension.https://example.com/onsale.html1023String
attribute:imageUrlFully-qualified URL for an image of this dimension.https://example.com/img/sale.png1023String
attribute:descriptionRepresents the description of the dimension and must contain at least one alphanumeric character.Products on Sale 1023String
attribute:promotableBoolean, which defaults to true even if no value is set. When false, the item will not be returned by the Interaction Studio recommendation system.TRUE1023Boolean
attribute:archivedBoolean, which defaults to false when no value is set. When true, the item will not be visible in the catalog. If this column is omitted from the feed file, no changes will be made to the archived attribute.FALSE, false, TRUE, true1023Boolean


Article and Blog ETL

Field Name

Minimum Requirements

Example Values

Max Length

Interaction Studio Data Type

idRequired. Article and Blog IDs must exactly match the ids captured by the Integration Studio Web SDK Sitemap or they will load as separate items.prod1237723255String
attribute:<attribute name>The custom attributes for this article. Column titles are the word 'attribute' followed by colon followed by the attribute name as configured in the attributes portion of the Catalog Setup -> Article screen. Attributes are parsed as the data type they are defined as in the config screen.

attribute:topic  Hats

attribute:readtime 10 minutes

1023any
dimension:Additional dimensions such as brand and color may be defined and imported with matching column names. Each dimension name must match a dimension configured in Catalog Setup. Column titles are the word dimension followed by colon followed by the attribute name. An article can have multiple dimensions in separate columns. An article can have multiple values for the same dimension, separated by the pipe character. 

dimension:author  R. Frost

1023String
categoriesList of category IDs that may be defined using pipe delimiting. Home|Bedroom|Bathroom1023String
System Fields



attribute:nameRepresents the name of the article and must contain at least one alphanumeric character.Slick New Kicks1023String
attribute:urlRFC-3986 Complete URLs that represent the canonical article display page for this article.https://example.com/articles/prod1.html1023String
attribute:imageUrlFully-qualified URL for an image of this item.https://example.com/img/img1.png1023String
attribute:descriptionRepresents the description of the article and must contain at least one alphanumeric character to be set.Some excellent new shoes250String
attribute:promotableBoolean which defaults to true, even if no value is set. When false, the item will not be returned by our recommendation systemTRUE1023Boolean
attribute:publishedISO 8601 Date time string for article published date.2017-04-22T10:23:37Z1023Date
attribute:expirationISO 8601 Date time string for article expiration date.2017-04-22T10:23:37Z1023Date
attribute:ratingThe rating value associated with an article, While no specific scale is required, only the value should be provided. For example, the value 9/10 is invalid, while 9 is valid.4.51023Decimal/Float
attribute:numRatingsThe number of ratings associated with an article.51023Integer
attribute:archivedBoolean, which defaults to false when no value is set. When true, the item will not be visible in the catalog. If this column is omitted from the feed file, no changes will be made to the archived attribute.FALSE, false, TRUE, true1023Boolean

  

Sample Files

As a reminder, the Dimension ETL cannot create a new Dimension Type. All dimension types identified in the dimensionid column must already exist in the catalog for the sample file(s) to run correctly. Please refer to Catalog Setup for instructions on how to define dimension types.

Sample Dimension File Download

id

dimensionId

attribute:name

attribute:archived

attribute:url

attribute:imageUrl

attribute:description

dimension:SaleStatus

attribute:saleLanguage

attribute:materialUsability
onSaleSaleStatusOn SaleFALSEhttp://www.sample.com/salehttp://www.sample.com/image/sale.jpgItems associated are on saleOnSaleSuper Sale
normalSaleStatusNormalFALSEhttp://www.sample.com/normalpricinghttp://www.sample.com/image/normal.jpgItems associated are not on sale
Half Off
lastChanceSaleStatusLast ChanceFALSEhttp://www.sample.com/lastchancehttp://www.sample.com/image/lastchance.jpgLast opportunity to get these itemsOnSaleSale Ends Soon
SequinsMaterialSequinsFALSEhttp://www.sample.com/sequinshttp://www.sample.com/image/sequins.pngSequins are a classic disc shaped bead used for clothing

difficult

Denim

MaterialDenimFALSEhttp://www.sample.com/denimhttp://www.sample.com/image/denim.pngMost commonly used in jeans, also a common material for jackets and less commonly socks

moderate
WoolMaterialWoolFALSEhttp://www.sample.com/woolhttp://www.sample.com/image/wool.pngProcured from sheep wool is one of the most easy to use materials when crafting clothing

easy
CottonMaterialCottonFALSEhttp://www.sample.com/cottonhttp://www.sample.com/image/cotton.pngA delightfully soft material used in crafting many garments

easy

Sample Article File Download

id

attribute:name

attribute:archived

attribute:url

attribute:imageUrl

attribute:description

attribute:promotable

categories

attribute:published

attribute:expiration

attribute:rating

attribute:numRatings

dimension:author

attribute:numViews

12568What is Interaction StudioFALSEhttp://www.sample.com/article/12568http://www.sample.com/image/article12568.jpgExplore what Interaction Studio has to offerTRUEinteractionstudio|marketing2020-01-152100-10-18578interactionstudio650
67455Marketing in 2020FALSEhttp://www.sample.com/article/67455http://www.sample.com/image/article67455.jpgMarketing in the time of wfhFalseinteractionstudio|Marketing|20202020-03-092025-03-154.8614tolkien1026
12054Setup your accountFALSEhttp://www.sample.com/article/12054http://www.sample.com/image/article12054.jpgSetting up your Interaction Studio AccountTrueinteractionstudio|Account|20202019-11-182024-10-16

4.99

322anonymous87165
98466Understanding EinsteinFALSEhttp://www.sample.com/article/98466http://www.sample.com/image/article98466.jpgUnderstand how Einstein interacts with Interaction StudioTrueinteractionstudio|Einstein|Marketing2020-02-142029-10-193.579anonymous10021



Sample Blog File Download

id

attribute:name

attribute: archived

attribute:url

attribute:imageUrl

attribute:description

attribute:promotable

categories

attribute:published

attribute:expiration

attribute:rating

attribute:numRatings

dimension:author

attribute:numViews

customerinsightWhat is Interaction StudioFALSEhttp://www.sample.com/blog/customer-insighthttp://www.sample.com/image/blog12568.jpgExplore our view on customers and gain insight about themTRUEinteractionstudio|marketing|customer2020-01-152100-10-18578interactionstudio650
fallfashionFall FashionFALSEhttp://www.sample.com/blog/fall-fashionhttp://www.sample.com/image/blog67455.jpgGet the hottest looks in fall fashion nowFalsefall|fashion|clothing|20202020-03-092025-03-154.8614John Smith1026
devTrendsWeb Developer TrendsFALSEhttp://www.sample.com/blog/web-dev-trendhttp://www.sample.com/image/blog12054.jpgKnow what's trending today in web devTruewebdev|git|2019|current2019-11-182024-10-16

4.99

322anonymous87165
EinsteinUnderstanding EinsteinFALSEhttp://www.sample.com/blog/einsteinhttp://www.sample.com/image/blog98466.jpgLearn about how Einstein can be appliedTrueinteractionstudio|Einstein|Marketing2020-02-142029-10-193.579anonymous10021
12120Understanding Interaction StudioFALSEhttp://www.sample.com/blog/understandishttp://www.sample.com/image/blog12120.jpgTake a peek into Interaction Studio EinsteinTRUEinteractionstudio|Einstein|2020|actions2020-08-192080-01-024.1541interactionstudio36451