Configure details

Next, we can configure the Data Sync expression file to tailor your integration.

An expression file in SnapLogic is a configuration file that can be used to house custom variables and values which are referenced by settings in the pipelines. In this case, we provide a template file that is designed to work specifically with the SFMC Data Sync.

We’ll complete this configuration in three main steps:

  • Download the expression file template
  • Configure the expression file
  • Upload the configured expression file to your project folder

Download expression file template

In the SnapLogic Manager tab:

  1. In the left navigation under the SFMC Data Sync project space, click on the SFMCDataSyncPattern folder to view its contents
  2. In the main panel, click directly on the SfmcData.expr file in the Name column to download it to your computer Download expression file in SnapLogic

Configure expression file

  1. Open the SfmcData.expr file you downloaded in a text editor
  2. Revise the values in the file to tailor it for your data export (see example and table below for details)

Example:

{
	"identityCloudSnapAccount": "My Akamai account",
	"identityCloudRestAccount": "My Identity Cloud REST account",
	"registrationDomain": "https://my-app.us.janraincapture.com",
	"sfmcRestAccount": "My Marketing Cloud REST account",
	"sfmcAuthBaseUri": "https://myuri-1234.auth.marketingcloudapis.com/",
	"sfmcSoapBaseUri": "https://myuri-1234.soap.marketingcloudapis.com/",
	"notificationEmails": "email1@company.com, email2@company.com",
	"maxSyncAttempts": 3,
	"entitiesToExport": [
		{"entityType": "user"},
		{ ANOTHER ENTITY TYPE }
	],
	"user" : {
		"captureClientIds": [
			"9ev6xath4c5twe2aqpxbkkf7knpktca7",
			"em2fpgvxjxcpzc3ea3mvawchfz8grrkr"
		],
		"requireVerifiedEmail": false,
		"subscriberMapping": x => {
			"header" : {
				"SubscriberKey" : x.email,
				"EmailAddress"	: x.email
			},
			"attributes" : {		
				"DisplayName" 	: x.displayName
			}
		},
		dataExtension: x => [
			{
				"dataExtensionExternalKey": "MY-EXTERNAL-KEY-ABC",
				"mapping": {
					"email" 			: x.email,
					"uuid"				: x.uuid,
					"displayName"		: x.displayName,
					"familyName"		: x.familyName,
					"givenName"			: x.givenName,
					"birthday"			: x.birthday,
					"marketingConsent"	: x.consents.marketing.granted			
				}
			},
			x.legalAcceptances.map(plural =>
				{
					"dataExtensionExternalKey": "MY-EXTERNAL-KEY-EFG",
					"mapping": {
						"email" 			: x.email,
						"id"				: plural.id,
						"clientId"			: plural.clientId,
						"dateAccepted" 		: plural.dateAccepted,
						"legalAcceptanceId" : plural.legalAcceptanceId	
					}
				}
			)
		],
		"deleteDataExtensionKeys": [
			'MY-EXTERNAL-KEY-ABC',
			'MY-EXTERNAL-KEY-EFG'
		]
	},
	{ ANOTHER ENTITY TYPE }
}
Key Value Instructions
identityCloudSnapAccount The Label/Name for the Akamai account you created in SnapLogic.
identityCloudRestAccount The Label/Name for the Akamai Identity Cloud REST account you created in SnapLogic.
registrationDomain Your Identity Cloud Registration Domain from Console. Make sure to include the https:// protocol.
sfmcRestAccount The Label/Name for the Salesforce Marketing Cloud REST account you created in SnapLogic.
sfmcAuthBaseUri The Authentication Base URI from the Package you created in Marketing Cloud. Copy it directly from Marketing Cloud and paste it here.
sfmcSoapBaseUri The SOAP Base URI from the Package you created in Marketing Cloud. Copy it directly from Marketing Cloud and paste it here.
notificationEmails A comma-separated list of email addresses to receive error notifications.

An error notification email will be sent if there is a failure in the pipeline when the integration is executed. The email contains error details including what needs to be fixed.
maxSyncAttempts The number of times the integration will attempt to sync a record from Identity Cloud to a subscriber in Marketing Cloud. If this number of attempts results in the same number of failures, the integration will stop attempting and will include this record in a list that gets emailed to the notificationEmails.

Default value: 3
entitiesToExport An array of objects, one for each Identity Cloud entity type to sync data from. If only syncing from one entity type, this will be an array containing one object.
entitiesToExport:
entityType		 The name of the Identity Cloud entity type to sync data from (e.g. user).
entity_type_name
(e.g. user)		 An object containing configurations specific to an entity type.
  • The name of the object must match the name of the entity type (e.g. user).
  • There must be one object per entityType defined in the entitiesToExport array.
