Datarelation API

This method returns a list of all available data relations that are available to the logged in account. Each returned entry contains informations about the parameters that are required to use the data relation as well as informations about the data relations capabilities.

Parameters:

• doneCallback - A callback method that will be executed in case no network or server error occured.
• failCallback - A callback method that will be executed in case a network or server error occured.

Structure of the result object (In JSON notation):

  
[
  {
    "type" : "Leads",                                     //The internal unique identifier that identifies the data relation inside the cross media system
    "displayName" : "Internal Database",                  //The display name for the data relation that is shown inside the CrossMedia Designer
    "description" : "Provides access to all stored ...",  //A short description about the purpose of this data relation
    "idColumnName" : "xmediaID",                          //The column name of the primary ID of each table that is returned by this data relation.
    "lastChangeDateColumnName" : "",                      //In case the data relations backend supports change tracking, the name of the column that contains the date of the last change for each record.
    "supportsButtonActions" : false,                      //Indicator if this data relation is able to expose some methods that can be executed by the end user.
    "supportsRecordCreation" : true,                      //Indicates if this data relation supports the creation of new records
    "supportsRecordWriting" : true,                       //Indicator that specifies if the data relation is able to update existing records
    "supportsRecordDeletion" : true,                      //Indicator if the data relation supports deletion of existing records
    "supportsFiltering" : true,                           //Indicator if the data relation supports filtering of records inside count and get calls
    "supportsOrderby" : true,                             //Indicator if the data relation supports sort ordering inside get calls
    "supportsPaging" : true,                              //Indicator if the data relation supports paging of results inside get calls
    "supportsEventWriting" : true,                        //Indicates if the data relation supports events that can be forwarded to the data relation
    "supportsColumnCreation" : true,                      //Indicator if the data relation supports the creation of new columns on tables that are exposed by the data relation.
    "supportsColumnDeletion" : true,                      //Indicates if the data relation supports the deletion of existing columns on tables that are exposed by the data relation.
    "parameters" : [                                      //Represents a list of parameters (e.g. user name, password etc) that are required by the data relation.
              {
                "name" : "Username",                      //The internal name for this parameter
                "displayName" : "User name",              //The display name that should be displayed inside the designer
                "defaultValue" : "",                      //The default value that should be displayed during data relation creation.
                "description" : "Login user name",        //A short description of this parameter
                "isPassword" : false,                     //Indicator if this parameter is a password (The characters will be hidden inside the designer)
              },
              {
                "name" : "Password",                      //The internal name for this parameter
                "displayName" : "Password",               //The display name that should be displayed inside the designer
                "defaultValue" : "",                      //The default value that should be displayed during data relation creation.
                "description" : "Login password",         //A short description of this parameter
                "isPassword" : true,                      //Indicator if this parameter is a password (The characters will be hidden inside the designer)
              }
             ],
    "buttonActions" : [                                   //A list, describing each button action that is exposed by that data relation.
                {
                  "name" : "ButtonAction1",               //The name of this button action
                  "description" : "Action1",              //A short description about what this button action does
                  "parameters" : [                        //A list of parameters that have to be provided to the button action
                            {
                              "name" : "Param1",          //The name of this parameter
                              "defaultValue" : "Param1",  //The default value for this parameter
                              "isPickList" : true,        //This parameter is set to true if this parameter only accepts one specific value of a list of given values (drop down)
                              "pickListValues" : ["Value1", "Value2"]  //If the parameter is a picklist value, this array will contain all values that are accepted by this parameter
                            }
                          ]
                }
            ]
  }
  {
    "type" : "countries",
    ...
  }
]

Example:

  
//The callback that will be executed in case no network or server errors occured
var successCallback = function(result) {
  //Check if everything was ok
  if(result.state == 0) {
    //iterate through all returned data relations and display their name
	var message = '';//The final result message that will be displayed

	for(var i = 0; i < result.responseObject.length; ++i) {
	  message += '[' + result.responseObject[i].type + '] ' + result.responseObject[i].displayName + "\r\n";
    }
	
	//display the result
	alert(message);
  } else {
	//There was an error while executing our request, display it.
	alert('Error while trying to execute statement: [' + result.failureDetail + '] ' + result.failureMessage);
  }
};

//The callback that will be executed in case of network / server errors
var failedCallback = function(result) {
  alert("Unable to execute method due to network related problems: \r\n" + JSON.stringify(result));
};

//Ask the server to return all data relations that are available
dsmx.api.datarelations.admin.getMetaData(successCallback, failedCallback);

This method returns a list of all tables that are exported by a given data relation

Parameters:

• dataRelationSettings

  An object containing all the settings that are required for a specified data relation:

    
  {
    "relationType" : "Leads",                               //The type of the data relation (not the display name, see getMetaData)
    "relationParameters" : {                                //The parameters that are reuqired for the data relation that is specified inside relationType (see getMetaData for required parameters)
                              "UserName" : "MyUser",
                              "Password" : "MyPassword"
                           },
    "campaignName" : "MyCampaign"                           //All data relation methods requires a campaign context (even if not used by the data relation itself, so we have to provide a campaig n name here).
  }
  

• doneCallback - A callback method that will be executed in case no network or server error occured.
• failCallback - A callback method that will be executed in case a network or server error occured.

Structure of the result object (In JSON notation):

  
[
  {
    "tableName" : "DefaultDatabase",                    //The name of the table
    "columns" : [                                       //A list of column descriptions that are vailable for this column
        {
          "name" : "xmediaID",                          //The name of the column
          "type" : "string",                            //The data type of this column
                                                        //Can be one of the following:
                                                        //string, int, float, bool, datetime, select
          "contentType" : "Undefined",                  //Some hint about the content of this column. Default value is "Undefined".
                                                        //Available content types:
                                                        //Undefined, Firstname, Lastname, City, Postcode, Country, State,
                                                        //AddressLine1, AddressLine2, AddressLine3, Email, DoNotEmail
          "possibleValues" : ["Option1", "Option2"],    //An array containing all values that are excepted by this column in case this column is of type select.
          "isNullable" : false,                         //Indicator if this column accepts null values
          "isRequiredForRecordCreation" : false,        //Indicator if a value for this field has to be provided while creating new records
          "isEditable" : false,                         //Indicator if this field is readonly
          "isAllowedInsideFilters" : true,              //Indicator if this field could be used inside filters
          "defaultSelectKey" : "Option1",               //The default value for select fields
          "isPrimaryColumn" : true                      //Indicates if this field contains the primary key
        }
                ]
  }
]

Example:

  
//Data relation specific settings
var dataRelationSettings = {
  "relationType" : "Leads",           //We are using the Internal Database data relation here
  "campaignName" : "WebAPIDocumentation" //We need to provide a camapign name to all data relations
//No more settings are required for the getTableNames method since the Internal Database relation
//does not require any more parameters like username or password
};

//The callback that will be executed in case of network errors
var failCallback = function() {
  //Just show an error message here
  alert('Unable to retrieve list of available tables');
};

//The callback  that will be executed in case there were no network or similar errors
var successCallback = function(result) {
  //Check if there was somethin gwrong with our call (wrong parameters etc)
  if(result.state != 0) {
    //There was an error, display the error details
    alert('[' + result.failureDetail + '] ' + result.failureMessage); 
  } else {
    //Everything went fine, so show a message that displays Tables, their columns and the corresponding data type
    var displayMessage = '';
    
    //collect all table names
    for(var i = 0; i < result.responseObject.length; ++i) {
      var currentTable = result.responseObject[i];
      
      displayMessage += currentTable.tableName + ':' + "\r\n";
      
      //Collect all column names and their data type
      for(var j = 0; j < currentTable.columns.length; ++j) {
        var column = currentTable.columns[j];
        
        displayMessage += "\t" + column.name + ' [' + column.type + "]\r\n";
      }
    }
    
    //Show the result
    alert(displayMessage);
  }
};

//Start retrieving the tables
dsmx.api.dataRelations.admin.getTables(dataRelationSettings, successCallback, failCallback);

Returns a list of all table names that are exported by a specified data relation.

Parameters:

• dataRelationSettings

  An object containing all the settings that are required for a specified data relation:

    
  {
    "relationType" : "Leads",                               //The type of the data relation (not the display name, see getMetaData)
    "relationParameters" : {                                //The parameters that are reuqired for the data relation that is specified inside relationType (see getMetaData for required parameters)
                              "UserName" : "MyUser",
                              "Password" : "MyPassword"
                           },
    "campaignName" : "MyCampaign"                           //All data relation methods requires a campaign context (even if not used by the data relation itself, so we have to provide a campaig n name here).
  }
  

• doneCallback - A callback method that will be executed in case no network or server error occured.
• failCallback - A callback method that will be executed in case a network or server error occured.

Structure of the result object (In JSON notation):

  
[
  "Table1",
  "Table2",
  "Table3"
]

Example:

  
//Data relation specific settings
var dataRelationSettings = {
  "relationType" : "Leads",	         //We are using the Internal Database data relation here
  "campaignName" : "WebAPIDocumentation" //We need to provide a camapign name to all data relations
//No more settings are required for the getTableNames method since the Internal Database relation
//does not require any more parameters like username or password
};

//The callback that will be executed in case of network errors
var failCallback = function() {
	//Just show an error message here
	alert('Unable to retrieve list of available table names');
};

//The callback  that will be executed in case there were no network or similar errors
var successCallback = function(result) {
	//Check if there was somethin gwrong with our call (wrong parameters etc)
	if(result.state != 0) {
		//There was an error, display the error details
		alert('[' + result.failureDetail + '] ' + result.failureMessage); 
	} else {
		//Everything went fine, so show a message that displays all table names
		var displayMessage = '';
		
		//collect all table names
		for(var i = 0; i < result.responseObject.length; ++i) {
			displayMessage += result.responseObject[i] + "\r\n";
		}
		
		//Show the result
		alert(displayMessage);
	}
};

