Possibilities for the bpm'online integration over the OData protocol
Glossary Item Box
General
Open Data (OData) protocol is an open web-protocol for requesting and updating data based on the REST architectural trekking using the Atom/XML and JSON standards .
The access to the bpm'online data and objects over the OData protocol may be received by any third-party application, which supports exchange with HTTP messages and may process XML or JSON data. In this case, data are available in the form of resources addressed over URI .
The access to data and its modification is implemented with the help of standard HTTP – GET, PUT/MERGE, POST and DELETE commands .
ATTENTION Using PUT and DELETE HTTP methods will cause “405 Method not allowed” error until WebDAV HTTP extension is switched off in application Web.Config. |
Working over the OData has several features conditioned by the specifics of the REST approach :
- The application server does not store session status. All data required for a request processing is contained in the request itself .
- OData objects have the idempotence property. This means that a repeated action over an object does not modify the latter.
- When the GET request receives the object value, no modification of this or any other object must occur.
Today, a large number of client libraries for work with OData have been developed for popular application and mobile platforms, including:
- .NET
- Silverlight
- JavaScript/HTML5
- Java
- PHP
- Ruby
- WP7
- Android
- iOS
All client libraries for working with OData may be downlowded using the following link http://www.odata.org/libraries.
Implementation of the OData protocol in bpm'online
The bpm'online application supports the following operations with objects and their collections over the OData protocol:
Group of operations | Operations |
---|---|
Operations with objects |
|
Functions of work with strings |
|
Functions of work with date and time |
|
NOTE Please note that bpm'online implements the forced paging when returning resultant objects collections. A request returns first 40 objects by default. To modify the default paging implementation, standard structures of OData requests may be used: $top, $skip, $orderby . |
Below are the examples of building requests for access to bpm'online objects over the OData protocol .
Work with bpm'online objects over the OData protocol
OData service for access to bpm'online objects
The access to bpm'online entities over the OData protocol is provided by the EntityDataService.svc web-service.
The address of the EntityDataService.svc service is as follows:
http[s]://<name_address_of_bpm'online>/0/ServiceModel/EntityDataService.svc
Example
https://myserver.com/BpmonlineWebApp/0/ServiceModel/EntityDataService.svc
The data model of the EntityDataService.svc service is described in its metadata which can be received using the standard OData syntaxes structure — $metadata.
Example
https://myserver.com/BpmonlineWebApp/0/ServiceModel/EntityDataService.svc/$metadata
Request authetication
All requests to bpm'online must be authenticated .
The authentication methods supported by bpm'online are described in the article Authenticating external requests to bpm'online services.
ForceUseSession
A new session is created for each OData request. A large number of requests may cause a database block.
Use the ForceUseSession parameter (for GET-requests) or ForceUseSession header (for all request types) to use an existing session when sending an OData request.
An example of the parameter in a request string:
https://mybpmonline.com/0/ServiceModel/EntityDataService.svc/ActivityFileCollection(guid'71fff37b-3e84-4042-a7bb-ec1b49876e1b')/Data?ForceUseSession=true
An example of the GET-query with ForceUseSession header:
GET http://mybpmonline.com/0/ServiceModel/EntityDataService.svc/ContactCollection?$expand=Account,Photo&$select=Name,Account/Id,Account/Name,Photo/Id,Photo/Name,Id&$orderby=Name%20asc&$skip=0&$top=25 Host: tscore-dev-19:8200 Connection: keep-alive MaxDataServiceVersion: 3.0 Authorization: Cookie X-Terrasoft-Mobile: true Accept: application/json;odata=verbose ForceUseSession: true User-Agent: Mozilla/5.0 (Windows NT 6.3; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/49.0.2623.112 Safari/537.36 UseUTC: true Accept-Encoding: gzip, deflate, sdch Accept-Language: ru-RU,ru;q=0.8,en-US;q=0.6,en;q=0.4 Cookie: BPMSESSIONID=uzyl0rpulps1u31ausa45djj; BPMLOADER=w2olybp2pnf3wcksluslc5ik; .ASPXAUTH=6CD87FE8950261E5A84774F24F256B2975A89A77ADBA1F52AF55AA3511FAAE7C5FF81A52AB33CC8A71EB8CF973DB059BF8357D68A337C81B4E6D1F1CA941BF6BEAA3E09A13C1EEB38D42BBA70DA9F965A4C87569EE53C4D2BB06B4EAC004E7CA3C497D32664C69BB9F4443B58A97E9335BCD09F6B655DD20DB75EAE1A7472B8840F8C56247D23966DD029B7570663A4827949D88A81BBCC958590C640F529179AB8FA1DE2CF8829C247372F7472AC5A1193F23461BDD52B8AF81125414FAA25C040C6922839D140EB57CE5B1B446A705326F0FFBE85CA65DA1DABA5A2A7EFADAF17E70111398C1DEAD142778C5106CAA4A42D88C74ACA0FC86AC95BB90723AEE3E483ACEEB3CB6EB45E38121C9F9EF4A8ECE354445355E970E825894773A9353F540E221A94261AC423592CAD7537C2D235D98BA; UserName=208, 144, 208, 180, 208, 188
Examples of implementing the access to bpm'online objects over the OData protocol
- Working with bpm'online objects over the OData protocol using Http request
- Working with bpm'online objects over the OData protocol WCF-client