- 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 23:06] 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:// | ||
- | | ||
- | {| 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> | ||
- | <?xml version="1.0" encoding="UTF-8"?> | ||
- | <wxQuery | ||
- | xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="wxQuery.xsd" | ||
- | id="root"><data | ||
- | for="root"><item/></ | ||
- | data><startingTypes><startingType& | ||
- | gt;a35234</startingType></ | ||
- | startingTypes></wxQuery> | ||
- | </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> | ||
- | |||