Creatio integration via the OData 4 protocol

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.

Implementation of OData 4 in Creatio

<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

---

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:

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:

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.

---