Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
api [2012/08/07 00:13]
lisa [Map Builder]
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> ​ 
-</​WRAP>​ 
- 
- 
-//​Corresponding response XML:// ​ 
-<WRAP center round box 80%> 
-<​wxResponse>​ 
-    <​callStatus status=”success” /> 
-    <​compatibilityLevel>​1</​compatibilityLevel>​ 
-    <dataSet reference=”accounts”>​ 
-        <item itemId=”u3541” /> 
-        <item itemId=”u511” /> 
-    </​dataSet>​ 
-</​wxResponse>​ 
-</​WRAP>​ 
-  
- ​====== Map Builder ====== 
-  
-WorkXpress provides a map builder to make requests easier to build. ​ To access the 
-map builder, click the “Build Maps For API Calls” link on the Tools tab of the Block 
-Creator. ​ The map builder works like a normal data lookup; however, after modifying 
-any part of the map the XML definition is reloaded and displayed. ​ The XML is 
-rendered in two different formats: XML is the normal XML with all HTML entities 
-visible, Encoded XML is the XML passed through PHP's htmlentities(). ​ Encoded XML is 
-the clean version of the map definition that must be used in any API call. 
-  ​ 
-{{ :​map_builder.gif?​nolink&​300 |}} 
-====== Action: Third Party Web Service ====== 
-  
- 
-Within the WorkXpress Engine, there is a Web Service Action Type, found under the  
-Third Party category. ​ This Action Type allows the Application to make a call to any 
-SOAP web service with a publicly accessible WSDL.  After entering the WSDL location, 
-WorkXpress will read the WSDL to determine the functions that are available to be 
-called and display a select box with those options. ​ Upon an option being chosen, 
-WorkXpress will then display the input parameters with a Formula to populate each 
-one.  The output parameters will be displayed below the input parameters, with a map 
-to choose a storage location for each one.  These parameters must be simple types 
-such as strings, numbers and booleans. 
- 
-{{ :​third_party_web_service.gif?​nolink&​300 |}} 
- 
- 
-For more information on the Web Service Action Type, please see 
-http://​www.workxpress.com/​training/​third-party-webservice.  ​ 
- 
-====== WorkXpress API Data Formats ====== 
-  
- 
-The WorkXpress Engine tries hard to store data in simple, easy, logical formats.  ​ 
-Below is a description of some of the less straightforward Field Types, and what format 
-their data is expected in. 
-  
-**Item Pickers** 
-  
-An Item Picker is a Field Type that stores a reference to another Item.  These fields can 
-be used to manage Relationships,​ create links to other Items or simply store a 
-reference. ​ For more information on Item Pickers, please visit 
-http://​www.workxpress.com/​training/​item-picker-select-one. 
- 
-Item Pickers are split into two storage types: single and multi. ​ Single Item Pickers can 
-only store a single Item in the format below: 
- 
-<​itemTypeId>​|<​itemId>​ (ex. e8|u1) ​ 
- 
-Multi Item Pickers use a similar format with the addition of a comma to delimit multiple 
-values: 
-  
-<​itemTypeId>​|<​itemId>,<​itemTypeId>​|<​itemId>​ (ex. e8|u1,​e8|u58) 
-  
-**Select** 
-  
-Select Fields use Items known as Select Options to populate their available values. ​ 
-These Fields store the id of the Select Option(s) that was selected, much like Item 
-Pickers. ​ However, attempting to store the title or alternate title of a valid Select Option 
-will result in the value being converted to the proper Select Option id before storage. ​ 
-This allows you to pass in the value “Pounds” instead of having to know the Select 
-Option id.  For more information on Select Fields, please visit 
-http://​www.workxpress.com/​training/​select-one. 
-  
-Much like Item Pickers, Select Fields are split into single and multi. ​ Single Select 
-Fields can only store a single Select Option using the format below: 
-  
-e11|<​selectOptionId>​ (ex. e11|a36789) or 
-<​title>​ (ex. Pounds) or 
-<​altTitle>​ (ex. lbs)  
-  
-Multi Select Fields use a similar format with the addition of a comma to delimit multiple 
-values: 
-  
-e11|<​selectOptionId>,​e11|<​selectOptionId>​ (ex. e11|a36789,​e11|a36791) 
-or 
-<​title>,<​title>​ (ex. Pounds,​Feet) or  
-<​altTitle>,<​altTitle>​ (ex. lbs,ft) 
- 
-**Check Box**  
- 
-A Check Box Field works much like a boolean value, it is either on or off.  When a 
-Check Box is “on”, the value is stored as a 1.  When the Field is “off”, the value is 
-blank. ​ To turn a Check Box Field on, any non-empty value may be passed in to the 
-API.  To turn a Check Box Field off, the value should be empty. ​ For more information 
-on Check Box Fields, please visit http://​www.workxpress.com/​training/​checkbox. 
-  
-**Date, Time, and Date Time** 
-  
-All Date Fields are stored as a Unix time stamp. ​ This number represents the number 
-of seconds since the Unix Epoch (January 1, 1970). ​ In PHP, you can convert any 
-standard date or date time format into a Unix time stamp: 
-  ​ 
-<WRAP center round box 60%> 
-// convert a date value 
-$date = '​01/​19/​1985';​ 
-$time_stamp = strtotime($date);​ 
- 
-// convert a date time value 
-$date = '​01/​19/​1985 11:35 AM'; 
-$time_stamp = strtotime($date);​ 
- 
-// convert a time value 
-$time = '11:35 AM'; 
-$time_stamp = strtotime('​January 1, 1970 '​.$time);​ 
-</​WRAP>​ 
-  
- 
-For more information on Date Fields, visit 
-http://​www.workxpress.com/​training/​date. ​ 
- 
-  
-**File Attachment** 
-  
-File Attachment Fields are what is known as a multi-part Field. ​ These Fields are stored 
-as XML that separate different parts of the full value. ​ In order to set a File Attachment 
-Field through the API you will need to base 64 encode the binary file and place that 
-into the encoded file part of the XML.  In PHP you would using the following code: 
-  
-<WRAP center round box 60%> 
-$file_path = '/​path/​to/​file.odf';​ 
-$encoded_file = base64_encode(file_get_contents($file_path));​ 
-</​WRAP>​ 
-  
- 
-For more information on File Fields, please visit 
-http://​www.workxpress.com/​training/​file-attachment. ​ 
- 
- 
-File Attachment Fields use the following XML format: 
- 
-**<​multi_part_field></​multi_part_field>​** - Root node for all multi-part Fields. 
-  
-**<​part></​part>​** - Defines the value for a single part of the Field. 
-  
- 
-//​Attributes:// ​ 
-id String The name of the part.  Valid 
-values include: 
- 
-filename – The name to be 
-given to the file, including 
-extension. 
- 
-mime_type – The file's mime 
-type. 
- 
-size – The file's size in bytes. 
- 
-encoded_file – The base 64 
-encoded file.  
- 
-**Example:​** ​ 
-  
-<WRAP center round box 60%> 
-<?xml version=”1.0”?>​ 
-<​multi_part_field>​ 
-    <part id=”filename”>​image.png</​part>​ 
-    <part id=”mime_type”>​image/​png</​part>​ 
-    <part id=”size”>​364544</​part>​ 
-    <part id=”encoded_file”>​encodedFile</​part>​ 
-</​multi_part_field>​ 
-</​WRAP>​ 
-  
- 
-**Address** ​ 
-  
-Address Fields are also multi-part Fields. ​ Address Fields can be one of two different 
-types: US and International. ​ This type will need to be defined when setting an Address 
-Field through the API.  For more information on Address Fields, please see 
-http://​www.workxpress.com/​training/​address. ​ 
- 
-Address Fields use the following XML format: ​ 
- 
-**<​multipart_field></​multi_part_field>​** - Root node for all multi-part Fields. ​ 
-  
-**<​part></​part>​** - Defines the value for a single part of the Field. ​ 
- 
-//​Attributes://​ 
-id String The name of the part.  Valid  
-  
-values include: 
- 
-street – The value for the first 
-street part. 
- 
-street2 – The value for the 
-second street part. 
- 
-street3 – The value for the third 
-street part, only used for 
-International addresses. 
- 
-city – The value for the city. 
- 
-state – The value for the state, 
-up to three characters for 
-International and two 
-characters for United States. 
- 
-zip_code – The value for the 
-postal code.  Should be 
-numeric for United States 
-addresses. 
- 
-country – The value for the 
-country. ​ Should be the 
-countries full name or the ISO 
-3166-1 alpha-3 formatted 
-country code (see 
-http://​en.wikipedia.org/​wiki/​IS 
-O_3166-1_alpha-3). 
- 
-type – Should be either ​ 
-International or United States. 
-  
-sort_value – Which street value 
-should be used to sort this field. ​ 
-Should be either street, street2 
-or street3. ​ Only used for 
-International address. ​ 
-  
-**Example:​** 
-  
-<WRAP center round box 60%> 
-<?xm version=”1.0”?>​ 
-<​multi_part_field>​ 
-    <part id=”street”>​Ostvorstadt</​part>​ 
-    <part id=”street2”>​Hauptstraße 5</​part>​ 
-    <part id=”street3”></​part>​ 
-    <part id=”city”>​Musterstadt</​part>​ 
-    <part id=”state”></​part>​ 
-    <part id=”zip_code”>​01234</​part>​ 
-    <part id=”country”>​Germany</​part>​ 
-    <part id=”type”>​International</​part>​ 
-    <part id=”sort_value”>​street2</​part>​ 
-</​multi_part_field>​ 
-</​WRAP>​ 
-  
- 
-**Phone Number** ​ 
- 
-Phone Number Fields are also multi-part. ​ Like Address Fields, Phone Numbers can be 
-either International or United States. ​ For more information on Phone Number Fields, 
-visit 
-http://​www.workxpress.com/​training/​phone-number. ​ 
- 
-Phone Number Fields use the following XML format: ​ 
- 
-**<​multipart_field></​multi_part_field>​** - Root node for all multi-part Fields. ​ 
- 
-**<​part></​part>​** - Defines the value for a single part of the Field. 
-  
- 
-//​Attributes:// ​ 
-id String The name of the part.  Valid values 
-include: 
- 
-area_code – The value for the area 
-code.  Should be three digits for 
-United States and up to five alphanumeric 
-characters 
-for 
- 
-International. 
- 
-prefix – For United States phone 
-numbers, this is the three digits 
-immediately following the area 
-code.  This is not used for 
-International numbers. 
- 
-line_number – For United States 
-phone numbers, this is the last four 
-digits of the number. ​ For 
-International phone numbers, this is 
-the entire number after the area 
-code.  
- 
-Example: ​ 
-  
-<?xm version=”1.0”?>​ 
-<​multi_part_field>​ 
-    <part id=”area_code”>​717</​part>​ 
-    <part id=”prefix”>​609</​part>​ 
-    <part id=”line_number”>​0029</​part>​ 
-    <part id=”extension”>​123</​part>​ 
-    <part id=”country_code”>​1</​part>​ 
-    <part id=”type”>​United States</​part>​ 
-</​multi_part_field> ​ 
-  
- 
-extension – The value for the 
-extension (if any). 
- 
-country_code – The country calling 
-code for International Phone 
-Numbers. ​ Should be 1 for United 
-States, 
- 
-type – Should be either International 
-or United States. ​ 
- 
-**Example:​** ​ 
-  
-<WRAP center round box 60%> 
-<?xm version=”1.0”?>​ 
-<​multi_part_field>​ 
-    <part id=”area_code”>​717</​part>​ 
-    <part id=”prefix”>​609</​part>​ 
-    <part id=”line_number”>​0029</​part>​ 
-    <part id=”extension”>​123</​part>​ 
-    <part id=”country_code”>​1</​part>​ 
-    <part id=”type”>​United States</​part>​ 
-</​multi_part_field>​ 
-</​WRAP>​ 
- 
-====== Display Format Parts ====== 
-  
- 
-WorkXpress provides several display format parts available through the API.  These 
-parts can be used to format Field values from the LookupData function. ​ For example, 
-say you want to format an address as follows: 
- 
-453 Lincoln Street - Carlisle, PA 17013 
- 
-You could use a display format part as the value for the format node as follows: 
-  
-<WRAP center round box 60%> 
-<format type=”text”>​Street - City, State ZipCode</​format>​ 
-</​WRAP>​ 
- 
-  
-You can use display format parts for either html or text formatted Fields. ​ When using 
-the stored format, display format parts are ignored. ​ Below is a list of the display 
-format parts available for each Field Type. 
-  
-**Address** 
-  * Unordered List ItemType – The type of address, either United States or International 
-  * Street – The first street input 
-  * Street2 – The second street 
-  * Street3 – The third street of an International address 
-  * City 
-  * State 
-  * ZipCode – The postal code 
-  * Country ​ 
- 
-**Currency** ​ 
-  * Unordered List ItemNumberOnly – Returns the value without the preceding dollar sign ($) 
-  
-**Phone** 
-  * Unordered List ItemType – The type of phone number, either United States or International 
-  * CountryCode ​ 
-  * AreaCode 
-  * Prefix – The three digits immediately following the area code in a United States phone number 
-  * LineNumber – The remaining digits of the phone number ​ 
-  * Extension 
- 
-**Select – Select One**  
-  * Unordered List ItemAltTitle – Returns the alternate title of the Select Option currently stored as the Field'​s value  
-  * WithOther – Returns the title of the Select Option along with the value of the “Other” Field associated with the Select Option separated by a hyphen (if one exists). 
-  * OtherOnly – Returns only the value of the “Other” Field associated with the  
-Select Option.  ​ 
- 
-**Check Box** 
-  * Unordered List ItemChecked – Returns the word “CHECKED” if the Field is checked and “UNCHECKED” if it is not. 
-  * FieldLabel – Returns the Field'​s label if it is checked and nothing if it is not.  
-  * WithOther – Returns the same as the “Checked” display format part with the value of the “Other” Field associated with the Field'​s current value separated by a hyphen (id one exists). 
-  * OtherOnly – Returns only the value of the “Other” Field associated with the  
-Field'​s current value 
-  
-**Date and Date Time** 
-  * Unordered List ItemAMPMLowercase – Returns the appropriate am/pm value. 
-  * AMPMUppercase – Returns the appropriate AM/PM value. 
-  * DayOfMonth ​ - Day of the month without leading zeros 
-  * DayOfMonthSuffix – English ordinal suffix for the day of the month, 2 characters 
-  * DayOfMonthLeadingZero – Day of the month, 2 digits with leading zeros  
-  * DayOfWeek – A full textual representation of the day of the week 
-  * DayOfWeekAbbreviated – A textual representation of a day, three letters 
-  * DayOfWeekNumber – ISO-8601 numeric representation of the day of the week 
-  * DayOfYear – The day of the year (starting from 0)  
-  * Hour – 12-hour format of an hour without leading zeros 
-  * Hour24 – 24-hour format of an hour without leading zeros 
-  * Hour24LeadingZero – 24-hour format of an hour with leading zeros 
-  * HourLeadingZero – 12-hour format of an hour with leading zeros 
-  * Minute - Minutes with leading zeros 
-  * MonthName – A full textual representation of a month 
-  * MonthNameAbbreviated – A short textual representation of a month, three letters 
-  * MonthOfYear – Numeric representation of a month, without leading zeros  
-  * MonthOfYearLeadingZero – Numeric representation of a month, with leading zeros  
-  * Second – Seconds, with leading zeros  
-  * Timestamp – Seconds since the Unix Epoch (January 1 1970 00:00:00 GMT) 
-  * WeekOfYear – ISO-8601 week number of year, weeks starting on Monday 
-  * Year – A full numeric representation of a year, 4 digits 
-  * YearShort – A two digit representation of a year  
- 
-**File** ​ 
-  * Unordered List ItemDownloadURL – URL to download the file.  If the Field is not set to allow the File to be public, this URL will require a login. ​ 
-  * Filename – The name of the file, including extension 
-  * FileSize – The size of the file in bytes 
-  * Height – The height in pixels if the file is an image 
-  * Image – Returns an HTML image tag if the file is an image 
-  * MimeType – The file's mime type • Thumbnail – Returns an HTML image tag to the file's thumbnail if it is an image 
-  * ThumbnailURL – URL to retrieve the thumbnail if the file is an image. ​ If the Field is not set to allow the File to be public, this URL will require a login. 
-  * Width – The width in pixels if the file is an image  
- 
-**Social Security Number** 
-  
-   * Unordered List ItemLastFour – Returns only the last four digits of the social security number ​ 
-  
api.1344298415.txt.gz · Last modified: 2012/08/07 00:13 by lisa
Copyright WorkXpress, 2024