Creatio Raises $200M at $1.2B valuation to lead the enterprise no-code market

Documentation

Creatio development guide
PDF
This documentation is valid for Creatio version 7.16.0. We recommend using the newest version of Creatio documentation.

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
Example of a POST request string
 
  
// Add an instnace of the “Contact” collection object
POST https://mycreatio.com/0/odata/Contact
Example of a GET request string
 
  
// 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.

Example of POST request headers
 
  
Accept: application/json
Content-Type: application/json; charset=utf-8
ForceUseSession: true
BPMCSRF: OpK/NuJJ1w/SQxmPvwNvfO
Example of GET request headers
 
  
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.
Example of a POST 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:

  1. 2xx (success) – successful acceptance and processing of the client request.
  2. 3xx (redirection) – you need to execute another request to successfully fulfill the operation.
  3. 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.
  4. 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:

200 OK The request that does not create a resource is successfully completed and the resource value does not equal zero. In this case, the response body must contain a resource value specified in the request URL. Information returned with the response depends on the method used in the request
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.  
201 Created The request that successfully creates a resource. The response body must contain the created resource. Used for POST requests, that create collection, create multimedia object (e.g., a picture) or call the action through import.  
202 Accepted The data processing request has been accepted but has not yet finished. There is no guarantee that the request will complete successfully (asynchronous request processing).  
204 No Content The request has been processed successfully but there is no need to return any data. The requested resource has a zero value. The response only returned the headers, the response body should be empty.  
3xx Redirection The redirection specifies that the client needs to take further action to execute the request. The response must contain header Location with URL that can be used to receive result. The response can also contain header Retry-After, displaying time (in seconds). Thhis time characterizes the period that the client can wait before repeating the request that has been returned in  header Location.  
304 Not Modified The client executes the GET request with  header If-None-Match and the contents has not changed. The response should not contain other headers.  
403 Forbidden The request is correct, but the server has refused to authorize it because the client has no permission to work with the requested resource. This may be caused by an invalid BPMCSRF cookie.  
404 Not Found The server cannot find a resource specified in the URL. The response body can have additional information.  
405 Method Not Allowed The resource specified in the request URL does not support the specified request method. The response should return the Allow header containing the list of request methods accessible for the resource.  
406 Not Acceptable The resource specified in the request URL does not have any current view 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 used the specified URL, but was deleted and is no longer available.  
412 Precondition Failed In the request header, the client specified a condition that cannot be processed by the resource.  
424 Failed Dependency The current request cannot be processed. The requested action depends on another action that has not been 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 by OData 4 and cannot be processed. The response body must contain the description of the functionality that has not been implemented.  

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.
Example of a response to a POST request
 
  
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

}
Example of a response to a GET request
 
  
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.
© Creatio 2002-2020.

Did you find this information useful?

How can we improve it?