CreatePrimaryItems

Description

This service creates one or more primary items within the same project using the data that is supplied.

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.
project (required)	ProjectIdentifier	The project in which new items are created. You must at least specify the TS_ID of the project.
parentItem	ItemIdentifier	If specified, items that are created using CreatePrimaryItems will become sub-items of this item.
item (required)	TTItem	Holds one or more items to be created. The TTItem type holds the generic data for each item.
submitTransition (optional)	TransitionIdentifier	Only used if you want to use an alternative submit transition.
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 new primary items are returned with updated item data, which shows the unique TS_IDs of each record and TS_IDs of the table to which they were added. For more detail, see TTItemHolder.

Usage

The CreatePrimaryItems call provides a method to add multiple new records to a given primary table. You can add new records to both custom and system primary tables, given the proper privileges.

To create notes, item links, and URL attachments on the new primary items, add records to these elements as defined in TTItem. To create a file attachment, see CreateFileAttachment.

Tip: You must have the table ID and item ID of the primary item prior to attaching a file to the item because the IDs are required in the ItemIdentifier argument of CreateFileAttachment.

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 you are creating 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.

Faults

Invalid database pointer.
The project ID is not valid.
The user lacks sufficient permission.
Creating the record fails.
The submit transition fails.
Validation constraint violation: data type mismatch in element

XML

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

