TransitionItems

Description

This service transitions one or more items.

Arguments

Response

TTItemHolder is returned, one for each transitioned item. The primary items are returned with updated item data, which shows the unique TS_IDs of each record and TS_IDs of the table. For more detail, see TTItemHolder.

Usage

The TransitionItems call provides a method to transition or update multiple records in a primary table or auxiliary table. If a transition of 0 is specified, the default update transition is used. 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. Failures do not result in a return before all items have been processed. You can update records in both custom and system primary tables, given the proper privileges.

If you specify a specific transition for the call to use, that transition needs to be a valid transition for the items' project.

To create notes, item links, and URL attachments on the items, add records to the lists that are defined in each TTItem. To update a file attachment, see UpdateFileAttachment.

Use the following elements in the options parameter to control how this call is processed and what data is returned:

• multiOption – Enables you to specify whether the service should continue if an error is encountered, or stop and throw 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. Failures do not result in a return before all items have been processed.
• sections and specifiedSections – Enables you to specify which parts of an item should be returned. This allows you to limit the data that is returned for a given item. The sections that aren't 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 the sections parameter to return only the sections of an item you want.
• limitedField – Enables you to specify which fields you want returned in the response. 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.

Usage

Faults

• Invalid database pointer.
• Invalid item.
• The user lacks sufficient permission.
• The transaction fails.
• Reading the item fails.
• Invalid project.

XML

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

<urn:TransitionItems>
    <urn:auth>
        <urn:userId>admin</urn:userId>
        <urn:password></urn:password>
        <urn:hostname></urn:hostname>
        <urn:loginAsUserId></urn:loginAsUserId>
    </urn:auth>
    <urn:item>
        <urn:id>
            <urn:displayName>000231</urn:displayName>
            <urn:id>197</urn:id>
            <urn:uuid></urn:uuid>
            <urn:tableId>1000</urn:tableId>
            <urn:tableIdItemId>1000:197</urn:tableIdItemId>
            <urn:issueId></urn:issueId>
        </urn:id>
        <urn:itemType></urn:itemType>
        <urn:project>
            <urn:displayName>Animation Pro</urn:displayName>
            <urn:id>6</urn:id>
            <urn:uuid></urn:uuid>
            <urn:fullyQualifiedName></urn:fullyQualifiedName>
        </urn:project>
        <urn:title></urn:title>
        <urn:description>This is a test item.</urn:description>
        <urn:extendedField>
            <urn:id>
                <urn:displayName>Developer</urn:displayName>
                <urn:id></urn:id>
                <urn:uuid></urn:uuid>
                <urn:dbName>DEVELOPER</urn:dbName>
            </urn:id>
            <urn:setValueBy>DISPLAY-VALUE</urn:setValueBy>
            <urn:setValueMethod>REPLACE-VALUES</urn:setValueMethod>
            <urn:value>
                <urn:displayValue>admin</urn:displayValue>
                <urn:internalValue></urn:internalValue>
                <urn:uuid></urn:uuid>
            </urn:value>
        </urn:extendedField>
    </urn:item>
    <urn:item>
        <urn:id>
            <urn:displayName>000232</urn:displayName>
            <urn:id>198</urn:id>
            <urn:uuid></urn:uuid>
            <urn:tableId>1000</urn:tableId>
            <urn:tableIdItemId>1000:198</urn:tableIdItemId>
            <urn:issueId></urn:issueId>
        </urn:id>
        <urn:itemType></urn:itemType>
        <urn:project>
            <urn:displayName>Animation Pro</urn:displayName>
            <urn:id>6</urn:id>
            <urn:uuid></urn:uuid>
            <urn:fullyQualifiedName></urn:fullyQualifiedName>
        </urn:project>
        <urn:title></urn:title>
        <urn:description>Another test.</urn:description>
        <urn:subtasks/>
        <urn:extendedField>
            <urn:id>
                <urn:displayName>Priority</urn:displayName>
                <urn:id></urn:id>
                <urn:uuid></urn:uuid>
                <urn:dbName>PRIORITY</urn:dbName>
            </urn:id>
            <urn:setValueBy>DISPLAY-VALUE</urn:setValueBy>
            <urn:setValueMethod>REPLACE-VALUES</urn:setValueMethod>
            <urn:value>
                <urn:displayValue>1</urn:displayValue>
                <urn:internalValue></urn:internalValue>
                <urn:uuid></urn:uuid>
            </urn:value>
        </urn:extendedField>
    </urn:item>
    <urn:transition>
        <urn:displayName>Fix</urn:displayName>
        <urn:id>8</urn:id>
        <urn:uuid></urn:uuid>
    </urn:transition>
    <urn:breakLock>true</urn:breakLock>
    <urn:options>
        <urn:sections>SECTIONS-SPECIFIED</urn:sections>
        <urn:specifiedSections>SECTION:FIXED</urn:specifiedSections>
        <urn:limitedField></urn:limitedField>
        <urn:multiOption>CONTINUE-ON-FAILURE</urn:multiOption>
    </urn:options>
</urn:TransitionItems>