//Start retrieving the tables
dsmx.api.dataRelations.admin.getTableNames(dataRelationSettings, successCallback, failCallback);

Returns a list of all available columns the are available for a given table.

Parameters:

• dataRelationSettings

  An object containing all the settings that are required for a specified data relation as well as the table name which columns should be returned.

    
  {
    "relationType" : "Leads",                               //The type of the data relation (not the display name, see getMetaData)
    "relationParameters" : {                                //The parameters that are reuqired for the data relation that is specified inside relationType (see getMetaData for required parameters)
                              "UserName" : "MyUser",
                              "Password" : "MyPassword"
                           },
    "campaignName" : "MyCampaign",                           //All data relation methods requires a campaign context (even if not used by the data relation itself, so we have to provide a campaig n name here).
    "tableName" : "DefaultDatabase"
  }
  

• doneCallback - A callback method that will be executed in case no network or server error occured.
• failCallback - A callback method that will be executed in case a network or server error occured.

Structure of the result object (In JSON notation):

  
[
    {
      "name" : "xmediaID",                       //The name of the column
      "type" : "string",                         //The data type of this column
                                                 //Can be one of the following:
                                                 //string, int, float, bool, datetime, select
      "contentType" : "Undefined",               //Some hint about the content of this column. Default value is "Undefined".
                                                 //Available content types:
                                                 //Undefined, Firstname, Lastname, City, Postcode, Country, State,
                                                 //AddressLine1, AddressLine2, AddressLine3, Email, DoNotEmail
      "possibleValues" : ["Option1", "Option2"],  //An array containing all values that are excepted by this column in case this column is of type select.
      "isNullable" : false,                      //Indicator if this column accepts null values
      "isRequiredForRecordCreation" : false,     //Indicator if a value for this field has to be provided while creating new records
      "isEditable" : false,                      //Indicator if this field is readonly
      "isAllowedInsideFilters" : true,           //Indicator if this field could be used inside filters
      "defaultSelectKey" : "Option1",            //The default value for select fields
      "isPrimaryColumn" : true                   //Indicates if this field contains the primary key
  }
]

Example:

  
//Data relation specific settings
var dataRelationSettings = {
  "relationType" : "Leads",	          //We are using the Internal Database data relation here
  "campaignName" : "WebAPIDocumentation", //We need to provide a camapign name to all data relations
  "tableName" : "DefaultDatabase"         //The name of the table wichs columns should be returned
//No more settings are required for the getColumns method since the Internal Database relation
//does not require any more parameters like username or password
};

//The callback that will be executed in case of network errors
var failCallback = function() {
	//Just show an error message here
	alert('Unable to retrieve list of available columns');
};

//The callback  that will be executed in case there were no network or similar errors
var successCallback = function(result) {
	//Check if there was something wrong with our call (wrong parameters etc)
	if(result.state != 0) {
		//There was an error, display the error details
		alert('[' + result.failureDetail + '] ' + result.failureMessage); 
	} else {
		//Everything went fine, so show a message that displays all the column names as well as their data type
		var displayMessage = '';
		
		//collect all columns
		for(var i = 0; i < result.responseObject.length; ++i) {
			displayMessage += result.responseObject[i].name + ' [' + result.responseObject[i].type + "]\r\n";
		}
		
		//Show the result
		alert(displayMessage);
	}
};

//Start retrieving the columns
dsmx.api.dataRelations.admin.getColumns(dataRelationSettings, successCallback, failCallback);

Returns a filtered set of records from a specified data relation.

Parameters:

• dataRelationSettings

  An object containing all the settings that are required for a specified data relation as well as the table name and the filter settings that should be used to return records.

    
  {
    "relationType" : "Leads",         //The type of the data relation
    "campaignName" : "MyCampaign",    //DataRelations need a campaign context
    "tableName" : "DefaultDatabase",  //The table name from which the records should be retrieved
    "relationParameters" : {	    //In case the data relation needs some parameters, they can be specified here
      "Param1" : "Value1",
      "Param2" : "Value2"
    },
    "query" : {                       //The filter settings that should be used
      "filter" : "",                  //The filter that should be used (See filter chapter)
      "currentPage" : 1,              //The number of the page that you would like to receive. The first page start at 1.
      "perPage" : 10,                 //The number of results per page (Ex. : a database with 100 records will have 10 pages if perPage is set to 10)
      "columns" : ["xmediaID","LpLogin"],  //A list of column names. To reduce network traffic and loading times, you can specify which columns you would like to retrieve.
                                           //To retrieve all available columns, specify a null value or an empty array here.
      "orderBy" : ["xmediaID"],       //A list of columns that should be used for sort ordering. A value of null or an empty arrayy will return the default sort order or unsorted results (depends on the data relation implementation)
      "descendingSortOrder" : false,  //false if the results should be returned in ascending sort order (default settings). true will return the results in descending sort order.
      "mode" : "data"                 //The data mode that should be used. "data" is the default one. In case the data relation supports distinct queries, "distinct" can be specified here.
    }
  }
  

• doneCallback - A callback method that will be executed in case no network or server error occured.
• failCallback - A callback method that will be executed in case a network or server error occured.

The results are returned as table object in the following format:

  
{
  "columns" : ["Column1","Column2","Column3"],          //A list of column names that are contained in this table. The index of each column name equals the index of the result inside each row array.
  "rows" : [                                            //An array containing all the rows.
    ["Column1Result","Column2Result","Column3Result"],  //Each row is represented as array of values. The name of each column can be evaluated by having a lookup to the columns array at the same index as the value.
    [1,2,3],
    [true,1,"somestring"]
  ]
}

Example:

  
//Data relation specific settings
var dataRelationSettings = {
  "relationType" : "Leads",         //In this example we are using the Internal Database data relation.
  "campaignName" : "WebAPIDocumentation",    //Use the current campaign as campaign context. This variable only works inside purls!
  "tableName" : "DefaultDatabase",  //We are using the DefaultDatabase Table. You will have to specify a table here that exists inside your account.
  "relationParameters" : null,		//The Internal DataRelation does not require any parameter.
  "query" : {                       //The filter settings that should be used
    "filter" : "(<|xmediaID|> > '0')",//The filter that should be used (See filter chapter)
    "currentPage" : 1,              //We would like to retrieve the first page
    "perPage" : 10,                 //We would like to have 20 results per page
    "columns" : ["xmediaID","EMail"],  //We only want to have the values for xmediaID and email
    "orderBy" : ["EMail"],       	   //We would like to sort the results by the email address
    "descendingSortOrder" : false,	   //we want to have an ascending sort order
    "mode" : "data"                 //We don't want to retrieve distinct values
  }
};

//The callback that will be executed in case of network errors
var failCallback = function() {
	//Just show an error message here
	alert('Unable to retrieve records');
};

//The callback  that will be executed in case there were no network or similar errors
var successCallback = function(result) {
	//Check if there was something wrong with our call (wrong parameters etc)
	if(result.state != 0) {
		//There was an error, display the error details
		alert('[' + result.failureDetail + '] ' + result.failureMessage); 
	} else {
		//Everything went fine, so show a message that displays all email addresses and their corresponding xmediaID
		
		//At first build a lookup object that we will use to retrieve the results by a given column name.
		var table = result.responseObject;
		var columnIndices = {};
		
		for(var i = 0; i < table.columns.length; ++i) {
			columnIndices[table.columns[i]] = i;
		}
		
		var displayMessage = '';
		
		//go through each row and read the xmediaID and the email address
		for(var row = 0; row < table.rows.length; ++row) {
			var currentRow = table.rows[row];
			
			displayMessage += currentRow[columnIndices["EMail"]] + " [" + currentRow[columnIndices["xmediaID"]] + "]\r\n";
		}
		
		//Show the result
		alert(displayMessage);
	}
};

//Start retrieving the records
dsmx.api.dataRelations.admin.get(dataRelationSettings, successCallback, failCallback);

Returns the number of records inside the data relation considering the provided filter.

Parameters:

• dataRelationSettings

  An object containing all the settings that are required for a specified data relation as well as the table name and the filter settings that should be used to return records.

    
  {
    "relationType" : "Leads",         //The type of the data relation
    "campaignName" : "MyCampaign",    //DataRelations need a campaign context
    "tableName" : "DefaultDatabase",  //The table name from which the records should be retrieved
    "relationParameters" : {	    //In case the data relation needs some parameters, they can be specified here
      "Param1" : "Value1",
      "Param2" : "Value2"
    },
    "query" : {                       //The filter settings that should be used
      "filter" : "",                  //The filter that should be used (See filter chapter)
      "mode" : "data"                 //The data mode that should be used. "data" is the default one. In case the data relation supports distinct queries, "distinct" can be specified here.
    }
  }
  

• doneCallback - A callback method that will be executed in case no network or server error occured.
• failCallback - A callback method that will be executed in case a network or server error occured.

The result consists of a single integer value.

Example:

  
//Data relation specific settings
var dataRelationSettings = {
  "relationType" : "Leads",         //In this example we are using the Internal Database data relation.
  "campaignName" : "WebAPIDocumentation",    //Use the current campaign as campaign context. This variable only works inside purls!
  "tableName" : "DefaultDatabase",  //We are using the DefaultDatabase Table. You will have to specify a table here that exists inside your account.
  "relationParameters" : null,		//The Internal DataRelation does not require any parameter.
  "query" : {                       //The filter settings that should be used
    "filter" : "(<|xmediaID|> > '0')",//The filter that should be used (See filter chapter)
    "mode" : "data"                 //We don't want to retrieve distinct values
  }
};

