Executing OData queries using Fiddler

Introduction

Integration with Creatio 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 “Creatio integration over the OData protocol” article.

Authentification

Before making requests to EntityDataService.svc, a third party application must be authenticated and receive the corresponding cookies. Creatio’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)://[Creatio application address]/ServiceModel/AuthService.svc/Login

Example:

https://012496-sales-enterprise.creatio.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":"Supervisor",
    "UserPassword":"Supervisor"
}

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

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)://[Creatio 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 and 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.

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.

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

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)://[Creatio 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.

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.

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

http(s)://[Creatio 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.

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>

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