Creating a FilterDefinition Object

Use the FilterDefinition object to separate out information for a data source, such as a subscriber list or a data extension. Use the sample code below as a model for creating your own API call.

All date values for a simple filter part must go into the DateValue collection.

The FilterDefinition object contains these properties.

ObjectID: A unique identifier for the property.
CustomerKey: A client-supplied identifier for the filter. This must be unique across all FilterDefinitions owned by the client.
Name: A unique name for the filter. Don’t use the name for lookup purposes.
Description: A description of the filter.
DataSource: Specifies whether the filter is list-based or data-extension-based. If the filter is based on a data extension, supply a DataExtension object. Otherwise, leave this value null and the filter uses profile attributes.
DataFilter: This property specifies the rules associated with the filter. You can include measures here.

DataFilter Valid Values for Specific Data Types

Data Type	Valid Values
Boolean	True or False
Date	ShortDate (date with no time)
List	Not supported
Numeric	Bigint

DataFilter Valid SimpleOperator Types

Data Type	Valid Values
Boolean	Equals
Date	equals notEquals isAnniversary isNotAnniversary greaterThan greaterThanAnniversary lessThan lessThanAnniversary
List	equals notEquals
Numeric	equals notEquals greaterThan greaterThanOrEqual
Text	equals notEquals greaterThan greaterThanOrEqual lessThan lessThanOrEqual existsInString existsInStringAsAWord notExistsInString beginsWith

Sample .NET Code to Create a FilterDefinition Object

1DataExtension de = new DataExtension();
2de.CustomerKey = "DE_UserSubscription"; // External key of data extension
3FilterDefinition fd = new FilterDefinition();
4fd.DataSource = de;
5fd.Name = "A new Filter Definition";
6fd.CustomerKey = "A_new_Filter_Definition";
7fd.Description = "A new Filter Definition";
8// Set up complex filter parts
9ComplexFilterPart cfp = new ComplexFilterPart();
10// set up simple filter parts
11SimpleFilterPart sfpA = new SimpleFilterPart();
12SimpleFilterPart sfpB = new SimpleFilterPart();
13SimpleFilterPart sfpC = new SimpleFilterPart();
14SimpleFilterPart sfpD = new SimpleFilterPart();
15sfpA.Property = "opt_in"; // boolean
16sfpA.SimpleOperator = SimpleOperators.equals;
17sfpA.Value = new string[] { "true" };
18
19sfpB.Property = "pub_id"; // number
20sfpB.SimpleOperator = SimpleOperators.equals;
21sfpB.Value = new string[] { "1" };
22sfpC.Property = "pub_type"; // text
23sfpC.SimpleOperator = SimpleOperators.equals;
24sfpC.Value = new string[] { "A" };
25sfpD.Property = "subscribed"; // boolean
26sfpD.SimpleOperator = SimpleOperators.equals;
27sfpD.Value = new string[] { "true" };
28// Joins the rules together
29cfp.LeftOperand = sfpA;
30cfp.LogicalOperator = LogicalOperators.AND;
31cfp.RightOperand = sfpB;
32cfp.AdditionalOperands = new FilterPart[2];
33cfp.AdditionalOperands[0] = sfpC;
34cfp.AdditionalOperands[1] = sfpD;
35
36// Associate the complex filter with the FilterDefinition
37fd.DataFilter = cfp;
38// Execute CreateRequest
39CreateResult[] results = integrationFramework.Create(null, new APIObject[] { fd }, out requestID, out status);
40// Output the Values
41Console.WriteLine(status);
42Console.WriteLine(requestID);
43Console.WriteLine(results.Length);
44foreach (CreateResult result in results)
45{
46      Console.WriteLine(result.ErrorCode);
47      Console.WriteLine(result.StatusCode);
48      Console.WriteLine(result.StatusMessage);
49      Console.WriteLine(result.NewObjectID);
50}

This code example creates a filter definition with a complex filter.

1Criteria 1  =
21 - test_cell = "CELL1"
3AND
42 - division_permalink = "chicago"
5
6Criteria 2 =
71 - status = "active"
8OR
92 - status = "bounced"

Using these criteria, the API performs the call on the test_subject_line data extension:

