Cloud Elements! Events Management BETA! API Version 2.0

Transcription

1 Cloud Elements Events Management BETA API Version 2.0

2 Event Management Version 1.0 Event Management Cloud Elements Event Management provides a uniform mechanism for subscribing to events from Endpoints (e.g. Dropbox, Box). Our Event Management gives you the flexibility to receive notifications to your app regarding user activity by having our Elements subscribe to Endpoint Events. Endpoints publish changes to notify the elements that events have occurred. For example, a user uploads a file to her Dropbox account using the Dropbox user interface. This change would be published to our Dropbox Element. The Dropbox Element would then notify your app that a new file has been uploaded. Your app can then be updated with the most current data making it that much more cooperative and powerful. Our Event Management currently supports the following Endpoints: Dropbox, Box, and Google Drive.

3 Event Management Version 1.0 We provide two areas of event handling: unsolicited events and solicited asynchronous API requests. Implementing unsolicited events: Set up a new connected application and enable webhooks (NOTE: Dropbox and Box require some extra configurations - directions below) Create an Element Instance for one of the following Endpoints: Dropbox, Box, Google Drive Enable Event Management for that Instance Your app will receive events from that Endpoint via the Element Instance. Currently, Dropbox and Box require some configuration on their end. View the and guides for directions and screenshots on how to integrate web hooks into your app. Create an Instance with Event Management Event Management can be configured for individual instances. You have the flexibility to provide a different callback URL for each instance of an element. Configuring an element instance to enable event management can be done via the Elements Manager or via the POST /instances API. An example of how to create an Instance via the Elements Manager will be shown first. Via a web browser go to: and login to your Cloud Elements account.

4 Event Management Version 1.0 Click Create Instance for Dropbox Click the Plus

5 Event Management Version 1.0 Name your Instance Tagging is optional so You may leave it set to "No" Select "True" to enable Event Notifications Input the callback URL to your application Click Next Login to your Dropbox Account and click "Allow"

6 Event Management Version 1.0 Click Done Create an Instance with Event Management via API HTTP Headers: Authorization- User <user secret>, Organization <organization secret> HTTP Verb: POST Request URL: /instances Request Body: Required see below Query Parameters: None POST /instances

7 Event Management Version 1.0 curl -X POST -H \'Authorization: User <INSERT_USER_SECRET>, Organization <INSERT_ORGANIZATION_SECRET>' -H \'Content-Type: application/json' ' Input JSON: This file must be included with your instance request "element": "key": "dropbox", "providerdata": "code": "Code on the Return URL", "configuration": "oauth.callback.url": "<SAMPLE_CALLLBACK_URL>", "oauth.api.key": "<SAMPLE_API_KEY>", "oauth.api.secret": "<SAMPLE_API_SECRET>", "event.notification.enabled": "true", "event.notification.callback.url": " elements/api-v2/events/dropbox" "document.tagging": false, "name": "<INSERT_INSTANCE_NAME>" Example of Successful Response from initial POST /instances call

8 Event Management Version 1.0 "id": 27, "name": "Event Management", "token": "<ELEMENT_TOKEN>", "element": "id": 14, "name": "Dropbox", "key": "dropbox", "description": "One place for all your stuff, wherever you are. Dropbox is a free service that lets you bring your photos, docs, and videos anywhere and share them easily. Anything you add to Dropbox will automatically show up on all your computers, phones and even the Dropbox website.", "active": true, "deleted": false, "typeoauth": true, "eventmanagement": true, "trialaccount": false, "existingaccountdescription": "Give your application access to your existing Dropbox accountenter your credentials and details for your Dropbox Account", "configdescription": "If you do not have an Dropbox account, you can create one at Dropbox Signup", "signupurl": " "elementprovisiontype": "OAUTH_TEMPLATE", "tags": [ "id": 12, "name": "Peter" ], "provisioninteractions": [], "valid": true, "disabled": false EXAMPLE POST /folder HTTP Headers: Authorization- User <user secret>, Organization <organization secret> HTTP Verb: POST Request URL: /instances Request Body: Required see below Query Parameters: None

