✎ api [WorkXpress]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== 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.

===== Exposed API Functions =====


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:

<WRAP center round box 60%>
$soap = new

SoapClient('http://example.workxpress.com/api/api.php?wsdl');

$response = $soap->UpdateItem(1, $auth_code, $xml);
</WRAP>


===== Compatibility Level =====


This document is written for compatibility level 1.

===== Authentication =====

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:

{{ :create_blocks.gif?nolink&300 |}}

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.

{{ :auth_key.gif?nolink |}}

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.

===== Function:  LookupData =====
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"
| Orange
| Apple
| align="right"| 12,333.00
|-
| Bread
| Pie
| align="right"| 500.00
|-
| Butter
| Ice cream
| align="right"| 1.00
|}

** <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:** 
<WRAP center round box 80%>
//An example of a basic LookupData Request might use the following XML://

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

//Corresponding response XML://
 
<WRAP center round box 80%>
<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> 
</WRAP>