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.
- 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)
|<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)
|<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.
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.
|Not equal to||NEQ|
|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>firstname.lastname@example.org</DataValue> </Single> </Condition> </Conditions>
The operators listed below are used within a Condition Collection in a GridRequest document.
|Not equal to||NEQ|
|Not In||NOT IN|
<Conditions> <Condition> <Collection> <DataElement>MailingID</DataElement> <DataValue>51223</DataValue> <DataValue>51238</DataValue> <SetOperator>IN</SetOperator> </Collection> </Condition> </Conditions>
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.
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>