Differences

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

Link to this comparison view

dev resources - services workxpress [2016/09/14 14:19] (current)
Line 1: Line 1:
 +====== Services WorkXpress ======
 +Services WorkXpress is a Pear package for PHP that makes communicating with the API easier. ​ The package allows one to make API calls using common data structures such as objects and arrays. ​ All of the functionality of the API is exposed through this package, so anything available through the API is supported.  ​
  
 +This document refers to Services WorkXpress version 1.0.  Services WorkXpress requires PHP 5.2+ with the base PEAR library installed. ​ For more information on PEAR, please visit [[http://​pear.php.net]].  ​
 +
 +  * Download Services WorkXpress only: [[http://​www.workxpress.com/​sites/​default/​files/​api/​Services_WorkXpress.tar.gz|Services_WorkXpress.tar.gz]].
 +  * Download a [[Dev Resources - Services WorkXpress Project|new project]] containing Services WorkXpress and supporting files: [[http://​www.workxpress.com/​sites/​default/​files/​api/​Services_WorkXpress_Project.tar.gz|Services_WorkXpress_Project.tar.gz]].
 +
 +===== Getting Started =====
 +Before making any calls to the API an instance of Services WorkXpress must be instantiated and properly configured. ​ Please ensure that you've run the /​scripts/​test.php file if you are using the provided new project package. ​ If not, be sure you've included all the pear files and folders so the following line generates no errors or warnings:
 +
 +<code php>
 +$workxpress = new Services_WorkXpress(); ​
 +</​code>​
 +
 +After instantiating the object there are three options that must be configured.  ​
 +
 +  * API version : The current API version is 1.  ​
 +  * Authentication Key : A different auth key must be provided for each different application role – projects, testing and production. ​ The authentication key represents the user that the API will act as on the application you are accessing. ​ To learn more about creating an auth key, please see the API documentation.  ​
 +  * Remote Host : This should be set to the address of your application. ​
 +
 +<code php>
 +$workxpress->​setAPIVersion(1); ​
 +$workxpress->​setAuthKey($auth_key); ​
 +$workxpress->​setRemoteHost('​http://​example.workxpress.com'​);​
 +</​code>​
 +
 +Once the object has been properly configured, it's time to start constructing the request. ​ There are four types of requests that can be made using the API: 
 +
 +  * LookupData – Queries for [[Record|records]],​ or references them by record id and pulls [[Field|field]] data and their record id's from the application. ​
 +  * AddItem – Adds new records to an application,​ setting fields and creating relationship records.
 +  * UpdateItem – Updates existing records'​ fields and relationship records.
 +  * ExecuteAction – Run Actions that exist in the application. ​
 +
 +All of the requests can be made either by using many method calls on the request object or passing a single array to the request object. To build the request, a request object must be instantiated using the Services_WorkXpress::​loadRequest() method: ​
 +
 +<code php>
 +$request = $workxpress->​loadRequest('​LookupData'​); ​
 +/* @var $request Services_WorkXpress_Request_LookupData */
 +</​code>​
 +
 +Each request can be made up of many data sets.  A data set is a definition of a single operation. ​ This allows for multiple lookups, updates, new items, or action executions to be made using a single call.  However, request types cannot be mixed. ​ Although you can have a single call with five different lookups, you cannot have a single call that performs a lookup and executes an Action. ​  Each request type is detailed in the sections that follow.
 +
 +===== LookupData Request =====
 +LookupData is a function for reading from the application database. ​ It allows you to define the [[Table|tables]] and [[Relationship Table|relationship tables]] that you wish to look up records from, as well as filter those records. ​ If you already know the record id of a specific record(s), you can also pull data from the record(s) without performing a search. ​
 +
 +==== Request Object Methods ====
 +The LookupData request object provides six methods to construct the request to the API: 
 +
 +**addDataSet()** - Adds a single data set to the request. ​
 +
 +//​addDataSet Arguments://​
 +^ $reference ​ (Optional) ​      ^ String ​ | An identifier that will be returned with the  response to identify each data set.  If the  reference is empty a random one will be  created. ​   |
 +^ $data_set_array ​ (Optional) ​ ^ Array   | An optional array that describes the contents of  the data set.  This argument can be used instead ​ of using the other methods on this object. ​ |
 +
 +**addItem()** - Adds a single record to the lookup. ​
 +
 +//addItem Arguments: //
 +^ $itemId ​ ^ String ​ | The record id of the record to lookup. ​ |
 +
 +**addMap()** - Adds a query to the request that will search for records instead of defining individual records. ​ For more information on building query'​s,​ please see the [[API Query Builder]] page. 
 +
 +//addMap Arguments: //
 +^ $definition ^ String | XML for the query definition. ​ Services WorkXpress will pass the string through htmlentities() to make it safe for inclusion in the SOAP call. |
 +
 +**addField()** - Adds a field to pull data from on the records that are specified/​found. ​
 +
 +//addField Arguments: //
 +
 +^ $fieldId ​           ^ String ​ | The id of the field to pull data from.                                                                                                                                                                                                                                                                                                                                                                                            |
 +^ $format (Optional) ​ ^ String ​ | One of the Services_WorkXpress::​FIELD_FORMAT_* constants. ​ These values correspond to the different formats that can be returned by the API.\\ \\  **STORED** (Default): Returns the data as it is stored in the application database. \\ **TEXT**: Returns the plain text format of the Field as it would be displayed inside of the application. \\ **HTML**: Returns the Field exactly how it would be displayed inside of the application,​ including and HTML.  |
 +^ $format_formula (Optional) ^ String | A string of display format parts used to create a custom format. ​ For more information,​ see the display format parts section of the API documentation. |
 +^ $reference (Optional) ^ String | An identifier that will be returned with the response to identify each Field. ​ If the reference is empty a random one will be created. |
 +
 +**addRelation()** - Adds a relation to the request. ​
 +
 +//​addRelation Arguments:// ​
 +
 +^ $relationType ^ String | Id of the Relationship Table for the relationship to pull data from. |
 +^ $from ^ String | Defines which side of the relationship to start from.\\ \\ Valid values are: \\ base – The base side of the relationship. \\ target – The target side of the relationship. |
 +^ $fields ^ Array | An array of fields to pull from the relationship,​ formated as follows: <code php>​array( ​
 +    '​fieldId'​ => String, ​
 +    '​format'​ => String stored|text|html, ​
 +    '​reference'​ => String (Optional), ​
 +    '​formatFormula'​ => String (Optional), ​
 +);</​code>​ |
 +^ $reference (Optional) ^ String | An identifier that will be returned with the response to identify each relation found by this addRelation() call.  If the reference is empty a random one will be created.|
 +
 +**call()** - Executes the API call 
 +
 +==== Example Using Array ====
 +Below is an example of a LookupData request using an array as input: ​
 +<code php>
 +<?​php ​
 +// load the Services_WorkXpress object ​
 +$workxpress ​ = new Services_WorkXpress(); ​
 +$workxpress->​setAPIVersion(1); ​
 +$workxpress->​setAuthKey($auth_key); ​
 +$workxpress->​setRemoteHost('​http://​example.workxpress.com'​);​
 +
 +// load the request object ​
 +$request = $workxpress->​loadRequest('​LookupData'​); ​
 +/* @var $request Services_WorkXpress_Request_LookupData */ 
 +
 +// we'll use a query to find our records
 +$query_definition = '<?​xml version="​1.0"​ encoding="​UTF-8"?>​
 +<wxQuery xmlns:​xsi="​http://​www.w3.org/​2001/​XMLSchema-instance"​ xsi:​noNamespaceSchemaLocation="​wxQuery.xsd"​ id="​root">​
 +<​startingTypes><​startingType>​a1</​startingType></​startingTypes><​data for="​root"​ /></​wxQuery>'; ​
 +
 +// build the data set array 
 +$data_set_array = array( ​
 +    '​items'​ => array ( 
 +        // we can also define any records that we know 
 +        array('​itemId'​ => '​u4'​), ​
 +        array('​definition'​ => $query_definition), ​
 +    ), 
 +    '​fields'​ => array ( 
 +        array( ​
 +            '​fieldId'​ => '​a14', ​
 +            '​reference'​ => '​Mailing Address', ​
 +            '​format'​ => Services_WorkXpress::​FIELD_FORMAT_TEXT,​
 +            '​formatFormula'​ =>  '​Street – City, State ZipCode',​
 +        ), 
 +        array( ​
 +            '​fieldId'​ => '​a26', ​
 +            '​reference'​ => '​PhoneNumber', ​
 +            '​format'​ => '​stored' ​
 +        ), 
 +    ), 
 +    '​relations'​ => array( ​
 +        array( ​
 +            '​relationType'​ => '​a47', ​
 +            '​from'​ => '​target', ​
 +            '​reference'​ => '​relation', ​
 +            '​fields'​ => array( ​
 +                array( ​
 +                    '​fieldId'​ => '​a56', ​
 +                    '​format'​ => Services_WorkXpress::​FIELD_FORMAT_HTML, ​
 +                ) 
 +            ), 
 +        ), 
 +    ) 
 +); 
 +$request->​addDataSet('​A',​ $data_set_array); ​
 +  ​
 +/** make the API call **/ 
 +try 
 +
 +    // make the call and get the data array 
 +    $response = $request->​call(); ​
 +    /* @var $response Services_WorkXpress_Response_LookupData */ 
 +    $items = $response->​getDataArray(Services_WorkXpress::​DATA_ARRAY_FORMAT_FULLY_COLLAPSED); ​
 +     
 +    // show the results ​
 +    echo '<​pre>'​.print_r($items, ​ true).'</​pre>'; ​
 +} // end try 
 +catch (Services_WorkXpress_Exception $e) 
 +{
 +    echo '<​h1>​Error</​h1><​pre>'​.$e->​getMessage().'</​pre>'; ​
 +} // end catch Services_WorkXpress_Exception ​
 +</​code>​
 +
 +==== Example Using Methods ====
 +Below is an example of a LookupData request using the methods provided by Services WorkXpress: ​
 +
 +<code php>
 +<?​php ​
 +// load the Services_WorkXpress object ​
 +$workxpress ​ = new Services_WorkXpress(); ​
 +$workxpress->​setAPIVersion(1); ​
 +$workxpress->​setAuthKey($auth_key); ​
 +$workxpress->​setRemoteHost('​http://​example.workxpress.com'​); ​
 +
 +// load the request object ​
 +$request = $workxpress->​loadRequest('​LookupData'​); ​
 +/* @var $request Services_WorkXpress_Request_LookupData */ 
 +  ​
 +// we'll use a query to find our records
 +$query_definition = '<?​xml version="​1.0"​ encoding="​UTF-8"?>​
 +<wxQuery xmlns:​xsi="​http://​www.w3.org/​2001/​XMLSchema-instance"​ xsi:​noNamespaceSchemaLocation="​wxQuery.xsd"​ id="​root">​
 +<​startingTypes><​startingType>​a1</​startingType></​startingTypes><​data for="​root"​ /></​wxQuery>'; ​
 +
 +// add the first data set 
 +$request->​addDataSet('​A'​); ​
 +$request->​addItem('​u4'​); ​
 +$request->​addField('​a26',​ Services_WorkXpress::​FIELD_FORMAT_STORED,​ null, '​PhoneNumber'​); ​
 +
 +// define fields for the relationship
 +$relation_fields = array( ​
 +  '​fieldId'​ => '​a56', ​
 +       '​format'​ => Services_WorkXpress::​FIELD_FORMAT_HTML, ​
 +) // end $relation_fields ​
 +
 +// add a second data set 
 +$request->​addDataSet('​B'​); ​
 +$request->​addMap($map_definition);​
 +$request->​addField('​a14', ​ Services_WorkXpress::​FIELD_FORMAT_TEXT, ​
 +    '​Street – City, State ZipCode',​ '​MailingAddress'​); ​
 +$request->​addField('​a26',​ Services_WorkXpress::​FIELD_FORMAT_STORED, ​
 +    null, '​PhoneNumber'​); ​
 +$request->​addRelation('​a47',​ '​target',​ $relation_fields,​ '​Relation'​); ​
 +/** make the API call **/ 
 +try 
 +
 +    // make the call and get the data array 
 +    $response = $request->​call(); ​
 +    /* @var $response Services_WorkXpress_Response_LookupData */ 
 +    $items = $response->​getDataArray(Services_WorkXpress::​DATA_ARRAY_FORMAT_FULLY_COLLAPSED); ​
 +     
 +    // show the results ​
 +    echo '<​pre>'​.print_r($items, ​ true).'</​pre>'; ​
 +} // end try 
 +catch (Services_WorkXpress_Exception $e) 
 +
 +    echo '<​h1>​Error</​h1><​pre>'​.$e->​getMessage().'</​pre>'; ​
 +} // end catch Services_WorkXpress_Exception ​
 +</​code>​
 +
 +===== AddItem Request =====
 +AddItem is a function for creating new records inside of an application. ​ When adding records through the API, any appropriate Table, Field and Relationship Table Actions will be executed.
 +
 +==== Request Object Methods ====
 +The AddItem request object provides four methods to construct the request to the API: 
 +
 +** addDataSet() ** - Adds a single data set to the request. ​
 +
 +//​addDataSet Arguments: //
 +^ $reference (Optional) ​ ^  String ​ | An identifier that will be returned with the response to identify each data set.  If the reference is empty a random one will be created. |
 +^ $data_set_array (Optional) ​ ^  Array  | An optional array that describes the contents of the data set.  This argument can be used instead of using the other methods on this object. |
 +
 +** addField() ** - Adds a Field to set data into on the new Item. 
 +
 +//addField Arguments: //
 +
 +^ $fieldId ​ ^  String ​ | The id of the Field to set. |
 +^ $value ​ ^  String ​ | The value to set into the Field. ​ See the [[Dev Resources - API#​WorkXpress API Data Formats|API documentation]] for information on the data formats of some Fields. |
 +
 +** addRelation() ** - Adds a relationship to be added with the record. ​
 +
 +//​addRelation Arguments: //
 +
 +^ $relationType ​ ^  String ​ | Id of the Relationship Table for the new relationship. |
 +^ $startingSide ​ ^  String ​ | Defines which side of the relationship the record being added will be on.\\ \\ Valid values are: \\ base – The base side of the relationship. \\ target – The target side of the relationship. |
 +^ $oppositeItemId ^  String ​ | The Item id of the Item that you wish to relate the Item you are adding to. |
 +^ $fields (Optional) ​ ^  Array  | An array of Fields to set on the relationship,​ formatted as follows: <code php>​array( ​
 +    '​fieldId'​ => String, ​
 +    '​value'​ => String, ​
 +); </​code>​ |
 +^ $reference (Optional) ​ ^  String ​ | An identifier that will be returned with the response to identify each relationship. ​ If the reference is empty a random one will be created. |
 +
 +**call()** - Executes the API call 
 +
 +==== Example Using Array ====
 +  ​
 +Below is an example of an AddItem request using an array as input: ​
 +
 +<code php>
 +<?​php ​
 +// load the Services_WorkXpress object ​
 +$workxpress ​ = new Services_WorkXpress(); ​
 +$workxpress->​setAPIVersion(1); ​
 +$workxpress->​setAuthKey($auth_key); ​
 +$workxpress->​setRemoteHost('​http://​example.workxpress.com'​); ​
 +
 +// load the request object ​
 +$request = $workxpress->​loadRequest('​AddItem'​); ​
 +/* @var $request Services_WorkXpress_Request_AddItem */ 
 +
 +// build the data set array 
 +$data_set_array = array( ​
 +    '​item'​ => array ( 
 +        array('​itemTypeId'​ => '​a22'​), ​
 +    ), 
 +    '​fields'​ => array ( 
 +        array( ​
 +            '​fieldId'​ => '​a37', ​
 +            '​value'​ => 123, 
 +        ), 
 +        array( ​
 +            '​fieldId'​ => '​a39', ​
 +           '​value'​ => 'Heres some Text!!', ​
 +        ), 
 +    ), 
 +    '​relations'​ => array( ​
 +        array( ​
 +            '​relationType'​ => '​a68', ​
 +            '​startingSide'​ => '​target', ​
 +            '​reference'​ => '​relation', ​
 +            '​oppositeItemId'​ => '​u2', ​
 +            '​fields'​ => array( ​
 +                array( ​
 +                    '​fieldId'​ => '​a75', ​
 +                    '​value'​ => 'From an array...', ​
 +                ), 
 +            ), 
 +        ), 
 +    ), 
 +); // end $data_set_array ​
 +
 +// Add the data set
 +$request->​addDataSet('​First Item', $data_set_array); ​
 +
 +/** make the API call **/ 
 +try 
 +
 +    // make the call and get the data array 
 +    $response = $request->​call(); ​
 +    /* @var $response Services_WorkXpress_Response_AddItem */ 
 +
 +    $items = $response->​getDataArray(Services_WorkXpress::​DATA_ARRAY_FORMAT_FULLY_COLLAPSED); ​
 +        ​
 +    // show the results ​
 +    echo '<​pre>'​.print_r($items,​ true).'</​pre>'; ​
 +} // end try 
 +catch (Services_WorkXpress_Exception $e) 
 +
 +    echo '<​h1>​Error</​h1><​pre>'​.$e->​getMessage().'</​pre>'; ​
 +} // end catch Services_WorkXpress_Exception ​
 +</​code>​
 +
 +==== Example Using Methods ====
 +  ​
 +Below is an example of an AddItem request using the methods provided by Services WorkXpress: ​
 +
 +<code php>
 +<?​php ​
 +// load the Services_WorkXpress object ​
 +$workxpress ​ = new Services_WorkXpress(); ​
 +$workxpress->​setAPIVersion(1); ​
 +$workxpress->​setAuthKey($auth_key); ​
 +$workxpress->​setRemoteHost('​http://​example.workxpress.com'​); ​
 +
 +// load the request object ​
 +$request = $workxpress->​loadRequest('​AddItem'​); ​
 +/* @var $request Services_WorkXpress_Request_AddItem */ 
 +
 +// add the data set 
 +$request->​addDataSet('​First Item'​); ​
 +
 +// add the record
 +$request->​addItem('​a22'​); ​
 +$request->​addField('​a37',​ 123); 
 +$request->​addField('​a39',​ 'Heres some Text!!'​); ​
 +
 +// setup the relationship fields ​
 +$relation_fields = array( ​
 +    array( ​
 +        '​fieldId'​ => '​a75', ​
 +        '​value'​ => 'From an array...' ​
 +    ), 
 +); // end $relation_fields ​
 +
 +// add the relationship
 +$request->​addRelatoin('​a68',​ '​target',​ '​u2',​ $relation_fields,​ '​relation'​); ​
 +    ​
 +/** make the API call **/ 
 +try
 +
 +    // make the call and get the data array 
 +    $response = $request->​call(); ​
 +    /* @var $response Services_WorkXpress_Response_AddItem */ 
 +    ​
 +    $items = $response->​getDataArray(Services_WorkXpress::​DATA_ARRAY_FORMAT_FULLY_COLLAPSED); ​
 +        ​
 +    // show the results ​
 +    echo '<​pre>'​.print_r($items,​ true).'</​pre>'; ​
 +} // end try 
 +catch (Services_WorkXpress_Exception $e) 
 +
 +    echo '<​h1>​Error</​h1><​pre>'​.$e->​getMessage().'</​pre>'; ​
 +} // end catch Services_WorkXpress_Exception
 +</​code>​
 +
 +===== UpdateItem Request =====
 +UpdateItem is called to perform a number of different tasks on existing records in an application.
 +
 +These tasks include: ​
 +  * Set Fields on records & relationships
 +  * Recycle records & relationships
 +  * Restore previously recycled records & relationships
 +  * Delete records & relationships
 +  * Create relationships between records
 +
 +Actions attached to any Tables, Fields or Relation Tables affected by the call will be run.  ​
 +
 +==== Request Object Methods ====
 +The UpdateItem request object provides six methods to construct the request to the API: 
 +
 +**addDataSet()** - Adds a single data set to the request. ​
 +
 +//​addDataSet Arguments://​
 +^ $action ​ ^  String ​ | One of the Services_WorkXpress::​DATA_SET_ACTION_* constants corresponding to the action that should be performed on the records in the data set. \\ \\ DELETE – Deletes the record. Records that have been deleted cannot be recovered. \\ RECYCLE – Recycles the record. ​ Records that have been recycled can be restored.\\ RESTORE – Restores a previously recycled record. \\ UPDATE – Updates an existing record. |
 +^ $reference (Optional) ​ ^  String ​ | An identifier that will be returned with the response to identify each data set.  If the reference is empty a random one will be created. |
 +^ $data_set_array (Optional) ​ ^  Array  | An optional array that describes the contents of the data set.  This argument can be used instead of using the other methods on this object. |
 +
 +**addItem()** - Adds a single item to the request. ​
 +
 +//addItem Arguments://​
 +^ $itemId ​ ^  String ​ | The id of the record to update. |
 +
 +**addMap()** - Adds a query to the request that will search for records instead of defining individual records. ​ For more information on building queries, please see the [[API Query Builder]] page. 
 +
 +//addMap Arguments: //
 +^ $definition ​ ^  String ​ | XML for the query definition. ​ Services WorkXpress will pass the string through htmlentities() to make it safe for inclusion in the SOAP call. |
 +
 +**addField()** - Adds a Field to set data into on the records. ​
 +
 +//addField Arguments://​
 +^ $fieldId ​ ^  String ​ | The id of the Field to set. |
 +^ $value ​ ^  String ​ | The value to set into the field. ​ See the [[Dev Resources - API#​WorkXpress API Data Formats|API documentation]] for information on the data formats of some Fields. |
 +
 +**addRelation()** - Adds a Relation to be added or updated. ​
 +
 +//​addRelation Arguments:// ​
 +^ $action ​ ^  String ​ | Action to be performed on the relationship. \\ \\ add – Creates a new relationship. \\ update – Updates an existing relationship. \\ delete – Deleted relationships are completely removed from the application and cannot be retrieved. \\ recycle – Recycled relationships are not removed from the application and can be restored. \\ restore – Restores a previously recycled relationship. ​ |
 +^ $relationType ​ ^  String ​ | Id of the Relation Type for the Relation. ​
 +^ $startingSide ​ ^  String ​ | Defines which side of the relationship the record being updated will be on.  Valid values are: \\ \\ base – The base side of the relationship. \\ target – The target side of the relationship. ​ |
 +^ $oppositeItemId (Optional) ​  ​^ ​ String ​ | The recordid of the record that you wish to relate the record you are updating to.  If no record id is provided, all relationships of the appropriate type and direction for the record will be found. ​ A record id is required for the add action. |
 +^ $fields (Optional) ​ ^  Array  | An array of Fields to set on the Relation, formatted as follows: \\ 
 +<code php>
 +array( ​
 +    '​fieldId'​ => String, ​
 +    '​value'​ => String, ​
 +); </​code>​
 +^ $reference (Optional) ​ ^  String ​ | An identifier that will be returned with the response to identify each relationship. ​ If the reference is empty a random one will be created. |
 +
 +call() - Executes the API call 
 +
 +==== Example Using Array ====
 +  ​
 +Below is an example of an UpdateItem request using an array as input: ​
 +
 +<code php>
 +<?php
 +// load the Services_WorkXpress object ​
 +$workxpress ​ = new Services_WorkXpress(); ​
 +$workxpress->​setAPIVersion(1); ​
 +$workxpress->​setAuthKey($auth_key); ​
 +$workxpress->​setRemoteHost('​http://​example.workxpress.com'​); ​
 +
 +// load the request object ​
 +$request = $workxpress->​loadRequest('​UpdateItem'​); ​
 +/* @var $request Services_WorkXpress_Request_UpdateItem */ 
 +
 +// we'll use a query to find our records
 +$query_definition = '<?​xml version="​1.0"​ encoding="​UTF-8"?>​
 +<wxQuery xmlns:​xsi="​http://​www.w3.org/​2001/​XMLSchema-instance"​ xsi:​noNamespaceSchemaLocation="​wxQuery.xsd"​ id="​root">​
 +<​startingTypes><​startingType>​a1</​startingType></​startingTypes><​data for="​root"​ /></​wxQuery>'; ​
 +
 +// create the first data set array 
 +$data_set_array = array( ​
 +    '​items'​ => array( ​
 +        array('​itemId'​ => '​u4'​), ​
 +    ), 
 +    '​fields'​ => array( ​
 +        array( ​
 +            '​fieldId'​ => '​a18', ​
 +            '​value'​ => 'Test Value', ​
 +        ), 
 +    ), 
 +    '​relations'​ => array( ​
 +        array( ​
 +            '​action'​ => '​add', ​
 +            '​relationType'​ => '​a47', ​
 +            '​startingSide'​ => '​target', ​
 +            '​oppositeItemId'​ => '​u8', ​
 +        ), 
 +    )
 +); // end $data_set_array ​
 +
 +// add the first data set 
 +$request->​addDataSet(Services_WorkXpress::​DATA_SET_ACTION_UPDATE,​ '​A',​ $data_set_array); ​
 +    ​
 +// create the second data set array 
 +$data_set_array = array( ​
 +    '​items'​ => array( ​
 +        array('​definition'​ => $query_definition), ​
 +    ), 
 +    '​fields'​ => array( ​
 +        array( ​
 +            '​fieldId'​ => '​a32', ​
 +            '​value'​ => 'Lots of text...', ​
 +        ), 
 +    ), 
 +    '​relations'​ => array( ​
 +        // recycle all relationships in relation table a47 on the records in this data set 
 +        array( ​
 +            '​action'​ => '​recycle', ​
 +            '​relationType'​ => '​a47', ​
 +            '​startingSide'​ => '​target', ​
 +            '​oppositeItemId'​ => '​u8', ​
 +            '​fields'​ => array( ​
 +                '​fieldId'​ => '​a56', ​
 +                '​value'​ => 'for ALL of them?' ​
 +            ), 
 +            '​reference'​ => '​relationAdd', ​
 +        ), 
 +        // add a relation between the record and record u8 with no fields ​
 +        array( ​
 +            '​action'​ => '​add', ​
 +            '​relationType'​ => '​a47', ​
 +            '​startingSide'​ => '​target', ​
 +            '​reference'​ => '​relationRecycle', ​
 +        ),
 +        // update all relations in relation table a32 on the items in this data set 
 +        array( ​
 +            '​action'​ => '​update', ​
 +            '​relationType'​ => '​a32', ​
 +            '​startingSide'​ => '​base', ​
 +            '​fields'​ => array( ​
 +                '​fieldId'​ => '​a56', ​
 +                '​value'​ => 'for ALL of them?' ​
 +            ), 
 +            '​reference'​ => '​relationUpdate', ​
 +        ), 
 +        // delete all relations in relation table a32 on the items in this data set 
 +        array( ​
 +            '​action'​ => '​delete', ​
 +            '​relationType'​ => '​a65', ​
 +            '​startingSide'​ => '​base', ​
 +            '​reference'​ => '​relationDelete', ​
 +        ), 
 +        // restore all relations in relation table a32 on the items in this data set 
 +        array( ​
 +            '​action'​ => '​restore', ​
 +            '​relationType'​ => '​a15', ​
 +            '​startingSide'​ => '​base', ​
 +            '​reference'​ => '​relationRestore', ​
 +        ), 
 +    ) 
 +); // end $data_set_array ​
 +
 +// add the second data set 
 +$request->​addDataSet(Services_WorkXpress::​DATA_SET_ACTION_UPDATE,​ '​B',​ $data_set_array);​
 +
 +/** make the API call **/ 
 +try 
 +
 +    // make the call and get the data array 
 +    $response = $request->​call(); ​
 +    /* @var $response Services_WorkXpress_Response_UpdateItem */ 
 +    ​
 +    $items = $response->​getDataArray(Services_WorkXpress::​DATA_ARRAY_FORMAT_FULLY_COLLAPSED); ​
 +    ​
 +    // show the results ​
 +    echo '<​pre>'​.print_r($items,​ true).'</​pre>'; ​
 +} // end try 
 +catch (Services_WorkXpress_Exception $e) 
 +
 +    echo '<​h1>​Error</​h1><​pre>'​.$e->​getMessage().'</​pre>'; ​
 +} // end catch Services_WorkXpress_Exception ​
 +?>
 +</​code>​
 +==== Example Using Methods ====
 +  ​
 +Below is an example of an UpdateItem request using the methods provided by Services WorkXpress. ​
 +
 +<code php>
 +<?php
 +// load the Services_WorkXpress object ​
 +$workxpress ​ = new Services_WorkXpress(); ​
 +$workxpress->​setAPIVersion(1); ​
 +$workxpress->​setAuthKey($auth_key); ​
 +$workxpress->​setRemoteHost('​http://​example.workxpress.com'​); ​
 +
 +// load the request object ​
 +$request = $workxpress->​loadRequest('​UpdateItem'​); ​
 +/* @var $request Services_WorkXpress_Request_UpdateItem */ 
 +
 +// we'll use a map to find our items 
 +$query_definition = '<?​xml version="​1.0"​ encoding="​UTF-8"?>​
 +<wxQuery xmlns:​xsi="​http://​www.w3.org/​2001/​XMLSchema-instance"​ xsi:​noNamespaceSchemaLocation="​wxQuery.xsd"​ id="​root">​
 +<​startingTypes><​startingType>​a1</​startingType></​startingTypes><​data for="​root"​ /></​wxQuery>'; ​
 +
 +// add the fist data set 
 +$request->​addDataSet(Services_WorkXpress::​DATA_SET_ACTION_UPDATE,​ '​A'​); ​
 +$request->​addItem('​u4'​); ​
 +$request->​addField('​a18',​ 'Test Value'​); ​
 +
 +// add a relationship between the record and record u8 with no fields ​
 +$request->​addRelation('​add',​ '​a47',​ '​target',​ '​u8'​); ​
 +
 +// add the second data set 
 +$request->​addDataSet(Services_WorkXpress::​DATA_SET_ACTION_UPDATE,​ '​B'​); ​
 +$request->​addMap($query_definition); ​
 +$request->​addField('​a32',​ 'Lots of text...'​); ​
 +
 +// recycle all relationships in relation table a47 on the records in this data set 
 +$request->​addRelation('​recycle',​ '​a47',​ '​target',​ null, array(), '​relationRecycle'​); ​
 +    ​
 +// setup the relationship fields ​
 +$relation_fields = array( ​
 +    array( ​
 +        '​fieldId'​ => '​a56', ​
 +        '​value'​ => 'for ALL of them?', ​
 +    ), 
 +); // end $relation_fields ​
 +
 +// add a new relationship to all of the records in this data set, with data on the relationship(s) ​
 +$request->​addRelation('​add',​ '​a47',​ '​target',​ '​u8',​ $relation_fields,​ '​relationAdd'​); ​
 +    ​
 +// update all relationships in relation table a32 on the records in this data set 
 +$request->​addRelation('​update',​ '​a32',​ '​base',​ null, $relation_fields,​ '​relationUpdate'​); ​
 +    ​
 +// delete all relationships in table a65 on the records in this data set. 
 +$request->​addRelation('​delete',​ '​a65',​ '​base',​ null, array(), '​relationDelete'​); ​
 +    ​
 +// restore all relationships in table a15 on the records in this data set. 
 +$request->​addRelation('​restore',​ '​a15',​ '​base',​ null, array(), '​relationRestore'​); ​
 +
 +/** make the API call **/
 +try 
 +
 +    // make the call and get the data array 
 +    $response = $request->​call(); ​
 +    /* @var $response Services_WorkXpress_Response_UpdateItem */
 +    ​
 +    $items = $response->​getDataArray(Services_WorkXpress::​DATA_ARRAY_FORMAT_FULLY_COLLAPSED); ​
 +    ​
 +    // show the results ​
 +    echo '<​pre>'​.print_r($items,​ true).'</​pre>'; ​
 +} // end try 
 +catch (Services_WorkXpress_Exception $e) 
 +
 +    echo '<​h1>​Error</​h1><​pre>'​.$e->​getMessage().'</​pre>'; ​
 +} // end catch Services_WorkXpress_Exception ​
 +?>
 +</​code>​
 +
 +===== ExecuteAction Request =====
 +ExecuteAction is called to run actions that already exist in the application on a set of records. ​ The request XML defines records and individual actions to execute. The engine reads this definition, triggers the actions and then returns each record that the action was run on. 
 +
 +==== Request Object Methods ====
 +The ExecuteAction request object provides five methods to construct the request to the API: 
 +
 +**addDataSet()** - Adds a single data set to the request. ​
 +
 +//​addDataSet Arguments:// ​
 +
 +^ $reference (Optional) ^  String ​ | An identifier that will be returned with the response to identify each data set.  If the reference is empty a random one will be created. |
 +^ $data_set_array (Optional) ^  Array  | An optional array that describes the contents of the data set.  This argument can be used instead of using the other methods on this object. |
 +
 +**addItem()** - Adds a single item to the action execution. ​
 +
 +//addItem Arguments:// ​
 +
 +^ $itemId ​ ^  String ​ | The id of the record to run the action on. |
 +
 +**addMap()** - Adds a query to the request that will search for records instead of defining individual records. ​ For more information on building queries, please see the [[API Query Builder]] page. 
 +
 +//addMap Arguments:// ​
 +
 +^ $definition ​ ^  String ​ | XML for the query definition. ​ Services WorkXpress will pass the string through htmlentities() to make it safe for inclusion in the SOAP call. |
 +
 +**addAction()** - Adds a an Action to be run on the Items. ​
 +
 +//addField Arguments:// ​
 +
 +^ $actionId ​ ^  String ​ | The id of the action to run.|
 +
 +**call()** - Executes the API call 
 +
 +==== Example Using Array ====
 +Below is an example of an Execute Action request using an array as input: ​
 +
 +<code php>  ​
 +<?​php ​
 +// load the Services_WorkXpress object ​
 +$workxpress ​ = new Services_WorkXpress(); ​
 +$workxpress->​setAPIVersion(1); ​
 +$workxpress->​setAuthKey($auth_key); ​
 +$workxpress->​setRemoteHost('​http://​example.workxpress.com'​); ​
 +
 +// load the request object ​
 +$request = $workxpress->​loadRequest('​ExecuteAction'​); ​
 +/* @var $request Services_WorkXpress_Request_ExecuteAction */ 
 +
 +// we'll use a query to find our records ​
 +$query_definition = '<?​xml version="​1.0"​ encoding="​UTF-8"?>​
 +<wxQuery xmlns:​xsi="​http://​www.w3.org/​2001/​XMLSchema-instance"​ xsi:​noNamespaceSchemaLocation="​wxQuery.xsd"​ id="​root">​
 +<​startingTypes><​startingType>​a121</​startingType></​startingTypes><​data for="​root"​ /></​wxQuery>'; ​
 +
 +// build the data set array 
 +$data_set_array = array( ​
 +    '​items'​ => array ( 
 +        array('​itemId'​ => '​u4'​), ​
 +        array('​itemId'​ => '​u7'​), ​
 +        array('​definition'​ => $query_definition), ​
 +    ), 
 +    '​actions'​ => array ( 
 +        array( ​
 +            '​actionId'​ => '​a286', ​
 +        ), 
 +    ), 
 +); // end $data_set_array ​
 +
 +$request->​addDataSet('​A',​ $data_set_array); ​
 +
 +/** make the API call **/ 
 +try 
 +
 +    // make the call and get the data array 
 +    $response = $request->​call(); ​
 +    /* @var $response Services_WorkXpress_Response_LookupData */ 
 +    ​
 +    $items = $response->​getDataArray(Services_WorkXpress::​DATA_ARRAY_FORMAT_NOT_COLLAPSED); ​
 +    ​
 +    // show the results ​
 +    echo '<​pre>'​.print_r($items,​ true).'</​pre>'; ​
 +} // end try 
 +catch (Services_WorkXpress_Exception $e) 
 +
 +    echo '<​h1>​Error</​h1><​pre>'​.$e->​getMessage().'</​pre>'; ​
 +} // end catch Services_WorkXpress_Exception ​
 +</​code>​
 +
 +==== Example Using Methods ====
 +Below is an example of an ExecuteAction request using the methods provided by Services WorkXpress. ​
 +
 +<code php>
 +<?​php ​
 +// load the Services_WorkXpress object ​
 +$workxpress ​ = new Services_WorkXpress(); ​
 +$workxpress->​setAPIVersion(1); ​
 +$workxpress->​setAuthKey($auth_key); ​
 +$workxpress->​setRemoteHost('​http://​example.workxpress.com'​); ​
 +
 +// load the request object ​
 +$request = $workxpress->​loadRequest('​ExecuteAction'​); ​
 +/* @var $request Services_WorkXpress_Request_ExecuteAction */ 
 +
 +// we'll use a query to find our records
 +$query_definition = '<?​xml version="​1.0"​ encoding="​UTF-8"?>​
 +<wxQuery xmlns:​xsi="​http://​www.w3.org/​2001/​XMLSchema-instance"​ xsi:​noNamespaceSchemaLocation="​wxQuery.xsd"​ id="​root">​
 +<​startingTypes><​startingType>​a121</​startingType></​startingTypes><​data for="​root"​ /></​wxQuery>'; ​
 +
 +// add the data set 
 +$request->​addDataSet('​A'​); ​
 +$request->​addItem('​u4'​); ​
 +$request->​addItem('​u7'​);​
 +$request->​addMap($map_definition); ​
 +$request->​addAction('​a286'​); ​
 +
 +/** make the API call **/ 
 +try 
 +
 +    // make the call and get the data array 
 +    $response = $request->​call(); ​
 +    /* @var $response Services_WorkXpress_Response_LookupData */ 
 +    ​
 +    $items = $response->​getDataArray(Services_WorkXpress::​DATA_ARRAY_FORMAT_NOT_COLLAPSED); ​
 +    ​
 +    // show the results ​
 +    echo '<​pre>'​.print_r($items,​ true).'</​pre>'; ​
 +} // end try 
 +catch (Services_WorkXpress_Exception $e) 
 +
 +    echo '<​h1>​Error</​h1><​pre>'​.$e->​getMessage().'</​pre>'; ​
 +} // end catch Services_WorkXpress_Exception
 +</​code>​
 +
 +===== Response Data Arrays =====
 +There are three different formats for the response arrays that may be retrieved after making a request. ​ Each of these formats corresponds to one of three constants: ​
 +
 +==== Services_WorkXpress::​DATA_ARRAY_FORMAT_NOT_COLLAPSED ====
 +<code php><?​php
 +  array( ​
 +    0 => array( ​
 +        '​reference'​ => '​account', ​
 +        '​items'​ => array( ​
 +            0 => array( ​
 +                '​itemId'​ => '​u113', ​
 +                '​fields'​ => array( ​
 +                    0 => array( ​
 +                        '​fieldId'​ => '​e52', ​
 +                        '​reference'​ => '​username', ​
 +                        '​value'​ => '​tuser', ​
 +                    ), 
 +                ), 
 +                '​relations'​ => array( ​
 +                    0 => array( ​
 +                        '​reference'​ => '​relation', ​
 +                        '​id'​ => '​u115', ​
 +                        '​relationType'​ => '​a41', ​
 +                        '​baseItemTypeId'​ => '​e8', ​
 +                        '​baseItemId'​ => '​u113', ​
 +                        '​targetItemTypeId'​ => '​a28', ​
 +                        '​targetItemId'​ => '​u114', ​
 +                        '​fields'​ => array( ​
 +                            0 => array( ​
 +                                '​fieldId => '​a118',​
 +                                '​reference'​ => '​position', ​
 +                                '​value'​ => '​Developer', ​
 +                            ), 
 +                        ), 
 +                    ), 
 +                ),     
 +            ), 
 +        ), 
 +    ), 
 +); 
 +?>
 +</​code>​
 +
 +==== Services_WorkXpress::​DATA_ARRAY_FORMAT_FULLY_COLLAPSED ====
 +<code php>
 +  '​accounts'​ => array( ​
 +    '​u113'​ => array( ​
 +        '​fields'​ => array( ​
 +            '​e52'​ => array( ​
 +                '​username'​ => '​tuser' ​
 +            ), 
 +        ), 
 +        '​relations'​ => array( ​
 +            '​relation'​ => array( ​
 +                '​u115'​ => array( ​
 +                    '​relationType'​ => '​a41', ​
 +                    '​baseItemTypeId'​ => '​e8', ​
 +                    '​baseItemId'​ => '​u113', ​
 +                    '​targetItemTypeId'​ => '​a28', ​
 +                    '​targetItemId'​ => '​u114', ​
 +                    '​fields'​ => array( ​
 +                        0 => array( ​
 +                            '​fieldId => '​a118', ​
 +                            '​reference'​ => '​position', ​
 +                            '​value'​ => '​Developer',​
 +                        ), 
 +                    ), 
 +                ), 
 +            ), 
 +        ), 
 +    ), 
 +  );
 +</​code>​
 +
 +==== Services_WorkXpress::​DATA_ARRAY_FORMAT_PARTIALLY_COLLAPSED ====
 +<code php><?​php
 +'​accounts'​ => array( ​
 +    '​u113'​ => array( ​
 +        '​fields'​ => array( ​
 +            '​e52'​ => array( ​
 +                '​username'​ => array( ​
 +                    '​fieldId'​ =>'​e52', ​
 +                    '​reference'​ => '​username', ​
 +                    '​value'​ => '​jarmes', ​                
 +                ), 
 +            ), 
 +        ), 
 +        '​relations'​ => array( ​
 +            '​u115'​ => array( ​
 +                '​reference'​ => array( ​
 +                    '​reference'​ => '​relation', ​
 +                    '​id'​ => '​u115', ​
 +                    '​relationType'​ => '​a41', ​
 +                    '​baseItemTypeId'​ => '​e8', ​
 +                    '​baseItemId'​ => '​u113', ​
 +                    '​targetItemTypeId'​ => '​a28', ​
 +                    '​targetItemId'​ => '​u114', ​
 +                    '​field'​ => array( ​
 +                        0 => array( ​
 +                            '​fieldId => '​a118', ​
 +                            '​reference'​ => '​position', ​
 +                            '​value'​ => '​Developer',​
 +                        ), 
 +                    ), 
 +                ), 
 +            ), 
 +        ), 
 +    ), 
 +); 
 +</​code>​
dev resources - services workxpress.txt · Last modified: 2016/09/14 14:19 (external edit)
Copyright WorkXpress, 2019