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

 Interaction Studio supports ingesting user profile objects via ETL to store against individual customer profiles and leverage for segmentation and personalization. User profile objects must be defined on the catalog and profile objects screen in advance of loading an ETL file. Profile object requirements and a spec file is provided in this article.

This Article Explains

This article details the requirements and schema for the User Profile Object ETL and provides a sample reference file.

Sections in this Article

Requirements and Schema 

  • Prior to uploading a user profile object ETL, confirm that the profile object is configured and enabled with all the necessary attributes and related catalog objects on the catalog and profile object screen. 
    • NOTE: If you try to pass in data associated to a profile object, related catalog object, or attribute that is NOT configured, the data will not be applied/stored. Profile objects, attributes & related catalog objects MUST be configured in advance of loading data.
  • Profile object limits are defined on the data model configuration page and should be reviewed prior to loading any profile object data.
  • If an ETL causes a user to exceed 100 profile objects of a certain type, Interaction Studio keeps the 100 newest objects.

Understanding the Profile Object ETL File Naming Structure:

  • File name structure is user-profile-objects-<objectTypeId>-<delta/replace>-<file number>.csv
    • The object Type ID and file mode is critical to how the information in the file gets processed. Make sure to review the details below before proceeding with any object uploads
  • Each profile object ETL file can only reference a single object type. The object type is defined in the file name and should map to the object name entered on the catalog and profile objects screen (user-profile-objects-<objectTypeId>-<delta/replace>-<file number>.csv)
    • Example: If you have 4 profile object types configured on the catalog and profile objects screen (Lease, Ownership, Warranty, Service Cases) and you want to load in data for each object type, you would need to leverage 4 ETL files. One file for each object type.
  • The profile object ETL has two configuration options: Delta and Replace. Before leveraging the ETL, make sure to review how each option works. The file mode is defined in the file name (user-profile-objects-<objectTypeId>-<delta/replace>-<file number>.csv)

    • Delta Mode:
      • Updates will only be made to the objects provided in the file
      • For objects in the file, information should be included for ALL columns even if the data is not changing from what is currently listed on the profile object (a blank value in a column will be interpreted as a request to null out an existing value on the object. If you wish to keep the current value, it should be entered in the object ETL file)
      • If an object is not included in the file, it will remain on the user unchanged
      • Delta mode is the only mode that supports the "remove" column header. Remove will delete the specified profile object from the user
    • Replace Mode:
      • Fully replaces the objects on a user for the given object type
      • For objects in the file, information should be included for ALL columns even if the data is not changing from what is currently listed on the profile object (a blank value in a column will be interpreted as a request to null out an existing value on the object. If you wish to keep the current value, it should be entered in the object ETL file)
      • If an object id for an existing object on a user is not included in the file, it will be deleted from the user profile (In replace mode, if you want to keep a profile object on a user even if no value is changing, you will need to include it as a row in the file)
  • The file number at the end of the naming structure simply helps you track profile object updates. It does not impact how the file runs or processes.

Profile Object ETL Identity Management and File Sorting:

  • Profile Object ETL files MUST be sorted BEFORE loading into Interaction Studio by identity so that all objects associated to a user are grouped together
    • Customers not on the Multiple Identity System:
      • The file must be sorted by user.Id so that all objects for an individual user are grouped together
    • Customers on the Multiple Identity System: 
      • The file must be group sorted so that all objects for a given user are grouped together
      • If multiple identity attribute columns are present in the file and a user appears on multiple rows, the same identity values must be present for each of those rows
      • The profile object ETL has a unique column header format for identity attributes. Instead of leveraging attribute: like you might in other user related ETLs, you will leverage identityAttribute:
      • Example: If a lease profile object file is being uploaded and a single user has multiple lease objects, each row must contain the same identity attribute values for that user. So if there are four identity attribute columns in the file, and the user has values for three of the four, those three values MUST be present on each row for that user to allow for proper sorting. If the identity values are not consistent across rows for a user, it can cause data within the file to overwrite itself on the user and result in not all of the objects being updated or applied.

Profile Object Behavior Upon User Profile Merge:

  • Upon profile merge, all profile objects will be appended to the new, combined profile
  • If in a user merge scenario the resulting number of profile objects for a certain object type exceeds the 100 objects per type per user outlined in the data model configuration article, the 100 most recent profile objects based on their creation date in Interaction Studio will be kept for the merged user
  • A shared profile object ID will NOT cause a profile merge
  • If profiles that share an object ID merge, Interaction Studio will keep the profile object that was most recently created


Profile Object Deletion:

  • Profile objects can only be deleted via ETL
  • Delta File Mode:
    • If you wish to delete a profile object, simply include the column remove in your file with a value of true on the row of the profile object that you wish to delete. If there are other columns in the file, these can be left blank for the object that is being deleted
  • Replace File Mode:
    • Replace mode replaces all profile objects of a single type with those in the file. This means that any existing profile object on a user whose ID is not included in the file will be deleted.


File Format

File Naming Structure: user-profile-objects-<objectTypeId>-<delta/replace>-<file number>.csv

Profile Object ETL Identity Attribute Formatting

For customers leveraging Interaction Studio’s multiple identities system, at least one identity attribute is required to be present in the ETL file. If you would like to send in multiple identity attributes for a single customer, this is supported by simply having multiple identity attribute columns in the file. 

The correct ETL header format for identity attributes in the profile object ETL is identityAttribute:value. Examples of the out-of-the box identity attributes with proper formatting is as follows:

  • identityAttribute:emailAddress
  • identityAttribute:sfmcContactKey
  • identityAttribute:customerId
  • identityAttribute:sfcrmContactId
  • identityAttribute:sfcrmLeadId

