GetItemsByQuery

Description

This service returns multiple items using a where clause and an order by clause to determine the set of items returned.

Arguments

Argument	Type	Description
auth (optional)	Auth	The Auth type supplies credentials and optionally, a host name for licensing. The userId and password can be specified with HTTP BASIC or WS-SECURITY instead.
table (required)	TableIdentifier	Specifies the table that contains the items that you want to return.
queryWhereClause (optional)	string	An SQL statement to find items with TS_ID>0. If not provided, all items in the table are returned.
orderByClause (optional)	string	An SQL statement to order the returned items. Enter a null or empty string for no ordering.
firstRecord	string	Used in combination with maxReturnSize to return chunks of records.
maxReturnSize (optional)	string	Enter the number of items to return.
options (optional)	MultipleResponseItemOptions	Specifies whether the service should continue if an error is encountered or stop. Also enables you to limit the data that is returned in the response.

Response

TTItemList is returned, one for each item that is returned in the call. The response is a list of items in the specified table that match the query where clause. The list is ordered and limited as specified. For more detailed information, see TTItemList.

Usage

To return items using a query, you can pass the conditions in the where clause itself. For example:

<urn:queryWhereClause>TS_ISSUEID LIKE '00106' OR TS_ISSUEID LIKE '00029'
 OR TS_ISSUEID LIKE '00105'</urn:queryWhereClause>

<urn:queryWhereClause>TS_ISSUEID='00038'</urn:queryWhereClause>

<urn:queryWhereClause>TS_ID='4'</urn:queryWhereClause>

To return all items, send a null query:

<urn:queryWhereClause></urn:queryWhereClause>

If the number of items that are found by the query exceed the system's Listing Report Items limit, no items are returned and an error appears instead.

The total number of records that are returned cannot exceed the system's Listing Report Items limit in any single call; if you use maxReturnSize and firstRecord to return chunks of records, the number of records in a single chunk cannot exceed the Listing Report Items limit. To return more records than the Listing Report Items limit, use sequential firstRecord and maxReturnSize parameters in separate calls.

For example, if 1028 records match the query, you can specify firstRecord and maxReturnSize together to return only 1000 items in the first call, and the remainder in the second call. For example:

<urn:firstRecord>1</urn:firstRecord>
<urn:maxReturnSize>1000</urn:maxReturnSize>

And then, in the second call:

<urn:firstRecord>1001</urn:firstRecord>
<urn:maxReturnSize>1000</urn:maxReturnSize>

You can also you the firstRecord and maxReturnSize arguments to return pages of items. For example, to return all 1028 records in chunks of 100, you would make eleven total calls. In each call, no chunk can be greater than the Listing Report Items limit.

In the maxReturnSize element, you can also set the value to zero to use the system "Listing Report Items" limit. A number greater than zero (but less than the Listing Report Items limit) returns the number of items that you specify.

You can use the following elements in the options argument to control the service handling and response:

multiOption – Use the multiOption element to specify whether the service should continue if an error is encountered, or stop and return an error. If any failures occur, each successive error message is appended to the string that is returned. Multiple error messages are separated by a single newline.
If you specify CONTINUE-ON-FAILURE, then failures do not result in a return before all items

have been processed.
sections and specifiedSections – Use these elements to specify which parts of an item should be returned in order to limit the data that is returned for a given item. The sections that are not specified are not included in the response. For example, if the items have a large number of item links, notes, URL and file attachments that don't need to be returned in the response, use these parameters to return only the sections of an item you want.
limitedField – Use the limitedField element to specify fields that control the item data that is returned. For example, you can specify one or more fields to limit a service response to return only the fields that you want to return.

For more information on the options elements, see MultipleResponseItemOptions.

Faults

Invalid database pointer.
The table ID is not valid.
The user lacks sufficient permission.
Creating the record fails.
Query exceeds system "Listing Report Items" limit.
Reading the item fails.

XML

The following XML is a snippet of the payload being sent with GetItemsByQuery.

<urn:GetItemsByQuery>
    <urn:auth>
        <urn:userId>admin</urn:userId>
        <urn:password></urn:password>
        <urn:hostname>localhost</urn:hostname>
    </urn:auth>
         <urn:table>
            <urn:displayName></urn:displayName>
            <urn:id>1000</urn:id>
            <urn:uuid></urn:uuid>
            <urn:dbName></urn:dbName>
         </urn:table>
    <urn:queryWhereClause>TS_TITLE LIKE 'New Item'</urn:queryWhereClause>
    <urn:orderByClause>TS_TITLE</urn:orderByClause>
    <urn:firstRecord>1</urn:firstRecord>
    <urn:maxReturnSize>100</urn:maxReturnSize>
    <urn:options>
        <urn:extraOption>
            <urn:name></urn:name>
            <urn:value></urn:value>
        </urn:extraOption>
        <urn:sections>SECTIONS-SPECIFIED</urn:sections>
        <urn:specifiedSections>SECTION:FIXED</urn:specifiedSections>
        <urn:limitedField></urn:limitedField>
        <urn:multiOption></urn:multiOption>
    </urn:options>			
</urn:GetItemsByQuery>