Rollbase SOAP API Examples

Transcription

1 Rollbase SOAP API Examples Updated At: October 15, 2008 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 JAVA JAVA CLIENT USING ECLIPSE WTP MICROSOFT EXCEL CREATING A CUSTOM FUNCTION USING A CUSTOM FUNCTION Page 1 of 21

2 PHP The following is an example of using the Rollbase SOAP API in PHP. To work with SOAP in PHP, we can use a number of SOAP toolkits. In our examples we will be using the PHP 5 SOAP Extension. More information can be found at: Another popular toolkit is NuSOAP: PHP 5 SOAP Extension Classes There are six classes implemented by the PHP 5 SOAP Extension. Three are high level classes with useful methods. These are SoapClient, SoapServer, and SoapFault. The other three classes are low level and do not have any methods other than constructors. These are SoapHeader, SoapParam, and SoapVar. 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

3 Creating a SOAP client There are two ways to create a SOAP client using the PHP 5 SOAP Extension toolkit: Using a WSDL URL Using a direct URL Creating a client from a WSDL can be done as follows: <?php $wsdl_url = " $SOAP_client = new SoapClient($wsdl_url, array('trace'=> true));?> The client object now contains the following structure: object(soapclient)[1] public 'trace' => int 1 public '_SOAP_version' => int 1 public 'sdl' => resource(6, Unknown) One can view the API defined by the WSDL that is now available to the PHP SOAP Extension client by dumping the following methods belonging to the $client object. var_dump($client-> getfunctions()); You will see: array 0 => string 'void delete(string $in0, long $in1)' (length=35) 1 => string 'LongArr search(string $in0, string $in1, string $in2)' (length=53) 2 => string 'long create(string $in0, string $in1, DataFieldArr $in2)' (length=56) 3 => string 'void update(string $in0, long $in1, DataFieldArr $in2)' (length=54) 4 => string 'string login(string $in0, string $in1)' (length=38) 5 => string 'void logout(string $in0)' (length=24) 6 => string 'string getobjectdef(string $in0, string $in1)' (length=45) 7 => string 'DataObj getdataobj(string $in0, long $in1)' (length=42) 8 => string 'DataField getdatafield(string $in0, long $in1, string $in2)' (length=59) 9 => string 'ByteArr getbinarydata(string $in0, long $in1, string $in2)' (length=58) 10 => string 'LongArr getrelationships(string $in0, long $in1, string $in2)' (length=61) 11 => string 'void setdatafield(string $in0, long $in1, DataField $in2)' (length=57) 12 => string 'void setbinarydata(string $in0, long $in1, string $in2, string $in3, string $in4, ByteArr $in5)' (length=95) 13 => string 'void setrelationships(string $in0, long $in1, string $in2, LongArr $in3)' (length=72) Page 3 of 21

