GetItems

Description

This service returns one or more items, given the table ID and internal item ID for each item.

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.
itemId (required)	ItemIdentifier	The item or items that should be returned.
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

TTItemHolder is returned, one for each item that is specified in the call. The itemIdentifiers, which show the unique TS_ID for each record and TS_ID of the table to which they belong is displayed. For more detail, see TTItemHolder.

Usage

The GetItems call enables you to see a snapshot of one or more auxiliary or primary items, without invoking any actual changes against the specified items. Specify the items that you want to return in one or more itemId arguments. To return results, you must provide the table ID and either one of the elements in the itemIdentifier or the issueId for each item.

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 specific fields to 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 returned.

For more information on the options elements, see MultipleResponseItemOptions.

Faults

The issueId = '<issue id>' provided is not unique for table '<database table name>'
Invalid item id 0 for table 0.
The item ID is not valid.
The user lacks sufficient permission.
Validation constraint violation: data type mismatch.

XML

The following XML is a snippet of the payload that is sent with GetItems.

<urn:GetItems>
    <urn:auth>
        <urn:userId>admin</urn:userId>
        <urn:password></urn:password>
        <urn:hostname></urn:hostname>
        <urn:loginAsUserId></urn:loginAsUserId>
        <urn:extendedData>
            <urn:data>
                <urn:name></urn:name>
                <urn:value></urn:value>
            </urn:data>
        </urn:extendedData>
    </urn:auth>
    <urn:itemId>
        <urn:displayName>BUG000164</urn:displayName>
        <urn:id>106</urn:id>
        <urn:uuid></urn:uuid>
        <urn:tableId>1000</urn:tableId>
        <urn:tableIdItemId>1000:106</urn:tableIdItemId>
        <urn:issueId>000164</urn:issueId>
    </urn:itemId>
    <urn:itemId>
        <urn:displayName>ENH000169</urn:displayName>
        <urn:id>107</urn:id>
        <urn:uuid></urn:uuid>
        <urn:tableId>1000</urn:tableId>
        <urn:tableIdItemId>1000:107</urn:tableIdItemId>
        <urn:issueId>000169</urn:issueId>
    </urn:itemId>
    <urn:itemId>
        <urn:displayName>BUG000173</urn:displayName>
        <urn:id>109</urn:id>
        <urn:uuid></urn:uuid>
        <urn:tableId>1000</urn:tableId>
        <urn:tableIdItemId>1000:109</urn:tableIdItemId>
        <urn:issueId>000173</urn:issueId>
    </urn:itemId>
    <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:displayName></urn:displayName>
        <urn:id></urn:id>
        <urn:uuid></urn:uuid>
        <urn:dbName></urn:dbName>
    </urn:limitedField>
    <urn:multiOption>CONTINUE-ON-FAILURE</urn:multiOption>
    </urn:options>
</urn:GetItems>