9 Event Management Version 1.0 POST /folder curl -X POST -H 'Authorization: User <INSERT_USER_SECRET>, Element <INSERT_ELEMENT_SECRET>' -H 'Content-Type: application/json' ' path=/testfoldercreate' TestFolderCreate JSON needed to create the folder. "path": "/testfoldercreate", "tags": [ "TestFolderCreate" ], "createddate": "", "size": 0, "name": "TestFolderCreate", "directory": false Example of Webhook Callback "eventid": 1088, "instanceid": 31, "response": "events": [ "path": "/testfoldercreate", "metadata": "path": "/TestFolderCreate", "name": "TestFolderCreate", "type": "folder" ], "notificationid": 1047 A NOTE ABOUT WEBHOOKS When a change is made at Dropbox or other Endpoint, whether through the Cloud Elements API, via the Dropbox web app or Dropbox desktop app, a webhook call will be generated. In other words, it s not just calls made through our API that will generate webhooks.

10 Event Management Version 1.0 Asynchronous API Requests Asynchronous API Requests gives you the flexibility to start a job that may take some time to complete and be notified when it has completed. For example, a user makes a request to copy a folder to her account. This request may take some time to process. With an Asynchronous API Request, your app will receive a notification that job has started, as well as, a notification when the job has processed. Performing an Asynchronous API Request: Additional Required Header: Elements-Async-Request this must be set to True Optional Header: Elements-Async-Callback-URL if not included in request, then the app will use the callback URL associated with the instance. If you do not have a callback URL associated with the instance configuration or supply one in the request, then an error will be returned. POST /folders/copy curl -X POST -H 'Authorization: User <INSERT_USER_SECRET>, Element <INSERT_ELEMENT_SECRET>' -H 'Content-Type: application/json' -H 'Elements-Async-Request: True' -H 'Elements-Async-Callback-Url: < ' path=/testfoldercreate' Copy-folder JSON needed to copy the folder

11 Event Management Version 1.0 "path": "/testfoldercopy", "tags": [ "TestFolderCopy" ], "createddate": "", "size": 0, "name": "TestFolderCopy", "modifieddate": "", "directory": false Example Message stating the Asynchronous Call has started "eventid": 1028, "eventstatus": "dispatched" Example of Webhook Callback stating job has completed. "eventid": 1028, "instanceid": 30, "response": "events": [ "path": "/testfoldercopy", "metadata": "path": "/TestFolderCopy", "name": "TestFolderCopy", "type": "folder", "path": "/testfoldercopy/testuploadfile.txt", "metadata": "path": "/TestFolderCopy/testUploadFile.txt", "name": "testuploadfile.txt", "type": "file" ], "notificationid": 1084

12 Event Management Version 1.0 Application Setup for Event Management Integration with Box Follow these steps to set up a Box application with the endpoint. Via a web browser, go to Enter the name of your application, select the appropriate options and click Create Application. For this example, let s assume that the URL for your application is After receiving confirmation that your application is created, click Configure your application.

13 Event Management Version 1.0 Please make a note of the client_id and client_secret assigned by Box for the Demonstrab.ly application. You will be required to enter a callback URL from the endpoint. Enter this URL: console.cloud-elements.com/elements/jsp/home.jsp Scroll down and click Create a New Webhook

14 Event Management Version 1.0 On Create Webhook Screen 1. Fill out app information Directions continued on next page. 2. Select Event Types Events your app will be notified on

15 Event Management Version Input this Endpoint URL: 4. Select Post 5. Input userid 6. Input #from_user_id# 7. Click Save Webhook Click Save Application at the bottom of the screen. Click Save application.

16 Event Management Version 1.0 Box requests you let them know you would like your app to allow webhooks Go to this URL: Scroll to the bottom of the page and click Contact Us to submit a request. You will need your API Key. This can be found at the bottom of the app configuration screen.

17 Event Management Version 1.0 Application Setup for Event Management Integration with Dropbox Follow these steps to set up a Dropbox application with the endpoint. Via a web browser, go to and login to your account. Select the Dropbox API app option, select the appropriate options and enter a name for your application. For this example, let s assume that the URL for your application is Click Create app.

18 Event Management Version Please make a note of the App key and App secret assigned by Dropbox for the Demonstrab.ly 2. For the Redirect URI, please enter this URL: jsp/home.jsp 3. For the Webhooks URI, please enter this URL: api-v2/events/dropbox

19 Event Management Version 1.0 This concludes the documentation for Event Management. If you need any support integrating our APIs, please let us know. You can or give us a call at If you are having a specific issue, please feel free to add it to our help desk support at support.cloud-elements.com. We will do our best to get back to you within 24 hours. Your success is our success. Thanks for reading The Cloud Elements Team