Rollbase SOAP Examples
Rollbase SOAP Examples
Rollbase SOAP Examples
CONTENTS PHP ................................................................................................................2 PHP 5 SOAP EXTENSION CLASSES .................................................................................................................... 2 CREATING A SOAP CLIENT................................................................................................................................ 3 SOAP CALLS ................................................................................................................................................. 4 getObjectDef ......................................................................................................................................... 4 search.................................................................................................................................................... 5 getDataObj............................................................................................................................................ 6 getBinaryData ....................................................................................................................................... 7 getDataField.......................................................................................................................................... 8 getRelationships.................................................................................................................................... 8 getUpdated ........................................................................................................................................... 8 setDataField .......................................................................................................................................... 9 delete .................................................................................................................................................... 9 setBinaryData ....................................................................................................................................... 9 setRelationships .................................................................................................................................. 10 JAVA ............................................................................................................. 12 JAVA CLIENT USING ECLIPSE WTP.................................................................................................................... 12 MICROSOFT EXCEL............................................................................................ 16 CREATING A CUSTOM FUNCTION ..................................................................................................................... 19 USING A CUSTOM FUNCTION .......................................................................................................................... 19
Page 1 of 21
We will now turn to examples of using the Rollbase SOAP API with PHP to Create a SOAP client Login to the Rollbase server using this client Call Rollbase functions to perform various operations
Page 2 of 21
Page 3 of 21
SOAP Calls
getObjectDef
Page 4 of 21
search
To retrieve IDs of all records that are accessible to the current user in a particular object or in all objects, we can use the search method. This method performs a full-text search throughout your Rollbase account: $result = $SOAP_client->__SOAPCall('search', array('sessionId'=> $sessionID, 'query'=> 'PR*', 'objDefName'=>'project')); In this example we search for PR* in a object called project. The $result variable hols all the record IDs returned from this call. These IDs can be used in PHP variables for further processing.
Page 5 of 21
getDataObj
This method is used to retrieve individual records for the given record ID. We can perform this SOAP call as follows for our example project object: $recId = $allIds[0]; //first id from the previous search result. try { $record = $SOAP_client->__SOAPCall('getDataObj', array('sessionId'=> $sessionID, 'id'=> $recId); } catch (SoapFault $ex1){ echo 'EXCEPTION='.$ex1; } Here $recId represents the ID of the record that we want to retrieve. The resulting $record that we get here has the following structure: ID of the record retrieved Object definition name of the current object Array of fields
We can retrieve these items as follows: $recordId = $record->id; $objDefName = $record->objDefName; $fieldArray = $record->fields->item; $fieldArray is an array of data field values contained in this record. The contents of this array can be wrapped in a container so it can be used for further processing. An example DataField container might be: class DataField { var $boolValue; var $dateValue; var $decimalValue; //used for lookup fields and multi-select picklists var $longArr; var var var var $longValue; $name; $stringValue; $type;
Page 6 of 21
To use this container: $datafield = $fieldArray[0]; // First Data Field. $datafieldContainer = new DataField($datafield); The datafieldContainer variable now holds a datafield with information such as the name, value and type of this field. The above DataField container class can be designed with more functionality as needed by the application.
getBinaryData
This method is used to retrieve binary data (i.e. a file attachment) associated with a particular file field from a specific record. try {
$result
Page 7 of 21
The result is a single Data Field values that can be wrapped in a DataFieldContainer that we illustrated above.
getRelationships
This method is used to retrieve all records that are related to a particular record given a particular relationship. For example, assume we want to retrieve all related records associated with a record with ID $recId in a relationship that has the integration name $relName: try { $result = $SOAP_client->__SOAPCall('getRelationships', array('sessionId'=> $sessionID, 'id'=> $recId, 'relName'=>$relName));
getUpdated
This method is used to retrieve an array of record IDs of a specific object type, which have either been created or updated within the given date/time interval. try {
$result
= $SOAP_client->__SOAPCall('getUpdated', array('sessionId'=> $sessionID, 'from'=> $utcDateFrom, 'till'=> $utcDateto, 'objDefName' => $objname));
} catch (SoapFault $ex1){ echo 'EXCEPTION='.$ex1; } The dates that are passed to this method are UTC times in 20080405T144800Z format. The result is an array of IDs that can be retrieved as:
Page 8 of 21
setDataField
This method is used to update a specific data field for a specific record. The parameters used in this method are session ID, record ID, and a datafield container that contains information about the field that needs to be updated: try {
$result
The $dataField variable is a container that wraps all information about the field in the structure shown below: object(stdClass)[3] public 'boolValue' => boolean false public 'dateValue' => null public 'decimalValue' => float 53.2 public 'longArr' => null public 'longValue' => int 0 public 'name' => string 'perc' (length=4) public 'stringValue' => null public 'type' => string 'decimal' (length=7) NOTE: When not set the values of boolValue, decimalValue, longValue will not be null.
delete
This method is used to move a specified record to the Recycle Bin. The parameters required are session ID and record ID: try { $record = $SOAP_client->__SOAPCall('delete', array('sessionId'=> $sessionID, 'id'=> $rid));
setBinaryData
This method is used to upload a file to the file field in a specific record. The parameters required are session ID, record ID, the file field name, a suggested file name that has a valid extension, and the contents of the file wrapped in a ByteArray container: try {
Page 9 of 21
} catch (SoapFault $ex1){ echo 'EXCEPTION='.$ex1; } The $binData variable is a container that holds the contents of the file to be uploaded, which should have the following format: object(stdClass)[3] public 'arr' => string 'this is the content of the file' (length=4) For example, to do this with a text file: $fhandle = fopen("filename.txt", "r"); while (!feof($fhandle)) { $str .= fgets($fhandle); } fclose($fhandle); The $str variable can be wrapped in a container called ByteArr as $binData = new ByteArr($str); where ByteArr is a custom PHP container that has a structure such as: class ByteArr { var $arr; public function __construct($str){ $this->arr = $str; } public function getData() { return $this->arr; } public function setData($str) { $this->arr = $str; } } Other types of files like .doc, .pdf, .gif, etc need to processed to fit this format before the data can be submitted.
setRelationships
This method is used to attach related records to a specific record. The parameters required are session ID, record ID, relationship integration name, and array of related record IDs: try {
Page 10 of 21
class LongArr { var $arr; public function __construct($item) { $this->arr = $item1; } public function setArr ($item) { $this->arr = $item1; } public function getArr() { return $this->arr; } } Thus, we can do something like: $item = new Item($ids); $arr = new LongArr($item); This sample is for demonstration purposes, you may consider more appropriate ways of designing these classes for your particular usage.
Page 11 of 21
Page 12 of 21
Page 13 of 21
If you want to choose a server different from the default, click the Server link to select a server, then click Finish. It will take approximately one minute for the wizard to assemble the Web service client project, start Apache Tomcat, and deploy the project to Tomcat. Once finished, the generated Sample JSP Web application will appear in your browser.
Page 14 of 21
These class stubs can now be used to test most of the Rollbase SOAP API methods in the generated Sample JSP page shown below.
Page 15 of 21
http://www.microsoft.com/downloads/Search.aspx?displaylang=en
Download and install the most appropriate version for your environment. Once you install the toolkit, you are ready to web-enable your worksheets: To enable Web services for a spreadsheet, open it in Excel and choose the Developer Tab. Click Visual Basic Editor from the menu.
In the Visual Basic editor, choose Tools -> Web Services References.
Page 16 of 21
Click on the Web Service URL option at the bottom of the window, and then enter the Rollbase WSDL URL as shown and click the Search button. It is usually easy to use this technique to go straight to the web service you want to use. Although the window also has options for hunting for web services, most web services aren't registered in public catalogs and therefore will not show up in a keyword search:
Page 17 of 21
Viewing the generated code you will find definitions for each Rollbase API method which can now be used by Excel.
Next we need to add custom functions that use this generated class. These functions can then be invoked just like any other function within a cell formula expression.
Page 18 of 21
Click on cell C1 and invoke the insert function dialog box, by clicking the fx symbol in the formula bar. This opens the functions dialog box is as shown below:
Page 19 of 21
In Or Select a Category select User Defined and you will see our custom function in the functions list. Select rb_login and click OK. In the next dialog box that appears, enter the cells that will contain the parameter values, in our case B1 and B2, and click OK.
Now entering a valid Rollbase username and password in cells B1 and B2 will return a SOAP API session ID in cell C1.
Page 20 of 21
You can continue with this process to define your own custom functions corresponding to each SOAP API function and call them as appropriate from cells in any of your spreadsheets. The above example can be used as a starting point since you will need a valid session ID (cell C1 here) to use as a parameter in all other API functions.
Page 21 of 21