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.
First, let’s get an understanding of how the request XML should be formed.
The root node for all request documents.
Contains a single UpdateItem request. You may have as many data sets as
you would like.
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
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
searching again. Restoring an Item will also restore any
recycled Relations to other Items.
update: Updates an existing Item.
Root node for the items that should be retrieved.
A single item to be updated. There is no limit to the number of item
nodes allowed in a data set.
itemId (string): The item id of the item to update from. Should be
in the format u# (ie. u123).
The root node for a map definition.
The actual definition for a map. The map XML must have its HTML entities
Root node for any fields that should be updated on the items that were
found in the items node.
A single field to update on the Item.
fieldId (string): Id of the field to set. Should be in the format a#
Value to set into the field.
Root node for relations that should be added or updated with the current
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.
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
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.
Root node for the fields that should be set on the relationship.