Creatio integration via the OData 4 protocol
Glossary Item Box
Introduction
OData (Open Data Protocol) is an ISO/IEC confirmed OASIS standard determining the best practices for building and using REST API. It enables creating REST-based services that allow web clients to publish and edit resources using simple HTTP requests. Such resources should be identified with a URL and defined in the data model.
Creatio supports OData 3 and OData 4 protocols. OData 4 replaces OData 3 and considerably enhances the capacity of the previous protocol. These two protocols are not compatible by data format returned by the server. You can learn more about the protocols in OData documentation.
To integrate with Creatio, use OData 4.
You need to authenticate your requests to Creatio.
Implementation of OData 4 in Creatio
Feature-UseODataV4 is the parameter responsible for using the OData 4 protocol in Creatio. For Creatio 7.15.3 and up, this parameter is included by default.
To include this parameter for Creatio 7.15.2 and lower versions, add the following string to the configuration file ..\Terrasoft.WebApp\Web.Config:
<add key="Feature-UseODataV4" value="true" />
The odata web service will provide access to Creatio objects via the OData 4 protocol.
Odata server address:
https://mycreatio.com/0/odata
Request structure
Structural elements of the request:
- String
- Headers
- Body
Query string
Query string structure:
method my_Creatio_site/0/odata/data_resource?$parameters
// Add an instnace of the “Contact” collection object POST https://mycreatio.com/0/odata/Contact
// Receive an instance of the “Employee” collection objects, whose “Full Job Title” field contains the “Developer” value. The “Name” field value of the nested “Account” object collection should be other than “Our company”. GET https://mycreatio.com/0/odata/Employee?$filter=FullJobTitle eq 'Developer' and Account/Name ne 'Our company'
method
Creatio supports the following request methods:
- GET – receiving data.
- POST – adding data.
- PATCH – modifying data.
- DELETE – deleting data.
data_resource
Data resource is the path to the source of information obtained in the request response.
Data resource structure:
objects_collection(object_id)/object_field
Structural elements of the data resource:
- objects_collection (required)
- The name of the database table (name of the object collection).
- You can receive the list of database tables if you run the following query:
-
For MySQL
SELECT * FROM INFORMATION_SCHEMA.TABLES
-
For Oracle
SELECT * FROM ALL_TABLES
-
For PostgreSQL
SELECT table_name FROM information_schema.tables
- object_id (optional)
-
The string identifier of the database table record (identifier of the collection object instance).
- object_field (optional)
-
The database table record field (field of the collection object instance).
parameters
Non required parameters that you can use in the Creatio GET request string:
- $value
-
Field value.
- $count
- $count=true
-
The number of elements in the build.
- $skip
- $skip=n
-
N of the first elements that should not be in the build.
- $top
- $top=n
-
N of the first elements that should be in the build.
- $select
- $select=field1,field2,...
-
List of fields that should be in the build.
- $orderby
- $orderby=field asc
- $orderby=field desc
-
Sorting of field values that are in the build.
- $expand
- $expand=field1,field2,...
-
Extension of the connected fields.
- $filter
- $filter=field template 'field_value'
-
Filtering of fields that should be in the build.
You can use the following operators when working with parameters:
- ?
-
Specifying the parameter.
- $
-
Specifying the parameter name.
- &
-
Using 2 or more parameters.
Request header
Headers that you can use in the requests to Creatio:
- Accept
- Accept: application/json
-
Possible data type of the server response.
- Content-Type
- Content-Type: application/json; charset=utf-8
-
Encoding and resource type passed in the query body.
- ForceUseSession
- ForceUseSession: true
-
The “ForceUseSession” title accounts for using the existing session. You do not need using AuthService.svc in your request to the authentication service.
- BPMCSRF
- BPMCSRF: authentication_cookie_value
-
Authentication cookie
The “Content-Type” and “Accept” headers are not required for the GET requests.
Accept: application/json
Content-Type: application/json; charset=utf-8
ForceUseSession: true
BPMCSRF: OpK/NuJJ1w/SQxmPvwNvfO
ForceUseSession: true
BPMCSRF: OpK/NuJJ1w/SQxmPvwNvfO
Request body
Request body structure:
{ "field1": "value1", "field2": "value2", ... }
Structural elements of the request body:
- field1, field2, ... (required)
-
Field names that are passed in the request body.
- value1, value2, ... (required)
-
field1, field2, ...values that are passed in the request body.
{ // Add the New User value in the Name field. "Name": "New User", // Add the Customer manager value in the JobTitle field. "JobTitle": "Customer manager" }
Request response structure
Structural elements of the query response:
- Status code
- Body
Status code
As a request response, the server returns a status code encrypted in 3 digits. The first digit specifies the status class. The second and the third digits determine the response ordinal number. The server returns the following HTTP code classes when integrating with Creatio via the OData 4 protocol:
- 2xx (success) – successful acceptance and processing of the client request.
- 3xx (redirection) – you need to execute another request to successfully fulfill the operation.
- 4xx (client error) – a request building error on the side of the client. The server must return a hypertext explanation of receiving the 4xx class code.
- 5xx (internal server error) – unsuccessful execution of the request due to server issues.
Receiving the 4xx and 5xx class codes is a result of the unsuccessful request execution.
You can receive the following status codes from the server when sending requests via the OData 4 protocol:
GET — the requested resource has been found and passed in the response body.
POST — resource that describes the server action to the request, is passed in the response body.
Response body
Response body structure:
{ "@odata.context": "http://my_Creatio_site/0/odata/$metadata#data_resource", "value": [ { "object1 field1": "object1 field_value1", "object1 field2": "object1 field_value2", ... }, { "object2 field1": "object2 field_value1", "object2 field2": "object2 field_value2", ... }, ... ] }
Structural elements of the response body:
- @odata.context
-
Information on the type of the returned data. In addition to the data source path, the data_resource element can also contain the “$entity” parameter. This parameter indicates that the response returned a singe instance of the collection object.
- value
-
Contains the object collection. Is not available if the response contains a single instance of the collection object.
- Square brackets
-
Object collection.
- Nested braces
-
Instances of collection objects.
- object1 field1, object1 field2, ..., object2 field1, object2 field2, ...
-
Names of the field1, field2, ... fields of the object1, object2, ...collection object instances.
- object1 field_value1, object1 field_value2, ..., object2 field_value1, object2 field_value2, ...
-
Values of the field1, field2, ... fields of the object1, object2, ...collection object instances.
Status: 201 Created { "@odata.context": "http://mycreatio.com/0/odata/$metadata#Contact/$entity", "Id": "37dab67d-199d-4275-9eb6-22bea86cb969", "Name": "New User", "OwnerId": "410006e1-ca4e-4502-a9ec-e54d922d2c00", "CreatedOn": "2020-03-02T08:31:34.8076517Z", "CreatedById": "410006e1-ca4e-4502-a9ec-e54d922d2c00", "ModifiedOn": "2020-03-02T08:31:34.8076517Z", "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": "Customer manager", "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": "", "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 }
Status: 200 OK { "@odata.context": "http://mycreatio.com/0/odata/$metadata#Employee", "value": [ { "Id": "c31c7862-fe33-4a13-9bbc-0943fa08fd02", "CreatedOn": "2017-03-30T14:50:04Z", "CreatedById": "76929f8c-7e15-4c64-bdb0-adc62d383727", "ModifiedOn": "2020-02-14T06:30:46.234Z", "ModifiedById": "410006e1-ca4e-4502-a9ec-e54d922d2c00", "ProcessListeners": 0, "ContactId": "227aab3b-7c0c-4181-abf9-81585563ab23", "Name": "William Walker", "OrgStructureUnitId": "d436a9ce-9690-4415-9e03-e8061d7cabb5", "Notes": "", "JobId": "11d68189-ced6-df11-9b2a-001d60e938c6", "FullJobTitle": "Developer", "OwnerId": "76929f8c-7e15-4c64-bdb0-adc62d383727", "CareerStartDate": "2019-09-08T00:00:00Z", "CareerDueDate": "0001-01-01T00:00:00Z", "ProbationDueDate": "2020-01-09T00:00:00Z", "ReasonForDismissalId": "00000000-0000-0000-0000-000000000000", "AccountId": "a0bf3e92-f36b-1410-0499-00155d043204", "ManagerId": "3e5bd47e-1ebd-41db-a9a6-a3560dcee3cb" } ] }
Request types
Reading data
Primary rules of GET requests
- Using parameters is allowed.
- Request body is not available.
- Response body is available.
GET request structure:
GET my_Creatio_site/0/odata/data_resource?$parameters
Accept: application/json
Content-Type: application/json; charset=utf-8
ForceUseSession: true
BPMCSRF: authentication_cookie_value
Structure of a response body to a GET request
{ "@odata.context": "http://my_Creatio_site/0/odata/$metadata#data_resource", "value": [ { "object1 field1": "object1 field_value1", "object1 field2": "object1 field_value2", ... }, { "object2 field1": "object2 field_value1", "object2 field2": "object2 field_value2", ... }, ... ] }
The structural elements of the response body to a GET request have the following values:
- @odata.context
-
Information on the type of the returned data. In addition to the data source path, the data_resource element can also contain the “$entity” parameter. This parameter indicates that the response returned a singe instance of the collection object.
- value
-
Contains the object collection. Is not available if the response contains a single instance of the collection object.
- object1 field1, object1 field2, ..., object2 field1, object2 field2, ...
-
Names of the field1, field2, ... fields of the object1, object2, ...collection object instances.
- object1 field_value1, object1 field_value2, ..., object2 field_value1, object2 field_value2, ...
-
Values of the field1, field2, ... fields of the object1, object2, ...collection object instances.
Adding data
Primary rules of POST requests:
- Using parameters is not allowed.
- Request body is available.
- Response body is available.
POST request structure:
POST my_Creatio_site/0/odata/objects_collection
Accept: application/json
Content-Type: application/json; charset=utf-8
ForceUseSession: true
BPMCSRF: authentication_cookie_value
Only the object collection where you create a new collection object instance can be the data resource for the POST request.
Structural elements of the POST request string:
- objects_collection (required)
-
The name of the collection where you need to create a new collection object instance.
Structure of the POST request body:
{ "field1": "value1", "field2": "value2", ... }
Structural elements of the POST request body:
- field1, field2, ... (required)
-
Field names of the created collection object instance that you need to populate.
- value1, value2, ... (required)
-
Field values of the field1, field2, ... of the created collection object instance that you need to populate.
Structure of a response body to a POST request:
{ "@odata.context": "http://my_Creatio_site/0/odata/$metadata#data_resource/$entity", "field1": "value1", "field2": "value2", ... }
The structural elements of the response body to a POST request have the following values:
- @odata.context
-
Information on the type of the returned data. In addition to the data source path, the data_resource element can also contain the “$entity” parameter. This parameter indicates that the response returned a singe instance of the collection object.
- field1, field2, ...
-
Field names of the created collection object instance.
- value1, value2, ...
-
Field values of the field1, field2, ... of the created collection object instance.
Modifying data
Primary rules of PATCH requests:
- Using parameters is not allowed.
- Request body is available.
- Response body is not available.
Only the object collection where you modify data of the object instance can be the data resource for the PATCH request.
PATCH request structure:
PATCH my_Creatio_site/0/odata/objects_collection(object_id)
Accept: application/json
Content-Type: application/json; charset=utf-8
ForceUseSession: true
BPMCSRF: authentication_cookie_value
Structural elements of the PATCH request string:
- objects_collection (required)
-
The name of the collection whose object instance needs to be modified.
- object_id (required)
-
Identifier of the modified collection object instance.
Structure of the PATCH request body:
{ "field1": "value1", "field2": "value2", ... }
Structural elements of the PATCH request body:
- field1, field2, ... (required)
-
Field names of the modified collection object instance.
- value1, value2, ... (required)
-
New field values of the field1, field2, ... of the created collection object instance.
Deleting data
Primary rules of DELETE requests:
- Using parameters is not allowed.
- Request body is not available.
- Response body is not available.
Only the object collection where you delete the object instance can be the data resource for the DELETE request.
DELETE request structure:
DELETE my_Creatio_site/0/odata/objects_collection(object_id)
Accept: application/json
Content-Type: application/json; charset=utf-8
ForceUseSession: true
BPMCSRF: authentication_cookie_value
Structural elements of the DELETE request string:
- objects_collection (required)
-
The name of the collection whose object instance needs to be deleted.
- object_id (required)
-
Identifier of the deleted collection object instance.