API Quick Start Guide - Grid Request Overview – Higher Logic

NOTE: The information in this article is specific to Higher Logic Thrive Marketing Professional (Thrive Marketing Professional).

A GridRequest is used to retrieve data from Thrive Marketing Professional. 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 Thrive Marketing Professional 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>