1// Create Filter
2DataExtension fde = new DataExtension();
3fde.CustomerKey = "test_subject_line"; // External key of data extension
4FilterDefinition fd = new FilterDefinition();
5fd.DataSource = fde;
6fd.Name = "SUBJECT LINE";
7fd.CustomerKey = "SUBJECT_LINE";
8fd.Description = "description";
9SimpleFilterPart sfpA = new SimpleFilterPart();
10sfpA.Property = "test_cell"; // boolean
11sfpA.SimpleOperator = SimpleOperators.equals;
12sfpA.Value = new string[] {"CELL1"};
13SimpleFilterPart sfpC = new SimpleFilterPart();
14sfpC.Property = "division_permalink"; // boolean
15sfpC.SimpleOperator = SimpleOperators.equals;
16sfpC.Value = new string[] { "chicago" };
17ComplexFilterPart cfp1 = new ComplexFilterPart();
18cfp1.LeftOperand = sfpA;
19cfp1.LogicalOperator = LogicalOperators.AND;
20cfp1.RightOperand = sfpC;
21// SFP for status = active or bounced
22SimpleFilterPart sfpB1 = new SimpleFilterPart();
23sfpB1.Property = "status"; // boolean
24sfpB1.SimpleOperator = SimpleOperators.equals;
25sfpB1.Value = new string[] { "active" };
26SimpleFilterPart sfpB2 = new SimpleFilterPart();
27sfpB2.Property = "status"; // boolean
28sfpB2.SimpleOperator = SimpleOperators.equals;
29sfpB2.Value = new string[] { "bounced" };
30ComplexFilterPart cfp2 = new ComplexFilterPart();
31cfp2.LeftOperand = sfpB1;
32cfp2.LogicalOperator = LogicalOperators.OR;
33cfp2.RightOperand = sfpB2;
34ComplexFilterPart cfp3 = new ComplexFilterPart();
35cfp3.LeftOperand = cfp1;
36cfp3.LogicalOperator = LogicalOperators.AND;
37cfp3.RightOperand = cfp2;
38fd.DataFilter = cfp3;
39// Execute CreateRequest
40CreateResult[] results2 = client.Create(null, new APIObject[] { fd }, out requestID2, out status2);
41if (status2.Equals("OK"))
42{
43lblMessage.Text = "Call is : " + status2;
44}
45else
46{
47lblMessage.Text = "Error Creating Data Extension: " + results2;
48}

Sample .NET Code toUpdate a FilterDefinition Object

The update call supports both CustomerKey and ObjectID as identifiers to specify which FilterDefinition to update. The API requires both the DataExtension and DataFilter to update a FilterDefinition object.

1DataExtension de = new DataExtension();
2de.CustomerKey = "DE_UserSubscription"; // External key of data extension
3FilterDefinition fd = new FilterDefinition();
4fd.DataSource = de;
5fd.CustomerKey = "A_new_Filter_Definition"; // Update using customer key
6// Simple
7ComplexFilterPart cfp = new ComplexFilterPart();
8SimpleFilterPart sfpA = new SimpleFilterPart();
9SimpleFilterPart sfpB = new SimpleFilterPart();
10SimpleFilterPart sfpC = new SimpleFilterPart();
11SimpleFilterPart sfpD = new SimpleFilterPart();
12sfpA.Property = "opt_in";
13sfpA.SimpleOperator = SimpleOperators.equals;
14sfpA.Value = new string[] { "true" };
15sfpB.Property = "pub_id";
16sfpB.SimpleOperator = SimpleOperators.equals;
17sfpB.Value = new string[] { "1" };
18sfpC.Property = "pub_type";
19sfpC.SimpleOperator = SimpleOperators.equals;
20sfpC.Value = new string[] { "A" };
21sfpD.Property = "subscribed";
22sfpD.SimpleOperator = SimpleOperators.equals;
23sfpD.Value = new string[] { "true" };
24cfp.LeftOperand = sfpA;
25cfp.LogicalOperator = LogicalOperators.AND;
26cfp.RightOperand = sfpB;
27cfp.AdditionalOperands = new FilterPart[2];
28cfp.AdditionalOperands[0] = sfpC;
29cfp.AdditionalOperands[1] = sfpD;
30fd.DataFilter = cfp;
31// Execute UpdateRequest
32UpdateResult[] results = integrationFramework.Update(null, new APIObject[] { fd }, out requestID, out status);
33// Output the Values
34Console.WriteLine(status);
35Console.WriteLine(requestID);
36Console.WriteLine(results.Length);
37foreach (UpdateResult result in results)
38{
39      Console.WriteLine(result.ErrorCode);
40}

