- Introduction to WorkXpress
- Building Your Application
- Examples and Best Practices
- Technical Manual
This is an old revision of the document!
The WorkXpress API exposes the complete WorkXpress Engine using only four simple functions. These functions include:
Each exposed function has the same three simple parameters and returns response XML containing the data requested. These parameters include:
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:
$soap = new
SoapClient('http://example.workxpress.com/api/api.php?wsdl');
$response = $soap→UpdateItem(1, $auth_code, $xml);
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: itemId String The id of the Item to lookup.
<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.
