OData (Open Data Protocol) is an ISO/IEC-approved OASIS standard. It defines a set of best practices for building and using REST API. Use OData to create REST-based services that let you publish and edit resources using simple HTTP requests. Such resources should be identified with a URL and defined in the data model.
The purpose of the OData protocol is to execute requests of external applications to the Creatio database server.
Creatio supports OData 4 and OData 3 protocols. OData 4 provides more features than OData 3. The main difference between the protocols is the data format of the server's response. Learn more about the differences between OData 3 and OData 4 protocols in the official OData documentation. Use OData 4 for Creatio integration.
All external requests to Creatio must be authenticated. We recommend using Forms authentication (cookie based) implemented using the AuthService.svc web service.
OData 4 protocol
The odata web service provides access to Creatio objects via the OData 4 protocol.
OData 3 protocol
The EntityDataService.svc web service provides access to Creatio objects via the OData 3 protocol.
Use the EntityDataService.svc service to work with Creatio objects in a WCF client.
Windows Communication Foundation (WCF) is a program framework that handles data exchange between applications. WCF is a part of .NET Framework.
The WCF client operates by receiving the service metadata and creating client proxy classes. The client application will communicate with Creatio's EntityDataService.svc service using these mediator classes.
To implement the client application:
- Create a .NET project where you will implement the Creatio integration.
- Generate client proxy classes for the EntityDataService.svc service.
- Create a context instance of the EntityDataService.svc service's runtime environment.
- Implement the integration's client business logic using the methods of the proxy class instance.
There are several ways to generate the proxy classes for the EntityDataService.svc service:
- Using the DataServiceModel Metadata Utility Tool (DataSvcutil.exe).
- From the Visual Studio client application project.
Generate proxy classes using the DataServiceModel Metadata Utility Tool
DataSvcUtil.exe is a command line program provided by WCF Data Services. The utility uses the OData channel and generates the data service's client classes required to access the service from the .NET Framework client application. The data classes are generated using the following metadata sources:
- WSDL is the service metadata document. Describes the data model the data service provides.
- CSDL is the data model file. Uses the common schema definition language (CSDL). Learn more: [MC–CSDL]: Conceptual Schema Definition File Format.
- EDMX is an *.xml file. Create it using programs for working with the EDM model. The programs are included in the Entity Framework. Learn more: [MC–EDMX]: Entity Data Model for Data Services Packaging Format.
The DataSvcUtil.exe tool is usually installed in the C:\Windows\Microsoft.NET\Framework\v4.0 directory. For 64-bit systems, the respective directory is usually C:\Windows\Microsoft.NET\Framework64\v4.0.
Find the detailed information about the DataSvcutil.exe utility in the official MSDN documentation.
Generate proxy classes from the Visual Studio client application project
To generate proxy classes from the Visual Studio client application project:
- Right-click the project where you want to implement Creatio integration and select Add Service Reference… in the context menu.
- Enter the complete address of the EntityDataService.svc service in the Address field.
- Click Go and specify the Creatio user credentials. The entities supported by the service will appear in the Services window upon success.
- Specify the namespace to include the generated proxy classes in the Namespace field. For example, CreatioServiceReference. You will also need to link this namespace in the using block of the project.
- Click OK to generate the proxy classes. This will add a new Reference.cs code file with the description of proxy classes to the project. Use the classes to call and interact with the data service's resources as objects.
Visual Studio also lets you generate the service's proxy classes from the service metadata file stored on your drive. To do this, enter the complete path to the metadata file, starting from the file:// prefix, in the Address field on step 2.
Visual Studio will link the Microsoft.Data.Services.Client.dll build in the project upon generating the service's proxy classes. This ensures OData 3 protocol support. If the client application requires an earlier version of the protocol, link the corresponding build manually. This client library lets you call the EntityDataService.svc data service using the standard .NET Framework programming templates and the LINQ request language.
Add the using directives to and declare the variable of the OData service URL in the project code to ensure successful compilation.
Limitations of OData protocol
When using the OData protocol, keep in mind the following limitations:
- It is not possible to create system users.
- It is not possible to specify the culture of the returned data. The culture is determined by the culture of the user on whose behalf you executed the request.
- The response body can contain up to 20 000 lines.
- A batch request can contain up to 100 sub-requests.
- The MaxFileSize system setting controls the maximum size of the files you can upload using requests. The default value is 10 Mb.
View the Creatio API documentation that has examples of various CRUD operations via OData 3 and OData 4 protocols on the Postman website.
The following elements have the Stream data type:
- Images
- Files
- Binaries
Use the following standard methods to work with the Stream data type:
- GET – retrieve data
- POST – add data
- PUT – modify data
- DELETE – delete data
Clear the browser cache to display Creatio request results when working with the Stream data type.
Retrieve data
Example. Use the OData service to retrieve the “New user” contact's photo.
Implement the example
-
Retrieve the identifier of the “New user” contact's photo.
The contact's photo is stored in the [Data] column of the [SysImage] database table. Run the following SQL query to retrieve the identifier of the “New user” contact's photo.
-
Retrieve the “New user” contact's photo.
Execute the following request to retrieve the “New user” contact's photo.
// Retrieve the [Data] field value for the 29FE7EDF-4DB9-4E09-92B0-018047BA1F71 [Id] object instance in the [SysImage] collection. GET http://mycreatio.com/0/odata/SysImage(29FE7EDF-4DB9-4E09-92B0-018047BA1F71)/Data
Status: 200 OK
Add data
Example. Use the OData service to add the “New user” contact. Then, add a photo to the contact.
Implement the example
-
Add the “New user” contact.
Creatio stores all contacts in the [Contact] database table. Execute the following request to add the “New user” contact.
// Add an object instance to the [Contact] collection. POST http://mycreatio.com/0/odata/Contact Accept: application/json; odata=verbose Content-Type: application/json; odata=verbose; IEEE754Compatible=true BPMCSRF: OpK/NuJJ1w/SQxmPvwNvfO { // Write the "New user" contact name to the [Name] field. "Name": "New user" }Status: 201 Created { "@odata.context": "http://mycreatio.com/0/odata/$metadata#Contact/$entity", "Id": "4c63c8fa-467b-48a6-973f-b2069298404f", "Name": "New user", "OwnerId": "410006e1-ca4e-4502-a9ec-e54d922d2c00", "CreatedOn": "2021-01-14T08:33:29.009023Z", "CreatedById": "410006e1-ca4e-4502-a9ec-e54d922d2c00", "ModifiedOn": "2021-01-14T08:33:29.009023Z", "ModifiedById": "410006e1-ca4e-4502-a9ec-e54d922d2c00", "ProcessListeners": 0, "Dear": "", "SalutationTypeId": "00000000-0000-0000-0000-000000000000", "GenderId": "00000000-0000-0000-0000-000000000000", "AccountId": "00000000-0000-0000-0000-000000000000", "DecisionRoleId": "00000000-0000-0000-0000-000000000000", "TypeId": "00000000-0000-0000-0000-000000000000", "JobId": "00000000-0000-0000-0000-000000000000", "JobTitle": "", "DepartmentId": "00000000-0000-0000-0000-000000000000", "BirthDate": "0001-01-01T00:00:00Z", "Phone": "", "MobilePhone": "", "HomePhone": "", "Skype": "", "Email": "", "AddressTypeId": "00000000-0000-0000-0000-000000000000", "Address": "", "CityId": "00000000-0000-0000-0000-000000000000", "RegionId": "00000000-0000-0000-0000-000000000000", "Zip": "", "CountryId": "00000000-0000-0000-0000-000000000000", "DoNotUseEmail": false, "DoNotUseCall": false, "DoNotUseFax": false, "DoNotUseSms": false, "DoNotUseMail": false, "Notes": "", "Facebook": "", "LinkedIn": "", "Twitter": "", "FacebookId": "", "LinkedInId": "", "TwitterId": "", "ContactPhoto@odata.mediaEditLink": "Contact(4c63c8fa-467b-48a6-973f-b2069298404f)/ContactPhoto", "ContactPhoto@odata.mediaReadLink": "Contact(4c63c8fa-467b-48a6-973f-b2069298404f)/ContactPhoto", "ContactPhoto@odata.mediaContentType": "application/octet-stream", "TwitterAFDAId": "00000000-0000-0000-0000-000000000000", "FacebookAFDAId": "00000000-0000-0000-0000-000000000000", "LinkedInAFDAId": "00000000-0000-0000-0000-000000000000", "PhotoId": "00000000-0000-0000-0000-000000000000", "GPSN": "", "GPSE": "", "Surname": "user", "GivenName": "New", "MiddleName": "", "Confirmed": true, "IsNonActualEmail": false, "Completeness": 0, "LanguageId": "6ebc31fa-ee6c-48e9-81bf-8003ac03b019", "Age": 0 }
The “New user” contact identifier is “4c63c8fa-467b-48a6-973f-b2069298404f.”
-
Add a photo to the “New user” contact.
The contact photo must be stored in the [Data] column of the [SysImage] database table. Since there is no table record for this contact, you must add it. Execute the following request to add a record to the table.
The record was added to the [SysImage] database table, however the value of the [Data] column is “0x.”
Pass the image in the request body. The image filename must match the value of the [Name] field. Execute the following request to add the contact photo to the [Data] column.
// Update the value of the [Data] field for the 410006e1-ca4e-4502-a9ec-e54d922d2c01 [Id] object instance in the [SysImage] collection. PUT http://mycreatio.com/0/odata/SysImage(410006e1-ca4e-4502-a9ec-e54d922d2c01)/Data Accept: application/json; text/plain; */* Content-Type: application/octet-stream; IEEE754Compatible=true BPMCSRF: OpK/NuJJ1w/SQxmPvwNvfO
Status: 200 OK -
Bind the added photo to the “New user” contact.
Link the [Data] field of the [SysImage] table to the [PhotoId] field of the [Contact] table to bind the photo to the “New user” contact. Execute the following request to set up the binding.
// Update the value of the [PhotoId] field for the 4c63c8fa-467b-48a6-973f-b2069298404f [Id] object instance in the [Contact] collection. PATCH http://mycreatio.com/0/odata/Contact(4c63c8fa-467b-48a6-973f-b2069298404f) Accept: application/json;odata=verbose Content-Type: application/json; odata=verbose; IEEE754Compatible=true BPMCSRF: OpK/NuJJ1w/SQxmPvwNvfO { // Write the identifier of the record in the [SysImage] table to the [PhotoId] field. "PhotoId": "410006e1-ca4e-4502-a9ec-e54d922d2c01" }Status: 204 No Content
Execute the following to add a photo to an existing contact:
- A POST request to add an object instance to the [SysImage] collection.
- A PUT request to update the value of the [Data] field for the object instance in the [SysImage] collection.
- A PATCH request to bind the added photo to the “New user” contact.
Modify data
Example. Use the OData service to update the photo of the existing “New user” contact.
Implement the example
-
Retrieve the identifier of the “New user” contact's photo.
The contact's photo is stored in the [Data] column of the [SysImage] database table. Run the following SQL query to retrieve the identifier of the “New user” contact's photo.
-
Update the “New user” contact's photo.
Execute the following request to update the “New user” contact's photo.
// Update the [Data] field for the 29FE7EDF-4DB9-4E09-92B0-018047BA1F71 [Id] object instance in the [SysImage] collection. PUT http://mycreatio.com/0/odata/SysImage(29FE7EDF-4DB9-4E09-92B0-018047BA1F71)/Data Accept: application/json; text/plain; */* Content-Type: application/octet-stream; IEEE754Compatible=true BPMCSRF: OpK/NuJJ1w/SQxmPvwNvfO
Status: 200 OK
Delete data
Example. Use the OData service to delete the photo of the “New user” contact.
Implement the example
-
Retrieve the identifier of the “New user” contact's photo.
The contact's photo is stored in the [Data] column of the [SysImage] database table. Run the following SQL query to retrieve the identifier of the “New user” contact's photo.
-
Delete the “New user” contact's photo.
Execute the following request to delete the “New user” contact's photo.
// Delete the value of the [Data] field for the 29FE7EDF-4DB9-4E09-92B0-018047BA1F71 [Id] object instance in the [SysImage] collection. DELETE http://mycreatio.com/0/odata/SysImage(29FE7EDF-4DB9-4E09-92B0-018047BA1F71)/Data Accept: application/json; text/plain; */* Content-Type: application/json; charset=utf-8; IEEE754Compatible=true BPMCSRF: OpK/NuJJ1w/SQxmPvwNvfO
Status: 204 No Content
Batch requests combine multiple HTTP requests by specifying each request as a separate object in the batch request's body. The Creatio database server returns a single HTTP response that contains the responses to each request. Use batch requests to improve Creatio performance.
The batch requests utilize:
- The POST HTTP method.
- The $batch parameter.
- The Content-Type header.
The values of the Content-Type header:
- application/json – restricts the content the server returns for each request within the batch request to a single type.
- multipart/mixed – allows you to set unique Content-Type headers for each request in the batch request body.
If one of the requests completes with a 4xx-5xx group response code, the subsequent requests will not be executed. Add the Prefer: continue-on-error header to the main HTTP request to enable the execution of the subsequent requests.
Attention. A batch request can contain up to 100 requests.
Batch request (Content-Type: application/json)
Batch request (Content-Type: application/json and Prefer: continue-on-error)
Batch request (Content-Type: multipart/mixed)
Batch request (Content-Type: multipart/mixed and different sets of requests)
Use the DataServiceQuery universal class to retrieve the service's object collection. This class is a request to the service that retrieves the collection of a specific type of entities.
Create a context object instance of the Creatio application environment to execute a request to EntityDataService.svc.
The examples in this article will use the forms authentication.
To implement the forms authentication:
- Create a LoginClass class.
- Implement the authServiceUri (a string that requests the Login method of the AuthService.svc authentication service) and AuthCookie (Creatio's authentication cookies) fields.
- Implement the TryLogin(string userName, string userPassword) method that authenticates the user and saves the server's response to the AuthCookie field.
-
Implement the OnSendingRequestCookie(object sender, SendingRequestEventArgs e) method that will be called in response to an event of the SendingRequest context instance (creating a new HttpWebRequest instance).
The OnSendingRequestCookie method authenticates the user and adds the cookies received in response to the data request.
There are several ways to execute the service request:
- A LINQ request to the named DataServiceQuery object received from the service context.
- Implicit enumeration of the DataServiceQuery object received from the service context.
- Explicit call of the Execute method of the DataServiceQuery object. Call the BeginExecute method for asynchronous execution.
Retrieve a contact collection via a LINQ request.
Example. Define and implement the LINQ request that returns all contact entities of the EntityDataService.svc service.
Implement the example
Retrieve a contact collection via an implicit request
Example. Use context to execute an implicit request that retrieves all contact entities of the EntityDataService.svc service.
Implement the example
Retrieve a contact collection via an explicit request
Example. Use the DataServiceContext context to execute an explicit request that retrieves all contact entities of the EntityDataService.svc service.
Implement the example
CRUD operation examples
Depending on the request type, OData 4 protocol can return different data. Learn more about the request and response structure below.
Request string
Creatio supports the following request methods:
- GET – retrieve data
- POST – add data
- PATCH – modify data
- DELETE – delete data
Creatio application URL.
OData 4 protocol's web service URL. Unmodifiable part of the request.
Name of the database table (the name of the object collection). Run the authentication and execute one of the requests to retrieve the list of database tables.
Identifier of the database table record string (the identifier of the collection object instance).
Database table record field (the field of the collection object instance).
Optional OData 4 parameters you can use in the GET Creatio request string. Use the ? Operator to specify the parameters. Add the parameter name after the $ operator. Use the & operator to use two or more parameters.
| $value | The field value. | |
| $count | $count=true | The number of elements in the selection. |
| $skip | $skip=n | The first n elements that must be excluded from the selection. |
| $top | $top=n | The first n elements that must be included in the selection. |
| $select | $select=field1,field2,... | A set of fields that must be included in the selection. |
| $orderby | $orderby=field asc or $orderby=field desc | How to sort the field values in the selection. |
| $expand | $expand=field1,field2,... | Extension of the connected fields. |
| $filter | $filter=field template 'field_value' | How to filter the fields in the selection. |
Request headers
Data type to expect in the server response. Optional for GET requests.
Encoding and type of the resource passed in the request body. Optional for GET requests.
ForceUseSession header forces the use of an existing session.
Authentication cookie.
Request body
The field names passed in the request body.
Values of the field1, field2, … fields passed in the request body.
HTTP status code
Response status code.
| 200 OK | A request that does not create a resource was completed successfully, and the resource's value does not equal 0. In this case, the response body should contain the value of the resource specified in the request URL. The information in the response depends on the request method:
GET – the resource was found and passed in the response body. POST – the resource with the description of server actions caused by the request was passed in the response body. |
|---|---|
| 201 Created | A request that creates a resource successfully. The response body should contain the created resource. Used for POST requests that create a collection, create a multimedia object (e. g., a photo), or call an action through import. |
| 202 Accepted | Data request processing has started but has not finished yet. There is no guarantee that the request will be completed successfully (asynchronous request processing). |
| 204 No content | The request was processed successfully, but there is no need to return any data. The value of the requested resource is 0. The response will pass only the headers, the response body should be empty. |
| 3xx Redirection | Redirection means the client must take further actions to execute the request. The response should contain the Location header with the URL that can be used to retrieve the result. The response can also contain the Retry-After header that displays time, in seconds. The time specifies how long the client can wait before executing another request to the resource in the Location header. |
| 304 Not modified | The client executes a GET request with the If-None-Match header, and the content remains unchanged. The response should not contain any other headers. |
| 403 Forbidden | The request is correct, but the server refused to authorize it. This means the client lacks permissions to work with the resource. This may be caused by an invalid BPMCSRF cookie. |
| 404 Not Found | The server cannot find the resource specified in the URL. The response body may contain additional information. |
| 405 Method Not Allowed | The resource specified in the request URL does not support the specified request method. The response should contain the Allow header with the list of request methods the resource supports. |
| 406 Not Acceptable | The resource specified in the request URL does not have any current view that is acceptable for the client as per Accept, Accept-Charset, and Accept-Language request headers. The service does not provide a default view. |
| 410 Gone | The requested resource is no longer available. The resource had used the specified URL but was deleted and is no longer available. |
| 412 Prediction Failed | The client specified a request header condition the resource cannot process. |
| 424 Failed Dependency | The current request cannot be processed because the requested action depends on another action that could not be executed. The request has not been executed due to dependency failure. |
| 501 Not Implemented | The client is using a request method that is not implemented in OData 4 protocol and cannot be processed. The response body should contain the description of the unimplemented functionality. |
Response body
Information about the type of the returned data. Besides the data source path, the data_resource element can contain the $entity parameter. This parameter indicates that the response returned a single instance of the collection object. Available only for GET and POST requests.
Contains the object collection. Not available if the response contains a single collection object instance. Available only for GET requests.
Object collection. Available only for GET requests.
Collection object instances. Available only for GET and POST requests.
The names of the field1, field2, … fields in the object1, object2, … collection object instances. Available only for GET and POST requests.
The values of the field1, field2, … fields in the object1, object2, … collection object instances. Available only for GET and POST requests.
The $count and $value OData 3 parameters will be retired in Creatio version 8.0.10.
Depending on the request type, OData 3 protocol can return different data. Learn more about the request and response structure below.
Request string
Creatio supports the following request methods:
- GET – retrieve data
- POST – add data
- PATCH – modify data
- DELETE – delete data
Creatio application URL.
OData 3 protocol’s web service URL. Unmodifiable part of the request.
OData 3 protocol’s web service URL. Unmodifiable part of the request.
Name of the database table (name of the object collection). When using the OData 3 protocol, add Collection to the first name of the object collection in the request string (e.g., ContactCollection). Run a query to receive the list of database tables.
The identifier of the database table record string (identifier of the collection object instance). For example, guid'00000000-0000-0000-0000-000000000000').
The database table record field (field of the collection object instance).
Optional OData 3 parameters you can use in the GET Creatio request string. Use the ? operator to specify the parameters. Add the parameter name after the $ operator. Use the & operator to use two or more parameters.
| $value | The field value. | |
| $count | $count=true | The number of elements in the selection. |
| $skip | $skip=n | The first n elements that must be excluded from the selection. |
| $top | $top=n | The first n elements that must be included in the selection. |
| $select | $select=field1,field2,... | The set of fields that must be included in the selection. |
| $orderby | $orderby=field asc or $orderby=field desc | How to sort the field values in the selection. |
| $expand | $expand=field1,field2,... | Extension of the connected fields. |
| $filter | $filter=field template 'field_value' | How to filter the fields in the selection. |
Request headers
Data type to expect in the server response. The server returns the response in XML. Optional for GET requests.
Ecoding and type of the resource passed in the request body. Optional for GET requests.
The ForceUseSession header forces the use of an existing session. You do not need to use AuthService.svc in your request to the authentication service.
Authentication cookie.
Request body
The names of the fields passed in the request body.
The values of the field1, field2, … fields passed in the request body.
HTTP status code
Response status code.
| 200 OK | GET, PUT, MERGE, or PATCH request was completed successfully. The response body should contain the value of the object or properly specified in the request URL. |
|---|---|
| 201 Created | POST request created an object or a link successfully. The response body should contain the updated object. |
| 202 Accepted | Processing of the data update request has started but has not finished yet. The response body should contain the Location header and the Retry-After header. The response body should be empty. The server should return the 303 response code with the Location header that contains the final URL that can be used to retrieve the result. The body and the header of the final URL should be formatted similar to the initial data update request. |
| 204 No content | Data update request. The value of the requested resource is 0. The response body should be empty. |
| 3xx Redirection | Data update request. The redirection means the client must take further actions to execute the request. The response should contain the Location header with the URL that can be used to retrieve the result. |
| 4xx Client Error | Incorrect requests. The server returns this code in response to client errors and requests to non-existent resources, such as entities, entity collections, or properties. If the response body is defined for the error code, the error body will be as defined for the corresponding format. |
| 404 Not Found | The object or collection specified in the URL does not exist. The response body should be empty. |