- Introduction to WorkXpress
- Building Your Application
- Examples and Best Practices
- Technical Manual
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
api [2012/08/06 22:18] lisa |
api [2016/09/14 18:19] (current) |
||
|---|---|---|---|
| Line 1: | Line 1: | ||
| - | ====== Description of use for the WorkXpress API ====== | + | API Overview |
| - | 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:// | ||
| - | 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. | ||
