Using the WorkXpress API: AddItem

24 Sep 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 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:
  • 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:
  • 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:
  • 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 created along with the new item.
/wxRequest/dataSet/relations/relation Defines a relation to be created.

Attributes:
  • 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:
  • 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 the item that was added to the WorkXpress application.

Attributes:
  • 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:
  • 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"></item>
    <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"></callstatus>
  <compatibilitylevel>1</compatibilitylevel>
  <dataset reference="workxpress">
    <item itemid="u7563" itemtypeid="a35234">
      <relation reference="account_to_contact" relationid="u7564">
    </relation></item>
  </dataset>
</wxresponse>

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.

comments powered by Disqus

Older · View Archive (34)

Using the WorkXpress API: LookupData

WorkXpress Last week 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: UpdateItem

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.