Sample SOAP Envelope - Create a Filter Definition Using Profile Attributes

1<?xml version="1.0" encoding="UTF-8"?>
2<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
3 <SOAP-ENV:Header>
4  <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
5   <wsu:Timestamp>
6   </wsu:Timestamp>
7   <wsse:UsernameToken>
8    <wsse:Username>XXXXX</wsse:Username>
9    <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">XXXXX</wsse:Password>
10    <wsse:Nonce>eSTcdVv9GBJGgiTLlEPDuRnpTXk=</wsse:Nonce>
11    <wsu:Created>2011-05-20T14:57:13Z</wsu:Created>
12   </wsse:UsernameToken>
13  </wsse:Security>
14 </SOAP-ENV:Header>
15 <SOAP-ENV:Body>
16  <CreateRequest xmlns="http://exacttarget.com/wsdl/partnerAPI">
17   <Options/>
18   <ns1:Objects xmlns:ns1="http://exacttarget.com/wsdl/partnerAPI" xsi:type="ns1:FilterDefinition">
19    <ns1:ModifiedDate xsi:nil="true"/>
20    <ns1:ObjectID xsi:nil="true"/>
21    <ns1:Name>PAFilterDef20110520105713606</ns1:Name>
22    <ns1:DataFilter xsi:type="ns1:SimpleFilterPart">
23     <ns1:Property>Gender</ns1:Property>
24     <ns1:SimpleOperator>equals</ns1:SimpleOperator>
25     <ns1:Value>Female</ns1:Value>
26    </ns1:DataFilter>
27   </ns1:Objects>
28  </CreateRequest>
29 </SOAP-ENV:Body>
30</SOAP-ENV:Envelope>

Sample SOAP Envelope - Create a Filter Definition For a Data Extension

1<?xml version="1.0" encoding="UTF-8"?>
2<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
3 <SOAP-ENV:Header>
4  <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
5   <wsu:Timestamp>
6   </wsu:Timestamp>
7   <wsse:UsernameToken>
8    <wsse:Username>XXXXX</wsse:Username>
9    <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">XXXXX</wsse:Password>
10    <wsse:Nonce>XC5M431QfCJQ+bjcVmj4idjZC/A=</wsse:Nonce>
11    <wsu:Created>2011-05-20T14:55:36Z</wsu:Created>
12   </wsse:UsernameToken>
13  </wsse:Security>
14 </SOAP-ENV:Header>
15 <SOAP-ENV:Body>
16  <CreateRequest xmlns="http://exacttarget.com/wsdl/partnerAPI">
17   <Options/>
18   <ns1:Objects xmlns:ns1="http://exacttarget.com/wsdl/partnerAPI" xsi:type="ns1:FilterDefinition">
19    <ns1:ModifiedDate xsi:nil="true"/>
20    <ns1:ObjectID xsi:nil="true"/>
21    <ns1:Name>FDDE20110520105536886</ns1:Name>
22    <ns1:DataSource xsi:type="ns1:DataExtension">
23     <ns1:ModifiedDate xsi:nil="true"/>
24     <ns1:ObjectID>756e860f-f182-e011-afb3-001cc494c760</ns1:ObjectID>
25    </ns1:DataSource>
26    <ns1:DataFilter xsi:type="ns1:SimpleFilterPart">
27     <ns1:Property>Gender</ns1:Property>
28     <ns1:SimpleOperator>equals</ns1:SimpleOperator>
29     <ns1:Value>Female</ns1:Value>
30    </ns1:DataFilter>
31   </ns1:Objects>
32  </CreateRequest>
33 </SOAP-ENV:Body>
34</SOAP-ENV:Envelope>