//The callback that will be executed in case of network errors
var failCallback = function() {
	//Just show an error message here
	alert('Unable to retrieve the record count');
};

//The callback  that will be executed in case there were no network or similar errors
var successCallback = function(result) {
	//Check if there was something wrong with our call (wrong parameters etc)
	if(result.state != 0) {
		//There was an error, display the error details
		alert('[' + result.failureDetail + '] ' + result.failureMessage); 
	} else {
		//Everything went fine, so show a message that displays the number of records
		alert('Number of records: ' + result.responseObject);
	}
};

//Start retrieving the record count
dsmx.api.dataRelations.admin.count(dataRelationSettings, successCallback, failCallback);

Updates one or more records inside a specified data relation.

Parameters:

• dataRelationSettingsAndTable

  An object containing the data relation settings, as well as a table that contains all the records that should be updatet.

    
  {
    "settings" : {                                            //The data relation specific settings
      "relationType" : "Leads",                               //The type of the data relation (not the display name, see getMetaData)
      "relationParameters" : {                                //The parameters that are reuqired for the data relation that is specified inside relationType (see getMetaData for required parameters)
                              "UserName" : "MyUser",
                              "Password" : "MyPassword"
                           },
      "campaignName" : "MyCampaign",                         //All data relation methods requires a campaign context (even if not used by the data relation itself, so we have to provide a campaign name here).
      "tableName" : "DefaultDatabase"                        //The name of the table in which the records should be updatet
    },
    "records" : {
      "columns" : ["xmediaID","Firstname","Lastname"],       //The column that contains the primary ID (xmediaID) and the columns that should be updated (Firstname, Lastname)
      "rows" : [                                             //An array containing all the records that should be updatet
  	  [1,"Mathilda","Denison"],                        //An array containing the primary id (xmediaID) in this case 1, and the values that should be updated (Firstname: Mathilda, Lastname: Denison)
  	  [22,"Dennis","Wright"],
  	  [13,"Craig","Spencer"]
      ]
    }
  }
  

• doneCallback - A callback method that will be executed in case no network or server error occured.
• failCallback - A callback method that will be executed in case a network or server error occured.

Example:

  
//Data relation specific settings as well as the records that should be updatet
var dataRelationSettingsAndTable = {
  "settings" : {                                            //The data relation specific settings
    "relationType" : "Leads",                               //The type of the data relation (not the display name, see getMetaData)
    "campaignName" : "WebAPIDocumentation",                 //All data relation methods requires a campaign context (even if not used by the data relation itself, so we have to provide a campaign name here).
    "tableName" : "DefaultDatabase"                         //The table name in which we would like to update records
  },
  "records" : {
    "columns" : ["xmediaID","Firstname","Lastname"],       //The column that contains the primary ID (xmediaID) and the columns that should be updated (Firstname, Lastname)
    "rows" : [                                             //An array containing all the records that should be updatet
	  [1,"Kelly","Rosario"]                            //An array containing the primary id (xmediaID) in this case 1, and the values that should be updated (Firstname: Kelly, Lastname: Rosario)
    ]
  }
};

//The callback that will be executed in case of network errors
var failCallback = function() {
	//Just show an error message here
	alert('Unable to update records');
};

//The callback  that will be executed in case there were no network or similar errors
var successCallback = function(result) {
	//Check if there was something wrong with our call (wrong parameters etc)
	if(result.state != 0) {
		//There was an error, display the error details
		alert('[' + result.failureDetail + '] ' + result.failureMessage); 
	} else {
		//Everything went fine, so show a message that the record was updated
		alert('Updated record successfully');
	}
};

//Start updating the record
dsmx.api.dataRelations.admin.update(dataRelationSettingsAndTable, successCallback, failCallback);

Creates one or more records on a specified data relation

Parameters:

• dataRelationSettingsAndTable

  An object containing the data relation settings, as well as a table that contains all the records that should be created.

    
  {
    "settings" : {                                            //The data relation specific settings
      "relationType" : "Leads",                               //The type of the data relation (not the display name, see getMetaData)
      "relationParameters" : {                                //The parameters that are reuqired for the data relation that is specified inside relationType (see getMetaData for required parameters)
                              "UserName" : "MyUser",
                              "Password" : "MyPassword"
                           },
      "campaignName" : "MyCampaign",                           //All data relation methods requires a campaign context (even if not used by the data relation itself, so we have to provide a campaign name here).
      "tableName" : "DefaultDatabase"                          //The table name in which the records should be created
    },
    "records" : {
      "columns" : ["EMail","Firstname","Lastname"],       //The columns thats values should be used for creating new records (EMail,Firstname, Lastname)
      "rows" : [                                       //An array containing all the records that should be created
  	  ["mathilda.denison@gmail.com","Mathilda","Denison"],  //An array containing the  values that should be used for record creation (EMail: mathilda.denison@gmail.com, Firstname: Mathilda, Lastname: Denison)
  	  ["dennis.wright@gmail.com","Dennis","Wright"],
  	  ["craigs@gmail.com","Craig","Spencer"]
      ]
    }
  }
  

• doneCallback - A callback method that will be executed in case no network or server error occured.
• failCallback - A callback method that will be executed in case a network or server error occured.

This method returns a list of primary ID's of each created record. The index of the primary ID equals the row index that was given inside the records table. In case some records could not be created, the list will contain a string "Failed" instead of the created ID.

Structure of the result object (In JSON notation):

  
[36,"Failed", 37]

Example:

  
//Data relation specific settings as well as the records that should be updatet
var dataRelationSettingsAndTable = {
  "settings" : {                                            //The data relation specific settings
    "relationType" : "Leads",                               //The type of the data relation (not the display name, see getMetaData)
    "campaignName" : "WebAPIDocumentation",                 //All data relation methods requires a campaign context (even if not used by the data relation itself, so we have to provide a campaign name here).
    "tableName" : "DefaultDatabase"                         //The table name in which we would like to create the records
  },
  "records" : {
    "columns" : ["EMail","Firstname","Lastname"],          //The column that contains the primary ID (xmediaID) and the columns that should be updated (Firstname, Lastname)
    "rows" : [                                             //An array containing all the records that should be updatet
	  ["firstcreatedrecord@gmail.com","FirstCreated","Record"],  //An array containing the values of the records that should be created (EMail: "firstcreatedrecord@gmail.com", Firstname: FirstCreated, Lastname: Record)
	  ["secondcreatedrecord@gmail.com","SecondCreated","Record"],
	  ["thirdcreatedrecord@gmail.com","ThirdCreated","Record"]
    ]
  }
};

//The callback that will be executed in case of network errors
var failCallback = function() {
	//Just show an error message here
	alert('Unable to update records');
};

//The callback  that will be executed in case there were no network or similar errors
var successCallback = function(result) {
  //Check if there was something wrong with our call (wrong parameters etc)
  if(result.state != 0) {
    //There was an error at least on one record, so iterate through the result list and display which records could not be created
    var succeededRecords = [];
    var failedRecords = [];

    //Check if we have a response object (if not, the error occured before trying to create records)
    if(result.responseObject != null && result.responseObject.length > 0) {
      for(var i = 0; i < result.responseObject.length; ++i) {
        if(result.responseObject[i] == "Failed") {
          //Display the data we used for creation
          failedRecords.push(dataRelationSettingsAndTable.records.rows[i][0] + "," + dataRelationSettingsAndTable.records.rows[i][1] + "," + dataRelationSettingsAndTable.records.rows[i][2]);
        }
        else {
          //Display the created primary id as well as the data we used for creation
          succeededRecords.push("[" + result.responseObject[i] + "] " + dataRelationSettingsAndTable.records.rows[i][0] + "," + dataRelationSettingsAndTable.records.rows[i][1] + "," + dataRelationSettingsAndTable.records.rows[i][2]);
        }
      }
    }
    
    var errorMessage = "";
    
    if(succeededRecords.length > 0) {
      errorMessage += "Succeeded records:\r\n";

      for(var i = 0; i < succeededRecords.length; ++i) {
        errorMessage += succeededRecords[i] + "\r\n";
      }
    }
    
    if(failedRecords.length > 0) {
      errorMessage += "Failed records:\r\n";

      for(var i = 0; i < failedRecords.length; ++i) {
        errorMessage += failedRecords[i] + "\r\n";
      }
    }

    errorMessage += "Error messages:\r\n";
    errorMessage += "[" + result.failureDetail + "] " + result.failureMessage + "\r\n";
    alert(errorMessage);
  } else {
    //Everything went fine, so show a message that the records were created:
    var message = "Succeeded records:\r\n";
    
    for(var i = 0; i < result.responseObject.length; ++i) {
      //Display the created primary id as well as the data we used for creation
      message += "[" + result.responseObject[i] + "] " + dataRelationSettingsAndTable.records.rows[i][0] + "," + dataRelationSettingsAndTable.records.rows[i][1] + "," + dataRelationSettingsAndTable.records.rows[i][2] + "\r\n";
    }
    
    alert(message);
  }
};

//Start creating the records
dsmx.api.dataRelations.admin.create(dataRelationSettingsAndTable, successCallback, failCallback);

Deletes a record on a specified data relation

Parameters:

• dataRelationSettings

  An object containing all the settings that are required for a specified data relation as well as the table name from which the record should be deleted.

    
  {
    "relationType" : "Leads",         //The type of the data relation
    "campaignName" : "MyCampaign",    //DataRelations need a campaign context
    "tableName" : "DefaultDatabase",  //The table name from which the records should be retrieved
    "relationParameters" : {	    //In case the data relation needs some parameters, they can be specified here
      "Param1" : "Value1",
      "Param2" : "Value2"
    }
  }
  

