Documentation

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

Working with Creatio objects over the OData protocol WCF-client

Glossary Item Box

General

The access to Creatio entities over the OData protocol is provided by the EntityDataService.svc web-service:

Address of the OData service

http[s]://<server_name>/<Creatio_application_name> + "/0/ServiceModel/EntityDataService.svc/"

Example of the OData service address

http://myserver.com/сreatioWebApp/0/ServiceModel/EntityDataService.svc

Generating proxy classes of the EntityDataService.svc service

General

The key point in the organization of the WCF client operation is receiving metadata of the service and creating client proxy classes. A client application will use these mediation classes to exchange data with the web-service.

The following must be performed to implement the .NET client application that could work with the OData service of Creatio:

  1. Create a .NET project where the integration with Creatio will be implemented.
  2. Generate client proxy classes of the EntityDataService.svc service.
  3. Create an instance of the execute environment for the EntityDataService.svc service.
  4. Implement the client business logic of integration using the methods of the created proxy class instance.

Proxy classes may be generated on the client by several methods considered below.

Creating proxy classes using the DataServiceModel Metadata Utility Tool (DataSvcutil.exe) utility

DataSvcUtil.exe is a command string program provided by WCF Data Services services. The program uses the OData channel and forms client classes of the data service required for access to the data service from the .NET Framework client application. This program forms data classes using the following sources of metadata:

The DataSvcUtil.exe program is installed in the .NET Framework catalogue.

This is usually the folder C:\Windows\Microsoft.NET\Framework\v4.0. For 64-bit system versions this is the folder C:\Windows\Microsoft.NET\Framework64\v4.0.

Format of calling the DataSvcutil.exe utility

datasvcutil /out:file [/in:file | /uri:serviceuri] [/dataservicecollection] [/language:devlang] [/nologo] [/version:ver] [/help]

The DataSvcutil.exe utility is covered in the corresponding section of the MSDN.

NOTE

Visual Studio may generate proxy classes of the service from the service metadata file saved on the disk. For this purpose, fulfill part. 1 of the instructions. Then, enter the full path to the metadata file with the prefix "file://" in the Address dialogue window.

Example: file://C:/metadata.xml"

After this, fulfill part. 3—5 of the instructions.

Examples of working with Creatio entities in the WCF client

When proxy classes of the service are generated, a link to the Microsoft.Data.Services.Client.dll assembly is added to the project. This assembly supports the OData v.3 protocol. If, by any reason, the earlier version of the protocol must be used in the client application, a link to the corresponding assembly must be added manually.

This client library allows making requests to the EntityDataService.svc data service using standard software templates .NET Framework, and include the use of the LINQ request language.

To ensure successful compilation of the examples below, the following must be added to the project code:

Using directives

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

Declaring the variable of the OData service address

private static Uri serverUri = new Uri("http://<server_name>/<application_name>/0/ServiceModel/EntityDataService.svc/");

Receiving the objects collection of the service

To receive the objects collection of the service, the DataServiceQuery universal class is used. This class represents a request to the service, which returns the collection of a certain type of entities. 

To implement the request to the EntityDataService.svc data service, an instance of the environment context object for the Creatio must be created.

One ought to bear in mind that all external requests to Creatio web-services must be authenticated. Detailed methods of authentication may be found in the article External requests authentication to Creatio services.

Forms authentication implemented on the basis of the example in the clause above will be in further examples.

To implement the forms authentication, the LoginClass class with authServiceUri fields (string of a request to the Login method of the AuthService.svc authenticated service) and AuthCookie (Cookie authentications of Creatio) were created. The TryLogin(string userName, string userPassword) method implementing the user authentication and saving the server response in the AuthCookie field may also be used.

In addition, the OnSendingRequestCookie (object sender, SendingRequestEventArgse) method is created. The method will be called in response to an event of the SendingRequest context instance (creating a new HttpWebRequest instance).

The OnSendingRequestCookie method authenticates the user and Cookies received in response are added to the data receipt request.

static void OnSendingRequestCookie(object sender, SendingRequestEventArgs e)
{
    // Calling the method of the LoginClass class, which authenticates the user method transmitted in parameters.
    LoginClass.TryLogin("CreatioUserName", "CreatioUserPassword");
    var req = e.Request as HttpWebRequest;
    // Adding pre-received authentication cookie to the data receipt request.
    req.CookieContainer = LoginClass.AuthCookie;
    e.Request = req;
}

A request to the service may be implemented by one of the following methods:

  • Implementing a LINQ request to the DataServiceQuery named object received from the service context.
  • Implicit listing of the DataServiceQuery object received from the service context.
  • Explicit call of the Execute method of the DataServiceQuery or BeginExecute object for asynchronous execution.

Below are the examples of access to EntityDataService.svc objects by one of the above methods.

 1) Example of receiving the contacts collection via a LINQ request

This example demonstrates how the LINQ request returning all contact entities of the EntityDataService.svc service must be determined and implemented.

