Introduction

Integration with bpm’online using the OData protocol requires executing HTTP requests to the EntityDataService.svc. Requests can be compiled in any programming language: C#, PHP, etc. However, it is recommended to use HTTP request debugging tools, such as PostMan or Fiddler for better understanding of general principles for request formatting. This article covers examples of requests composed with the help of Fiddler.

More information about OData protocol can be found in the “Possibilities for the bpm'online integration over the OData protocol” article.

Preliminary settings

ATTENTION If the user who is making requests to EntityDataService.svc is not a member of the system administrator user group, add this user to the [Access to OData] group in the [Operation permissions] section (Fig. 1 and 2). Also, enable access to object for external services for this user to work with bpm’online objects via OData (Fig. 3).

Fig. 1. The [Access to OData] group in the [Operation permissions] section

Fig. 2. User in the [Access to OData] group

Fig. 3. Enabling access to object for external services for the [Activity] object

Authentification

Before making requests to EntityDataService.svc, a third party application must be authenticated and receive the corresponding cookies. Bpm’online’s authentication uses a separate web service: AuthService.svc. For more information about this service, please see the “The AuthService.svc authentication service” article.

To execute a request to AuthService.svc using Fiddler, go to the [Composer] tab and execute the following (Fig. 4):

1. Select HTTP method POST.

2. Specify the authentication service URL generated according to the following mask:

http(s)://[bpm'online application address]/ServiceModel/AuthService.svc/Login

Example:

https://012496-sales-enterprise.bpmonline.com/ServiceModel/AuthService.svc/Login

3. Specify HTTP protocol version 1.1.

4. Specify the type of the request body:

Content-Type: application/json

5. Add the request body – a JSON object with the authentication data (login and password):

{"UserName": "User01", "UserPassword":"User01"}

Fig. 4. Generating authentication request

Execute the request by clicking the [Execute] button. As a result, the Fiddler session window will display a response from the AuthService.svc service (Fig. 5). Double-click the reply string (1) to open the [Inspectors] tab with the response properties.

Fig. 5. Properties of HTTP response from the AuthService.svc

ATTENTION The cookies received in the HTTP response (BPMLOADER, .ASPXAUTH and BPMCSRF) are to be used in all further requests to bpm'online, that require authentication data (Fig. 5, 2).

ATTENTION If the authentication has been successful, the response body will contain a JSON object whose Code property will be set to “0” (Fig. 5, 3). In case of errors, JSON obkect properties will contain corresponding code and message.

NOTES If it is necessary to send a request and get a response in the JSON format, use the following key-value pairs in the request header: Content-Type = "application/json" Accept = "application/json;odata=verbose"

Adding data

Example: add a new activity. Fill out the [Title], [Owner] and [Notes] columns.

To compose a request to add such data using Fiddler, go to the [Composer] tab and execute the following (Fig. 6):

1. Select HTTP method POST.

2. Specify the EntityDataService.svc service URL generated according to the following mask:

http(s)://[bpm'online application address]/0/ServiceModel/EntityDataService.svc/ActivityCollection/

3. Specify HTTP protocol version 1.1.

4. Add the following in the request title:

• Query content type – application/json.
• Required cookies (BPMLOADER, .ASPXAUTH, BPMSESSIONID и BPMCSRF).
• CSRF token BPMCSRF that contains the value of the corresponding cookie (BPMCSRF).

Example of request’s HTTP title:

Accept: application/atom+xml
Content-Type: application/atom+xml;type=entry
Cookie: BPMSESSIONID=cxa54p2dsb4wnqbbzvgyxcoo; BPMCSRF=6yCmyILSlIE8/toyQm9Ca.; BPMLOADER=rqqjjeqyfaudfyk4xu404j5f; .ASPXAUTH=697...A292D8164;
BPMCSRF: 6yCmyILSlIE8/toyQm9Ca.

ATTENTION If protection from CSRF attacks is enabled, use both the BPMCSRF cookie and BPMCSRF token. For more information, see “Protection from CSRF attacks during integration with bpm'online”. Protection from CSRF attacks is disabled on bpm’online trial websites. Therefore, there is no need to use both BPMCSRF cookie and token in the request titles.

ATTENTION User session is created only upon the first request to the EntityDataService.svc, after which the BPMSESSIONID cookie will be returned in the response (Fig. 8, 2). Therefore, there is no need to add BPMSESSIONID cookie to the title of the first request (Fig. 6, 4). If you do not add BPMSESSIONID cookie to each subseqnent request, then each request will create a new user session. Significant frequency of requests (several or more requests a minute) will increase the RAM consumption which will decrease performance.

NOTES If it is necessary to send a request and get a response in the JSON format, use the following key-value pairs in the request header: Content-Type = "application/json" Accept = "application/json;odata=verbose"

5. Add contents in XML format to the HTTP request body:

<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
    <content type="application/xml">
        <properties xmlns="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata">
            <Title xmlns="http://schemas.microsoft.com/ado/2007/08/dataservices">process the incomming website form request</Title>
            <Notes xmlns="http://schemas.microsoft.com/ado/2007/08/dataservices">please, email to client@gmail.com and process the following request: clients request</Notes>
            <OwnerId xmlns="http://schemas.microsoft.com/ado/2007/08/dataservices">64844c83-c6c2-4eee-a0e9-e26cef529d2f</OwnerId>
        </properties>
    </content>
</entry>

