Version: 8.0

OData basics

Level: advanced

Important

The $count and $value OData 3 parameters will be retired in Creatio version 8.0.10.

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 service URL for .NET Framework
odata service URL for .NET Core and .NET 6

https://mycreatio.com/0/odata

https://mycreatio.com/odata

OData 3 protocol

The EntityDataService.svc web service provides access to Creatio objects via the OData 3 protocol.

EntityDataService.svc service URL
https://mycreatio.com/0/ServiceModel/EntityDataService.svc

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 properties 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 property sources:

WSDL is the service property 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.

DataSvcutil.exe utility calling format
datasvcutil /out:file [/in:file | /uri:serviceuri] [/dataservicecollection] [/language:devlang] [/nologo] [/version:ver] [/help]

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 property file stored on your drive. To do this, enter the complete path to the property file, starting from the file:// prefix, in the Address field on step 2.

file://C:/metadata.xml

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.

using directives
using System;
using System.Data.Services.Client;
using System.Net;
using Terrasoft.Sdk.Examples.CreatioServiceReference;
using System.Linq;

Declare the variable of the OData service URL
private static Uri serverUri = new Uri("https://<server_name>/<application_name>/0/ServiceModel/EntityDataService.svc/");

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.