TransitionItem

Description

This service transitions an 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.
item (required)	TTItem	The items to be transitioned. The TTItem type holds the generic data for the item. You must have the itemID filled in at a minimum.
transition (optional)	TransitionIdentifier	The transition that you intend to invoke against the item.
breakLock	boolean	Specify True to break any existing item lock. Specify False to honor the item lock.
options (optional)	ResponseItemOptions	Enables you to limit the data that is returned in the response.

Response

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

Usage

The TransitionItem call provides a method to transition or update a single record in a primary table or auxiliary table. If a transition of 0 is specified, the default update transition is used. 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 use a specific project for post transitions, include the PostProjectInternalName option in the extendedData element and enter the internal name of the project's Submit transition. For example:

<urn:item>
    <urn:id>
        <urn:tableIdItemId>10003:35</urn:tableIdItemId>
    </urn:id>
<urn:extendedData>
    <urn:data>
        <urn:name>PostProjectInternalName</urn:name>
        <urn:value>CHANGE_REQUEST_MANAGEMENT.SUBMIT</urn:value>
    </urn:data>
</urn:extendedData>
</urn:item>

If the PostProjectInternalName is not included, but a project override for the Post transition is specified in Application Administrator, that project is used to post the new item. If neither of these methods are used, the new item is posted into the same project as the originating item.

To create notes, item links, and URL attachments on the item, add records to the lists that are defined in 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:

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 ResponseItemOptions.

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 TransitionItem.

<urn:TransitionItem>
    <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>Base Project||Base IDT Project||
            Software Development||Animation Pro</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: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:options>
</urn:TransitionItems>