Using the WorkXpress API: UpdateItem

21 Oct 2009 | API, PHP, SOAP, Web Services, WorkXpress

WorkXpress 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:
  • 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 searching 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:
  • 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:
  • 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:
  • 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:
  • 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:
  • 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:
  • 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:
  • 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:
  • 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"></item>
    </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@example.com</value>
          </field>
        </fields>
      </relation>
    </relations>
  </dataset>
  <dataset action="recycle" reference="account_recycle">
    <items><map>
        <definition>
          &amp;lt;?xml version="1.0" encoding="UTF-8"?&amp;gt;
          &amp;lt;wxQuery xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="wxQuery.xsd" id="root"&amp;gt;
            &amp;lt;data for="root"&amp;gt;
              &amp;lt;item/&amp;gt;
            &amp;lt;/data&amp;gt;
            &amp;lt;startingTypes&amp;gt;
              &amp;lt;startingType&amp;gt;a5543&amp;lt;/startingType&amp;gt;
            &amp;lt;/startingTypes&amp;gt;
            &amp;lt;paramGroup id="wx4adfb3c227d12"&amp;gt;
              &amp;lt;join&amp;gt;and&amp;lt;/join&amp;gt;
              &amp;lt;fieldSearch id="wx4adfb3d738a91"&amp;gt;
                &amp;lt;fieldId&amp;gt;a39651&amp;lt;/fieldId&amp;gt;
                &amp;lt;operator&amp;gt;fieldLessThanEqualTo&amp;lt;/operator&amp;gt;
                &amp;lt;input&amp;gt;
                  &amp;amp;lt;?xml version="1.0"?&amp;amp;gt;
                  &amp;amp;lt;search_value&amp;amp;gt;
                    &amp;amp;lt;first_value&amp;amp;gt; -1 years &amp;amp;lt;/first_value&amp;amp;gt;
                  &amp;amp;lt;/search_value&amp;amp;gt;
                &amp;lt;/input&amp;gt;
              &amp;lt;/fieldSearch&amp;gt;
            &amp;lt;/paramGroup&amp;gt;
          &amp;lt;/wxQuery&amp;gt;
        </definition></map>
    </items>
  </dataset>
</wxrequest>

Below is the corresponding response document for the above example:

<wxresponse>
  <callstatus status="success"></callstatus>
  <compatibilitylevel>1</compatibilitylevel>
  <dataset reference="account_update">
    <item itemid="u7563">
      <relation reference="account_to_contact" relationid="u7564"></relation>
    </item>
  </dataset>
  <dataset reference="account_recycle">
    <item itemid="u1782"></item>
  </dataset>
</wxresponse>

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.

comments powered by Disqus

Older · View Archive (34)

Using the WorkXpress API: AddItem

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

Newer

Using the WorkXpress API: ExecuteAction

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