Documentation

Creatio development guide
This documentation is valid for Creatio version 7.14.0. We recommend using the newest version of Creatio documentation.

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
  • Adding an object
  • Updating an object
  • Deleting an object
  • Adding relationships between objects
  • Deleting relationships between objects
  • Receiving metadata — description of all business entities
  • Receiving an objects collection
  • Receiving a specific object
  • Receiving a separate field of a specific object
  • Selecting several fields of a specific object
  • Extending an object with fields from lookup objects
  • Sorting objects
  • Receiving first N objects of the collection
  • Returning objects collections by bypassing first N objects (with N+1 of the object)
  • All arithmetical and logic operations supported by the protocol
  • Grouping filters
Functions of work with strings
  • bool substringof(string po, string p)
  • string toupper(string p0)
  • bool endswith(string p0, string p1)
  • bool startswith(string p0, string p1)
  • int length(string p0)
  • string trim(string p0)
Functions of work with date and time
  • int year (DateTime p0)
  • int month(DateTime p0)
  • int day(DateTime p0)

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 External requests authentication 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

See Also

© bpm'online 2002-2019.

Did you find this information useful?

How can we improve it?