userId is not referenced in ETL processing when the multiple identities system is enabled. For customers NOT leveraging Interaction Studio’s multiple identities system, userId will still be supported for profile merging.

Field Name

Minimum Requirements

Example Values

Max Length

Interaction Studio Data Type

Required Fields



userId OR an Identity Attribute

Required.

  • Four (4) character minimum.
  • For clients that ARE NOT using Interaction Studio's multiple identities system, a userId must be included. This ID must be one that is tracked within the Evergage platform so that the events can be tied to the specific user profile.
  • For clients that ARE using Interaction Studio's multiple identities system, userId is not referenced in ETL file loads. At least one identity attribute is required. Multiple identity attributes can be included for a single user by simply including multiple columns in the file. The proper format for identity attributes is detailed in the comment above.
  • If a user is present on more than one row in a profile object file, the file must be sorted prior to loading into Interaction Studio so that all rows for a given user are grouped together and a user must have the same identity attributes present on each row
jdoe john.doe@example.com c2e384084c8ac233120String
objectId

Required.

  • Each object on a user requires an object ID. This ID is referenced for object updates/replacements (The objectId is different from the ObjectTypeId that is used in the file name. The ObjectTypeId maps to the name of an object type configured in the profile and catalog objects page while this object id is simply the id of a profile object stored against a user profile.)
  • An Object ID must be alphanumeric and only contain letter, numbers, dashes, or underscores
  • An object ID can exist across multiple users and a match on an Object ID does NOT trigger a profile merge
  • As noted above, if two profiles merge that have a matching object ID, Interaction Studio will keep the object and all associated meta-data that was created most recently
mortgage1, lease1, case12330String
Additional Fields



attribute:<name>

Optional.

  • The custom attributes configured on the profile object (the attribute must be pre-configured on the catalog and profile objects screen in order for a value sent in via ETL to be applied. The ETL will not create an attribute on a profile object type)
  • Column titles are the word 'attribute' followed by colon followed by the attribute name as configured on the profile object.
  • Different attribute value formatting is required depending on the attribute type
  • Supported attribute types for ETL data ingestion on a profile object include string, decimal, integer, boolean, and date
  • If you leave an attribute column empty, it will be treated as an indication to clear any existing value on the object if it already exists. This means that if you wish to keep an existing value, you MUST include it in the file even if it is not changing.


Examples of different attribute types that might be included are listed below. 

String:

  • attribute:loyaltyTier = Gold
  • attribute:subscriberEmail = bob@test.com


Integer / Decimal:

  • attribute:APR = .4
  • attribute:caseTier = 2


Boolean:

  • attribute:caseOpen = True


Date:

  • attribute:leaseStart = 2020-10-15
    • Note: Accepted format = ISO 8601 Date time string 


Depends on attribute type

String,

Decimal,

Boolean,

Integer,

Date

relatedCatalogObject:<name>

Optional.

  • The related catalog objects configured on the profile object (The related catalog object must be already assigned to the profile object on the catalog and profile objects screen. If a related catalog object is included in the file that is not assigned to the profile object, it will be ignored)
  • Column titles are the word 'relatedCatalogObject' followed by colon followed by the catalog object ID as configured on the profile object.
  • If the cardinality of the related catalog object is many per item, values should be comma separated

Product: creditCard|debitCard

Make: carMake1

Mortgage: fixedRateMortgage

string255
remove

Optional.

  • If you wish to delete a catalog object from a user, include the column header "remove" and have the value be true
  • Once deleted, a profile object cannot be recovered
  • If the "remove" header is present and an is left blank, the default assumption is that the value is false
truestring1023

Sample File

Sample File Structure For Clients NOT leveraging Interaction Studio's multiple identities system

user-profile-objects-Lease-delta-1

userIdobjectIdattribute:startDateattribute:endDateattribute:Mileageattribute:activerelatedCatalogObject:MakerelatedCatalogObject:ModelrelatedCatalogObject:Yearremove
jdoe123lease12021-01-01T00:00:00.000Z2023-01-01T00:00:00.000Z30000TrueJeepWrangler2021
jdoe123lease22021-01-01T00:00:00.000Z2023-01-01T00:00:00.000Z50000TrueJeepGrand Cherokee2021
user103925lease32021-01-01T00:00:00.000Z2025-01-01T00:00:00.000Z75000TrueChryslerPacifica2021
a30bkcqfo941afclease42021-01-01T00:00:00.000Z2025-01-01T00:00:00.000Z50000TrueFiatSpider2021
interactionstudiouserlease5






true


Sample File Structure For Clients leveraging Interaction Studio's multiple identities system

user-profile-objects-Lease-delta-1

identityAttribute:emailidentityAttribute:customerIdidentityAttribute:sfcrmContactIdobjectIdattribute:startDateattribute:endDateattribute:Mileageattribute:activerelatedCatalogObject:MakerelatedCatalogObject:ModelrelatedCatalogObject:Yearremove
jdoe123@example.comjdoe12345zxaqw
lease12021-01-01T00:00:00.000Z2023-01-01T00:00:00.000Z30000TrueJeepWrangler2021
jdoe123@example.comjdoe12345zxaqw
lease22021-01-01T00:00:00.000Z2023-01-01T00:00:00.000Z50000TrueJeepGrand Cherokee2021
sample@company.com

5003000000D8cuIQAA

lease32021-01-01T00:00:00.000Z2025-01-01T00:00:00.000Z75000TrueChryslerPacifica2021
sample@company.com

5003000000D8cuIQAA

lease42021-01-01T00:00:00.000Z2025-01-01T00:00:00.000Z50000TrueFiatSpider2021
leaseremove@example.com

lease5






true