Knowledge Base

Grid Requests Overview

  • Updated

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

IMPORTANT: This article references Informz, a prior name of the Thrive Marketing Professional product. Instances of Informz remain in some areas of the API in order to ensure its functionality.

Grid Requests are used to retrieve data from Thrive Marketing Professional. After data has been retrieved, it can be analyzed, reported on, and included within your application.

There are numerous Grid Requests available to retrieve the data you want. For example, you might want summarized data from the publishing of one mailing (MailingActivity) or detailed mailing activity broken down by subscribers (Subscriber_Mailing_History).

Notes

Important things to understand about the organization of Informz data:

  • Each returned entity is contained within its own Record element.
  • Each request can return a maximum of 1,000 rows.

Details

Node Type Req'd Description
<DataElement> String True At least one return field is required in a Grid Request. Pass the descriptive name of the data element that you want 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 Grid Request.
<ReturnFields>   N/A Available fields that can be returned.
<SetOperator>IN String False Values: IN (in range), EQ (equal to), GT (greater than), GTE (greater than or equal to), LT (less than), LTE (less than or equal to), NE (not equal to)
If you want a range of values, use IN as the set operator and provide two data values to indicate the lower and upper boundaries of the range.
<SortField order="asc">DataElement String False Values: asc (ascending), desc (descending)
DataElement is the field to be sorted.
<StartRow> Int N/A The ordinal placement of the first row in the return set.

Notes

The Conditions Collection accommodates multiple Condition criteria.

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 number.
  • The maximum number of rows returned is dependent upon the <NumberOfRows> indicated in the request.

Conditions block

The Conditions block is how certain data can be specified for the Grid Request. By using the appropriate combination of comparators and set operators, the Conditions block can be tailored to meet specific data needs.

Comparators

The comparators that are listed below can be used within any Conditions block in a Grid Request document.

NOTE: When using EQ or IN, a time is required; it is optional for all others. If a time is not specified, it defaults to 00:00:00 UTC.

Comparator Function
EQ Equal To
NEQ Not equal to
GT Greater than
LT Less than
LTE Less than or equal to
GTE Greater than or equal to

The example below illustrates 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>

Set Operators

The set operators that are listed below can be used within a Conditions Collection block in a Grid Request document.

Set Operator Function
EQ Equal To
NEQ Not equal to
IN In
NOT IN Not In

The example below illustrates searching for mailing instances within a range of IDs.

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

Between

This creates a range for a Grid Request, as shown in the example below.

TIP: When creating a date or time range, be sure that the earlier date or time (i.e., the "from" value) is listed above the later date or time (i.e., the "to" value).

<Condition>
  <Between>
    <DataElement>mailing_date</DataElement>
    <DataValue>2021-04-28T04:40:00</DataValue>
    <DataValue>2021-04-28T04:48:00</DataValue>
  </Between>
</Condition>

Paging

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

  • This is only applicable for Grid Request documents.
  • If order is not specified, it defaults to ascending (i.e., asc). Use desc for descending order.
  • The Grid Response reflects the appropriate row numbers.

The Grid Request would implement paging using SortField, StartRow, and NumberOfRows as shown below.

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

Date format

When a date is returned in a Grid Response, it includes milliseconds, and will resemble:

2009-08-12T22:54:06.0000000Z

The time portion is to the right of the "T" in the data.

Response formats

The following format is applicable for all Grid Requests. The list of data elements requested will vary within the document.

Tag Name Type Required Comments
Order Enum N/A Asc, desc

The following format is applicable for all Grid Responses. The list of fields returned will vary within the document.

Was this article helpful?
0 out of 0 found this helpful
Return to top

Can’t find what you’re looking for?

Create a Case Call US Support