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).
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.
|<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.|
The Conditions Collection accommodates multiple Condition criteria.
|<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.
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.
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.
|NEQ||Not equal to|
|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>firstname.lastname@example.org</DataValue> </Single> </Condition> </Conditions>
The set operators that are listed below can be used within a Conditions Collection block in a Grid Request document.
|NEQ||Not equal to|
|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>
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>
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>
When a date is returned in a Grid Response, it includes milliseconds, and will resemble:
The time portion is to the right of the "T" in the data.
The following format is applicable for all Grid Requests. The list of data elements requested will vary within the document.
The following format is applicable for all Grid Responses. The list of fields returned will vary within the document.