RESTful Cloud - Sample Application

Introduction

We are going to build a sample application using the Pervasive DataCloud API and the saleforce.com VisualForce and APEX API.

After we are done we will have:

Requirements

We are going to be using the following 3 libraries: jquery, connection and apex.

The following are the imports required:

  • <script src=https://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js type="text/javascript"></script>
  • <script src="/soap/ajax/16.0/connection.js" type="text/javascript"> </script>
  • <script src="/soap/ajax/16.0/apex.js" type="text/javascript"> </script>

Logging In

In order to utilize the DataCloud API we need to obtain a session id. This id will be used for all future calls that we make.

First, obtain the username and password from a form on the page. In this case use the jquery selector to grab the two fields with the class .dsuser and .dspass.

  • var dsuser = $('.dsuser').val();
  • var dspass = $('.dspass').val();

Then construct the data body to be sent to the rest call.

  • var dataObj = 'username=' + dsuser + '&password=' + dspass;

We will then call the function that will make the rest call. We need to specify a response handler. In this case its hdlLogin

The call to the function:

  • restCall('login', 'POST', dataObj, hdlLogin, hdlLogin);

The function definition:

var restCall = function(methodCall, type, requestData, response, responseHandlerFailure) {


    var reqObj = {

        url: 'https://datacloud2.pervasive.com/cloudrest/' + methodCall,
        method: type,

        requestData: requestData,

        requestHeaders: {

            Accept: 'application/xml',

        },

        onSuccess: responseHandler,

        onFailure: responseHandlerFailure

    }

    sforce.connection.remoteFunction(reqObj);

}

 

The response handler "hdlLogin()" is defined as:

var hdlLogin = function(data) {

                var jsondata = eval("(" + data + ")");

    if (jsondata.success == 'false') {

                                //handle failed login

    } else {

                                //store off the sessionid for future calls

                                sessionId = jsondata.sessionId;

                                //handle successful login

    }

}

Listing Provisionings

Now that we have successfully obtained a session id by logging in, let's do something useful. In this case we'll modify one of our Provisionings. Keep in mind we can have many provisionings.

First, list all of the provisionings out so that we can select the one that we want to modify. In order to do this utilize the listProvisionings call.

Utilize the same function as before except you will notice that the first parameter in the restCall now contains a query parameter called "s" which is being assigned to our stored sessionid. This is how to authenticate all future calls with our credentials.

  • restCall('provisioning?s=' + sessionId', 'GET', ' ', hdlListProvisioningSuccess, hdlListProvisioningFailure);

With the handler looking like:


var hdlListProvisioningSuccess = function(data) {

                alert(data);

}

var hdlListProvisioningFailure = function(data) {

                alert('There was an error obtaining the provisioning list');

}

 

The data which is returned will look like this:


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<Provisioning>

                <item id="12086">

                                 <expirationDate>2010-06-25T00:00:00-04:00</expirationDate>

                                 <parameters>

                                                <parameter key="SalesforceOpportunitiesBasics.0.file.urimeta"/>

                                                <parameterkey="SalesforceContactBasics.1.password.password">
                                                  PASSWORD</parameter>

                                   </parameters>

                                   <process/>

                                   <product>PRODUCTID</product>

                                   <productOwnedId>OWNERID</productOwnedId>

                </item>

                <item id="12272">

                                 <expirationDate>2030-12-30T19:00:00-05:00</expirationDate>

                                 <parameters>

                                             <parameter key="Salesforce.com.password">PASSWORD</parameter>

                                             <parameter key="Salesforce.com.username">USERNAME</parameter>

                                  </parameters>

                                  <process>piccp.1.0.djar</process>

                                  <product>PRODUCTID</product>

                                  <startDate>2009-10-12T00:00:00-04:00</startDate>

                </item>

                <item id="12301">

                                <expirationDate>2030-12-30T19:00:00-05:00</expirationDate>

                                <parameters>

                                        <parameter key="Salesforce.com.password">bb</parameter>

                                        <parameter key="Salesforce.com.username">aa</parameter>

                                </parameters>

                                <process>test.1.0.djar</process>

                                <product>PRODUCTID</product>

                                <startDate>2009-10-12T00:00:00-04:00</startDate>
            </item>

</Provisioning>

Editing a Provisioning

We are now going to modify an existing provisioning. In this case select provisioning "12272" (we obtained the id from the item parameter from the response above). In this case we want to add some missing functionality to this particular provisioning by adding some parameters and rescheduling the runs.

First, fetch the provisioning itself. In order to do this use:

  • restCall('provisioning/12272?s=' + sessionId', 'GET', ' ', hdlfindProvisioningSuccess, hdlfindProvisioningFailure);

With the handler looking like:


var hdlfindProvisioningSuccess = function(data) {

                alert(data);

}


var hdlfindProvisioningFailure = function(data) {

                alert('There was an error obtaining the provisioning');

}

 

In this case the response looks like:


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<Provisioning id="12272">

                <expirationDate>2030-12-30T19:00:00-05:00</expirationDate>

                <parameters>

                            <parameter key="Salesforce.com.password">PASSWORD</parameter>

                            <parameter key="Salesforce.com.username">USERNAME</parameter>

                </parameters>

                <process>piccp.1.0.djar</process>

                <product>PRODUCTID</product>

                <schedule>0</schedule>

                <startDate>2009-10-12T00:00:00-04:00</startDate>

</Provisioning>

 

So we will modify the xml since this is what we will use to post back to the system to make our changes. In this case we will add a third parameter called "DEBUG Mode" and set the value to "TRUE". We are also going to change the schedule option to a "360" which run the provisioning every 360 min. This number represents the time between runs.


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<Provisioning id="12272">

                <expirationDate>2030-12-30T19:00:00-05:00</expirationDate>

                <parameters>

                            <parameter key="Salesforce.com.password">PASSWORD</parameter>

                            <parameter key="Salesforce.com.username">USERNAME</parameter>

                            <parameter key="DEBUG Mode">TRUE</parameter>

                </parameters>

                <process>piccp.1.0.djar</process>

                <product>PRODUCTID</product>

                <schedule>360</schedule>

                <startDate>2009-10-12T00:00:00-04:00</startDate>

</Provisioning>

We will store our xml inside a variable called "XMLOBJ"

var XMLOBJ = <XML DATA WE EDITED ABOVE>

We will now POST the data that we have modified:

restCall('provisioning?s=' + sessionId', 'POST', XMLOBJ, hdlmodifyProvisioningSuccess, hdlmodifyProvisioningFailure);

var hdlmodifyProvisioningSuccess = function(data) {

                alert('Success');

}

var hdlmodifyProvisioningFailure = function(data) {

                alert('Failed to modify provisioning');

}

Running a Provisioning

We will now run our provisioning, which is the same as running our job. In this case, a scheduled run will execute ever 360 min, but we may want to run manually. We are going to execute a run with no runtime parameters for provisioning "12272".

First, create the POST body containing the provisioning id.


var dataObj = 'provid=12272';

restCall('run?s=' + sessionId', 'POST', dataObj, hdlRunSuccess, hdlRunFailure);

With the handler looking like:

var hdlRunSuccess = function(data) {

                alert('Successfully queued');

}

var hdlRunFailure = function(data) {

                alert('Failed to queue provisioning');

}

 

As long as the provisioning was queued successfully the DataCloud should execute the job at its next available time. Wait for the run to execute.