<urn:CreatePrimaryItems>
    <urn:auth>
        <urn:userId>admin</urn:userId>
        <urn:password></urn:password>
        <urn:hostname></urn:hostname>
        <urn:loginAsUserId></urn:loginAsUserId>
    </urn:auth>
    <urn:project>
        <urn:displayName>Animation Pro</urn:displayName>
        <urn:id>2</urn:id>
        <urn:uuid></urn:uuid>
        <urn:fullyQualifiedName>Base Project||Base IDT Project||
        Software Development||Animation Pro</urn:fullyQualifiedName>
    </urn:project>
    <urn:parentItem>
    </urn:parentItem>
    <urn:item>
        <urn:id>
            <urn:displayName></urn:displayName>
            <urn:id></urn:id>
            <urn:uuid></urn:uuid>
            <urn:tableId></urn:tableId>
            <urn:tableIdItemId></urn:tableIdItemId>
            <urn:issueId></urn:issueId>
        </urn:id>
        <urn:itemType></urn:itemType>
        <urn:project>
            <urn:displayName></urn:displayName>
            <urn:id></urn:id>
            <urn:uuid></urn:uuid>
            <urn:fullyQualifiedName></urn:fullyQualifiedName>
        </urn:project>
        <urn:title>Test item</urn:title>
        <urn:description>This is a test item.</urn:description>
        <urn:createdBy>
            <urn:displayName></urn:displayName>
            <urn:id></urn:id>
            <urn:uuid></urn:uuid>
            <urn:loginId></urn:loginId>
        </urn:createdBy>
        <urn:createDate></urn:createDate>
        <urn:modifiedBy>
            <urn:displayName></urn:displayName>
            <urn:id></urn:id>
            <urn:uuid></urn:uuid>
            <urn:loginId></urn:loginId>
        </urn:modifiedBy>
        <urn:modifiedDate></urn:modifiedDate>
        <urn:activeInactive></urn:activeInactive>
        <urn:state>
            <urn:displayName></urn:displayName>
            <urn:id></urn:id>
            <urn:uuid></urn:uuid>
            <urn:isClosed></urn:isClosed>
        </urn:state>
        <urn:owner>
            <urn:displayName></urn:displayName>
            <urn:id></urn:id>
            <urn:uuid></urn:uuid>
            <urn:loginId></urn:loginId>
        </urn:owner>
        <urn:url/>
        <urn:subtasks/>
        <urn:extendedField>
            <urn:id>
                <urn:displayName>Severity</urn:displayName>
                <urn:id></urn:id>
                <urn:uuid></urn:uuid>
                <urn:dbName>SEVERITY</urn:dbName>
            </urn:id>
            <urn:setValueBy>DISPLAY-VALUE</urn:setValueBy>
            <urn:setValueMethod>REPLACE-VALUES</urn:setValueMethod>
            <urn:value>
                <urn:displayValue>Critical</urn:displayValue>
                <urn:internalValue></urn:internalValue>
                <urn:uuid></urn:uuid>
            </urn:value>
        </urn:extendedField>
        <urn:extendedField>
            <urn:id>
                <urn:displayName>How Found</urn:displayName>
                <urn:id>74</urn:id>
                <urn:uuid>b999082f-ef27-47c9-890f-b4d80a3c4c23</urn:uuid>
                <urn:dbName>HOW_FOUND</urn:dbName>
            </urn:id>
            <urn:setValueBy>INTERNAL-VALUE</urn:setValueBy>
            <urn:setValueMethod>REPLACE-VALUES</urn:setValueMethod>
            <urn:value>
                <urn:displayValue>Code Review</urn:displayValue>
                <urn:internalValue>24</urn:internalValue>
                <urn:uuid>931259b4-dc0a-46c5-b567-ff04dd5c9395</urn:uuid>
            </urn:value>
        </urn:extendedField>
        <urn:extendedData>
            <urn:data>
                <urn:name></urn:name>
                <urn:value></urn:value>
            </urn:data>
        </urn:extendedData>
    </urn:item>
    <urn:item>
        <urn:id>
            <urn:displayName></urn:displayName>
            <urn:id></urn:id>
            <urn:uuid></urn:uuid>
            <urn:tableId></urn:tableId>
            <urn:tableIdItemId></urn:tableIdItemId>
            <urn:issueId></urn:issueId>
        </urn:id>
        <urn:itemType></urn:itemType>
        <urn:project>
            <urn:displayName></urn:displayName>
            <urn:id></urn:id>
            <urn:uuid></urn:uuid>
            <urn:fullyQualifiedName></urn:fullyQualifiedName>
        </urn:project>
        <urn:title>Test item</urn:title>
        <urn:description>This is a second test item.</urn:description>
        <urn:createdBy>
            <urn:displayName></urn:displayName>
            <urn:id></urn:id>
            <urn:uuid></urn:uuid>
            <urn:loginId></urn:loginId>
        </urn:createdBy>
        <urn:createDate></urn:createDate>
        <urn:modifiedBy>
            <urn:displayName></urn:displayName>
            <urn:id></urn:id>
            <urn:uuid></urn:uuid>
            <urn:loginId></urn:loginId>
        </urn:modifiedBy>
        <urn:modifiedDate></urn:modifiedDate>
        <urn:activeInactive></urn:activeInactive>
        <urn:state>
            <urn:displayName></urn:displayName>
            <urn:id></urn:id>
            <urn:uuid></urn:uuid>
            <urn:isClosed></urn:isClosed>
        </urn:state>
        <urn:owner>
            <urn:displayName></urn:displayName>
            <urn:id></urn:id>
            <urn:uuid></urn:uuid>
            <urn:loginId></urn:loginId>
        </urn:owner>
        <urn:url/>
        <urn:subtasks/>
        <urn:extendedField>
            <urn:id>
                <urn:displayName>Severity</urn:displayName>
                <urn:id></urn:id>
                <urn:uuid></urn:uuid>
                <urn:dbName>SEVERITY</urn:dbName>
            </urn:id>
            <urn:setValueBy>DISPLAY-VALUE</urn:setValueBy>
            <urn:setValueMethod>REPLACE-VALUES</urn:setValueMethod>
            <urn:value>
                <urn:displayValue>Critical</urn:displayValue>
                <urn:internalValue></urn:internalValue>
                <urn:uuid></urn:uuid>
            </urn:value>
        </urn:extendedField>
        <urn:extendedField>
            <urn:id>
                <urn:displayName>How Found</urn:displayName>
                <urn:id>74</urn:id>
                <urn:uuid>b999082f-ef27-47c9-890f-b4d80a3c4c23</urn:uuid>
                <urn:dbName>HOW_FOUND</urn:dbName>
            </urn:id>
            <urn:setValueBy>INTERNAL-VALUE</urn:setValueBy>
            <urn:setValueMethod>REPLACE-VALUES</urn:setValueMethod>
            <urn:value>
                <urn:displayValue>Code Review</urn:displayValue>
                <urn:internalValue>24</urn:internalValue>
                <urn:uuid>931259b4-dc0a-46c5-b567-ff04dd5c9395</urn:uuid>
            </urn:value>
        </urn:extendedField>
        <urn:extendedData>
            <urn:data>
                <urn:name></urn:name>
                <urn:value></urn:value>
            </urn:data>
        </urn:extendedData>
    </urn:item>
    <urn:submitTransition>
        <urn:displayName></urn:displayName>
        <urn:id></urn:id>
        <urn:uuid></urn:uuid>
    </urn:submitTransition>
    <urn:options>
        <urn:extraOption>
            <urn:name></urn:name>
            <urn:value></urn:value>
        </urn:extraOption>
        <urn:sections>SECTIONS-ALL</urn:sections>
        <urn:specifiedSections></urn:specifiedSections>
        <urn:limitedField/>
        <urn:multiOption>STOP-ON-FAILURE</urn:multiOption>
    </urn:options>
</urn:CreatePrimaryItems>