Data Extension API Object

Home Page

Data Extension API Object: A Comprehensive Guide

Introduction:

In the era of data-driven decision-making, the Data Extension API object emerges as a powerful ally for organizations seeking to expand and enhance their datasets. This comprehensive guide will take you through key attributes of the Data Extension API object, unraveling its functionality and showcasing how each element contributes to seamless data extension processes.

1. Name and Description: Laying the Foundation

Attribute	Type	Description
Name	string	The name of the Data Extension.
Description	string	A description providing additional information about the Data Extension.

2. Sendability and Testability: Ensuring Data Effectiveness

Attribute	Type	Description
IsSendable	boolean	Indicates whether the Data Extension is sendable.
IsTestable	boolean	Specifies whether the Data Extension is testable.

3. Sendable Fields and Template: Crafting Precision in Communication

Attribute	Type	Description
SendableDataExtensionField	DataExtensionField	Specifies the field determining sendability, adding granularity to communication strategies.
Template	DataExtensionTemplate	The 'Template' attribute refers to the associated Data Extension template, streamlining structure and management.

4. Data Retention: Balancing Storage and Compliance

Attribute	Type	Description
DataRetentionPeriodLength	int	Denotes the length of the data retention period, indicating how long data will be stored.
RowBasedRetention	boolean	Indicates whether row-based retention is applied, offering nuanced control over data lifecycle management.

5. Miscellaneous Attributes: Configuring Additional Settings

Attribute	Type	Description
ResetRetentionPeriodOnImport	boolean	Determines whether to reset the retention period on import, tailoring data management strategies.
DeleteAtEndOfRetentionPeriod	boolean	Specifies whether data should be automatically deleted at the end of the retention period.
RetainUntil	string	Sets a date until which data should be retained, defining precise timelines for data persistence.

6. Data Extension Fields and Categorization: Enhancing Granularity

Attribute	Type	Description
Fields	ComplexType	Represents a collection of Data Extension fields, providing building blocks for data organization.
CategoryID	long	Identifies the category to which the Data Extension belongs, facilitating efficient data retrieval.

SSJS : Data Extension Properties Retrieve

SSJS block to retrieve a data extension properties

<script runat="server">
  // Load the Core library with version 1
  Platform.Load("Core", "1");
  try {
    // Retrieve the Data Extension details based on CustomerKey
    var results = DataExtension.Retrieve({
      Property: "CustomerKey",
      SimpleOperator: "equals",
      Value: "IGO_PRODUCTS"
    });

    // Output the retrieved Data Extension details
    // Display the name of the Data Extension
    Write("Name: " + results[0].Name + '\n');
    // Display the description of the Data Extension
    Write("Description: " + results[0].Description + '\n');
    // Display whether the Data Extension is sendable
    Write("IsSendable: " + results[0].IsSendable + '\n');
    // Display whether the Data Extension is testable
    Write("IsTestable: " + results[0].IsTestable + '\n');
    // Display the CategoryID of the Data Extension
    Write("CategoryID: " + results[0].CategoryID + '\n');
    // Display whether the Data Extension is a platform object
    Write("IsPlatformObject: " + results[0].IsPlatformObject + '\n');
    // Display the CustomerKey of the Data Extension
    Write("CustomerKey: " + results[0].CustomerKey + '\n');
    // Display the creation date of the Data Extension
    Write("CreatedDate: " + results[0].CreatedDate + '\n');
    // Display the last modified date of the Data Extension
    Write("ModifiedDate: " + results[0].ModifiedDate + '\n');
    // Display the ObjectID of the Data Extension
    Write("ObjectID: " + results[0].ObjectID + '\n');
    // Display the status of the Data Extension
    Write("Status: " + results[0].Status + '\n');
    // Display the Client ID associated with the Data Extension
    Write("Client Id: " + results[0].Client.ID + '\n');
  } catch (ex) {
    // Handle any exceptions and output the error details
    // Display the error message
    Write("Error Message: " + ex.message + '\n');
    // Display the error description
    Write("Error Description: " + ex.description + '\n');
  }
</script>
                

Explanation of Script

This script is written in JavaScript and is intended to be run on the Salesforce Marketing Cloud platform using the server-side scripting language supported by the platform.

Let's break down the key components of the script:

1. Script Tag:

   The script is enclosed within a

   <script runat="server"></script>

   tag, indicating that it is meant to be executed on the server side.

2. Load Core Library:

   The line

   Platform.Load("Core", "1");

   loads the Core library with version 1, providing fundamental functionalities for server-side scripting.

3. Try-Catch Block:

   The script is wrapped in a

   try-catch

   block. The try block contains the main logic, and if any errors occur, they are caught and handled in the catch block.

4. Retrieve Data Extension Details:

   The script uses

   DataExtension.Retrieve

   to fetch details of a Data Extension with the CustomerKey "IGO_PRODUCTS".

5. Output Data Extension Details:

   Various details of the retrieved Data Extension, such as Name, Description, IsSendable, etc., are output using the

   Write

   function.

6. Handle Exceptions:

   If an exception occurs, the catch block handles and outputs the error message and description.

This script interacts with Data Extensions in the Salesforce Marketing Cloud environment to retrieve and display specific details.

7. DataExtensionFieldType:

Value
Text
Number
Date
Boolean
EmailAddress
Phone
Decimal
Locale
Base16Encrypted
Base16EncryptedEmail

Write an SSJS block to create a data extension

