Creatio integration via the OData 3 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. Using the OData 4 protocol is covered in the “Creatio integration via the OData 4 protocol” article.
You need to authenticate your requests to Creatio.
Implementation of OData 3 in Creatio
The EntityDataService.svc web service will provide access to Creatio objects via the OData 3 protocol.
EntityDataService.svc server address:
https://mycreatio.com/0/ServiceModel/EntityDataService.svc
OData 3 request structure
Structural elements of the request:
- String
- Headers
- Body
Query string
Query string structure:
method my_Creatio_site/0/ServiceModel/EntityDataService.svc/data_resource?$parameters
// Add an instnace of the “AcademyURL” collection object. POST https://mycreatio.com/0/ServiceModel/EntityDataService.svc/AcademyURLCollection
// 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/ServiceModel/EntityDataService.svc/EmployeeCollection?$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_collectionCollection(guid'object_id')/object_field
When integrating with Creatio via OData 3, add Collection to the first name of the collection objects in the request string (e.g., ContactCollection). Use the guid'object_id’ construction to specify the identifier of the collection object instance (e.g., guid'00000000-0000-0000-0000-000000000000').
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 OData 3 parameters that you can use in the Creatio GET request string:
- $value
-
Field value.
- $count
- $count
-
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/atom+xml; type=entry
-
Possible data type of the server response. The server returns its response in the XML format.
- Content-Type
- Content-Type: application/json; odata=verbose
-
Encoding and resource type passed in the request body.
- ForceUseSession
- ForceUseSession: true
-
The “ForceUseSession” header 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/atom+xml; type=entry
Content-Type: application/json; odata=verbose
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 Academy value in the Name field. "Name": "Academy", // Add https://academy.creatio.com/ value in the Description field. "Description": "https://academy.creatio.com/" }
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 3 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.
Receiving the 4xx class code is a result of the unsuccessful request execution.
You can receive the following status codes from the server when sending requests via the OData 3 protocol:
Response body
Response body structure:
<?xml version="1.0" encoding="utf-8"?> <feed xml:base="http://mycreatio.com/0/ServiceModel/EntityDataService.svc/" xmlns="http://www.w3.org/2005/Atom" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"> <id>http://mycreatio.com/0/ServiceModel/EntityDataService.svc/data_resource</id> <title type="text">data_resource</title> <updated>date and time of request</updated> <link rel="self" title="data_resource" href="data_resource" /> <entry> metadata_data <content type="application/xml"> <m:properties> <d:object1 field1>object1 field_value1</d:object1 field1> <d:object1 field2>object1 field_value2</d:object1 field2> ... </m:properties> </content> </entry> <entry> metadata_data <content type="application/xml"> <m:properties> <d:object2 field1>object2 field_value1</d:object2 field1> <d:object2 field2>object2 field_value2</d:object2 field2> ... </m:properties> </content> </entry> ... </feed>
Structural elements of the response body:
- entry
-
Instance of the collection object.
- metadata_data
-
Metadata of the collection object instance.
- 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 <?xml version="1.0" encoding="utf-8"?> <entry xml:base="http://mycreatio.com/0/ServiceModel/EntityDataService.svc/" xmlns="http://www.w3.org/2005/Atom" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"> <id>http://mycreatio.com/0/ServiceModel/EntityDataService.svc/AcademyURLCollection(guid'b634e2d0-6baf-4a13-b9e5-869b717f6406')</id> <category term="Terrasoft.Configuration.AcademyURL" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" /> <link rel="edit" title="AcademyURL" href="AcademyURLCollection(guid'b634e2d0-6baf-4a13-b9e5-869b717f6406')" /> <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/CreatedBy" type="application/atom+xml;type=entry" title="CreatedBy" href="AcademyURLCollection(guid'b634e2d0-6baf-4a13-b9e5-869b717f6406')/CreatedBy" /> <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/ModifiedBy" type="application/atom+xml;type=entry" title="ModifiedBy" href="AcademyURLCollection(guid'b634e2d0-6baf-4a13-b9e5-869b717f6406')/ModifiedBy" /> <title /> <updated>2020-04-01T05:46:43Z</updated> <author> <name /> </author> <content type="application/xml"> <m:properties> <d:Id m:type="Edm.Guid">b634e2d0-6baf-4a13-b9e5-869b717f6406</d:Id> <d:Name>Academy</d:Name> <d:CreatedOn m:type="Edm.DateTime">2020-04-01T05:46:41.7819089Z</d:CreatedOn> <d:CreatedById m:type="Edm.Guid">410006e1-ca4e-4502-a9ec-e54d922d2c00</d:CreatedById> <d:ModifiedOn m:type="Edm.DateTime">2020-04-01T05:46:41.7819089Z</d:ModifiedOn> <d:ModifiedById m:type="Edm.Guid">410006e1-ca4e-4502-a9ec-e54d922d2c00</d:ModifiedById> <d:ProcessListeners m:type="Edm.Int32">0</d:ProcessListeners> <d:Description>https://academy.creatio.com/</d:Description> </m:properties> </content> </entry>
Status: 200 OK <?xml version="1.0" encoding="utf-8"?> <feed xml:base="http://mycreatio.com/0/ServiceModel/EntityDataService.svc/" xmlns="http://www.w3.org/2005/Atom" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"> <id>http://mycreatio.com/0/ServiceModel/EntityDataService.svc/EmployeeCollection</id> <title type="text">EmployeeCollection</title> <updated>2020-03-31T06:32:52Z</updated> <link rel="self" title="EmployeeCollection" href="EmployeeCollection" /> <entry> <id>http://mycreatio.com/0/ServiceModel/EntityDataService.svc/EmployeeCollection(guid'c31c7862-fe33-4a13-9bbc-0943fa08fd02')</id> <category term="Terrasoft.Configuration.Employee" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" /> <link rel="edit" title="Employee" href="EmployeeCollection(guid'c31c7862-fe33-4a13-9bbc-0943fa08fd02')" /> <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/CreatedBy" type="application/atom+xml;type=entry" title="CreatedBy" href="EmployeeCollection(guid'c31c7862-fe33-4a13-9bbc-0943fa08fd02')/CreatedBy" /> <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/ModifiedBy" type="application/atom+xml;type=entry" title="ModifiedBy" href="EmployeeCollection(guid'c31c7862-fe33-4a13-9bbc-0943fa08fd02')/ModifiedBy" /> <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Contact" type="application/atom+xml;type=entry" title="Contact" href="EmployeeCollection(guid'c31c7862-fe33-4a13-9bbc-0943fa08fd02')/Contact" /> <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/OrgStructureUnitCollectionByHead" type="application/atom+xml;type=feed" title="OrgStructureUnitCollectionByHead" href="EmployeeCollection(guid'c31c7862-fe33-4a13-9bbc-0943fa08fd02')/OrgStructureUnitCollectionByHead" /> <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/OrgStructureUnit" type="application/atom+xml;type=entry" title="OrgStructureUnit" href="EmployeeCollection(guid'c31c7862-fe33-4a13-9bbc-0943fa08fd02')/OrgStructureUnit" /> <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Job" type="application/atom+xml;type=entry" title="Job" href="EmployeeCollection(guid'c31c7862-fe33-4a13-9bbc-0943fa08fd02')/Job" /> <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Owner" type="application/atom+xml;type=entry" title="Owner" href="EmployeeCollection(guid'c31c7862-fe33-4a13-9bbc-0943fa08fd02')/Owner" /> <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/ReasonForDismissal" type="application/atom+xml;type=entry" title="ReasonForDismissal" href="EmployeeCollection(guid'c31c7862-fe33-4a13-9bbc-0943fa08fd02')/ReasonForDismissal" /> <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Account" type="application/atom+xml;type=entry" title="Account" href="EmployeeCollection(guid'c31c7862-fe33-4a13-9bbc-0943fa08fd02')/Account" /> <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Manager" type="application/atom+xml;type=entry" title="Manager" href="EmployeeCollection(guid'c31c7862-fe33-4a13-9bbc-0943fa08fd02')/Manager" /> <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/EmployeeCollectionByManager" type="application/atom+xml;type=feed" title="EmployeeCollectionByManager" href="EmployeeCollection(guid'c31c7862-fe33-4a13-9bbc-0943fa08fd02')/EmployeeCollectionByManager" /> <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/EmployeeCareerCollectionByEmployee" type="application/atom+xml;type=feed" title="EmployeeCareerCollectionByEmployee" href="EmployeeCollection(guid'c31c7862-fe33-4a13-9bbc-0943fa08fd02')/EmployeeCareerCollectionByEmployee" /> <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/EmployeeFileCollectionByEmployee" type="application/atom+xml;type=feed" title="EmployeeFileCollectionByEmployee" href="EmployeeCollection(guid'c31c7862-fe33-4a13-9bbc-0943fa08fd02')/EmployeeFileCollectionByEmployee" /> <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/EmployeeInFolderCollectionByEmployee" type="application/atom+xml;type=feed" title="EmployeeInFolderCollectionByEmployee" href="EmployeeCollection(guid'c31c7862-fe33-4a13-9bbc-0943fa08fd02')/EmployeeInFolderCollectionByEmployee" /> <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/EmployeeInTagCollectionByEntity" type="application/atom+xml;type=feed" title="EmployeeInTagCollectionByEntity" href="EmployeeCollection(guid'c31c7862-fe33-4a13-9bbc-0943fa08fd02')/EmployeeInTagCollectionByEntity" /> <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/SalaryCollectionByEmployee" type="application/atom+xml;type=feed" title="SalaryCollectionByEmployee" href="EmployeeCollection(guid'c31c7862-fe33-4a13-9bbc-0943fa08fd02')/SalaryCollectionByEmployee" /> <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/VwEmployeesHierarchyCollectionByEmployee" type="application/atom+xml;type=feed" title="VwEmployeesHierarchyCollectionByEmployee" href="EmployeeCollection(guid'c31c7862-fe33-4a13-9bbc-0943fa08fd02')/VwEmployeesHierarchyCollectionByEmployee" /> <title /> <updated>2020-03-31T06:32:52Z</updated> <author> <name /> </author> <content type="application/xml"> <m:properties> <d:Id m:type="Edm.Guid">c31c7862-fe33-4a13-9bbc-0943fa08fd02</d:Id> <d:Name>William Walker</d:Name> <d:CreatedOn m:type="Edm.DateTime">2017-03-30T14:50:04Z</d:CreatedOn> <d:CreatedById m:type="Edm.Guid">76929f8c-7e15-4c64-bdb0-adc62d383727</d:CreatedById> <d:ModifiedOn m:type="Edm.DateTime">2020-02-14T06:30:46.234Z</d:ModifiedOn> <d:ModifiedById m:type="Edm.Guid">410006e1-ca4e-4502-a9ec-e54d922d2c00</d:ModifiedById> <d:ProcessListeners m:type="Edm.Int32">0</d:ProcessListeners> <d:ContactId m:type="Edm.Guid">227aab3b-7c0c-4181-abf9-81585563ab23</d:ContactId> <d:OrgStructureUnitId m:type="Edm.Guid">d436a9ce-9690-4415-9e03-e8061d7cabb5</d:OrgStructureUnitId> <d:Notes></d:Notes> <d:JobId m:type="Edm.Guid">11d68189-ced6-df11-9b2a-001d60e938c6</d:JobId> <d:FullJobTitle>Developer</d:FullJobTitle> <d:OwnerId m:type="Edm.Guid">76929f8c-7e15-4c64-bdb0-adc62d383727</d:OwnerId> <d:CareerStartDate m:type="Edm.DateTime">2019-09-08T00:00:00</d:CareerStartDate> <d:CareerDueDate m:type="Edm.DateTime">0001-01-01T00:00:00</d:CareerDueDate> <d:ProbationDueDate m:type="Edm.DateTime">2020-01-09T00:00:00</d:ProbationDueDate> <d:ReasonForDismissalId m:type="Edm.Guid">00000000-0000-0000-0000-000000000000</d:ReasonForDismissalId> <d:AccountId m:type="Edm.Guid">a0bf3e92-f36b-1410-0499-00155d043204</d:AccountId> <d:ManagerId m:type="Edm.Guid">3e5bd47e-1ebd-41db-a9a6-a3560dcee3cb</d:ManagerId> </m:properties> </content> </entry> </feed>
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/ServiceModel/EntityDataService.svc/data_resource?$parameters
ForceUseSession: true
BPMCSRF: authentication_cookie_value
Structure of a response body to a GET request
<?xml version="1.0" encoding="utf-8"?> <feed xml:base="http://mycreatio.com/0/ServiceModel/EntityDataService.svc/" xmlns="http://www.w3.org/2005/Atom" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"> <id>http://mycreatio.com/0/ServiceModel/EntityDataService.svc/data_resource</id> <title type="text">data_resource</title> <updated>date and time of request</updated> <link rel="self" title="data_resource" href="data_resource" /> <entry> metadata_data <content type="application/xml"> <m:properties> <d:object1 field1>object1 field_value1</d:object1 field1> <d:object1 field2>object1 field_value2</d:object1 field2> ... </m:properties> </content> </entry> <entry> metadata_data <content type="application/xml"> <m:properties> <d:object2 field1>object2 field_value1</d:object2 field1> <d:object2 field2>object2 field_value2</d:object2 field2> ... </m:properties> </content> </entry> ... </feed>
The structural elements of the response body to a GET request have the following values:
- entry
-
Instance of the collection object.
- metadata_data
-
Metadata of the collection object instance.
- 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/ServiceModel/EntityDataService.svc/objects_collectionCollection
Accept: application/atom+xml; type=entry
Content-Type: application/json; odata=verbose
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:
<?xml version="1.0" encoding="utf-8"?> <feed xml:base="http://mycreatio.com/0/ServiceModel/EntityDataService.svc/" xmlns="http://www.w3.org/2005/Atom" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"> <id>http://mycreatio.com/0/ServiceModel/EntityDataService.svc/data_resource</id> <title type="text">data_resource</title> <updated>date and time of request</updated> <link rel="self" title="data_resource" href="data_resource" /> <entry> metadata_data <content type="application/xml"> <m:properties> <d:object1 field1>object1 field_value1</d:object1 field1> <d:object1 field2>object1 field_value2</d:object1 field2> ... </m:properties> </content> </entry> <entry> metadata_data <content type="application/xml"> <m:properties> <d:object2 field1>object2 field_value1</d:object2 field1> <d:object2 field2>object2 field_value2</d:object2 field2> ... </m:properties> </content> </entry> ... </feed>
The structural elements of the response body to a POST request have the following values:
- entry
-
Instance of the collection object.
- metadata_data
-
Metadata of the created collection object instance.
- object1 field1, object1 field2, ..., object2 field1, object2 field2, ...
-
Field names of the created collection object instance.
- object1 field_value1, object1 field_value2, ..., object2 field_value1, object2 field_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/ServiceModel/EntityDataService.svc/objects_collectionCollection(guid'object_id')
Accept: application/atom+xml; type=entry
Content-Type: application/json; odata=verbose
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/ServiceModel/EntityDataService.svc/objects_collectionCollection(guid'object_id')
Accept: application/atom+xml; type=entry
Content-Type: application/json; odata=verbose
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.