Overview

This document provides the instructions on real-time and event-driven capabilities of the DataCloud.

Real-Time Services

Use this section to execute configurations in DataCloud in real-time. As a guide, REST is more lightweight and SOAP has more settings.
Both our REST and SOAP APIs allow you to run an execution in real-time. The methods for both are listed below.

Asynchronous runExecution() SOAP call

Complete the following steps to use an asynchronous runExecution() SOAP call:

  1.  Use the login method to obtain a valid session ID.
  2.  Submit desired method parameters to runExecution():
    1. provisioningid – The ID for the configuration you wish to execute.
    2. msgbody (optional) - May be used to send data to your process.
    3. parameters (optional) – Adds to or overrides existing provisioning parameters for this execution only.
    4. sessionId – A valid DataCloud session id. Can be obtained via the login method.

Sample SOAP Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:crud="http://datasolutions.pervasive.com/api/crud">
 <soapenv:Header/>
 <soapenv:Body>
  <crud:runExecution>
   <provisioningid>12345</provisioningid>
   <!--Optional:-->
   <msgBody>TEST_DATA</msgBody>
   <!--Optional:-->
   <parameters>
    <parameter key="New_Execution_Parameter">parameter_value</parameter>
    <parameter key="Override_Parameter">121212</parameter>
   </parameters>
   <sessionId>12345678-abcd-1234-abcd-1234567890ab</sessionId>
  </crud:runExecution>
 </soapenv:Body>
</soapenv:Envelope>

Asynchronous runExecution() REST call

Complete the following steps to use an asynchronous runExecution() REST call:

  1. Use the login method to obtain a valid session ID.
  2. POST the provisioning ID and session ID to the runExecution resource:
    1. provisioningid – The ID for the configuration you wish to execute
    2. s - A valid DataCloud session ID. Can be obtained via the login method.

Endpoint URL

https://datacloud2.pervasive.com/EntityAPIService/REST/run?provisioningid={provisioningid}&s={sessionid}

Sample POST

POST https://datacloud2.pervasive.com/EntityAPIService/REST/run?s=12345678-abcd-1234-abcd-1234567890ab&provisioningid=12345

Event-Driven Services

Salesforce.com Event Notification Service

The Salesforce.com event notification service asynchronously processes outbound messages sent from your Salesforce.com organization. These outbound messages will execute a desired provisioning and can pass Salesforce data to your integration.

To use the event driven Salesforce.com event notification service, complete the following steps:

  1. Login to Salesforce.com as an administrator.
  2. Create a Custom Setting.
    1. Click Setup -> App Setup -> Develop -> Custom Settings -> New
      1.  Label = DataCloud User Credential
      2.  Object Name = DataCloud_User_Credential
      3. Setting Type = Hierarchy
      4. Visibility = Public

     Creating a custom setting in Salesforce.com
    Figure 1. Creating a custom setting in Salesforce.com


    Creating the DataCloud User Credential custom setting in Salesforce.com
    Figure 2. Creating the DataCloud User Credential custom setting in Salesforce.com

    1.  Custom Fields -> New
      1. Data Type = Text
      2. Click Next.
      3. Field Label = Password
      4. Length = 120
      5. Field Name = Password
      6. Click Next.
      7. Save
    2. Custom Fields -> New
      1. Data Type = Text
      2. Click Next
      3. Field Label = Username
      4. Length = 120
      5. Field Name = Username
      6. Click Next
      7. Save
    Adding a new custom field  
    Figure 3 Adding a new custom field
  1. Create a new DataCloud User Credential.
    1. Click Setup -> App Setup -> Develop -> Custom Settings.
    2. Click Manage next to the DataCloud User Credential setting.
    3. Click New.
    4. Add the DataCloud username and password the outbound message will use to login to DataCloud and click Save.
  2. Create a workflow by selecting Setup -> App Setup -> Create -> Workflow & Approvals -> Workflow Rules -> New Rule.
    1. Creating a workflow rule in Salesforce.com
      Figure 4 Creating a workflow rule in Salesforce.com

    2. Set up your workflow rule as you see fit.
    3. When you get to Step 3: Specify Workflow Actions, select Add Workflow Action -> New Outbound Message.
    4. Configure your outbound message making sure to set your Endpoint URL to the correct provisioning notification point (the provisioningid will be the configuration that you would like to execute upon DataCloud’s receipt of the message). You must check the Send Session ID box.
    5. Sample Endpoint URL:
      https://notifications.pervasive.com/notification/sfdc/provisioning/${provisioningid}

       Configuring outbound message
      Figure 5. Configuring outbound message

    6. Save your workflow.
    7. Activate your workflow
      1. Setup -> App Setup -> Create -> Workflow & Approvals -> Workflow Rules
      2. Click Activate in the Action column next to your new workflow rule.

       

      Activating a workflow rule
      Figure 6. Activating a workflow rule

Now, anytime your workflow rule is triggered, an outbound message will be sent to DataCloud and your configuration will execute.

Note: You can monitor the messages in Salesforce by going to Setup -> Administration Setup -> Monitoring -> Outbound Messages.

Generic Event Notification Service

The generic event notification service asynchronously processes HTTP messages from varying sources sent over SSL, converting the HTTP request body to an input message property within your integration.

To use the generic event notification service, complete the following steps:

  1. Configure your notification emitter to POST securely over SSL to the following endpoint URL (where {provisioningid} is the ID of the configuration that you would like to execute):

    https://notifications.pervasive.com/notification/provisioning/{provisioningid}

  2. Include the following custom HTTP request headers in your request:
    1.  dcuid – The DataCloud username you would like to use to login to DataCloud. 
    2. dcpwd – The password associated with the username

      Note: The DataCloud will only accept notifications over SSL, so the transport will be secure, but you should take measures to ensure your method of creating the messages is also secure.

Sample Request

    POST https://notifications.pervasive.com/notification/provisioning/12345 HTTP/1.1
    Accept-Encoding: gzip,deflate
    Accept: null
    Content-Type: text/xml
    dcpwd: password
    dcuid: username
    User-Agent: Jakarta Commons-HttpClient/3.1
    Host: notifications.pervasive.com
    Content-Length: 69

Sample Response

A successful response will contain two interesting HTTP response headers:
  • dcurl: The version of the API that is currently being used.
  • dcuuid: The unique identifier for the execution that was submitted.

    HTTP/1.1 200 OK
    Content-Type: text/plain;charset=UTF-8
    Date: Tue, 04 Dec 2012 19:35:53 GMT
    dcurl:
    https://datacloud2.pervasive.com/EntityAPIService/EntityAPIWebService
    dcuuid: 12345678-1234-abcd-efgh-1234abcd5678
    Server: Apache-Coyote/1.1
    Content-Length: 1
    Connection: keep-alive