Description of use for the WorkXpress API

The WorkXpress API exposes the complete WorkXpress Engine using only four simple functions. These functions include:

• LookupData
• AddItem
• UpdateItem
• ExecuteAction

Each exposed function has the same three simple parameters and returns response XML containing the data requested. These parameters include:

• API version
• Authentication Code
• Request XML

Before each call is made, the client program must assemble an appropriate Request XML string. Then, a connection to the WorkXpress API must be made through the SOAP WSDL. A SOAP connection object must be instantiated, and finally, the call is made.

This call returns a Response XML document, which needs to be parsed by the client program, to extract its requested data.

A complete specification of the request and response XML documents for each exposed API function follows. All code examples are in PHP and will need to be modified for the appropriate language.

For PHP developers there is a PEAR package that makes communicating with WorkXpress easier. For more information, please see http://www.workxpress.com//sites/default/files/Services%20WorkXpress.pdf.

In most programming languages making an API call requires the client application to first instantiate a connection to the server, to a specific WSDL file. The WSDL file defines what functions and data structures are available for consumption through the API.

The URL for the WorkXpress WSDL is: http://example.workxpress.com/api/api.php?wsdl

Once the object is instantiated against the WorkXpress WSDL, all of the functions detailed below are available on the connection object, and can be called like any other function in the client language.

Example:

This document is written for compatibility level 1.

Before you can use the WorkXpress API, an authentication key must be generated for the Application. To generate an auth key on any project, click the “Crete API Auth Key” from the Tools tab in the Block Creator:

The build tools are not available on testing and production applications. However, this page can be accessed via http://example.workxpress.com/im_tools/create_auth_key.php.

Once the page loads, three Fields will be rendered. A user to associate the key with must be provided as well as that user's password. Once the Layout has been saved with the appropriate data, the Layout will reload and the Auth Key Field will be an editable Text Area with the authentication key. Auth keys cannot be retrieved. If an auth key is lost it must be regenerated from within WorkXpress.

LookupData is a function for reading from the WorkXpress database. The Request XML defines what Item Types and Relations should be looked up, as well as the Fields to retrieve from each Item/Relation. The engine reads this definition, looks up the data requested and returns a similar structure containing the requested data.

Request XML – Every XML document contains a root node, with blocks of nested child nodes. Each node opens, contains attributes and child nodes, and then closes. Below is a description of the node types, their attributes and the valid child node types.

<wxRequest></wxRequest> - The root node for the Request XML document.

<dataSet></dataSet> - Contained inside of the wxRequest node, the dataSet node contains the information required for a single lookup. You may have as many data sets as you want, allowing you to combine many lookups into one call.

dataSet Attributes: reference String An identifier that will be returned with the response to identify different data sets.

<items></items> - Contained inside of the dataSet node, the items node contains the information required to identify the item types that you want to lookup, and tells the API it will be working with items.

<item></item> - Contained inside of the items node, the item node identifies a single item within the data set.

item Attributes:

{| class=“wikitable”

<map></map> - Contained inside of the items node, the map node contains the information required to lookup each item type, including the item type id and any filters.

<definition></definition> - Contained inside of the map node, the definition node holds the XML definition of the map. The XML must have any HTML entities encoded; this is done in PHP by passing the XML to htmlentities(). * For more information on building maps, see the “Map Builder” section below.

<fields></fields> - Contained inside of the dataSet and relation nodes, the fields node is the parent node for the fields to retrieve from.

<field></field> - Contained inside of the fields node, the field node defines a single Field to retrieve data from.

field Attributes: fieldId String Id of the Field. reference String An identifier that will be returned with the response to identify each Field.

<format></format> - Contained inside of the field node, the format node defines the format of the data to return for the selected Field. This node may hold a string of display format parts used to define a format. If no format is provided, the full Field value will be returned. For more information please see the section on display format parts at the end of this document.

format Attributes: type String There are three different options for the format of the data:

html – Includes any HTML used when rendering the noneditable Field inside of the

WorkXpress Application.

stored – The format of the Field

as it is stored in the

WorkXpress database.

text – Returns the value as plain

text.

This is the recommended

format.

<relations></relations> - Contained inside of the dataSet node, the relations node is the parent node for any relationships to look up for the items that were previously defined.

<relation></relation> - Contained inside of the relations node, the relation node defines a single Relation to lookup.

relation Attributes: relationType String Id of the Relation Type. from String Defines which side of the Relation to start from. Valid values are:

base – The base side of the Relation Type.

target – The target side of the Relation Type. reference String An identifier that will be returned with the response to identify each Relation Type.

Response XML - Below is a description of the valid nodes returned in the Response XML from a LookupData request.

<wxResponse></wxResponse> - The root node for the Response XML document.

<callStatus></callStatus> - Contained inside of the wxResponse node, the callStatus node contains the status of the SOAP call.

callStatus Attributes: status String The call's status. Values include success and failure.

<compatibilityLevel></compatibilityLevel> - Contained inside of the wxResponse node, the compatibilityLevel node contains the version of the API that was used.

<dataSet></dataSet> - Contained inside of the wxResponse node, one data set is returned for each data set in the request document.

dataSet Attributes: reference String The reference that was defined for the data set in the request document.

<item></item> - Contained inside of the dataSet node, the item node identifies a single item within the data set.

item Attributes: ItemId String The id of the current item.

<field></field> - Contained inside of the item or relation node, the field node contains data about a single field on the current Item or Relation.

field Attributes: ItemId String Id of the Field. reference String The reference that was defined for the field in the request document.

<value></value> - Contained inside of the field node, the value node holds the value for the current Field.

<relation></relation> - Contained inside of the item node, the relation node contains data about a single relationship from the current item.

relation Attributes: reference String The reference that was

orrespond

defined for the Relation Type in the request document. id String Id of the current Relationship. relationType String Relation Type id of the current Relationship. baseItemTypeId String Item Type id of the base Item. baseItemId String Id of the base Item. targetItemTypeId String Item Type id of the target Item. targetItemId String Id of the target Item. Examples:

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

Corresponding response XML:

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