API Quick Start Guide - Grid Request Overview

A GridRequest is used to retrieve data from Informz. Once retrieved, the data can be analyzed, reported on, or included within your application. Selecting the appropriate GridRequest is dependent upon your data needs. For example, summarized data from the publishing of one mailing is available in the MailingActivity document. If detailed mailing activity was needed on a subscriber (email) basis, then using Subscriber_Mailing_History would be the appropriate source. Here are some other important things to understand about the organization of Informz data.

Notes

  • Each entity returned is contained within its own Record element.
  • There is a maximum of 1,000 rows that can be returned in one request.

Details (Part 1)

Node Type Req'd? Description
<DataElement> String True At least one return field is required in a GridRequest. Pass the descriptive name of the data element you wish to retrieve.
<DataElement>MailingInstanceID String True The "key value" of the pair. In this case, a mailing instance ID.
< DataValue>##### String True The associated value of the DataElement.
<NumberOfRows>### Int False The number of rows to be returned per request.
<ReturnFields> N/A Available fields that can be returned.
<SetOperator>IN String False Choices: IN (in range), EQ (equals), GT (greater than), GTE (greater than or equal to), LT (less than), LTE (less than or equal to), NE (not equal) If a range of values is desired, use "IN" as the SetOperator and provide two data values to indicate the lower bound and upper bound of the range.
<SortField order="asc">   <DataElement> String False Choices: asc (Ascending) or desc (descending) The DataElement is the field to be sorted.
<StartRow> Int N/A The ordinal placement of the first row in the return set.

Please note that the the Conditions Collection accommodates multiple Condition criteria.

Details (Part 2)

Node Type Description
<Field element="abc">#### Int Element = "abc" the previously requested data element with its value. The data type for code is always Int and for description it’s always String.
<Record row="#"> Int A unique row #.

The maximum number of rows returned is dependent upon the <NumberOfRows> indicated in the request.

Conditions

The conditions block is the way in which certain data can be specified for the GridRequest. By 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.

Paging

It may be appropriate to use paging within the document to manage the data, which would occur in the client application.

This is only applicable for GridRequest documents. If order is not specified, ascending is used. Use "desc" for descending. The GridResponse reflects the appropriate row numbers. 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>