• recordId - The primary ID of the record that should be deleted
• doneCallback - A callback method that will be executed in case no network or server error occured.
• failCallback - A callback method that will be executed in case a network or server error occured.

Example:

  
var recordID = '12';//The ID of the record that should be deleted

//Data relation specific settings
var dataRelationSettings = {
    "relationType" : "Leads",                 //The type of the data relation (not the display name, see getMetaData)
    "campaignName" : "WebAPIDocumentation",   //All data relation methods requires a campaign context (even if not used by the data relation itself, so we have to provide a campaign name here).
    "tableName" : "DefaultDatabase"           //The table name in which we would like to delete the record
};

//The callback that will be executed in case of network errors
var failCallback = function() {
  //Just show an error message here
  alert('Unable to delete record');
};

//The callback  that will be executed in case there were no network or similar errors
var successCallback = function(result) {
  //Check if there was something wrong with our call (wrong parameters etc)
  if(result.state != 0) {
    alert('[' + result.failureDetail + '] ' + result.failureMessage)
  } else {
    alert('Deleted record successfully');
  }
};

//Start dleting the records
dsmx.api.dataRelations.admin.delete(dataRelationSettings, recordID, successCallback, failCallback);

Writes an event to the specified data relation.

Parameters:

• dataRelationSettingsAndEvent

  The settings object that contains the data rleation specific settings, as well as the settings for the event that should be written

    
  {
    "settings" : {                                            //The data relation specific settings
      "relationType" : "Leads",                               //The type of the data relation (not the display name, see getMetaData)
      "relationParameters" : {                                //The parameters that are reuqired for the data relation that is specified inside relationType (see getMetaData for required parameters)
                              "UserName" : "MyUser",
                              "Password" : "MyPassword"
                           },
      "campaignName" : "MyCampaign",                           //All data relation methods requires a campaign context (even if not used by the data relation itself, so we have to provide a campaign name here).
      "tableName" : "DefaultDatabase"                          //The table name to which the event should be written to  },
    "event" : {                                                //The event that should be written to the data relation
      "leadID" : "10",                                         //The record ID to which this event applies to
      "eventName" : "Visited",                                 //The event name
      "occuredOnUTC" : Date.now(),                             //The date and time at which this event happened
      "context" : "Event context",                             //The source of the event, e.g. The name of the purl that was vistied on a Visited event.
      "destination" : "Purl1",                                 //The event destination. In case of link click event the destination page name.
      "message" : "Some event message"                         //Some additional event message
    }
  }
  

• doneCallback - A callback method that will be executed in case no network or server error occured.
• failCallback - A callback method that will be executed in case a network or server error occured.

Example:

  
//Data relation specific settings and event config
var dataRelationSettingsAndEvent = {
  "settings" : {                                            //The data relation specific settings
    "relationType" : "Leads",                               //The type of the data relation (not the display name, see getMetaData)
    "relationParameters" : {                                //The parameters that are reuqired for the data relation that is specified inside relationType (see getMetaData for required parameters)
                            "UserName" : "MyUser",
                            "Password" : "MyPassword"
                         },
    "campaignName" : "WebAPIDocumentation",                  //All data relation methods requires a campaign context (even if not used by the data relation itself, so we have to provide a campaign name here).
    "tableName" : "DefaultDatabase"                          //The table name to which the event should be written to
  },
  "event" : {                                                //The event that should be written to the data relation
    "leadID" : "1",                                          //The record ID to which this event applies to
    "eventName" : "Visited",                                 //The event name
    "occuredOnUTC" : Date.now(),                             //The date and time at which this event happened
    "context" : "Event context",                             //The source of the event, e.g. The name of the purl that was vistied on a Visited event.
    "destination" : "Purl1",                                 //The event destination. In case of link click event the destination page name.
    "message" : "Some event message"                         //Some additional event message
  }
};

//The callback that will be executed in case of network errors
var failCallback = function() {
	//Just show an error message here
	alert('Unable to delete record');
};

//The callback  that will be executed in case there were no network or similar errors
var successCallback = function(result) {
  //Check if there was something wrong with our call (wrong parameters etc)
  if(result.state != 0) {
    alert('[' + result.failureDetail + '] ' + result.failureMessage)
  } else {
    alert('Event was written successful');
  }
};

//Start writing the event
dsmx.api.dataRelations.admin.event(dataRelationSettingsAndEvent, successCallback, failCallback);

Executes a button action on a specified data relation.

Parameters:

• dataRelationSettingsAndButtonAction

  An object containing the required settings for the data relation as well as the settings that specifies the button action and its required parameters.

    
  {
    "settings" : {                                            //The data relation specific settings
      "relationType" : "Leads",                               //The type of the data relation (not the display name, see getMetaData)
      "relationParameters" : {                                //The parameters that are reuqired for the data relation that is specified inside relationType (see getMetaData for required parameters)
                              "UserName" : "MyUser",
                              "Password" : "MyPassword"
                           },
      "campaignName" : "MyCampaign",                           //All data relation methods requires a campaign context (even if not used by the data relation itself, so we have to provide a campaign name here).
      "tableName" : "DefaultDatabase"                          //The table name to which the event should be written to
    },
    "name" : "ButtonActionName",                               //The name of the button action that should be executet.
    "parameters" : {                                           //In case the button action requires some parameters, their values can be specified here.
                                                               //See getMetaData to get a list of required parameters
                    "ParamName1" : "ParamValue",               //A parameter and its value
  	          "ParamName2" : "SomeOtherParamValue"
    }
  }
  

• doneCallback - A callback method that will be executed in case no network or server error occured.
• failCallback - A callback method that will be executed in case a network or server error occured.

Returns a list of data types that are supported for the creation of new columns in a specified table.

Parameters:

• dataRelationSettings

  The settings object that contains the data relation specific settings as well as the table name on which the column should be created.

    
  {  
      "relationType" : "Leads",                               //The type of the data relation (not the display name, see getMetaData)
      "relationParameters" : {                                //The parameters that are required for the data relation that is specified inside relationType (see getMetaData for required parameters)
                              "UserName" : "MyUser",
                              "Password" : "MyPassword"
                           },
      "campaignName" : "MyCampaign",                           //All data relation methods requires a campaign context (even if not used by the data relation itself, so we have to provide a campaign name here).
      "tableName" : "DefaultDatabase"                          //The table name on which the column should be created.
  }
  

• doneCallback - A callback method that will be executed in case no network or server error occured.
• failCallback - A callback method that will be executed in case a network or server error occured.

This methods returns a string array, containing all the supported data types for the provided Table.

Possible data types are:

• string
• int
• float
• bool
• datetime
• select

Structure of the result object (In JSON notation):

  
["string","float"]

Example:

  
//Data relation specific settings
var dataRelationSettings = {  
    "relationType" : "Leads",                               //The type of the data relation (not the display name, see getMetaData)
    "relationParameters" : {                                //The parameters that are required for the data relation that is specified inside relationType (see getMetaData for required parameters)
	                                                    //In case of the internal Database relation, no parameters are required. We keep them just for demonstration purposes
                            "UserName" : "MyUser",
                            "Password" : "MyPassword"
                         },
    "campaignName" : "WebAPIDocumentation",                  //All data relation methods requires a campaign context (even if not used by the data relation itself, so we have to provide a campaign name here).
    "tableName" : "DefaultDatabase"                          //The table name on which the column should be created.
};

//The callback that will be executed in case of network errors
var failCallback = function() {
  //Just show an error message here
  alert('Unable to retrieve list of data types');
};

//The callback  that will be executed in case there were no network or similar errors
var successCallback = function(result) {
  //Check if there was something wrong with our call (wrong parameters etc)
  if(result.state != 0) {
    alert('[' + result.failureDetail + '] ' + result.failureMessage)
  } else {
    if(result.responseObject == null || result.responseObject.length == 0) {
      alert("The table does not support column creation.");
    } else {
      var message = "Supported data types for column creation:\r\n";

      for(var i = 0; i < result.responseObject.length; ++i) {
        message += result.responseObject[i] + "\r\n";
      }
	
      alert(message);
    }
  }
};

//Start retrieving data types
dsmx.api.dataRelations.admin.getAvailableDataTypesForColumnCreation(dataRelationSettings, successCallback, failCallback);

Creates a new column on a specified data relations table.

Parameters:

• dataRelationSettings

  The settings object that contains the data relation specific settings as well as the table name on which the column should be created.

    
  {  
      "relationType" : "Leads",                               //The type of the data relation (not the display name, see getMetaData)
      "relationParameters" : {                                //The parameters that are required for the data relation that is specified inside relationType (see getMetaData for required parameters)
                              "UserName" : "MyUser",
                              "Password" : "MyPassword"
                           },
      "campaignName" : "MyCampaign",                           //All data relation methods requires a campaign context (even if not used by the data relation itself, so we have to provide a campaign name here).
      "tableName" : "DefaultDatabase"                          //The table name on which the column should be created.
  }
  

• columnName - The name of the new column.

• dataType

  The following data types are supported by this API:

  string

  int

  float

  bool

  datetime

  select

  All data types has to be provided as string. Examples:
  createColumn({}, 'MyColumn', 'string', 255, function() {}, function() {});
  createColumn({}, 'MyColumn', 'int', 0, function() {}, function() {});
  createColumn({}, 'MyColumn', 'bool', 0, function() {}, function() {});
  However, the select data type has to be treated diffrently.
  A select column needs to specify the values that are valid for this column. This can be done by passing an array of values to the createColumn method:
  createColumn({}, 'MyColumn', ['Value1','Value2'], 255, function() {}, function() {});
  In case you need a difffrent display value, this can be done by passing an object instead of an array (Display values must be supported by the data relation):
  var dataType = {
    "Value1" : "DisplayValue1",
    "Value2" : "DisplayValue2"
  };
  createColumn({}, 'MyColumn',dataType, 255, function() {}, function() {});
• length - In case of string columns, the maximum string length for this column. -1 for maximum possible size.
• doneCallback - A callback method that will be executed in case no network or server error occured.
• failCallback - A callback method that will be executed in case a network or server error occured.

Example:

  
//Data relation specific settings
var dataRelationSettings = {  
    "relationType" : "Leads",                               //The type of the data relation (not the display name, see getMetaData)
    "relationParameters" : {                                //The parameters that are required for the data relation that is specified inside relationType (see getMetaData for required parameters)
						            //In case of the internal Database relation, no parameters are required. We keep them just for demonstration purposes
                            "UserName" : "MyUser",
                            "Password" : "MyPassword"
                         },
    "campaignName" : "WebAPIDocumentation",                  //All data relation methods requires a campaign context (even if not used by the data relation itself, so we have to provide a campaign name here).
    "tableName" : "DefaultDatabase"                          //The table name on which the column should be created.
};

//The callback that will be executed in case of network errors
var failCallback = function() {
  //Just show an error message here
  alert('Unable to create column');
};

//The callback  that will be executed in case there were no network or similar errors
var successCallback = function(result) {
  //Check if there was something wrong with our call (wrong parameters etc)
  if(result.state != 0) {
    alert('[' + result.failureDetail + '] ' + result.failureMessage)
  } else {
    alert('Created column sucessfully');
  }
};

//Create a string column
dsmx.api.dataRelations.admin.createColumn(dataRelationSettings,'StringColumn', 'string', 255,successCallback, failCallback);

//Create an int column
//dsmx.api.dataRelations.admin.createColumn(dataRelationSettings,'IntegerColumn', 'int', 255,successCallback, failCallback);

//Create a select column without display values (Internal Database relation does not support string columns yet)
//dsmx.api.dataRelations.admin.createColumn(dataRelationSettings,'PicklistColumn1', ['Value1','Value2', 'Value3'], 255,successCallback, failCallback);
 
//Create a select column with display values (Internal Database relation does not support string columns yet)
//dsmx.api.dataRelations.admin.createColumn(dataRelationSettings,'PicklistColumn2', {"Value1" : "Display, Value1", "Value2" : "Display, Value2", "Value3" : "Display, Value3"}, 255,successCallback, failCallback);

Returns a list of columns that are available for deletion.

Parameters:

• dataRelationSettings

  The settings object that contains the data relation specific settings as well as the table name from which the column should be deleted.

    
  {  
      "relationType" : "Leads",                               //The type of the data relation (not the display name, see getMetaData)
      "relationParameters" : {                                //The parameters that are required for the data relation that is specified inside relationType (see getMetaData for required parameters)
                              "UserName" : "MyUser",
                              "Password" : "MyPassword"
                           },
      "campaignName" : "MyCampaign",                           //All data relation methods requires a campaign context (even if not used by the data relation itself, so we have to provide a campaign name here).
      "tableName" : "DefaultDatabase"                          //The table name from which the column should be deleted.
  }
  

• doneCallback - A callback method that will be executed in case no network or server error occured.
• failCallback - A callback method that will be executed in case a network or server error occured.

Structure of the result object (In JSON notation):

  
["Column1","Column2","Column3"]

Example:

  
//Data relation specific settings
var dataRelationSettings = {  
    "relationType" : "Leads",                               //The type of the data relation (not the display name, see getMetaData)
    "relationParameters" : {                                //The parameters that are required for the data relation that is specified inside relationType (see getMetaData for required parameters)
															//In case of the internal Database relation, no parameters are required. We keep them just for demonstration purposes
                            "UserName" : "MyUser",
                            "Password" : "MyPassword"
                         },
    "campaignName" : "WebAPIDocumentation",                           //All data relation methods requires a campaign context (even if not used by the data relation itself, so we have to provide a campaign name here).
    "tableName" : "DefaultDatabase"                          //The table name on which the column should be created.
};

//The callback that will be executed in case of network errors
var failCallback = function() {
  //Just show an error message here
  alert('Unable to retrieve list of deletable columns');
};

//The callback  that will be executed in case there were no network or similar errors
var successCallback = function(result) {
  //Check if there was something wrong with our call (wrong parameters etc)
  if(result.state != 0) {
    alert('[' + result.failureDetail + '] ' + result.failureMessage)
  } else {
    //Display the list of deletable columns
    var message = "The following columns can be deleted:\r\n";

    for(var i = 0; i < result.responseObject.length; ++i) {
	  message += result.responseObject[i] + "\r\n";
    }
	
    alert(message);
  }
};

//Start retrieving a list of deleteable columns
dsmx.api.dataRelations.admin.getDeleteableColumns(dataRelationSettings, successCallback,failCallback);

Deletes a column that is given by its name

Parameters:

• dataRelationSettings

  The settings object that contains the data relation specific settings as well as the table name from which the column should be deleted.

    
  {  
      "relationType" : "Leads",                               //The type of the data relation (not the display name, see getMetaData)
      "relationParameters" : {                                //The parameters that are required for the data relation that is specified inside relationType (see getMetaData for required parameters)
                              "UserName" : "MyUser",
                              "Password" : "MyPassword"
                           },
      "campaignName" : "MyCampaign",                           //All data relation methods requires a campaign context (even if not used by the data relation itself, so we have to provide a campaign name here).
      "tableName" : "DefaultDatabase"                          //The table name from which the column should be deleted.
  }
  

• columnName - The name of the column that should be deleted.
• doneCallback - A callback method that will be executed in case no network or server error occured.
• failCallback - A callback method that will be executed in case a network or server error occured.

Example:

  
//Data relation specific settings
var dataRelationSettings = {  
    "relationType" : "Leads",                               //The type of the data relation (not the display name, see getMetaData)
    "relationParameters" : {                                //The parameters that are required for the data relation that is specified inside relationType (see getMetaData for required parameters)
		                                            //In case of the internal Database relation, no parameters are required. We keep them just for demonstration purposes
                            "UserName" : "MyUser",
                            "Password" : "MyPassword"
                         },
    "campaignName" : "WebAPIDocumentation",                  //All data relation methods requires a campaign context (even if not used by the data relation itself, so we have to provide a campaign name here).
    "tableName" : "DefaultDatabase"                          //The table name on which the column should be created.
};

var columnName = 'txt_head1';                               //The column name of the column that should be deleted.

//The callback that will be executed in case of network errors
var failCallback = function() {
  //Just show an error message here
  alert('Unable to retrieve list of deletable columns');
};

//The callback  that will be executed in case there were no network or similar errors
var successCallback = function(result) {
  //Check if there was something wrong with our call (wrong parameters etc)
  if(result.state != 0) {
    alert('[' + result.failureDetail + '] ' + result.failureMessage)
  } else {
    alert('Deleted column successfully');
  }
};

//Start deleting the column
dsmx.api.dataRelations.admin.deleteColumn(dataRelationSettings, columnName, successCallback,failCallback);

This method returns a list of all data relations that are created inside the current campaign. Each returned entry contains informations about the data relation's capabilities.

Parameters:

• doneCallback - A callback method that will be executed in case no network or server error occured.
• failCallback - A callback method that will be executed in case a network or server error occured.

Structure of the result object (In JSON notation):

  
[
  {
    "dataRelationName" : "DefaultDatabase",           //The name that you gave to your data relation inside the campaign
    "type" : "Leads",                                 //The internal type of the data relation. The type is not required for campaign data relations.
    "displayName" : "Internal Database",              //The name of the data relation that is displayed inside The CrossMedia Designer during data relation creation.
    "description" : "...",                            //A short discription about what this data relation does.
    "idColumnName" : "xmediaID",                      //The name of the column that contains the primary ID of each record.
    "lastChangeDateColumnName" : "LastChangeDate",    //If supported by the data relation, the name of the column that contains the date of the last change of each record. (This value is empty in case the data relation does not support this field.)
    "mode" : "Data",                                  //The mode that the data relation is configured to use. Possible values are Data and Distinct
    "supportsButtonActions" : false,                  //Indicator if this data relation supports button actions.
    "supportsRecordCreation" : true,                  //Indicator if this data relation supports creation of records.
    "supportsRecordWriting" : true,                   //Indicator if this data relation supports updating of records.
    "supportsRecordDeletion" : true,                  //Indicator if this data relation supports deletion of records.
    "supportsFiltering" : = true,                     //Indicator if this data relation supports filtering. (In case the data relation does not support filters, the CrossMedia system tries to filter the records itself.)
    "supportsOrderby" : = true,                       //Indicator if this data relation supports order by statements. (In case the data relation does not support order by's, the CrossMedia system tries to order them.)
    "supportsPaging" : true,                          //Indicator if this data relation supports paging. (In case paging is not supported by the data relation, the CrossMedia system does the paging.)
    "supportsEventWriting" : true,                    //Indicator if this data relation supports the creation of events.
    "supportsColumnCreation" : true,                  //Indicator if this data relation supports the creation of columns.
    "supportsColumnDeletion" = true,                  //Indicator if this data relation supports the deletion of columns.
    "buttonActions" : [                               //A list, describing each button action that is exposed by that data relation.
    {
      "name" : "ButtonAction1",                      //The name of this button action
      "description" : "Action1",                     //A short description about what this button action does
      "parameters" : [                               //A list of parameters that have to be provided to the button action
        {
          "name" : "Param1",                         //The name of this parameter
          "defaultValue" : "Param1",                 //The default value for this parameter
          "isPickList" : true,                       //This parameter is set to true if this parameter only accepts one specific value of a list of given values (drop down)
          "pickListValues" : ["Value1", "Value2"]    //If the parameter is a picklist value, this array will contain all values that are accepted by this parameter
        }
      ]
    },
    "columns" : [                                     //A list of column descriptions that are vailable for this column
      {
        "name" : "xmediaID",                          //The name of the column
        "type" : "string",                            //The data type of this column
                                                      //Can be one of the following:
                                                      //string, int, float, bool, datetime, select
        "contentType" : "Undefined",                  //Some hint about the content of this column. Default value is "Undefined".
                                                      //Available content types:
                                                      //Undefined, Firstname, Lastname, City, Postcode, Country, State,
                                                      //AddressLine1, AddressLine2, AddressLine3, Email, DoNotEmail
        "possibleValues" : ["Option1", "Option2"],    //An array containing all values that are excepted by this column in case this column is of type select.
        "isNullable" : false,                         //Indicator if this column accepts null values
        "isRequiredForRecordCreation" : false,        //Indicator if a value for this field has to be provided while creating new records
        "isEditable" : false,                         //Indicator if this field is readonly
        "isAllowedInsideFilters" : true,              //Indicator if this field could be used inside filters
        "defaultSelectKey" : "Option1",               //The default value for select fields
        "isPrimaryColumn" : true                      //Indicates if this field contains the primary key
      }
    ]
  },
  {
   "dataRelationName" : "Countries",
   ...
  }
]

Example:

  
//The callback that will be executed in case of network errors
var failCallback = function() {
  //Just show an error message here
  alert('Unable to retrieve MetaData');
};

//The callback  that will be executed in case there were no network or similar errors
var successCallback = function(result) {
  //Check if there was something wrong with our call (wrong parameters etc)
  if(result.state != 0) {
    alert('[' + result.failureDetail + '] ' + result.failureMessage)
  } else {
    var message = "Available data relations:\r\n";
	
    for(var i = 0; i < result.responseObject.length; ++i) {
	  message += result.responseObject[i].dataRelationName;
    }
	
	alert(message);
  }
};

//Start retrieving a list of all available data relations
dsmx.api.dataRelations.getMetaData(successCallback,failCallback);

Returns a list of all data relation columns that are available to the current campaign.

Parameters:

• dataRelationName - The name of the data relation whichs columns should be returned.
• doneCallback - A callback method that will be executed in case no network or server error occured.
• failCallback - A callback method that will be executed in case a network or server error occured.

Structure of the result object (In JSON notation):

  
[
  {
    "name" : "Column1",                         //The name of the column
    "type" : "string",                          //The data type of this column
                                                //Can be one of the following:
                                                //string, int, float, bool, datetime, select
    "contentType" : "Undefined",                //Some hint about the content of this column. Default value is "Undefined".
                                                //Available content types:
                                                //Undefined, Firstname, Lastname, City, Postcode, Country, State,
                                                //AddressLine1, AddressLine2, AddressLine3, Email, DoNotEmail
    "possibleValues" : ["Value1","Value2"],     //An array containing all values that are excepted by this column in case this column is of type select.
    "isNullable" : true,                        //Indicator if this column accepts null values
    "isRequiredForRecordCreation" : false,      //Indicator if a value for this field has to be provided while creating new records
    "isEditable" : true,                        //Indicator if changes to this column are allowed
    "isAllowedInsideFilters" : "true",          //Indicator if this field could be used inside filters
    "defaultSelectKey" : "Value2",              //The default value for select fields
    "isPrimaryColumn" : false                   //Indicates if this field contains the primary key
  },
  {
    "name" : "Column1",
	...
  }
]

Example:

  
var dataRelationName = "DefaultDatabase";//The name of the data relation whose columns should be retrieved.

//The callback that will be executed in case of network errors
var failCallback = function() {
  //Just show an error message here
  alert('Unable to retrieve columns');
};

//The callback  that will be executed in case there were no network or similar errors
var successCallback = function(result) {
  //Check if there was something wrong with our call (wrong parameters etc)
  if(result.state != 0) {
    alert('[' + result.failureDetail + '] ' + result.failureMessage)
  } else {
    var message = "Available columns:\r\n";
	
    for(var i = 0; i < result.responseObject.length; ++i) {
      message += result.responseObject[i].name + "\r\n";
    }
	
    alert(message);
  }
};

//Start retrieving a list of all available columns
dsmx.api.dataRelations.getColumns(dataRelationName, successCallback,failCallback);

Returns a filtered set of records.

Parameters:

• dataRelationName - The name of the data relation inside the campaign.

• dataRelationQuery

  The filter settings that should be used for record retrieval.

    
  {                                   //The filter settings that should be used
      "filter" : "",                  //The filter that should be used (See filter chapter)
      "currentPage" : 1,              //The number of the page that you would like to receive. The first page start at 1.
      "perPage" : 10,                 //The number of results per page (Ex. : a database with 100 records will have 10 pages if perPage is set to 10)
      "columns" : ["xmediaID","LpLogin"],  //A list of column names. To reduce network traffic and loading times, you can specify which columns you would like to retrieve.
                                           //To retrieve all available columns, specify a null value or an empty array here.
      "orderBy" : ["xmediaID"],       //A list of columns that should be used for sort ordering. A value of null or an empty arrayy will return the default sort order or unsorted results (depends on the data relation implementation)
      "descendingSortOrder" : false,  //false if the results should be returned in ascending sort order (default settings). true will return the results in descending sort order.
      "mode" : "data"                 //The data mode that should be used. "data" is the default one. In case the data relation supports distinct queries, "distinct" can be specified here.
    }
  
  

• doneCallback - A callback method that will be executed in case no network or server error occured.
• failCallback - A callback method that will be executed in case a network or server error occured.

Structure of the result object (In JSON notation):

  
{
  "columns" : ["Column1","Column2","Column3"],          //A list of column names that are contained in this table. The index of each column name equals the index of the result inside each row array.
  "rows" : [                                            //An array containing all the rows.
    ["Column1Result","Column2Result","Column3Result"],  //Each row is represented as array of values. The name of each column can be evaluated by having a lookup to the columns array at the same index as the value.
    [1,2,3],
    [true,1,"somestring"]
  ]
}

Example:

  
var dataRelationName = "DefaultDatabase";//The name of the data relation whose columns should be retrieved.

//Data relation specific settings
var query = {
  "filter" : "(<|xmediaID|> > '0')",//The filter that should be used (See filter chapter)
  "currentPage" : 1,              //We would like to retrieve the first page
  "perPage" : 10,                 //We would like to have 20 results per page
  "columns" : ["xmediaID","EMail"],  //We only want to have the values for xmediaID and email
  "orderBy" : ["EMail"],       	   //We would like to sort the results by the email address
  "descendingSortOrder" : false,	   //we want to have an ascending sort order
  "mode" : "data"                 //We don't want to retrieve distinct values
}; 

//The callback that will be executed in case of network errors
var failCallback = function() {
  //Just show an error message here
  alert('Unable to retrieve records');
};

//The callback  that will be executed in case there were no network or similar errors
var successCallback = function(result) {
  //Check if there was something wrong with our call (wrong parameters etc)
  if(result.state != 0) {
    //There was an error, display the error details
    alert('[' + result.failureDetail + '] ' + result.failureMessage); 
  } else {
    //Everything went fine, so show a message that displays all email addresses and their corresponding xmediaID
		
    //At first build a lookup object that we will use to retrieve the results by a given column name.
    var table = result.responseObject;
    var columnIndices = {};
		
    for(var i = 0; i < table.columns.length; ++i) {
      columnIndices[table.columns[i]] = i;
    }
		
    var displayMessage = '';
		
    //go through each row and read the xmediaID and the email address
    for(var row = 0; row < table.rows.length; ++row) {
      var currentRow = table.rows[row];

      displayMessage += currentRow[columnIndices["EMail"]] + " [" + currentRow[columnIndices["xmediaID"]] + "]\r\n";
    }
		
    //Show the result
    alert(displayMessage);
  }
};

//Start retrieving the records
dsmx.api.dataRelations.get(dataRelationName, query, successCallback, failCallback);

Returns the record count of a filtered set of records.

Parameters:

• dataRelationName - The name of the data relation inside the campaign.

• dataRelationQuery

  The filter settings that should be used for record retrieval.

    
  {                                 //The filter settings that should be used
    "filter" : "",                  //The filter that should be used (See filter chapter)
    "mode" : "data"                 //The data mode that should be used. "data" is the default one. In case the data relation supports distinct queries, "distinct" can be specified here.
  }
  

• doneCallback - A callback method that will be executed in case no network or server error occured.
• failCallback - A callback method that will be executed in case a network or server error occured.

Example:

  
var dataRelationName = "DefaultDatabase";//The name of the data relation whose columns should be retrieved.

//Data relation specific settings
var query = {
  "filter" : "(<|xmediaID|> > '0')",//The filter that should be used (See filter chapter)
  "mode" : "data"                 //We don't want to retrieve distinct values
}; 

//The callback that will be executed in case of network errors
var failCallback = function() {
  //Just show an error message here
  alert('Unable to retrieve records');
};

//The callback  that will be executed in case there were no network or similar errors
var successCallback = function(result) {
  //Check if there was something wrong with our call (wrong parameters etc)
  if(result.state != 0) {
    //There was an error, display the error details
    alert('[' + result.failureDetail + '] ' + result.failureMessage); 
  } else {
    //Everything went fine, so show a message that displays the record count
    alert('The data relation contains ' + result.responseObject + ' records for the specified filter.');
  }
};

//Start retrieving the record count
dsmx.api.dataRelations.count(dataRelationName, query, successCallback, failCallback);

Updates one or more records inside a specified data relation.

Parameters:

• dataRelationName - The name of the data relation inside the campaign.

• dataRelationTable

  A table object that contains all the values for each record that should be updatet.

  The given table must contain the primary ID colum in order to update the correct records.

    
  {
    "columns" : ["xmediaID","Firstname","Lastname"],   //The column that contains the primary ID (xmediaID) and the columns that should be updated (Firstname, Lastname)
    "rows" : [                                         //An array containing all the records that should be updatet
      [1,"Mathilda","Denison"],                        //An array containing the primary id (xmediaID) in this case 1, and the values that should be updated (Firstname: Mathilda, Lastname: Denison)
      [22,"Dennis","Wright"],
      [13,"Craig","Spencer"]
    ]
  }
  

• doneCallback - A callback method that will be executed in case no network or server error occured.
• failCallback - A callback method that will be executed in case a network or server error occured.

Example:

  
var dataRelationName = "DefaultDatabase";//The name of the data relation whose columns should be retrieved.

//The records that should be updatet
var table = {
  "columns" : ["xmediaID","Firstname","Lastname"],       //The column that contains the primary ID (xmediaID) and the columns that should be updated (Firstname, Lastname)
  "rows" : [                                             //An array containing all the records that should be updatet
    [1,"Kelly","Rosario"]                                //An array containing the primary id (xmediaID) in this case 1, and the values that should be updated (Firstname: Kelly, Lastname: Rosario)
  ]
};

//The callback that will be executed in case of network errors
var failCallback = function() {
	//Just show an error message here
	alert('Unable to update records');
};

//The callback  that will be executed in case there were no network or similar errors
var successCallback = function(result) {
	//Check if there was something wrong with our call (wrong parameters etc)
	if(result.state != 0) {
		//There was an error, display the error details
		alert('[' + result.failureDetail + '] ' + result.failureMessage); 
	} else {
		//Everything went fine, so show a message that the record was updated
		alert('Updated record successfully');
	}
};

//Start updating the record
dsmx.api.dataRelations.update(dataRelationName, table, successCallback, failCallback);

Creates one or more records on a specified data relation.

Parameters:

• dataRelationName - The name of the data relation inside the campaign.

• dataRelationTable

  A table object that contains all the values for each record that should be created.

    
  {
    "columns" : ["EMail","Firstname","Lastname"],           //The columns thats values should be used for creating new records (EMail,Firstname, Lastname)
    "rows" : [                                              //An array containing all the records that should be created
      ["mathilda.denison@gmail.com","Mathilda","Denison"],  //An array containing the values that should be used for record creation (EMail: mathilda.denison@gmail.com, Firstname: Mathilda, Lastname: Denison)
      ["dennis.wright@gmail.com","Dennis","Wright"],
      ["craigs@gmail.com","Craig","Spencer"]
    ]
  }
  

• doneCallback - A callback method that will be executed in case no network or server error occured.
• failCallback - A callback method that will be executed in case a network or server error occured.

This method returns a list of primary ID's of each created record. The index of the primary ID equals the row index that was given inside the records table. In case some records could not be created, the list will contain a string "Failed" instead of the created ID.

Structure of the result object (In JSON notation):

  
[36,"Failed", 37]

Example:

  
var dataRelationName = "DefaultDatabase";//The name of the data relation whose columns should be retrieved.

//The recors that should be created
var table = {
  "columns" : ["EMail","Firstname","Lastname"],          //The column that contains the primary ID (xmediaID) and the columns that should be updated (Firstname, Lastname)
  "rows" : [                                             //An array containing all the records that should be updatet
    ["firstcreatedrecord@gmail.com","FirstCreated","Record"],  //An array containing the values of the records that should be created (EMail: "firstcreatedrecord@gmail.com", Firstname: FirstCreated, Lastname: Record)
    ["secondcreatedrecord@gmail.com","SecondCreated","Record"],
    ["thirdcreatedrecord@gmail.com","ThirdCreated","Record"]
  ]
};

//The callback that will be executed in case of network errors
var failCallback = function() {
	//Just show an error message here
	alert('Unable to create records');
};

//The callback  that will be executed in case there were no network or similar errors
var successCallback = function(result) {
  //Check if there was something wrong with our call (wrong parameters etc)
  if(result.state != 0) {
    //There was an error at least on one record, so iterate through the result list and display which records could not be created
    var succeededRecords = [];
    var failedRecords = [];

    //Check if we have a response object (if not, the error occured before trying to create records)
    if(result.responseObject != null && result.responseObject.length > 0) {
      for(var i = 0; i < result.responseObject.length; ++i) {
        if(result.responseObject[i] == "Failed") {
          //Display the data we used for creation
          failedRecords.push(table.rows[i][0] + "," + table.rows[i][1] + "," + table.rows[i][2]);
        }
        else {
          //Display the created primary id as well as the data we used for creation
          succeededRecords.push("[" + result.responseObject[i] + "] " + table.rows[i][0] + "," + table.rows[i][1] + "," + table.rows[i][2]);
        }
      }
    }
    
    var errorMessage = "";
    
    if(succeededRecords.length > 0) {
      errorMessage += "Succeeded records:\r\n";

      for(var i = 0; i < succeededRecords.length; ++i) {
        errorMessage += succeededRecords[i] + "\r\n";
      }
    }
    
    if(failedRecords.length > 0) {
      errorMessage += "Failed records:\r\n";

      for(var i = 0; i < failedRecords.length; ++i) {
        errorMessage += failedRecords[i] + "\r\n";
      }
    }

    errorMessage += "Error messages:\r\n";
    errorMessage += "[" + result.failureDetail + "] " + result.failureMessage + "\r\n";
    alert(errorMessage);
  } else {
    //Everything went fine, so show a message that the records were created:
    var message = "Succeeded records:\r\n";
    
    for(var i = 0; i < result.responseObject.length; ++i) {
      //Display the created primary id as well as the data we used for creation
      message += "[" + result.responseObject[i] + "] " + table.rows[i][0] + "," + table.rows[i][1] + "," + table.rows[i][2] + "\r\n";
    }
    
    alert(message);
  }
};

//Start creating the records
dsmx.api.dataRelations.create(dataRelationName, table, successCallback, failCallback);

Deletes a record on a specified data relation.

Parameters:

• dataRelationName - The name of the data relation inside the campaign.
• recordId - The primary ID of the record that should be deleted
• doneCallback - A callback method that will be executed in case no network or server error occured.
• failCallback - A callback method that will be executed in case a network or server error occured.

Example:

  
var dataRelationName = "DefaultDatabase";//The name of the data relation whose columns should be retrieved.
var recordID = '106';//The ID of the record that should be deleted

//The callback that will be executed in case of network errors
var failCallback = function() {
  //Just show an error message here
  alert('Unable to delete record');
};

//The callback  that will be executed in case there were no network or similar errors
var successCallback = function(result) {
  //Check if there was something wrong with our call (wrong parameters etc)
  if(result.state != 0) {
    alert('[' + result.failureDetail + '] ' + result.failureMessage)
  } else {
    alert('Deleted record successfully');
  }
};

//Start dleting the records
dsmx.api.dataRelations.delete(dataRelationName, recordID, successCallback, failCallback);

Writes an event to the specified data relation.

Parameters:

• dataRelationName - The name of the data relation inside the campaign.

• dataRelationEvent

  An object that contains the settings for the event that should be written.

    
  {                                                          //The event that should be written to the data relation
    "leadID" : "10",                                         //The record ID to which this event applies to
    "eventName" : "Visited",                                 //The event name
    "occuredOnUTC" : Date.now(),                             //The date and time at which this event happened
    "context" : "Event context",                             //The source of the event, e.g. The name of the purl that was vistied on a Visited event.
    "destination" : "Purl1",                                 //The event destination. In case of link click event the destination page name.
    "message" : "Some event message"                         //Some additional event message
  }
  
  

• doneCallback - A callback method that will be executed in case no network or server error occured.
• failCallback - A callback method that will be executed in case a network or server error occured.

Example:

  
var dataRelationName = "DefaultDatabase";//The name of the data relation whose columns should be retrieved.
//Data relation specific settings and event config
var event = 
{                                                //The event that should be written to the data relation
  "leadID" : "1",                                //The record ID to which this event applies to
  "eventName" : "Visited",                       //The event name
  "occuredOnUTC" : Date.now(),                   //The date and time at which this event happened
  "context" : "Event context",                   //The source of the event, e.g. The name of the purl that was vistied on a Visited event.
  "destination" : "Purl1",                       //The event destination. In case of link click event the destination page name.
  "message" : "Some event message"               //Some additional event message
};

//The callback that will be executed in case of network errors
var failCallback = function() {
	//Just show an error message here
	alert('Unable to delete record');
};

//The callback  that will be executed in case there were no network or similar errors
var successCallback = function(result) {
  //Check if there was something wrong with our call (wrong parameters etc)
  if(result.state != 0) {
    alert('[' + result.failureDetail + '] ' + result.failureMessage)
  } else {
    alert('Event was written successful');
  }
};

//Start writing the event
dsmx.api.dataRelations.event(dataRelationName, event, successCallback, failCallback);

Executes a button action on a specified data relation.

Parameters:

• dataRelationName - The name of the data relation inside the campaign.
• buttonActionName - The name of the button action that should be executed.

• parameters

  An object containing the parameters for the button action

    
  {
    "Param1" : "Value1",
    "Param2" : "Value2",
    "Param3" : "Value3"
  }
  

• doneCallback - A callback method that will be executed in case no network or server error occured.
• failCallback - A callback method that will be executed in case a network or server error occured.

Returns a list of data types that are supported for the creation of new columns in a specified table.

Parameters:

• dataRelationName - The name of the data relation inside the campaign.
• doneCallback - A callback method that will be executed in case no network or server error occured.
• failCallback - A callback method that will be executed in case a network or server error occured.

This methods returns a string array, containing all the supported data types for the provided Table.

Possible data types are:

• string
• int
• float
• bool
• datetime
• select

Structure of the result object (In JSON notation):

  
["string","float"]

Example:

  
var dataRelationName = "DefaultDatabase";//The name of the data relation whose columns should be retrieved.

//The callback that will be executed in case of network errors
var failCallback = function() {
  //Just show an error message here
  alert('Unable to retrieve list of data types');
};

//The callback  that will be executed in case there were no network or similar errors
var successCallback = function(result) {
  //Check if there was something wrong with our call (wrong parameters etc)
  if(result.state != 0) {
    alert('[' + result.failureDetail + '] ' + result.failureMessage)
  } else {
    if(result.responseObject == null || result.responseObject.length == 0) {
      alert("The table does not support column creation.");
    } else {
      var message = "Supported data types for column creation:\r\n";

      for(var i = 0; i < result.responseObject.length; ++i) {
        message += result.responseObject[i] + "\r\n";
      }
	
      alert(message);
    }
  }
};

//Start retrieving data types
dsmx.api.dataRelations.getAvailableDataTypesForColumnCreation(dataRelationName, successCallback, failCallback);

Creates a new column on a specified data relations table.

See getMetaData method to verify if the specified data relation supports creation of columns. In some cases, not all of the tables that are available supports column creation. To verify that a specific table supports column creation, the getAvailableDataTypesForColumnCreation can be used.

Parameters:

• dataRelationName - The name of the data relation inside the campaign.
• columnName - The name of the new column.

• dataType

  The following data types are supported by this API:

  string

  int

  float

  bool

  datetime

  select

  All data types has to be provided as string. Examples:
  createColumn("DefaultDatabase", 'MyColumn', 'string', 255, function() {}, function() {});
  createColumn("DefaultDatabase", 'MyColumn', 'int', 0, function() {}, function() {});
  createColumn("DefaultDatabase", 'MyColumn', 'bool', 0, function() {}, function() {});
  However, the select data type has to be treated diffrently.
  A select column needs to specify the values that are valid for this column. This can be done by passing an array of values to the createColumn method:
  createColumn("DefaultDatabase", 'MyColumn', ['Value1','Value2'], 255, function() {}, function() {});
  In case you need a difffrent display value, this can be done by passing an object instead of an array (Display values must be supported by the data relation):
  var dataType = {
  "Value1" : "DisplayValue1",
  "Value2" : "DisplayValue2"
  };
  createColumn("DefaultDatabase", 'MyColumn',dataType, 255, function() {}, function() {});
• length - In case of string columns, the maximum string length for this column. -1 for maximum possible size.
• doneCallback - A callback method that will be executed in case no network or server error occured.
• failCallback - A callback method that will be executed in case a network or server error occured.

Example:

  
var dataRelationName = "DefaultDatabase";//The name of the data relation whose columns should be retrieved.

//The callback that will be executed in case of network errors
var failCallback = function() {
  //Just show an error message here
  alert('Unable to create column');
};

//The callback  that will be executed in case there were no network or similar errors
var successCallback = function(result) {
  //Check if there was something wrong with our call (wrong parameters etc)
  if(result.state != 0) {
    alert('[' + result.failureDetail + '] ' + result.failureMessage)
  } else {
    alert('Created column sucessfully');
  }
};

//Create a string column
dsmx.api.dataRelations.createColumn(dataRelationName,'StringColumn', 'string', 255,successCallback, failCallback);

//Create an int column
//dsmx.api.dataRelations.createColumn(dataRelationName,'IntegerColumn', 'int', 255,successCallback, failCallback);

//Create a select column without display values (Internal Database relation does not support string columns yet)
//dsmx.api.dataRelations.createColumn(dataRelationName,'PicklistColumn1', ['Value1','Value2', 'Value3'], 255,successCallback, failCallback);
 
//Create a select column with display values (Internal Database relation does not support string columns yet)
//dsmx.api.dataRelations.createColumn(dataRelationName,'PicklistColumn2', {"Value1" : "Display, Value1", "Value2" : "Display, Value2", "Value3" : "Display, Value3"}, 255,successCallback, failCallback);

Returns a list of columns that are available for deletion.

Parameters:

• dataRelationName - The name of the data relation inside the campaign.
• doneCallback - A callback method that will be executed in case no network or server error occured.
• failCallback - A callback method that will be executed in case a network or server error occured.

Structure of the result object (In JSON notation):

  
["Column1","Column2","Column3"]

Example:

  
var dataRelationName = "DefaultDatabase";//The name of the data relation whose columns should be retrieved.

//The callback that will be executed in case of network errors
var failCallback = function() {
  //Just show an error message here
  alert('Unable to retrieve list of deletable columns');
};

//The callback  that will be executed in case there were no network or similar errors
var successCallback = function(result) {
  //Check if there was something wrong with our call (wrong parameters etc)
  if(result.state != 0) {
    alert('[' + result.failureDetail + '] ' + result.failureMessage)
  } else {
    //Display the list of deletable columns
    var message = "The following columns can be deleted:\r\n";

    for(var i = 0; i < result.responseObject.length; ++i) {
	  message += result.responseObject[i] + "\r\n";
    }
	
    alert(message);
  }
};

//Start retrieving a list of deleteable columns
dsmx.api.dataRelations.getDeleteableColumns(dataRelationName, successCallback,failCallback);

Deletes a column that is given by its name.

Parameters:

• dataRelationName - The name of the data relation inside the campaign.
• columnName - The name of the column that should be deleted.
• doneCallback - A callback method that will be executed in case no network or server error occured.
• failCallback - A callback method that will be executed in case a network or server error occured.

Example:

  
var dataRelationName = "DefaultDatabase";//The name of the data relation whose columns should be retrieved.
var columnName = 'StringColumn';//The column name of the column that should be deleted.

//The callback that will be executed in case of network errors
var failCallback = function() {
  //Just show an error message here
  alert('Unable to retrieve list of deletable columns');
};

//The callback  that will be executed in case there were no network or similar errors
var successCallback = function(result) {
  //Check if there was something wrong with our call (wrong parameters etc)
  if(result.state != 0) {
    alert('[' + result.failureDetail + '] ' + result.failureMessage)
  } else {
    alert('Deleted column successfully');
  }
};

//Start deleting the column
dsmx.api.dataRelations.deleteColumn(dataRelationName, columnName, successCallback,failCallback);

This chapter describes the basic structure of filters that can be used for querying data on DataRelations.

A DataRelation filter basically is a list of conditions that can be combined combined by logic "and" or "or" operators.

A condition constists of the column name that should be filtered, an operator and a value that should be tested against the given column: ColumnName Equals Value.

The column name has to be enclosed by 2 square brackets: [[Firstname]]

The operator can be one of the following:

• Equals
• NotEqual
• Contains
• StartsWith
• EndsWith
• GreaterThan
• LessThan

Example: [[Firstname]] NotEqual 'Sebastian'

All conditions have to be wrapped into round brackets so that the final condition looks like: ([[Firstname]] NotEqual 'Sebastian')

Single conditions can be combined with the use of "and" or "or" operators. The Combined conditions have to be wrapped into round brackets:

( ([[Firstname]] StartsWith 'St') And ([[Firstname]] EndsWith 'd') )

Combined condition statements has always to consist of 2 parts. The left part and the right part. the left part consists of previously combined conditions that are wrapped by round brackets whereas the right part consists of the newly added condition.

( ( (CONDITION1) And (CONDITION2) ) And (CONDITION3) )

( (([[Firstname]] StartsWith 'St') And ([[Firstname]] EndsWith 'd')) And ([[Lastname]] Contains 'abc') )

This chapter describes the restrictions that applies to DataRelation filters

The above described filters works fine on each data relation, as long as "And" and "Or" filters are not mixed (the filter only contains And's or Or's). As soon as these are mixed within one filter statement, you will quickly recognize that the filtering does not work as expected any more.

The reason for this, is how filters are represented internally. For easier implementation on the DataRelation side and for easier transformation to other filter systems (Like SQL databases or CRM system filters), filters are represented in a diffrent much simpler object form internally.

  
<ANDS>
  <ORS1>
    <Condition1 />
    <Condition2 />
  </ORS>
  <ORS2>
    <Condition3 />
    <Condition4 />
  </ORS>
  <ORS3>
    <Condition5 />
  </ORS>
</ANDS>

Conditions can only be wrapped inside OR blocks. All conditions inside one OR block will be combined by OR statements.

  
<ORS1>
    <Condition1 />
    <Condition2 />
    <Condition3 />
 </ORS>

In the DataRelation filter notation that would be:

(((Condition1) Or (Condition2)) Or (Condition3))

All OR blocks are combined into one big AND block => All OR blocks will be combined with each other by ANDs.

  
<ANDS>
  <ORS1>
    <Condition1 />
    <Condition2 />
  </ORS>
  <ORS2>
    <Condition3 />
    <Condition4 />
  </ORS>
  <ORS3>
    <Condition5 />
  </ORS>
</ANDS>

Will result in:

((((Condition1) Or (Condition2)) AND ((Condition3) Or (Condition4))) And (Condition5))

So, basically, whenever the parser finds an AND statement, it closes the current OR block and opens a new one. In case your filter does not work as expected, its always recomnmended to try expressing it using the above xml structure and have a look if it fits inside this AND / OR logic.