Using the WorkXpress API: AddItem

Earlier I introduced you to the WorkXpress API. If you have not read it already you should do so before reading this post. Once you have a basic understanding of what it is and how it works, it's time to start diving into the API.

This post will cover how to add Items to a WorkXpress application using the AddItem API function. AddItem allows you to set Fields and create Relationships while adding the new Item. Like the LookupData function, you can make many AddItem requests in one call using data sets.

Request XML

First, let's get an understanding of how the request XML should be formed.

Element

Description

/wxRequest

The root node for all request documents.

/wxRequest/dataSet

Contains a single AddItem request. You may have as many data sets as you would like.

Attributes:

Name	Type	Description
reference	string	An identifier that will be returned in the request document to distinguish between different data sets. If this attribute is left blank, a random string will be generated.

/wxRequest/dataSet/
item

Used to specify the item type id of the new item.

Attributes:

Name	Type	Description
itemTypeId	string	The item type id of the new item. Should be in the format a# (ie. a123).

/wxRequest/dataSet/fields

Root node for the fields that should be set on the new item.

/wxRequest/dataSet/
fields/field

A single field to be set on the new item.

Attributes:

Name	Type	Description
fieldId	string	Id of the field containing to set. Should be in the format a# (ie. a123).

/wxRequest/dataSet/
fields/field/
value

Value to set into the field.

/wxRequest/dataSet/
relations

Root node for relations that should be created along with the new item.

/wxRequest/dataSet/
relations/relation

Defines a relation to be created.
Attributes:

Name	Type	Description
action	string	The action to perform for this relation. This should always be set to "add" for AddItem requests.
oppositeItemId	string	Id of the item on the opposite side of the relation. For example, if the item being created is an account and you want to relate it to a contact, this would be the id of the contact. Should be in the format u# (ie. u123).
reference	string	An identifier that will be returned with the response to identify each relation.
relationType	string	Relation type of the new relation. Should be in the format a# (ie. a123).
startingSide	string	Defines which side of the relation that the item defined above should be on. Valid values are base and target.

/wxRequest/dataSet/
relations/relation/
fields

Root node for the fields that should be set on the new relation.

/wxRequest/dataSet/
relations/relation/
fields/field

A single field to be set on the new relation.

Attributes:

Name	Type	Description
fieldId	string	Id of the field containing to set. Should be in the format a# (ie. a123).

/wxRequest/dataSet/
relations/relation/
fields/field/
value

Value to set into the field.

Response XML

Now let's get an understanding of how the response XML will be formed.

Element

Description

/wxResponse

The root node for all response documents.

/wxRequest/callStatus

The status of the SOAP call as it was processed by WorkXpress.

Attributes:

Name	Type	Description
status	string	The call's status. Values include success and failure.

/wxResponse/compatibilityLevel

The version of the API that was used to process the request.

/wxRequest/dataSet

One data set is returned for each data set in the request document.

Attributes:

Name	Type	Description
reference	string	The identifier that was assigned to the data set in the request.

/wxRequest/dataSet/
item

Defines the item that was added to the WorkXpress application.

Attributes:

Name	Type	Description
itemId	string	Id of the item that was added, in the format u# (ie. u123).
itemTypeId	string	Item type id of the item that was added, in the format a# (ie. a123).

/wxRequest/dataSet/
item/relation

Defines a relation that was added to the WorkXpress application.
Attributes:

Name	Type	Description
reference	string	The identifier of the relation that was assigned to the relation in the request.
relationId	string	Id of the relation that was added, in the format u# (ie. u123).

Examples

Below is an example of a basic AddItem request document:

<wxRequest>

  <dataSet reference=”workxpress”>

    <item itemTypeId=”a35234” />

    <fields>

      <field fieldId=”a66969”>

        <value>WorkXpress</value>

      </field>

      <field fieldId=”a36314”>

        <value>http://www.workxpress.com</value>

      </field>

    </fields>

    <relations>

      <relation action=”add” oppositeItemId=”u7436”
        reference=”account_to_contact”
        relationType=”a36495” startingSide=”base”>

        <fields>

          <field fieldId=”a36498”>

            <value>Developer</value>

          </field>

        </fields>

      </relation>

    </relations>

  </dataSet>
</wxRequest>

Below is the corresponding response document for the above example:

<wxResponse>

  <callStatus status=”success” />

  <compatibilityLevel>1</compatibilityLevel>

  <dataSet reference=”workxpress”>

    <item itemId=”u7563” itemTypeId=”a35234”>

      <relation reference=”account_to_contact” relationId=”u7564”/>

    </item>

  </dataSet>
</wxRequest>

If you have any questions or would like assistance making some AddItem requests of your own, please feel free to comment below. My next post will be on how to use the UpdateItem request.