4 The API methods that Rollbase provides for integration are now available to the PHP $client object. This definition gives us a good starting point for building any integration code. For example we can see the login function, string login(string $in0, string $in1) takes two strings as parameters and also returns a string. (Our Rollbase SOAP API documentation gives a detailed listing of these functions; see A client can also be created without using the Rollbase WSDL as follows: <?php $SOAP_client = new SoapClient(null, array('location' => ' => 'urn:rollbase','trace' => 1));?> Once we have the client object we can now make a series of SOAP calls to integrate Rollbase with existing PHP systems. Let us now connect to the Rollbase server and retrieve some information. The first SOAP call should always be login to establish an API session. This method will return a session ID. We must use this session ID to make further SOAP calls. For example, to login to a Rollbase account with username TestUser and password mypass, the PHP 5 SOAP call would look like: $uname = TestUser ; $pword = mypass ; $rb_sessionid = $SOAP_client-> SOAPCall('login', array('loginname' => $uname, 'password' => $pword)); The session ID is obtained as $rb_sessionid and we can store this in the user s current PHP session to use in future API calls. One important thing to note in non-wsdl mode is that the parameters passed in the SOAP calls may throw a Bad Types error if they do not confirm to the type that Rollbase expects. In WSDL mode, the types are automatically assigned to these parameters based on the WSDL definition. To solve this issue we need to use the SoapVar class and the SoapParam class to match types. For example: $sv_rid = new SoapVar($rid, XSD_LONG); $record = $soap_client-> soapcall('getdataobj', array( 'sessionid' => $sessionid, new SoapParam($sv_rid, 'id'))); Now that we have established an API session with Rollbase, we can send and retrieve data. Let us now look at some further SOAP calls in detail. SOAP Calls getobjectdef Page 4 of 21

5 This method retrieves the full object definition given the integration name of the target object. The result is an XML file, which can be parsed as necessary to find information required to access various object resources. (The schema definition describing the object definition XML format is available at: $Oresult = $SOAP_client-> SOAPCall('getObjectDef', array('sessionid'=> $sessionid, 'objdefname'=>'person')); Here person is the integration name for an object called Person. The following is an example of an object definition in XML format of an object definition: <DataObjectDef objdefname="person" > <SingularName>Person</SingularName> <PluralName>Persons</PluralName> <Description>Person</Description> <DataFieldDefs> <DataFieldDef fieldname="mobilephone" groupname="contact" dataname="fieldstring" isrequired="yes" isreadonly="no" maxlength="50" > <DisplayLabel>Mobile Phone</DisplayLabel> <Description>Mobile Phone</Description> </DataFieldDef> </DataFieldDefs> <RelationshipDefs> <RelationshipDef relname="person_comm" objdef1="person" objdef2="commlog" /> </RelationshipDefs> </DataObjectDef> This XML file can be parsed and information about the object such as the singular and plural name, field integration names, display names, etc can be easily retrieved. For example a field definition in this XML file is represented as: <DataFieldDef fieldname="mobilephone" groupname="contact" dataname="fieldstring" isrequired="yes" isreadonly="no" maxlength="50" > <DisplayLabel>Mobile Phone</DisplayLabel> <Description>Mobile Phone</Description> </DataFieldDef> where the fieldname attribute represents the integration name of this field, and the <DisplayLabel> and <Description> elements contain display information about this field. 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

6 $allids = $result->arr->item; Here $allids is the array of record IDs returned from the search method. The object name parameter is optional. We can retrieve all record IDs from all objects in an account that match the given search pattern by providing an empty string for objdefname: $result = $SOAP_client-> SOAPCall('search', array('sessionid'=> $sessionid, 'query'=> 'PR*', 'objdefname'=>'')); 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 $longvalue; var $name; var $stringvalue; var $type; Page 6 of 21

7 function DataField ($field) { $this ->boolvalue = $field ->boolvalue; $this ->datevalue = $field ->datevalue; $this ->decimalvalue = $field ->decimalvalue; $this ->longarr = $field ->longarr; $this ->longvalue = $field ->longvalue; $this ->name = $field ->name; $this ->stringvalue = $field->stringvalue; $this ->type = $field ->type; public function getname() { return $this->name; public function setname($objname){ $this->name = $objname; Public function gettype() { return $this->type; //more functions as needed 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 = $SOAP_client-> SOAPCall('getBinaryData', array('sessionid'=> $sessionid, 'id'=> $recid, 'fieldname'=>$fieldname)); catch (SoapFault $ex1){ echo 'EXCEPTION='.$ex1; The result is binary data that is returned as a Bytes array. Page 7 of 21

8 getdatafield This method is used to retrieve the value of a single field from a specific record. try { $result = $SOAP_client-> SOAPCall('getDataField', array('sessionid'=> $sessionid, 'id'=> $recid, 'fieldname'=>$fieldname)); catch (SoapFault $ex1){ echo 'EXCEPTION='.$ex1; 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)); catch (SoapFault $ex1){ echo 'EXCEPTION='.$ex1; The result is an array of IDs that can be retrieved as $relatedids = $result->arr->item; 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 T144800Z format. The result is an array of IDs that can be retrieved as: Page 8 of 21

9 $relatedids = $result->arr->item; 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 = $SOAP_client-> SOAPCall('setDataField', array( 'sessionid'=> $sessionid, 'id'=> $recid, 'df' => $datafield)); catch (SoapFault $ex1){ echo 'EXCEPTION='.$ex1; 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)); catch (SoapFault $ex1){ echo 'EXCEPTION='.$ex1; 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

10 $result = $SOAP_client-> SOAPCall('setBinaryData', array( 'sessionid'=> $sessionid, 'id'=> $recid, 'fieldname' => $fieldname, 'contenttype' => $contenttype, 'suggestedfilename' =>$suggname, 'bindata' =>$bindata)); 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

11 $result = $SOAP_client-> SOAPCall('setRelationships', array( 'sessionid'=> $sessionid, 'id'=> $recid, 'relname'=>$relname, 'arr' => $arr)); catch (SoapFault $ex1){ echo 'EXCEPTION='.$ex1; Here the $arr variable contains an array of related IDs. The structure of this array is: object(stdclass)[2] public 'arr' => object(stdclass)[3] public 'item' => int int int Sample classes in PHP that can contain information such as this are: class Item { var $item; public function construct($itemarr) { $this->item = $itemarr; public function getitem() { $this->item; public function setitem($itemarr) { $this->item = $itemarr; 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

12 JAVA Java Client using Eclipse WTP This example shows how to connect to the Rollbase servers using a Java toolkit. The toolkit used here is Eclipse WTP (Web Tools Platform) which can create Java stubs by reading and parsing WSDL files. These stubs can then be used to integrate any of your Java applications with Rollbase. In this example we will create a simple dynamic application that will test the Rollbase SOAP API. Steps to establish and test the Rollbase SOAP API in Java: Create a new web application (or use an existing application) Create a web service client as part of this web project Test the API code generated. In Eclipse: Open File New Other... Web Dynamic Web Project Page 12 of 21

13 Configure the web project: Right click on the project name and choose New Other Web Services Web Services Client Page 13 of 21

14 Click Next and move the client slider to the Test Client position: 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

15 All Java classes necessary to develop the client application are automatically created by Eclipse: 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

16 MICROSOFT EXCEL As with other Microsoft Office applications, Excel now provides the ability to use SOAP-based web services. Therefore it is possible to use the Rollbase SOAP API through an Excel spreadsheet and integrate it with your Rollbase account. Calling a web service in Excel is similar to calling a built-in Excel function, in that you supply information (as arguments) and retrieve a result. The first step is to download the Office Web Services Toolkit, a free add-in that provides the ability to call remote web services from inside an Office document. To download this toolkit, go to the Microsoft Download Center and search for Office Web Services Toolkit: 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

17 The dialog box shows options to connect to your web service: 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

18 Once the search is complete, the tool shows the list of service methods that was retrieved from the server. Select this Web Service and click on Add to complete the process. Once you complete these steps, Excel automatically generates code for calling the web service. Excel places all each generated method inside a class called clws_iwebservicesservice: 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

19 Creating a Custom Function Creating a custom function in Excel is a straightforward exercise. The first step is to create a new module by choosing Insert -> Module in the Visual Basic Editor window. Next you need to add a function inside the module that calls the appropriate API method. For example, to call the login method we might create the following function: Function rb_login(uname As String, pass As String) Dim clientobj As New clsws_iwebservicesservice Dim session_id As String rb_login = clientobj.wsm_login(uname, pass) End Function The first line defines the name of the function. The two parameters define arguments that the code calling the function needs to supply. In this case, username and password are required. The second line creates the web service object. Note that clsws IWebServicesService is used as the name because this is the name of the file Excel generated when we added the web service. At this point, all the initialization you need has performed automatically. The third line calls the actual web service (with the supplied parameters) and returns the result to the caller of the rb_login() function. Using a Custom Function Now that we have defined a login function, we can use it in a spreadsheet. Close the Editor, go back to the blank spreadsheet, and create the following cells: 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

20 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

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