--- schema_version: "1" id: c5ec0c6bd0c22fb09a4683ecabe540414235028483ec50326fe14b92a04327ac title: JSON Metadata Usage and Examples for External Activation Platforms collection: admin version: current locale: en-us portal_url: https://docs.salesforce.com/admin/current/en-us/data/264-0-0/c360_a_activation_toolkit_isv.md canonical_url: https://help.salesforce.com/s/articleView?id=data.c360_a_activation_toolkit_isv.htm&release=264.0.0&type=5 source_site: help.salesforce.com content_type: documentation content_hash: bd81be75054de816864f45e92a662b8e582eb70cacd829496a8ff5d90ff35814 description: Here are the JSON examples followed by the field descriptions and best practices to help you define your external activation platform. products: - Data 360 release: "264" --- # JSON Metadata Usage and Examples for External Activation Platforms Here are the JSON examples followed by the field descriptions and best practices to help you define your external activation platform. Sample JSON for Output Grouping by PER\_USER `{ { "name": "abc-user-identifiers", "apiName": "abc_user_identifiers", "description": "Activation platform to activate only user identifiers", "platformType": "Advertising", "outputGrouping": "PER_USER", "refreshFrequency": "TWENTY_FOUR", "refreshMode": "FULL", "connector": { "connectorType": "S3", "bucketName": "example-uswest2-cdp001-sample-data", "exportDirectory": "datacloud-activations" }, "activationAttributes": [ { "displayName": "Hashed Email", "destinationName": "EmailAddress", "objectName": "ContactPointEmail", "fieldName": "Email", "isRequired": true, "applyHash": true, "isIdentifier": true }, { "displayName": "Hashed Phone", "destinationName": "PhoneNumber", "objectName": "ContactPointPhone", "fieldName": "E164FormattedPhoneNumber", "isRequired": true, "applyHash": true, "isIdentifier": true }, { "displayName": "Hashed Digital id value", "destinationName": "DigitalIdValue", "objectName": "ContactPointDigitalId", "fieldName": "DigitalIdValue", "isRequired": true, "applyHash": true, "isIdentifier": true } ], "fields": [ { "name": "AccountId", "helpText": "", "isRequired": true, "isHidden": false, "type": "Text" }, { "name": "AccountName", "helpText": "", "isRequired": false, "isHidden": true, "type": "Text", "values": [ { "isDefault": true, "value": "Name of your account" } ] } ], "activationPlatformCustomMetadata": { "connectorType": "S3", "accessKey": "DUMMY1234EXAMPLE5678KEY", "secretKey": "dUmMySeCrEtKeY12345EXAMPLE67890" }, "activationPlatformAdditionalMetadata": { "hashMethod": "SHA256", "outputProperties": { "outputFormat": "CSV", "compression": "GZIP", "maxFileSizeInMB": 128, "maxRecordsPerFile": 1000000, "minRecordsPerFile": 10000, "outputPartitions": 20, "delimiter": "COMMA" }, "partnerSupportedIds": [ { "destinationName": "DigitalIdValue", "supportedIdTypes": [ "Google", "Facebook", "Trade desk", "Instagram" ] } ], "subscriberOverrideOptions": {}, "supportCustomAttributes": false } }` Sample JSON for Output Grouping by PER\_SEGMENT `{ "name": "abc-segment", "apiName": "abc_segment", "description": "ActivationTest platform to activate user identifiers and additional match keys", "platformType": "Advertising", "outputGrouping": "PER_SEGMENT", "refreshMode": "FULL", "connector": { "connectorType": "S3", "bucketName": "example-uswest2-cdp001-sample-data", "exportDirectory": "datacloud-activations" }, "activationAttributes": [ { "displayName": "First Name", "destinationName": "fName", "objectName": "Individual", "fieldName": "FirstName", "isRequired": true, "applyHash": false, "isIdentifier": false }, { "displayName": "Last Name", "destinationName": "lname", "objectName": "Individual", "fieldName": "LastName", "isRequired": false, "applyHash": false, "isIdentifier": false }, ​​{ "displayName": "Hashed Digital id value", "destinationName": "DigitalIdValue", "objectName": "ContactPointDigitalId", "fieldName": "DigitalIdValue", "isRequired": true, "applyHash": true, "isIdentifier": true }, { "displayName": "Hashed Email", "destinationName": "EmailAddress", "objectName": "ContactPointEmail", "fieldName": "Email", "isRequired": false, "applyHash": true, "isIdentifier": true } ], "fields": [ { "name": "AccountId", "helpText": "", "isRequired": true, "isHidden": false, "type": "Text" }, { "name": "AccountName", "helpText": "", "isRequired": false, "isHidden": false, "type": "Text" } ​​], "activationPlatformCustomMetadata": { "connectorType": "S3", "accessKey": "DUMMY1234EXAMPLE5678KEY", "secretKey": "dUmMySeCrEtKeY12345EXAMPLE67890" }, "activationPlatformAdditionalMetadata": { "hashMethod": "SHA256", "outputProperties": { "outputFormat": "CSV", "compression": "GZIP", "maxFileSizeInMB": 128, "maxRecordsPerFile": 1000000, "minRecordsPerFile": 10000, "outputPartitions": 20, "delimiter": "COMMA" }, "partnerSupportedIds": [ { "destinationName": "DigitalIdValue", "supportedIdTypes": [ "Google", "Facebook", "Trade desk", "Instagram" ] } ], "subscriberOverrideOptions": {}, "supportCustomAttributes": false } }`
Field Name Description Required (Y/N) Allowed Values Sub Fields Allowed Values Sub Fields Description Required (Y/N)
name Name of the activation platform Y NA NA NA NA NA
apiName Unique API name of the activation platform Y NA NA NA NA NA
description A short description of the activation platform Y NA NA NA NA NA
platformType Specifies the type of activation platform Y

