Trace:

Differences

This shows you the differences between two versions of the page.

--- api [2012/08/06 23:44]
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>
-                    &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>
-===== Function: UpdateItem =====
-WorkXpress API Documentation
-UpdateItem is called to perform a number of different tasks on existing Items in
-WorkXpress. These tasks include:
-  * Unordered List ItemSet Fields on Items & Relations
-  * Recycle Items & Relations
-  * Restore previously recycled Items & Relations
-  * Delete Items & Relations
-  * Create Relations to Items
-The Request XML defines Fields to store, as well as Relations to create. The engine
-reads this definition, performs its’ tasks and then returns an item node for each Item
-effected, along with relation nodes for each Relation that was added or updated.
-Actions attached to any Items, Fields or Relations affected by the call will be run.
-**Request XML** - Below is a description of the node types, their attributes and the valid
-child node types supported for an UpdateItem request.
-**<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 to perform the requested operation.  You may have
-as many data sets as you want, allowing you to combine many operations into one call.
-//dataSet Attributes://
-reference String An identifier that will be
-returned with the response
-to identify different data
-sets.
-action String The operation to perform on
-the Item.  Valid values are:
-delete – Deleted Items are
-completely removed from
-WorkXpress and cannot be
-retrieved.
-recycle – Recycled Items
-are not removed from
-WorkXpress and can be
-restored.
-restore – Restores a
-previously recycled item.
-update – Updates an
-existing Item.
-**<items></items>** - Contained inside of the dataSet node, the items node contains
-the information required to identify the Items you wish to update.
-**<item></item>** - Contained inside of the items node, the item node identifies a
-single item in the data set.
-//item Attributes://
-itemId String The id of the Item to perform
-the operation on
-**<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 be updated.
-**<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
-**<value></value>** - Contained inside of the field node, the value node holds the
-value to store into the Field.
-**<relations></relations>** - Contained inside of the dataSet node, the relations
-node is the parent node for any Relationships that should be added or updated.
-**<relation></relation>** - Contained inside of the relations node, the relation node
-defines a single Relation to add or update.
-//relation Attributes://
-action String The action to perform on the
-Relationship.  Valid values
-are:
-add – Creates a new
-Relationship.
-update – Updates an existing
-Relationship.
-delete – Deleted
-Relationships are completely
-removed from WorkXpress
-and cannot be retrieved.
-recycle – Recycled
-Relationships are not
-removed from WorkXpress
-and can be restored.
-restore – Restores a
-previously recycled
-Relationship.
-oppositeItemId String The Item Id of the Item that
-you wish to relate the Item
-you are updating to.  If the
-action is not set to add, this
-will be used to find an
-existing Relationship.
-reference String An identifier that will be
-returned with the response to
-identify each Relationship
-that was created or updated.
-relationType String Id of the Relation Type you
-would like to create.
-startingSide String Defines which side of the
-Relation the Item being
-updated will be on.  Valid
-values are:
-base – The Item will be on
-the base side.
-target – The Item will be on
-the target side.
-**Response XML** - Below is a description of the valid nodes returned in the Response
-XML from an UpdateItem request.
-**<wxResponse></wxResponse>** - The root node for the Response XML document.
-**<callStatus></callStatus>** - Contained inside of the wxResponse node, the
-callStatus node contains 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, defines an Item that was
-updated.
-//item Attributes://
-itemId String Id of the Item that was updated
-**<relation></relation>** - Contained inside of the item node, the relation node
-defines a Relation that was added or updated.
-//relation Attributes://
-Reference String The reference that was defined
-for the Relation in the request
-document.
-relationId String Id of the Relationship.
-**Examples:**
-//An example of a basic UpdateData request might use the following XML ://
-<WRAP center round box 80%>
-<wxRequest>
-    <dataSet action=”update” reference=”account”>
-        <items>
-            <item itemId=”u7563” />
-        </items>
-        <fields>
-            <field fieldId=”a66969”>
-                <value>WorkXpress</value>
-            </field>
-        </fields>
-        <relations>
-            <relation action=”update” oppositeItemId=”u7436”
-                reference=”account_to_contact” relationType=”a36495”
-                startingSide=”base”>
-                <fields>
-                    <field fieldId=”a36498”>
-                        <value>Intern</value>
-                    </field>
-                </fields>
-            </relation>
-        </relations>
-    </dataSet>
-</wxRequest>
-</WRAP>
-//Corresponding response XML://
-<WRAP center round box 80%>
-<wxResponse>
-    <callStatus status=”success” />
-    <compatibilityLevel>1</compatibilityLevel>
-    <dataSet reference=”account”>
-        <item itemId=”u7563”>
-          <relation reference=”account_to_contact” relationId=”u7564” />
-        </item>
-    </dataSet>
-</wxRequest>
-</WRAP>
-===== Function: ExecuteAction =====
-ExecuteAction is called to run Actions that already exist in the WorkXpress
-Application on a set of Items.  The request XML defines Items and individual Actions to
-execute. The engine reads this definition, performs its’ tasks and then returns each
-Item that the Action was run on.
-**Request XML** - Below is a description of the node types, their attributes and the valid
-child node types supported for a ExecuteAction request.
-**<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 to perform the requested operation.  You may have
-as many data sets as you want, allowing you to combine many requests 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 Items you wish to run the Actions on.
-**<item></item>** - Contained inside of the items node, the item node identifies a
-single item in the data set.
-//item Attributes://
-itemId String The id of the Item to run the
-Action on.
-**<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.
-**<actions></actions>** - Contained inside of the dataSet node, the actions node
-defines the Actions that should be run on the items that were previously defined.
-**<action></action>** - Contained inside of the actions node, the action node defines
-a single Action to be executed.
-//action Attributes://
-actionId String Id of the Action
-**Response XML** - Below is a description of the valid nodes returned in the Response
-XML from an ExecuteActions request.
-**<wxResponse></wxResponse>** - The root node for the Response XML document.
-**<callStatus></callStatus>** - Contained inside of the wxResponse node, the
-callStatus 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.
-**<item></item>** - Contained inside of the dataSet node, defines a single Item that the
-Actions were run on.
-//item Attributes://
-itemId String Id of the Item.
-**Examples:**
-//An example of a basic ExecuteAction request might use the following XML ://
-<WRAP center round box 80%>
-<wxResponse>
-    <dataSet reference=”accounts”>
-        <items>
-            <item itemId=”u3541” />
-            <item itemId=”u511” />
-        </items>
-        <actions>
-            <action actionId=”a314558” />
-        </actions>
-    </dataSet>
-</wxResponse>
-Corresponding response XML:
-<wxResponse>
-    <callStatus status=”success” />
-    <compatibilityLevel>1</compatibilityLevel>
-    <dataSet reference=”accounts”>
-        <item itemId=”u3541” />
-        <item itemId=”u511” />
-    </dataSet>
-</wxResponse>
-</WRAP>

api.1344296671.txt.gz · Last modified: 2012/08/06 23:44 by lisa

Show page Old revisions

Recent Changes Sitemap Back to top