Differences

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

Link to this comparison view

dev resources - api [2016/09/14 14:19] (current)
Line 1: Line 1:
 +====== API Overview ======
  
 +
 +The WorkXpress API exposes the complete WorkXpress Engine using only four
 +simple functions. These functions include:
 +
 +  * [[Dev Resources - API#​Function LookupData|LookupData]]
 +  * [[Dev Resources - API#​Function AddItem|AddItem]]
 +  * [[Dev Resources - API#​Function UpdateItem|UpdateItem]]
 +  * [[Dev Resources - API#​Function ExecuteAction|ExecuteAction]]
 +
 +Each exposed function has the same three simple parameters and returns response
 +XML containing the data requested. These parameters are:
 +
 +  * API version
 +  * Authentication Code
 +  * Request XML
 +
 +===== API Version =====
 +This document is written for API Version **1**.
 +===== Authentication Code =====
 +Before you can use the WorkXpress API, an authentication key must be generated for
 +the application and user you wish the API to act as. Follow [[API Key Generator|these instructions]] to generate an auth key.
 +===== Request XML =====
 +The Request XML contains the details of what the call is supposed to do.  A complete specification of the request and response XML documents for each exposed API function follows.
 +===== Response XML =====
 +Each call returns a Response XML document, which needs to be parsed by the client program, to extract its requested data.
 +
 +====== API Functions and code samples ======
 +//All code examples are in PHP and will need to be modified for the appropriate language. ​ For PHP developers we maintain a [[Dev Resources - Services WorkXpress|PEAR package called Services WorkXpress]] that makes communicating with WorkXpress easier.
 +//
 +
 +In most programming languages making an API call requires the client application to
 +first instantiate a connection to a server through 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:
 +
 +''​$soap = new SoapClient('​http://​example.workxpress.com/​api/​api.php?​wsdl'​);​
 +$response = $soap->​UpdateItem(1,​ $auth_code, $xml);''​
 +
 +===== Function: ​ LookupData =====
 +LookupData is a function for reading record and relationship record data from the WorkXpress application. The Request XML
 +defines which tables to look in, and what filters to apply as well as the fields to
 +retrieve from each record. The API 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 tables that you want to lookup data from, and tells
 +the API it will be working with records.
 +
 +**<​item></​item>​** - Contained inside of the items node, the item node identifies a 
 +single record within the data set.
 +
 +^Item Attributes ^^^
 +|itemId | String | The record id of the record to lookup|
 +
 +
 +** <​map></​map>​** - Contained inside of the items node, the map node contains the
 +information required to lookup records from tables, including the table id and any 
 +filters.
 +
 +**<​definition></​definition>​** - Contained inside of the map node, the definition ​
 +node holds the XML definition of a [[API Query Builder|query to find records]]. ​ The XML must have any HTML entities
 +encoded; this is done in PHP by passing the XML to htmlentities().
 +
 +**<​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
 +[[Dev Resources - API#Display Format Parts|display format parts]] used to define a format. ​ If no format is provided, the full field
 +value will be returned.
 +
 +^format Attributes: ^^^
 +|type | String | ID of the field.|
 +|reference | 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 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 record to lookup.
 +
 +^relation Attributes: ^^^
 +|relationType | String | Relation table ID |
 +|from | String | Defines which side of the relation record to start from.  Valid values are:|
 +| ::: | ::: |base – The base side of the relation table.|
 +| ::: | ::: |target – The target side of the relation Table. |
 +|reference |String |An identifier that will be returned with the response to identify each relationship table. |
 +
 +==== 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 record within the data set.
 +
 +
 +^item Attributes: ^^^
 +|ItemId | String | The record id of the current record. ​ |
 +
 + 
 +**<​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: ^^^
 +|fieldId | 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 record from the current record. ​
 +
 +^relation Attributes: ^^^
 +|reference |String |The reference that was defined for the relationship table in the request document.| ​
 +|id |String |Id of the current relationship record.|
 +|relationType |String |Relationship table id of the current relationship record.|
 +|baseItemTypeId |String |Table id of the base record.|
 +|baseItemId |String |Id of the base record.|
 +|targetItemTypeId |String | Table id of the target record.|
 +|targetItemId |String |Id of the target record.|
 + 
 +**Examples:​** ​
 +<WRAP center round box 80%>
 +//An example of a basic LookupData Request might use the following XML://
 +
 +<​code><​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></​code>​
 +</​WRAP>​
 +
 +
 + 
 +<WRAP center round box 80%>//​Corresponding response XML://
 +<​code><​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></​code> ​
 +</​WRAP>​
 +===== Function: AddItem =====
 + ​AddItem is a function for creating new Items inside of WorkXpress. ​ When adding
 +Items through the WorkXpress API, any appropriate Item, Field and Relation Actions
 +will be executed.
 + 
 +**Request XML** - Below is a description of the node types, their attributes and the valid
 +child node types supported for an AddItem 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 for a item add request. ​ You may have as many data
 +sets as you want, allowing you to combine many add items requests into one call. 
 +
 +^dataSet Attributes: ^^^
 +|reference |String |An identifier that will be returned with the response to identify different data sets. |
 +
 +**<​item></​item>​** - Contained inside of the dataSet node, the item node contains the Item Type id of the Item being added.
 +
 +^item Attributes: ^^^
 +|itemTypeId |String |The Item Type id of the item being created. |
 +
 +**<​fields></​fields>​** - Contained inside of the dataSet and relation nodes, the fields ​
 +node is the parent node for the Fields to set on the Item or Relation previously defined.
 +
 +**<​field></​field>​** - Contained inside of the fields node, the field node defines a 
 +single Field to store data into.
 +
 +^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 when the Item is
 +added. ​
 +
 +**<​relation></​relation>​** - Contained inside of the relations node, the relation node
 +defines a single Relation to create. ​
 +
 +^relation Attributes:​^^^
 +|action |String |The action to perform on the Relationship. ​ This should be set to “add” when adding a Relationship. |
 +|oppositeItemId |String |The Item Id of the Item that you wish to relate the Item you are adding to. |
 +|reference |String |An identifier that will be returned with the response to identify each Relationship that was created. |
 +|relationType |String |Id of the Relation Type you would like to create.| ​
 +|startingSide |String |Defines which side of the Relation the Item being added will be on.  Valid values are:|
 +| ::: | ::: |base – The new Item is on the base side.|
 +| ::: | ::: |target – The new Item is on the target side. |
 +
 +**Response XML** - Below is a description of the valid nodes returned in the Response XML from an AddItem 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, defines an Item that was 
 +added to the WorkXpress application.
 +
 +^item Attributes: ^^^
 +|itemId |String |Id of the Item that was added. |
 +|ItemTypeId |String |Item Type id of the Item that was added. |
 +
 +**<​relation></​relation>​** - Contained inside of the item node, the relation node 
 +defines a Relation that was added to the WorkXpress application.
 +
 +^relation Attributes: ^^^
 +|reference |String |The reference that was defined for the Relation Type in the request document. |
 +|relationId |String |Id of the Relationship.|
 +
 +**Examples:​** ​
 +<WRAP center round box 80%>
 +An example of an AddItem request might use the following XML :
 +<​code><​wxRequest> ​
 +    <dataSet reference=”workxpress”>​
 +        <item itemTypeId=”a35234” />
 +        <​fields>​
 +            <field fieldId=”a66969”>​
 +                <​value>​WorkXpress</​value>​
 +            </​field>​
 +            <field fieldId=”a36314”>​
 +                <​value>​http://​www.workxpress.com</​value>​
 +            </​field>​
 +        </​fields>​
 +        <​relations>​
 +            <​relation action=”add” oppositeItemId=”u7436”
 +reference=”account_to_contact”
 +                relationType=”a36495” startingSide=”base”>​
 +                <​fields>​
 +                    <field fieldId=”a36498”>​
 +                        <​value>​Developer</​value>​
 +                    </​field>​
 +                </​fields>​
 +            </​relation>​
 +        </​relations>​
 +    </​dataSet>​
 +</​wxRequest>​ </​code>​
 +</​WRAP>​
 +
 +
 +<WRAP center round box 80%>
 +Corresponding response XML: 
 +<​code><​wxResponse>​
 +    <​callStatus status=”success” />
 +    <​compatibilityLevel>​1</​compatibilityLevel>​
 +    <dataSet reference=”workxpress”>​
 +        <item itemId=”u7563” itemTypeId=”a35234”>​
 +            <​relation reference=”account_to_contact” relationId=”u7564”
 +/>
 +        </​item>​
 +    </​dataSet>​
 +</​wxRequest>​ </​code>​
 +
 +</​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:​** ​
 +
 +<WRAP center round box 80%>//An example of a basic UpdateData request might use the following XML ://
 +<​code>​
 +    <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>​ </​code>​
 +
 +</​WRAP>​
 +
 +
 + 
 +<WRAP center round box 80%>//​Corresponding response XML://<​code>​
 +<​wxResponse>​
 +    <​callStatus status=”success” />
 +    <​compatibilityLevel>​1</​compatibilityLevel>​
 +    <dataSet reference=”account”>​
 +        <item itemId=”u7563”>​
 +          <​relation reference=”account_to_contact” relationId=”u7564” />
 +        </​item>​
 +    </​dataSet>​
 +</​wxRequest></​code>​
 +</​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:​** ​
 +<WRAP center round box 80%>//An example of a basic ExecuteAction request might use the following XML ://
 +<​code>​
 +<​wxResponse> ​
 +    <dataSet reference=”accounts”>​
 +        <​items>​
 +            <item itemId=”u3541” />
 +            <item itemId=”u511” />
 +        </​items>​
 +        <​actions>​
 +            <action actionId=”a314558” />
 +        </​actions>​
 +    </​dataSet>​
 +</​wxResponse>​ </​code>​
 +</​WRAP>​
 +
 +
 +<WRAP center round box 80%>//​Corresponding response XML:// ​
 +<​code>​
 +<​wxResponse>​
 +    <​callStatus status=”success” />
 +    <​compatibilityLevel>​1</​compatibilityLevel>​
 +    <dataSet reference=”accounts”>​
 +        <item itemId=”u3541” />
 +        <item itemId=”u511” />
 +    </​dataSet>​
 +</​wxResponse></​code>​
 +</​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&​500 |}}
 +====== 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&​500 |}}
 +
 +
 +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:
 +
 +<​code><​itemTypeId>​|<​itemId>​ (ex. e8|u1) </​code>​
 +
 +Multi Item Pickers use a similar format with the addition of a comma to delimit multiple
 +values:
 + 
 +<​code><​itemTypeId>​|<​itemId>,<​itemTypeId>​|<​itemId>​ (ex. e8|u1,​e8|u58)</​code>​
 + 
 +**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:
 + 
 +<​code>​e11|<​selectOptionId>​ (ex. e11|a36789) or
 +<​title>​ (ex. Pounds) or
 +<​altTitle>​ (ex. lbs) </​code>​
 + 
 +Multi Select Fields use a similar format with the addition of a comma to delimit multiple
 +values:
 + 
 +<​code>​e11|<​selectOptionId>,​e11|<​selectOptionId>​ (ex. e11|a36789,​e11|a36791)
 +or
 +
 +<​title>,<​title>​ (ex. Pounds,​Feet) or 
 +
 +<​altTitle>,<​altTitle>​ (ex. lbs,​ft)</​code>​
 +
 +**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 80%>
 +<​code>​
 +// 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);</​code>​
 +</​WRAP>​
 +
 +
 +For more information on Date Fields, visit
 +http://​www.workxpress.com/​training/​date. ​
 +
 +
 + 
 +**File Attachment and Signature **
 + 
 +File Attachment and Signature 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 or Signature ​
 +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 80%>
 +<​code>​
 +$file_path = '/​path/​to/​file.odf';​
 +$encoded_file = base64_encode(file_get_contents($file_path));​
 +</​code>​
 +</​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 80%>
 +<​code>​
 +<?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>​
 +</​code>​
 +</​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 fame 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 80%><​code>​
 +<?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>​
 +</​code></​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. |
 +| ::: | ::: |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 80%>
 +<​code>​
 +<?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>​
 +</​code>​
 +</​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**
 +  * Type – 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 ​
 +  * Longitude - If geo-coding is enabled
 +  * Latitude - If geo-coding is enabled ​
 +
 +**Credit Card**
 +  * CardHolderName– The name as it appears on the card.
 +  * CardType – The type of card (MasterCard,​ Visa, etc)
 +  * ExpirationMonth– The numeric representation of the month the card will expire
 +  * ExpirationYear – The 4 digit numeric representation of the year the card will expire
 +  * FirstSix - The first six numbers of the credit card (represents the type and the issuing bank)
 +  * LastFour - The last four digits of the credit card number
 +
 +**Currency** ​
 +  * NumberOnly – Returns the value without the preceding dollar sign ($)
 + 
 +**Phone**
 +  * Type – 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** 
 +  * AltTitle – 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**
 +  * Checked – 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**
 +  * AMPMLowercase – 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 and Signature** ​
 +  * DownloadURL – 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**
 + 
 +  * LastFour – Returns only the last four digits of the social security number ​
 + 
 +
 + 
dev resources - api.txt · Last modified: 2016/09/14 14:19 (external edit)
Copyright WorkXpress, 2019