Grid Request Conditions

The conditions block is the way in which certain data can be specified for the GridRequest. Using the appropriate combination of comparators and operators the conditions block can be tailored to meet specific data needs.

Comparators and Operators

The comparators listed below are used within any conditions statement in a GridRequest document.

Description Code
Equal To EQ
Not equal to NEQ
Greater than GT
Less than LT
Less than or equal to LTE
Greater than or equal to GTE

Below is an example of searching for a specific mailing instance:

      <Conditions>
        <Condition>
          <Single>
            <DataElement>MailingInstanceID</DataElement>
            <Comparator>EQ</Comparator>
            <DataValue>478922</DataValue>
          </Single>
        </Condition>
        <Condition>
          <Single>
            <DataElement>EmailAddress</DataElement>
            <Comparator>EQ</Comparator>
            <DataValue>gulliver@yahoo.com</DataValue>
          </Single>
        </Condition>
      </Conditions>

The operators listed below are used within a Condition Collection in a GridRequest document.

Description Code
Equal To EQ
Not equal to NEQ
In IN
Not In NOT IN

      <Conditions>
        <Condition>
          <Collection>
            <DataElement>MailingID</DataElement>
            <DataValue>51223</DataValue>
            <DataValue>51238</DataValue>
            <SetOperator>IN</SetOperator>
          </Collection>
        </Condition>
      </Conditions>

Between

The creates a range for a request - see the example below:

<Condition>
  <Between>
    <DataElement>mailing_date</DataElement>
    <DataValue>2008-04-28T04:40:00</DataValue>
    <DataValue>2008-04-28T04:41:00</DataValue>
  </Between>
</Condition>

When creating a range for dates, make sure that the smaller (earlier) value is first (above) the larger (later) time.

DateTime with a Comparator

Time is required when using EQ or IN. It is optional for all others.

If not specified, time defaults to 00:00:00 UTC.

Count

When requesting count, it can be the only DataElement ReturnField. This example shows how to retrieve a count of mailings in a specific folder.

Element List

Data Element Type Length Conditional? Description
Count Int N/A False Matches found based upon the criteria used.

Request

<GridRequest xmlns="http://partner.informz.net/aapi/2009/08/">
 <Password>password</Password>
 <Brand id="9999">Test Brand</Brand>
 <User>testuser</User>
 <Grids>
  <Grid type="mailing_folder">
   <ReturnFields>
    <DataElement>count</DataElement>
   </ReturnFields>
  </Grid>
 </Grids>
</GridRequest>

Notes

  1. When Count is requested that is the only ReturnFields that can be requested.
  2. The <Count /> must include the slash.

Response

<?xml version="1.0" encoding="utf-16"?>
<GridResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://partner.informz.net/aapi/2009/08/">
 <Brand id="9999">Test Brand</Brand>
 <User>testuser</User>
 <Grids>
  <Grid type="mailing_folder">
   <Record row="0">
    <Fields>
     <Field element="count">17</Field>
    </Fields>
   </Record>
  </Grid>
 </Grids>
</GridResponse>

Paging

Depending upon the amount of data being retrieved, it may be appropriate to use paging within the document to manage the data. The management of the pages would occur in the client application.

This is only applicable for GridRequest documents. If order is not specified, ascending will be used. Use "desc" for descending.

The grid request would implement paging using SortField, StartRow, and NumberOfRows like this:

<SortField order="asc">Mailing_Date</SortField>
<StartRow>200</StartRow>
<NumberOfRows>50</NumberOfRows>

The GridResponse will reflect the appropriate row numbers.