Using the WorkXpress API: UpdateItem

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 update existing Items in a WorkXpress application using the UpdateItem API function. UpdateItem allows you to set Fields, create Relationships and recycle and delete Items & Relationships. Like the other functions, you can make many UpdateItem 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 UpdateItem 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.
action	string	The operation to be performed on the requested action delete: Once an Item has been deleted from WorkXpress, it can only be retrieved by restoring an earlier backup. You should only delete Items if you know for sure that you will not need it in the future. Deleting an Item will also delete any Relationships to other Items. recycle: Recycled Items can be restored using the restore action (see below). When an Item is recycled, it will no longer be returned in search results; this includes (but is not limited to) Actions and List Layouts. All Relationships to other Items will also be recycled. restore: Restoring a recycled Item will make it available to searchng again. Restoring an Item will also restore any recycled Relations to other Items. update: Updates an existing Item.

/wxRequest/dataSet/
items

Root node for the items that should be retrieved.

/wxRequest/dataSet/
items/item

A single item to be updated. There is no limit to the number of item nodes allowed in a data set.

Attributes:

Name	Type	Description
itemId	string	The item id of the item to update from. Should be in the format u# (ie. u123).

/wxRequest/dataSet/
items/map

The root node for a map definition.

/wxRequest/dataSet/
items/map/definition

The actual definition for a map. The map XML must have its HTML entities encoded.

/wxRequest/dataSet/fields

Root node for any fields that should be updated on the items that were found in the items node.

/wxRequest/dataSet/
fields/field

A single field to update on the Item.

Attributes:

Name	Type	Description
fieldId	string	Id of the field 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 added or updated with the current item.

/wxRequest/dataSet/
relations/relation

Defines a single relation to be added or updated. If the action is not "add", the attributes will be used to look up an existing relation.
Attributes:

Name	Type	Description
action	string	The action to perform for this relation. add: Creates a new relationship using the other attributes to define the new relationship. delete: Similar to items, deleted relationships are completely removed from WorkXpress and can only be retrieved by restoring a previous backup. recycle: Recycled relationships are not removed from WorkXpress and can be restored using the restore action. restore: Restores a relationship that was previously recycled. update: Updates an existing relation.
oppositeItemId	string	Id of the item on the opposite side of the relation. For example, if the item being updated is an account and you want to relate it to a contact (or update an existing relationship 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 relationship.
relationType	string	Relation type of the relationship. 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 relationship.

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

A single field to be set on the relationship.

Attributes:

Name	Type	Description
fieldId	string	Id of the field 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 an item that was updated. One item node is returned for each item that was updated by WorkXpress.

Attributes:

Name	Type	Description
itemId	string	Id of the item that was updated, in the format u# (ie. u123).

/wxRequest/dataSet/
item/relation

Defines a relationship that was added or updated. Returns one relation node for each relationship from the item that was added or updated by WorkXpress.
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 or updated, in the format u# (ie. u123).

Examples

Below is an example of a basic UpdateItem request document:

<wxRequest>

  <dataSet action="update" reference="account_update">

    <items>

      <item itemId="u7563" />

    </items>

    <fields>

      <field fieldId="a66969">

        <value>WorkXpress</value>

      </field>

    </fields>

    <relations>

      <relation action="update" oppositeItemId="u7436"
        reference="account_to_contact" relationType="a36495"
        startingSide="base">

        <fields>

          <field fieldId="a36498">

            <value>Intern</value>

          </field>

                  <field fieldId="a36513">

            <value>foo [at] example [dot] com</value>

          </field>

        </fields>

      </relation>

    </relations>

  </dataSet>

  <dataSet action="recycle" reference="account_recycle">

    <items>

      <map>

        <definition>

          &lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;

          &lt;wxQuery

            xmlns:xsi=&quot;http://www.w3.org/2001/XMLSchema-instance&quot;

            xsi:noNamespaceSchemaLocation=&quot;wxQuery.xsd&quot;

            id=&quot;root&quot;&gt;

            &lt;data for=&quot;root&quot;&gt;

              &lt;item/&gt;

            &lt;/data&gt;

            &lt;startingTypes&gt;

              &lt;startingType&gt;a5543&lt;/startingType&gt;

            &lt;/startingTypes&gt;

            &lt;paramGroup id=&quot;wx4adfb3c227d12&quot;&gt;

              &lt;join&gt;and&lt;/join&gt;

              &lt;fieldSearch id=&quot;wx4adfb3d738a91&quot;&gt;

                &lt;fieldId&gt;a39651&lt;/fieldId&gt;

                &lt;operator&gt;fieldLessThanEqualTo&lt;/operator&gt;

                &lt;input&gt;

                  &amp;lt;?xml version=&quot;1.0&quot;?&amp;gt;

                  &amp;lt;search_value&amp;gt;

                    &amp;lt;first_value&amp;gt;

                      -1 years

                    &amp;lt;/first_value&amp;gt;

                  &amp;lt;/search_value&amp;gt;

                &lt;/input&gt;

              &lt;/fieldSearch&gt;

            &lt;/paramGroup&gt;

          &lt;/wxQuery&gt;

        </definition>

      </map>

    </items>

  </dataSet>
</wxRequest>

Below is the corresponding response document for the above example:

<wxResponse>

  <callStatus status="success" />

  <compatibilityLevel>1</compatibilityLevel>

  <dataSet reference="account_update">

    <item itemId="u7563">

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

    </item>

  </dataSet>

  <dataSet reference="account_recycle">

    <item itemId="u1782"></item>

  </dataSet>
</wxRequest>

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