Advertising

Publishing

Analytics

Marketing

Technology

 NA NA NA NA
logoUrl The URL of the Activation Platform logo N NA NA NA NA NA
outputGrouping Specifies how the activation payload output is delivered to the partner. Output grouping by segment groups all attributes within a segment into a single file, while output grouping by user identifier activates each user identifier in a separate file, such as CSV. This field can't be modified during the edit workflow. Y

PER_SEGMENT

PER_USER

 NA NA NA NA
refreshMode Refresh mode for the activation platform. For "outputGrouping": "PER_USER" only Full is supported. Y

INCREMENTAL

FULL

 NA NA NA NA
refreshFrequency Refresh frequency for the activation platform. Applicable only when "outputGrouping": "PER_USER" is true Y TWENTY_FOUR NA NA NA NA
periodicFullRefresh Indicates how often you want to schedule a full refresh for Incremental Refresh. Applicable only when "outputGrouping": "PER_SEGMENT" is true and refresh mode is incremental. Y

REFRESH_30

REFRESH_60

 NA NA NA NA
connector Amazon S3 Connector details Y NA

"connectorType"

"bucketName"

"exportDirectory"

 NA exportDirectory: The folder path where the data is exported. Y
activationPlatformCustom Metadata Contains the connector credential details. Y NA

"connectorType"

"accessKey"

"accessSecret"

 NA NA Y
fields An array containing details of the activation target fields. Add at least one field (for example, Account ID). You can add a maximum of five fields. Y NA "name" NA The name of the field to be displayed in the activation target. Y
NA "helpText" NA A short descriptive text providing guidance for the field in the activation target. N
NA "isRequired"

true

false

 Indicates whether the field is required. A required field can't be hidden, and vice versa. Y
NA "isHidden"

true

false

 A required field can't be hidden, and vice versa. Hidden fields must always have a default value. Y
NA "type" NA The data type defined by the user based on the field requirement. N
NA

"values"

"isDefault"

"value"

 NA This is optional unless "isHidden": true, in which case, you must set "isDefault": true and provide a default value as shown in the example. Hidden fields must always have a default value. N