This request fills out all required object columns.

ATTENTION If an object column is a lookup, specify the lookup database Id instead of lookup name. Add the “Id” suffix to the lookup column name in the request. In the current example, the lookup column is [Owner], and the “OwnerId” identifier is specified for it in the request. You can view the OwnerId value in the browser, by opening corresponding record for editing (Fig. 7) obtain via a query.

Fig. 6. Composing an insert query

Fig. 7. Contact Id displayed in the browser

Execute the request by clicking the [Execute] button. As a result, the Fiddler session window will display a response from the EntityDataService.svc service (Fig. 8). Double-click the reply string (1) to open the [Inspectors] tab with the response properties.

Fig. 8. Properties of HTTP response from the EntityDataService.svc

NOTE The response from the EntityDataService.svc service may contain the BPMSESSIONID cookie if the request is executed for the first time (Fig. 8, 2).

The response body contains the added record in the XML format (Fig. 8, 3). The <id> XML element contains the identifier of the added activity, that can be used in other requests that need to work with this record.

As a result, a new record will be added in the [Activities] section (Fig. 9).

Fig. 9. Results of the activity add request

Data selection

The data select query does not have body. Data filtering is done based on the URL parameter values. For more information on the data select queries with filters, see the “Examples of requests for filter selection” article.

To compose a request to select data using Fiddler, go to the [Composer] tab and execute the following (Fig. 10):

1. Select HTTP method POST.

2. Specify the EntityDataService.svc service URL generated according to the following mask:

http(s)://[bpm'online application address]/0/ServiceModel/EntityDataService.svc/ActivityStatusCollection?$filter=Code%20eq%20'InProgress'

3. Specify HTTP protocol version 1.1.

4. In the request title, specify the request body type as application/atom+xml. Add all necessary cookies to the request title (BPMLOADER, .ASPXAUTH, BPMSESSIONID, BPMCSRF) and the BPMCSRF token:

Accept: application/atom+xml
Content-Type: application/atom+xml;type=entry
Cookie: BPMSESSIONID=cxa54p2dsb4wnqbbzvgyxcoo; BPMCSRF=6yCmyILSlIE8/toyQm9Ca.; BPMLOADER=rqqjjeqyfaudfyk4xu404j5f; .ASPXAUTH=697...A292D8164;
BPMCSRF: 6yCmyILSlIE8/toyQm9Ca.

NOTES If it is necessary to send a request and get a response in the JSON format, use the following key-value pairs in the request header: Content-Type = "application/json" Accept = "application/json;odata=verbose"

Fig. 10. Composing data select query

Execute the request by clicking the [Execute] button. As a result, the Fiddler session window will display a response from the EntityDataService.svc service (Fig. 11). Double-click the reply string (1) to open the [Inspectors] tab with the response properties. The body of the HTTP response contains the selection result (2).

Fig. 11. Properties of HTTP response from the EntityDataService.svc

Update data

Example: modify the title of the added activity.

To compose a request to add data using Fiddler, go to the [Composer] tab and execute the following (Fig. 12):

1. Specify HTTP method POST.

ATTENTION Using HTTP methods PUT and DELETE will cause the "405 Method not allowed” error if HTTP extension WebDAV is disabled in the application’s Web.Config file.

2. Specify the EntityDataService.svc service URL generated according to the following mask:

http(s)://[bpm'online application address]/0/ServiceModel/EntityDataService.svc/ActivityCollection(guid'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX')

Use the unique identifier of the added record (a record Id looks like this: 9741fffe-ff81-46ba-8d99-1f488ec5502e), which can be obtained in an HTTP response to rhe add request. You can also view record Id in a browser, by opening a record for editing (Fig. 13).

3. Specify HTTP protocol version 1.1.

4. In the request title, specify the request body type as application/atom+xml. Add all necessary cookies to the request title (BPMLOADER, .ASPXAUTH, BPMSESSIONID, BPMCSRF) and the BPMCSRF token:

Accept: application/atom+xml
Content-Type: application/atom+xml;type=entry
Cookie: BPMSESSIONID=cxa54p2dsb4wnqbbzvgyxcoo; BPMCSRF=6yCmyILSlIE8/toyQm9Ca.; BPMLOADER=rqqjjeqyfaudfyk4xu404j5f; .ASPXAUTH=697...A292D8164;
BPMCSRF: 6yCmyILSlIE8/toyQm9Ca.

NOTES If it is necessary to send a request and get a response in the JSON format, use the following key-value pairs in the request header: Content-Type = "application/json" Accept = "application/json;odata=verbose"

5. Add contents in the XML format to the request body.

<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
    <content type="application/xml">
        <properties xmlns="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata">
            <Title xmlns="http://schemas.microsoft.com/ado/2007/08/dataservices">process the incomming website form request (Updated)</Title>
        </properties>
    </content>
</entry>

NOTE It is recommended to specify only columns that can be modified.

Fig. 12. Composing data update query

Fig. 13. Activity Id displayed in the browser

Execute the request by clicking the [Execute] button. As a result, the Fiddler session window will display a response from the EntityDataService.svc service (Fig. 14). Double-click the reply string (1) to open the [Inspectors] tab with the response properties. The body of the HTTP response is empty (2).

Fig. 14. Properties of HTTP response from the EntityDataService.svc

As a result, the title of the record will be modified (Fig. 15).

Fig. 15. Results of the activity edit request