Using the WorkXpress API: LookupData

02 Sep 2009 | API, PHP, SOAP, Web Services, WorkXpress

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.

This post will cover how to read data from a WorkXpress Application using the LookupData function. LookupData allows you to retrieve values from items and relationships. If you know the item or relation id, you can retrieve the data directly from the Item. If you don’t have an id, you can use a map to search for items and relationships. The WorkXpress API allows you to make many LookupData requests in the same function 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 LookupData 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/items Root node for the items that should be retrieved.
/wxRequest/dataSet/items/item A single item to be retrieved. 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 retrieve data 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 the fields that should be read from the items that were found in the items node.
/wxRequest/dataSet/fields/field A single field to read data from.

Attributes:
  • fieldId (string): Id of the field containing the data you wish to pull. Should be in the format a# (ie. a123).
  • reference (string): An identifier that will be returned with the response to identify each field.
/wxRequest/dataSet/fields/field/format Display format for the defined field. Display formats will be explained in a later post. For now we will pull the "text" value of all fields.

Attributes:
  • type (string): The type of format that should be returned. Must be one of the following:
    • html: Includes any HTML used when rendering the Field in view mode within the Application.
    • stored: The format of the field when it is stored in the WorkXpress database. This may contain XML for multi-part fields, item ids for item pickers, etc. Stay tuned for a future post on special field values.
    • text: Returns the plain text value. This is the recommended format.
/wxRequest/dataSet/relations Root node for relations that should be looked up from the items found in the items node.
/wxRequest/dataSet/relations/relation Root node for relations that should be looked up from the items found in the items node.

Attributes:
  • relationType (string): Id of the relation type to search for. Should be in the format a# (ie. a123).
  • from (string): Defines which side of the relation that the search should start from. Valid values are base and target.
  • reference (string): An identifier that will be returned with the response to identify each relation.
/wxRequest/dataSet/relations/relation/fields Root node for the fields that should be read from the relations that were found in the items node.
/wxRequest/dataSet/relations/relation/fields/field A single field to read data from.

Attributes:
  • fieldId (string): Id of the field containing the data you wish to pull. Should be in the format a# (ie. a123).
  • reference (string): An identifier that will be returned with the response to identify each field.
/wxRequest/dataSet/relations/relation/fields/field/format Display format for the defined field. Display formats will be explained in a later post. For now we will pull the "text" value of all fields.

Attributes:
  • type (string): The type of format that should be returned. Must be one of the following:
    • html: Includes any HTML used when rendering the Field in view mode within the Application.
    • stored: The format of the field when it is stored in the WorkXpress database. This may contain XML for multi-part fields, item ids for item pickers, etc. Stay tuned for a future post on special field values.
    • text: Returns the plain text value. This is the recommended format.

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 A single item found based on the items defined in the request.

Attributes:
  • itemId (string): The item id of the item that was found, in the format u# (ie. u123).
/wxRequest/dataSet/item/field A single field that was retrieved based on the request.

Attributes:
  • fieldId (string): Id of the field, in the format a# (ie. a123).
  • reference (string): The identifier that was assigned to the field in the request document.
/wxRequest/dataSet/item/field/value The value of the current field, in the format defined in the request.
/wxRequest/dataSet/item/relation Contains the data for a single relation that was found.

Attributes:
  • relationType (string): Id of the relation type for the current relation, in the format a# (ie. a123).
  • id (string): Id of the current relation, in the format u# (ie. u123).
  • reference (string): The identifier of the relation that was assigned to the relation in the request.
  • baseItemTypeId (string): Item type id of the item on the base side of the relation, in the format a# (ie. a123).
  • baseItemId (string): Item id of the item on the base side of the relation, in the format u# (ie. u123).
  • targetItemTypeId (string): Item type id of the item on the target side of the relation, in the format a# (ie. a123).
  • targetItemId (string): Item id of the item on the target side of the relation, in the format u# (ie. u123).
/wxRequest/dataSet/item/relation/field A single field that was retrieved based on the request.

Attributes:
  • fieldId (string): Id of the field, in the format a# (ie. a123).
  • reference (string): The identifier that was assigned to the field in the request document.
/wxRequest/dataSet/item/relation/field/value The value of the current field, in the format defined in the request.

Examples

Below is an example of a basic LookupData request document:

<wxrequest>
  <dataset reference="accounts">
    <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;a35234&amp;lt;/startingType&amp;gt;
            &amp;lt;/startingTypes&amp;gt;
          &amp;lt;/wxQuery&amp;gt;
        </definition></map>
    </items>
    <fields>
      <field fieldid="a66969" reference="name">
        <format type="text">
      </format></field>
    </fields>
    <relations>
      <relation from="base" reference="account_to_contact" relationtype="a36495">
        <fields>
          <field fieldid="a36498" reference="position">
            <format type="text">
          </format></field>
        </fields>
      </relation>
    </relations>
  </dataset>
</wxresponse>

Below is the corresponding response document for the above example:

<wxresponse>
  <callstatus status="success"></callstatus>
  <compatibilitylevel>1</compatibilitylevel>
  <dataset reference="accounts">
    <item itemid="u7324">
      <field fieldid="a66969" reference="name">
        <value>WorkXpress</value>
      </field>
      <relation baseitemid="u7324" baseitemtypeid="a35234" id="u7437" reference="account_to_contact" relationtype="a36495" targetitemid="u7436" targetitemtypeid="a35334">
        <field fieldid="a36498" reference="position">
          <value>Developer</value>
        </field>
      </relation>
    </item>
  </dataset>
</wxresponse>

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

comments powered by Disqus

Older · View Archive (34)

Introducing the WorkXpress API

WorkXpress I recently finished documenting the WorkXpress API and thought I would share some of the details. First of all, the documentation can be downloaded at http://www.workxpress.com/sites/default/files/WorkXpress%20API_1.pdf (PDF). For PHP, there is a PEAR package that makes working with the API easier. Look for that in a later post.

Newer

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.