DME API

The DME API enables querying data from a Data Model Extension (DME) using filters and retrieving a specified number of records. This is particularly useful for scenarios where you need to enrich or personalize content using trusted, first-party data—such as customer attributes, historical orders, or audience segments.

Syntax

1
2
3
var resArray = dme.getDme(dmeName)
    .withQueryFilter(field, operator, value)
    .invoke(recordCount);

Method Description

Function Example

Example: Fetching a Customer's Favorite Brands

This script fetches up to 10 favorite brands for a specific user, using DME as a trusted data source for personalized content.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// Retrieves up to 10 favorite brands for a given user from the DME.
function getFavoriteBrands_main(userId) {
  var output = {};

  try {
    // Query the DME for the user's favorite brands
    var dmeData = dme.getDme("user_favorites")
      .withQueryFilter("user_id", "=", userId)
      .invoke(10);

    // Extract and return the data array, or an empty list if none    
    output.data = dmeData.data ? dmeData.data : [];
  } catch (error) {    
    console.log("[getFavoriteBrands_main] DME call failed:"+ error);
    output.data = [];
  }

    console.log("[getFavoriteBrands_main] Output:"+ output);
  return output;
}

What this example shows:

• Dynamically builds a DME query using the provided user ID.

• Limits the response to 10 records for efficiency.

• Returns a clean data array, ready for use in personalized Active Content.

Using Filters in Queries

The withQueryFilter() method is used to filter records based on specific field values.

Filter Parameters

• field: Represents a column in the specified DME.

• operator: Defines the comparison condition.

  • For text fields: =, !=, like, starts with, ends with.

  • For integer or float fields: =, !=.

  • For dateTime fields: =, !=.

• value: Specifies the comparison value.

Example - Querying User Favorites

1
2
3
var results = dme.getDme("user_favorites")
    .withQueryFilter("user_id", "=", "12345")
    .invoke(10);

• Fetches data from the user_favorites DME.

• Filters results where user_id = "12345".

• Retrieves up to 10 records.

Note: A maximum of 50 records can be retrieved per request. Setting a higher value will result in an error.

Sorting Results

To sort your DME results, use one of these methods:

Joining API Response Data with the DME Data

You can merge results from an external API with DME fallback data, ensuring robust data delivery even if your primary source is unavailable or incomplete.

1
2
3
4
5
var response = app.join(apiData, dmeData).data;
response.forEach(function(item) {
  apiData = apiData.concat(item);
});

• apiData and dmeData are arrays of records.

• app.join() merges these arrays, ensuring de-duplication and completeness.

Handling API Responses

Response Structure

The DME API returns the query results as a JSON object.

General Response Structure

1
2
3
4
5
6
7
8
{
  "data": [
    {
      "data1": "value1",
      "data2": "value2"
    }
  ]
}

• data: Contains the array of records matching the query filters.

Note: If no records match the filters, the data object will be empty.

Sample DME API Response

Success Response Example

1
2
3
4
5
6
7
8
9
10
11
{
  "dmedata": {
    "data": [
      {
        "user_id": "12345",
        "favorite_brand": "Brand1",
        "last_accessed_brand": "Brand2"
      }
    ]
  }
}

The response contains user preference details, such as favorite_brand and last_accessed_brand.

Failure Case

Note: If no records match the specified filter, the response will be an empty object