<script runat="server">
  // Load the Core library with version 1
  Platform.Load("Core", "1");

  try {
    // Define the properties of the Data Extension to be created
    var deObj = {
      "CustomerKey": "Example8",
      "Name": "Example8",
      "Fields": [
        { "Name": "AccountID", "FieldType": "Number","IsPrimaryKey" : true, "IsRequired" : true,"Ordinal" : 1 },
        { "Name": "OYBAccountID", "FieldType": "Number", "IsRequired" : true ,"Ordinal" : 2},
        { "Name": "JobID", "FieldType": "Number", "IsRequired" : true,"Ordinal" : 3 },
        { "Name": "ListID", "FieldType": "Number", "IsRequired" : true ,"Ordinal" : 4},
        { "Name": "BatchID", "FieldType": "Number","DefaultValue":1234 },
        { "Name": "SubscriberID", "FieldType": "Number"},
        { "Name": "SubscriberKey", "FieldType": "Text", "MaxLength": 254,"IsPrimaryKey" : true, "IsRequired" : true },
        { "Name": "EventDate", "FieldType": "Date" },
        { "Name": "Domain", "FieldType": "Text", "MaxLength": 128 },
        { "Name": "TriggererSendDefinitionObjectID", "FieldType": "Text", "MaxLength": 36 },
        { "Name": "TriggeredSendCustomerKey", "FieldType": "Text", "MaxLength": 36,"StorageType":"Plain" },
        {"Name": "EncryptedAccountID", "FieldType": "Base16Encrypted","IsEditable":false},
        {"Name": "EncryptedEmail", "FieldType": "Base16EncryptedEmail" }
      ],
      SendableInfo : {
        Field : { "Name" : "SubscriberKey", "FieldType" : "Text" },
        RelatesOn : "Subscriber Key"
    },
      "IsTestable": true
    };

    // Create the Data Extension
    var myDE = DataExtension.Add(deObj);

    // Output the created Data Extension details
    Write(Stringify(myDE));
  } catch (ex) {
    // Handle any exceptions and output the error details
    Write("Error Message: " + ex.message + '\n');
    Write("Error Description: " + ex.description + '\n');
  }
</script>     
    

Write an SSJS block to add a new attribute to a data extension

        
 <script runat="server">
  // Load the Core library with version 1
  Platform.Load("Core", "1");

  try {
    // Initialize a Data Extension object named 'Example10'
    var de = DataExtension.Init('Example10');

    // Define the properties of a new field to be added
    var newField = {
      Name: "NewFieldV2",
      CustomerKey: "NewFieldV2",
      FieldType: "Number",
      IsRequired: true,
      DefaultValue: "100"
    };

    // Add the new field to the Data Extension
    var status = de.Fields.Add(newField);

    // Output the created Data Extension details
    Write(Stringify(status));
  } catch (ex) {
    // Handle any exceptions and output the error details
    Write("Error Message: " + ex.message + '\n');
    Write("Error Description: " + ex.description + '\n');
  }
</script>
        
    

Write an SSJS block to add a update attribute to a data extension

        
<script runat="server">
  // Load the Core library with version 1
  Platform.Load("Core", "1");

  try {
    // Initialize a Data Extension object named 'Example10'
    var de = DataExtension.Init('Example10');

    // Define the properties of a new field
    var field = {
      "Name": "NewFieldV2",
      "DefaultValue": "200",
      "ObjectID": null
    }

    // Retrieve all fields from the Data Extension
    var fields = de.Fields.Retrieve();

    // Find the ObjectID of the field to be updated
    for (var i in fields) {
      if (fields[i].Name == field.Name) field.ObjectID = fields[i].ObjectID;
    }

    // Define attributes for the Data Extension update
    var attrs = {
      CustomerKey: 'Example10', // Replace 'customerKey' with the actual customer key
      Fields: [field]
    };

    // Update the Data Extension with the new field
    var result = de.Update(attrs);
    Write(Stringify(result));
  } catch (ex) {
    // Handle any exceptions and output the error details
    Write("Error Message: " + ex.message + '\n');
    Write("Error Description: " + ex.description + '\n');
  }
</script>
        
    

Write WS-Proxy to rename the Data Extension Name

        
 <script runat="server" language="javascript">
    // Load the Core library with version 1
    Platform.Load("core", "1");

    try {
        // Create a WSProxy object for making SOAP API calls
        var prox = new Script.Util.WSProxy();

        // Specify the CustomerKey of the Data Extension to be updated
        var CustomerKey = "Example7";

        // Specify the new name for the Data Extension
        var name = "Renamed DE";

        // Update the Data Extension using WSProxy
        var res = prox.updateItem("DataExtension", {
            "CustomerKey": CustomerKey,
            "Name": name
        });

        // Output the result of the update
        Write(Stringify(res));
    } catch (e) {
        // Handle any exceptions and output the error details
        Write(e.message);
    }
</script>
        
    

Conclusion:

In the intricate landscape of data extension, the Data Extension API object emerges as a linchpin, enabling organizations to tailor and expand their datasets with precision. By understanding and leveraging the attributes discussed in this guide, businesses can embark on a journey of enhanced data management, ensuring that their extended datasets not only meet compliance standards but also serve as valuable assets in the quest for actionable insights and informed decision-making. The Data Extension API object, with its rich set of attributes, opens up a world of possibilities for organizations striving to master the art of data extension in a dynamic and data-rich environment.

TOP