entity_type_name:
captureClientIds		 OPTIONAL array of Identity Cloud client IDs to filter on.

If you only want to sync records associated with one or more specific properties, add the Client Id for each of those properties to this array. Users that are not associated with a client in this array will not be synced.

If you don’t need to filter by Client Id, leave this array blank ([]).
entity_type_name:
requireVerifiedEmail		 Boolean indicating whether or not user records in Identity Cloud must have a verified email address in order to be synced to Marketing Cloud. Possible values:
  • true: A verified email address is required. Records without a verified email address will not be synced.
  • false: A verified email address is NOT required. Records will be synced regardless of email verification status.
entity_type_name:
subscriberMapping		 An object containing instructions for which Identity Cloud profile attributes to map to Marketing Cloud subscriber attributes. The subscriber header attributes, SubscriberKey and EmailAddress, are required. Additional subscriber attributes can optionally be mapped under attributes.

The name of the Marketing Cloud attribute is the key on the left. The name of the Identity Cloud attribute to map to it is the value on the right, and must be prepended with x..

"MarketingCloudAttribute": x.identityCloudAttribute

Notes on SubscriberKey: It is generally recommended to map the Identity Cloud email to the SubscriberKey, however any unique identifier stored in Identity Cloud will work. If you plan to sync deletes, you MUST map the uuid to the SubscriberKey. For more info, see Sync deletes.
entity_type_name:
dataExtension		 An array of objects, one for each Marketing Cloud data extension to sync data to. If only syncing to one data extension, this will be an array containing one object. If you do not want to sync data to a data extension, this will be an empty array.

Notice in the example above that the format of the object is special for data extensions that will contain plural data. The data exension object for plural data must be wrapped in the following:

x.pluralName.map(plural => { DATA EXTENSION OBJECT } )

where pluralName is the name of the parent plural in Identity Cloud (e.g. legalAcceptances).
entity_type_name:
dataExtension:
dataExtensionExternalKey		 The EXTERNAL KEY for the data extension, found in Salesforce Marketing Cloud.
entity_type_name:
dataExtension:
mapping		 An object containing instructions for which Identity Cloud profile attributes to map to data extension fields. The name of the data extension field is the key on the left. The name of the Identity Cloud attribute to map to it is the value on the right.

"dataExtensionField": x.identityCloudAttribute

As seen in the example, the format of the value is:
  • x.attributeName for root-level attributes
  • x.objectName.attributeName for object attributes
  • plural.attributeName for plural attributes
entity_type_name:
deleteDataExtensionKeys		 OPTIONAL array of dataExtensionExternalKeys, one for each Marketing Cloud data extension to sync deletes to. This means when a user profile is deleted in Identity Cloud, the related rows in the specified data extensions will be deleted from Marketing Cloud (along with the subscriber).

If you do not want to sync deletes to data extensions, or if you do not plan to sync deletes to Marketing Cloud at all, remove this configuration from the expression file.

Notes:

  • This setting only works if you are using the SFMCDeleteSync and SFMCDeleteSync_DataExtensions pipelines.
  • Note that the sample expression file shown above this table contains an incompatibility - it includes this setting but it also maps email to SubscriberKey. In real life, this would not work. In order to utilize the delete-sync functionality, you must map uuid to SubscriberKey.
  1. Save the expression file to your computer in a place you’ll remember should you decide to revise the configuration in the future.

DO NOT RENAME THE FILE! The expression file you upload to your project folder must be named SfmcData.expr - Any other file name will not be recognized by the Data Sync pattern.

Upload expression file

Once you’ve configured and saved your expression file locally, you can upload it to your project folder. In the Manager tab:

  1. In the left navigation under the SFMC Data Sync project space, click on your project folder to view its contents
  2. In the main panel, click on the Files tab
  3. In the upper right corner, click the Create icon ()
  4. Choose your configured SfmcData.expr file from your computer and click Upload Upload expression file in SnapLogic

You can view the content of the file you uploaded in SnapLogic by hovering over the file name, clicking the little arrow next to it, and selecting View. View file in SnapLogic

Good to know: It is not possible to edit the expression file directly in the SnapLogic interface. In the future when you need to update your expression file, you must:

  1. Make your updates locally
  2. Delete the existing file from your project folder in SnapLogic (select the file then click the trash icon in the upper-right corner)
  3. Upload the updated file to your project folder in SnapLogic

Your project folder should now contain:

  • Four (4) or six (6) pipelines
  • Three (3) accounts
  • One (1) expression file