activationAttributes The attributes array contains all attributes that you allow your customers to map, including details on required and optional attributes. After defining an attribute, it can’t be removed during edit flow. Y NA "objectName" NA This is used as a hint for customers and it refers to the data model object (DMO) name . This helps customers map destination fields to Data 360 DMO attributes during activation mapping. For the ContactPointDigitalId DMO, the object name must be "ContactPointDigitalId". N (Read further for specific conditions where this field is required.)
NA "fieldName" NA

This is used as a hint for customers and it refers to the attribute name in the DMO for the corresponding destination field. This helps customers map destination fields to Data 360 DMO attributes during the activation mapping process.

 N
NA "displayName" NA The user-friendly name for the corresponding destinationName, which is displayed on the right side of the activation mapping interface. Y
NA "destinationName" NA Refers to the destination schema field name. This destinationName is used as the column header in the exported file (for example, CSV) when the output is grouped by segment. When the output is grouped by a user identifier, ‌ destinationName is used as the name of the folder that’s created automatically for each user identifier. This field can’t be Id, ID, or id for any of the activation attributes. This field value is displayed as thePreferred Attribute Namein the Contact Point filtering page. Y
NA "isRequired"

true

false

 Indicates whether this attribute is a required field. Y
NA "isIdentifier"

true

false

 Indicates whether this attribute is used as a user identifier. Y
NA

"applyHash"

true

false

 Indicates whether the attribute value should be hashed during Activation. It is recommended to set this flag to "true" for user identifier fields, unless partners prefer to retain the original values without hashing. Y
activationPlatformAdditional Metadata This object contains additional metadata that partners can configure as needed. NA NA "hashMethod" "SHA256" NA Required if any field is set to "applyHash": true
NA

“outputProperties"

"outputFormat"

CSV

JSON

PARQUET

 NA Y
NA "compression"

GZIP

BZIP2

NONE

 NA Y
NA "maxFileSizeInMB" Defaults to 128 MB if not configured Make sure that no file exceeds the specified file size. Recommended to not exceed 512 MB. N
NA "maxRecordsPerFile" Defaults to 1 million records per file if not configured Make sure that no file contains more than the specified number of records. Recommended to not exceed 5 million. N
NA "minRecordsPerFile" Min -1 The minimum number of records that must be present in a file. N
NA "outputPartitions” Min -1 Controls the number of files created in the output payload. N
NA "delimiter”

COMMA

SEMICOLON

TAB

PIPE

COLON

TILDE

CARET

HASH

UNDERSCORE

BROKEN_PIPE

SLASH

 NA Required if the output format is CSV
