Applies to QAComplete 12.31 SaaS & On-Premises, last modified on September 12, 2019

QAComplete SOAP API has the LoadByCriteria operations that let you query data in QAComplete. You can get all items, or items that match a specific condition (all resolved defects, all defects created by a specific user, and so on). This topic describes the parameter syntax and specifics of usage.

Working with paginated results

To improve server performance and data transfer speed, the LoadByCriteria methods return results split in pages rather than all items at once. Each page can have up to 200 items. You specify the page size and page number as parameters to LoadByCriteria. To get all items, you need to call LoadByCriteria several times with increasing page numbers starting from 1. If the returned page has less items than the requested page size, you reached the end of the result set.

For example, to get results 100 at a time, you call LoadByCriteria one time to get items from 1 to 100, then call LoadByCriteria again to get items from 101 to 200, and so on, until you get a page with less than 100 items.

The following example shows how you can get all pages:

C#

ServiceSoapClient service = new ServiceSoapClient();
AuthenticationData authData = new AuthenticationData();
// Specify authentication data
...

int pageSize = 200;
int pageNumber = 1;
Bug[] bugs;

do
{
  bugs = service.Bugs_LoadByCriteria(authData, "", "", pageSize, pageNumber);

  // Do something with the bugs
  ...

  pageNumber++;
}
while (bugs.Length == pageSize);

Java

ServiceSoap service = new Service().getServiceSoap12();
AuthenticationData authData = new AuthenticationData();
// Specify authentication data
...

int pageSize = 200;
int pageNumber = 1;
List<Bug> bugs;

do {
  bugs = service.bugsLoadByCriteria(authData, "", "", pageSize, pageNumber).getBug();

  // Do something with the bugs
  ...

  pageNumber++;
} while (bugs.size() == pageSize);

Limit number of returned items

You can limit the number of items returned by the LoadByCriteria operation using the third parameter, PageSize. It can be 1 to 200. You usually use PageSize in combination with the Sorting and Condition parameters to sort and filter the results.

For example, to get the latest 10 defects, you can use:

C#

Bug[] bugs = service.Bugs_LoadByCriteria(authData, null, "DateCreated DESC", 10, 1);

Java

List<Bug> bugs = service.bugsLoadByCriteria(authData, null, "DateCreated DESC", 10, 1).getBug();

To get a requirement with the longest estimated remaining time:

C#

FunctionalSpec[] reqs = service.FunctionalSpecs_LoadByCriteria(authData, null, "EstHrsRemaining DESC", 1, 1);

Java

List<FunctionalSpec> reqs = service.functionalSpecsLoadByCriteria(authData, null, "EstHrsRemaining DESC", 1, 1).getFunctionalSpec();

Condition syntax

The LoadByCriteria operation can return only those items that match a specific condition. For example, items created by a specific user, items with a specific word in the title, all resolved defects, and so on.

You can specify the condition in the Condition parameter of the LoadByCriteria operation. The condition string has the following format:

XML

<Conditions
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    Operation="COMPARISON_OPERATOR">

   <Items Type="tField">
      <Value xsi:type="xsd:string">FIELD_NAME</Value>
   </Items>
   <Items Type="VALUE_TYPE">
      <Value xsi:type="xsd:DATA_TYPE">COMPARED_VALUE</Value>
   </Items>
</Conditions>

For example, “Title starts with NEWS” can be encoded like this:

XML

<Conditions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" Operation="opLIKE">
   <Items Type="tField">
      <Value xsi:type="xsd:string">Title</Value>
   </Items>
   <Items Type="tString">
      <Value xsi:type="xsd:string">NEWS%</Value>
   </Items>
</Conditions>

For NULL comparisons (opNULL and opNOTNULL), the condition looks like this:

XML

<Conditions
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    Operation="opNULL">

   <Items Type="tField">
      <Value xsi:type="xsd:string">FIELD_NAME</Value>
   </Items>
</Conditions>

You can combine several conditions using logical AND and OR (opAND and opOR):

XML

<Conditions
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    Operation="opAND">

   <Conditions Operation="COMPARISON_1">
      ...
   </Conditions>
   <Conditions Operation="COMPARISON_2">
      ...
   </Conditions>
</Conditions>

See more examples below.

If you create SOAP requests manually, you need to put the condition string inside CDATA in the Condition element:

<Condition>
   <![CDATA[
      <Conditions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" Operation="opLIKE">
         <Items Type="tField">
            <Value xsi:type="xsd:string">Title</Value>
         </Items>
         <Items Type="tString">
            <Value xsi:type="xsd:string">NEWS%</Value>
         </Items>
      </Conditions>
   ]]>
</Condition>

Operator types

LoadByCriteria supports the following operators in conditions:

Operator Description
opAND Logical AND.
opOR Logical OR.
opNOT Logical NOT.
opLT Less than ( < ).
opLTE Less than or equal to ( <= ).
opEQU Equal to ( = ).
opNOTEQU Not equal to ( !=, <> ).
opGT Greater than ( > ).
opGTE Greater than or equal to ( >= ).
opIN Equal to any value in a set.
opNOTIN Not equal to any value in a set.
opLIKE Matches a pattern. Patterns can include wildcards:
% – Matches any string of zero or more characters.
_ – Matches any single character.
Example patterns:
NEWS% – Check if text starts with NEWS.
%NEWS – Check if text ends with NEWS.
%NEWS% – Check if text contains NEWS.
opNOTLIKE Does not match the pattern.
opNULL Equal to NULL.
opNOTNULL Not NULL.

Item types

The comparison string can include the following item types:

Item Type Description
tField The name of an object’s property. For example, Title or AssigneeUserId.

Show Example

tConst A number. For example, item ID.

Show Example

tString A string. For example, user name or item status.

Show Example

tDate The date and time in format yyyy-mm-ddThh:mm:ss.

Show Example

tArray An array of values (for example, a string array). Use this with opIN and opNOTIN conditions.

Show Example

tSQLstring An SQL function call. For example, you can use the getdate() function to specify the current date and time.

Show Example

Condition examples

Assigned to a specific user

All resolved items

All closed or resolved items

Title begins with

Non-closed items assigned to a specific user

Items created between 2014/01/01 and today

See Also

SOAP API Introduction

Highlight search results