public static void GetOdataCollectioByLinqWcfExample()
{
    // Creating the context of the Creatio application.
    var context = new Creatio(serverUri);
    // Determining the method which adds authentication cookie when creating a new request.
    context.SendingRequest += new EventHandler<SendingRequestEventArgs>(OnSendingRequestCookie);
    try
    {
        // Building a LINQ request to receive the contacts collection.
        var allContacts = from contacts in context.ContactCollection
                          select contacts;
        foreach (Contact contact in allContacts)
        {
            // Implementing actions with contacts.
        }
    }
    catch (Exception ex)
    {
        // Error processing.
    }
}

 2) Example of receiving the contacts collection via an implicit request to the OData service via the context object

This example demonstrates how the context must be used to implement the implicit request returning all contact entities of the EntityDataService.svc service.

public static void GetOdataCollectionByImplicitRequestExample()
{
    // Creating a context object of the Creatio application.
    var context = new Creatio(serverUri);
    // Determining the method which adds authentication cookie when creating a new request.
    context.SendingRequest += new EventHandler<SendingRequestEventArgs>(OnSendingRequestCookie);
    try
    {
        // Determining an implicit request to the service to receive the contacts collection.
        DataServiceQuery<Contact> allContacts = context.ContactCollection;
        foreach (Contact contact in allContacts)
        {
            // Implementing actions with contacts.
        }
    }
    catch (Exception ex)
    {
        // Error processing.
    }
}

3) Example of receiving the contacts collection via an explicit request to the OData service via the context object

This example demonstrates how the DataServiceContext context must be used to implement a request to the EntityDataService.svc service returning all contact entities.

public static void GetOdataCollectionByExplicitRequestExample()
{
    // Determining a Uri request to the service which returns the contacts collection.
    Uri contactUri = new Uri(serverUri, "ContactCollection");
    // Creating a context object of the Creatio application.
    var context = new Creatio(serverUri);
    // Determining the method which adds authentication cookie when creating a new request.
    context.SendingRequest += new EventHandler<SendingRequestEventArgs>(OnSendingRequestCookie);
    try
    {
        // Implementing an explicit request to the service by calling the Execute<>() method.
        foreach (Contact contact in context.Execute<Contact>(contactUri))
        {
            // Implementing actions with contacts.
        }
    }
    catch (Exception ex)
    {
        // Error processing.
    }
}

Receiving an object with set features

public static void GetOdataObjectByWcfExample()
{
    // Creating the context of the Creatio application.
    var context = new Creatio(serverUri);
    // Determining the method which adds authentication cookie when creating a new request.
    context.SendingRequest += new EventHandler<SendingRequestEventArgs>(OnSendingRequestCookie);
    var contact = context.ContactCollection.Where(c => c.Name.Contains("User")).First();
    // Implementing actions over the contact.
}

Creating a new object

public static void CreateCreatioEntityByOdataWcfExample()
{
    // Creating a new contact, initiating properties.
    var contact = new Contact()
    {
        Id = Guid.NewGuid(),
        Name = "New Test User"
    };
    // Creating and initiating properties of a new account, to which the created contact refers. 
    var account = new Account()
    {
        Id = Guid.NewGuid(),
        Name = "Some Company"
    };
    contact.Account = account;
    // Creating the context of the Creatio application.
    var context = new Creatio(serverUri);
    // Determining the method which adds authentication cookie when creating a new request.
    context.SendingRequest += new EventHandler<SendingRequestEventArgs> (OnSendingRequestCookie);
    // Adding the created contact to the contacts collection of the service data model. 
    context.AddToAccountCollection(account);
    // Adding the created account to the accounts collection of the service data model.
    context.AddToContactCollection(contact);
    // Setting the relationship between the created contact and account in the service data model.
    context.SetLink(contact, "Account", account);
    // Saving the modification of data in Creatio by one request.
    DataServiceResponse responces = context.SaveChanges(SaveChangesOptions.Batch);
    // Processing the server responses.
}

Modifying an existing object

public static void UpdateCreatioEntityByOdatetWcfExample()
{
    // Creating the context of the Creatio application.
    var context = new Creatio(serverUri);
    // Determining the method which adds authentication cookie when creating a new request.
    context.SendingRequest += new EventHandler<SendingRequestEventArgs>(OnSendingRequestCookie);
    // The contact on which basis the data will be modified is selected from the contacts collection.
    var updateContact = context.ContactCollection.Where(c => c.Name.Contains("Test")).First();
    // Modifying the selected contact properties.
    updateContact.Notes = "New updated description for this contact.";
    updateContact.Phone = "123456789";
    // Saving the modifications in the service data model.
    context.UpdateObject(updateContact);
    // Saving the modification of data in Creatio by one request.
    var responces = context.SaveChanges(SaveChangesOptions.Batch);
}

Deleting an object

public static void DeleteCreatioEntityByOdataWcfExample()
{
    // Creating the context of the Creatio application.
    var context = new Creatio(serverUri);

    context.SendingRequest += new EventHandler<SendingRequestEventArgs>(OnSendingRequestCookie);
    // The object which will be deleted is selected from the contacts collection.
    var deleteContact = context.ContactCollection.Where(c => c.Name.Contains("Test")).First();
    // Deleting the selected object from the service data model.
    context.DeleteObject(deleteContact);
    // Saving the modification of data in Creatio by one request.
    var responces = context.SaveChanges(SaveChangesOptions.Batch);
    // Processing the server responses.
}

 

See Also

© Creatio 2002-2020.

Did you find this information useful?

How can we improve it?