NA "partnerSupportedIds" NA NA Required if ContactPointDigitalId is used as objectName in activationAttributes
NA "destinationName" NA The field name on the destination schema which accepts Digital identifiers. Once defined, this can’t be changed during edit flow.
NA "supportedIdTypes" NA The digital identifier types supported by the partner (for example, Google, Meta, Instagram). Required if ContactPointDigitalId is used as objectName in activationAttributes
## Guidelines to Prevent JSON Validation Errors - The apiName value can't contain spaces. - When outputGrouping is set to `PER_USER`, make sure that all the activation attributes are configured as identifiers by setting isIdentifier to true. - When outputGrouping is set to `PER_SEGMENT`, make sure that at least one attribute is an identifier by setting isIdentifier to true‌. - Specify the hash method as "hashMethod": "SHA256" in activationPlatformAdditionalMetadata when atleast one attribute is set to “applyHash” : true. - The array of fields in the activation target must contain at least one entry, but can’t exceed five entries. AccountId is a required field. Use the field "name": "AccountId" as provided in the sample JSON. Don’t update or remove this field. - If you’re including ContactPointDigitalId as objectName in the attributes list, provide the "PartnerSupportedIds" object in the activationPlatformAdditionalMetadata. Make sure that the destinationName for ContactPointDigitalId matches the destinationName specified in “partnerSupportedIds.” Don’t use Id, ID, or id as the destinationName for any of the activation attributes. - If the destinationName of an activationAttribute matches the destinationName of partnerSupportedIds, specify the objectName for such an activationAttribute as "objectName": "ContactPointDigitalId". - If partnerSupportedIds is defined, specify the supportedIdTypes, and don't enter null for the destinationName field. - At least one supportedIdTypes must be retained when updating the JSON. ![Important](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-data-data_cloud-264-0-0-production-enus/f3569962-3c9b-4f83-9d0c-b6a574e785da/images/icon_important.png) Important After creating the package and setting up the activation platform, don't update the JSON to change `outputGrouping`, `destinationName`, or remove activation attributes or `supportedIdTypes`. These changes could impact existing customers who have already set up activations using these configurations. ## Best Practices and Recommendations - For email data normalization to work, set the preferred destinationName for email to EmailAddress(case-sensitive). - Set "applyHash" : true at each attribute level if you want to hash the user identifier values for attributes such as email and phone. - After activation, certain folders are automatically created in the Amazon S3 bucket with the preferred destinationName. However, when the Contact Point Digital Id DMO is used, the values specified by the ISV partner in the supportedIdTypes field are used as folder names. - For optimal performance, it's recommended not to exceed 512 MB for maxFileSizeInMB. If this optional field isn't configured, it defaults to 128 MB. - It's recommended to not exceed 5,000,000 maxRecordsPerFile. If this optional field isn't configured, the system defaults to 1,000,000 records. - Including maxFileSizeInMB and maxRecordsPerFile values make sure that each output file stays within the specified size and record count limits. - Make sure that minRecordsPerFile is less than or equal to maxRecordsPerFile, if configured. - The outputPartitions controls the number of files generated in the output location per activation run. When output is grouped by segment, the outputPartitions defined in the JSON is applied per segment publish, which is considered ‌an activation run. See [Find External Activation Platform Segments in Cloud File Storage](https://help.salesforce.com/s/articleView?id=data.c360_a_package_external_activation_platform_find_metadata.htm&release=264.0.0&type=5 "After admins install your external activation platform, you can receive segments to Cloud File Storage (Amazon S3). For each activation target, you receive a success file, metadata file, and activation output files once a day for each identifier type when the output is grouped by user identifiers (PER_USER). Because files arrive only once a day, there’s a delay between Data 360 customers updating segments and those changes arriving to S3.") for more information. - When the platform output is grouped per user identifier, then the 24-hour refresh frequency is considered as an activation run for each activation target created by the customer. See [Find External Activation Platform Segments in Cloud File Storage](https://help.salesforce.com/s/articleView?id=data.c360_a_package_external_activation_platform_find_metadata.htm&release=264.0.0&type=5 "After admins install your external activation platform, you can receive segments to Cloud File Storage (Amazon S3). For each activation target, you receive a success file, metadata file, and activation output files once a day for each identifier type when the output is grouped by user identifiers (PER_USER). Because files arrive only once a day, there’s a delay between Data 360 customers updating segments and those changes arriving to S3.") for more information. - outputPartitions and minRecordsPerFile determine how data is divided into partitions. If outputPartitions is set, it takes precedence. Otherwise, partitions are calculated based on minRecordsPerFile and the total number of records in all the output files. If the outputPartitions field isn't configured, the total record count is divided by minRecordsPerFile value to calculate the number of partitions. - In the PartnerSupportedIds section, include under supportedIdTypes only those attributes that are mapped to ContactPointDigitalId in the activationAttributes section. For example, exclude email and phone attributes from supportedIdTypes if they aren’t mapped to ContactPointDigitalId. ![Note](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-data-data_cloud-264-0-0-production-enus/f3569962-3c9b-4f83-9d0c-b6a574e785da/images/icon_note.png) Note When the exportDirectory is set to `"exportDirectory": "/"`, activation files are uploaded to the root directory of the specified S3 bucket. A date-based folder structure is automatically created and maintained to organize the exported files.