Using the WorkXpress API: LookupData

workxpress-logo.png    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:
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.
/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:
Name Type Description
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:
Name Type Description
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:
Name Type Description
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:
Name Type Description
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:
Name Type Description
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:
Name Type Description
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:
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		 A single item found based on the items defined in the request.

Attributes:
Name Type Description
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:
Name Type Description
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:
Name Type Description
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:
Name Type Description
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>
          &lt;?xml version="1.0" encoding="UTF-8"?&gt;
          &lt;wxQuery
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:noNamespaceSchemaLocation="wxQuery.xsd"
            id="root"&gt;
            &lt;data for="root"&gt;
              &lt;item/&gt;
            &lt;/data&gt;
            &lt;startingTypes&gt;
              &lt;startingType&gt;a35234&lt;/startingType&gt;
            &lt;/startingTypes&gt;
          &lt;/wxQuery&gt;
        </definition>
      </map>
    </items>
    <fields>
      <field fieldId="a66969" reference="name">
        <format type="text" />
      </field>
    </fields>
    <relations>
      <relation relationType="a36495" from="base"
       reference="account_to_contact">
        <fields>
          <field fieldId="a36498" reference="position">
            <format type="text" />
          </field>
        </fields>
      </relation>
    </relations>
  </dataSet>
</wxRequest>

Below is the corresponding response document for the above example:

<wxResponse>
  <callStatus status="success" />
  <compatibilityLevel>1</compatibilityLevel>
  <dataSet reference="accounts">
    <item itemId="u7324">
      <field fieldId="a66969" reference="name">
        <value>WorkXpress</value>
      </field>
      <relation reference="account_to_contact" id="u7437"
       relationType="a36495" baseItemTypeId="a35234" baseItemId="u7324"
       targetItemTypeId="a35334" targetItemId="u7436">
        <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.

Share this post:
  • LinkedIn
  • Twitter
  • StumbleUpon
  • Digg
  • Facebook