Introducing the WorkXpress API

16 Jul 2009 | API, PHP, Java, SOAP, Web Services, WorkXpress

WorkXpress I recently finished documenting the WorkXpress API and thought I would share some of the details. First of all, the documentation can be downloaded at http://www.workxpress.com/sites/default/files/WorkXpress%20API_1.pdf (PDF). For PHP, there is a PEAR package that makes working with the API easier. Look for that in a later post.

Available Functions

The WorkXpress API provides four different SOAP calls that allow access to four of the five building blocks (there is no way to interact with Layouts through the API).

Creating Your Authentication Key

Before using the API, you need to create an authentication key. You will need a separate key for each role of your application. In your project, you can click on the “Tools” tab of the Block Creator (see below) where you will find the “Create Auth Key” Link. On testing and production applications, you can visit http://example.workxpress.com/im_tools/create_auth_key.php to create your keys.

Tools Tab of the WorkXpress Block Creator
Tools Tab of the WorkXpress Block Creator

Once the page has loaded, you will be presented with two fields used to generate the key. The first is the user that the key should be associated with. When using the API, this user will be the “current user” for the session. The second field is the password for the selected user. This allows the API to log in as that user. After hitting the “Save” button, the page will reload and the Auth Key field will contain your authentication key.

Creating a WorkXpress Auth Key
Creating a WorkXpress Auth Key

Connecting To Your Application

To connect to your WorkXpress application, you will need to point your SOAP client at http://example.workxpress.com/api/api.php?wsdl. In PHP, you would pass this in as the first parameter to SoapClient::__construct()

$soap = new SoapClient('http://example.workxpress.com/api/api.php?wsdl');
var_dump($soap->__getFunctions());
$response = $soap->UpdateItem(1, $auth_code, $xml);

In Java, you would pass this URL to the wsimport function on the command line. This will produce two files that will allow you to connect to your application: com\workxpress\workxpressapi\WorkXpressAPIPortType.java and com\workxpress\workxpressapi\WorkXpressAPIService.java.

$ wsimport -verbose -keep http://fsip.workxpress.com/api/api.php?wsdl

Building Maps

Maps are available for three out of the four available functions (AddItem does not use a map). Maps allow you to search for Items within the application instead of having to know the item ids. Maps are XML strings that will need to have any HTML entities encoded (for PHP see htmlentities.)

To make generating maps easier, WorkXpress has created a map builder tool. To access the tool, log into your project and click on the “Tools” tab of the Block Creator (see above) where you will find the “Build Maps For API Calls” link.

The map builder functions like a normal WorkXpress query builder. You can jump across relations, filter on field values, etc. However, after making modifications to the map, there are two text areas that update with the XML version of the map. The first text area contains the human readable XML. The second text area contains the encoded XML, this is the value that will need to be placed into the XML for your API call.

WorkXpress Map Builder
WorkXpress Map Builder

More To Come

The WorkXpress API allows for some very complex interactions with WorkXpress. For this reason, I am splitting this post into several smaller post. In my next post, I will cover the LookupData function. To ensure that you catch the post as soon as it is up, subscribe to the feed.

comments powered by Disqus

Older · View Archive (34)

Selenium: Waiting For AJAX

Selenium RC I was playing around with Selenium RC a little while ago and ran into a little problem that I thought I would share with everyone. I was writing a test that bounced around WorkXpress to give me some performance benchmarks. My test added a new item that had a list layout of related items on it. I wanted to be able to follow a link to add items to that list.  Seems easy enough right?

Newer

Using the WorkXpress API: LookupData

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