Documentation

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

Choosing the method of integration with Creatio

Glossary Item Box

Introduction

Creatio enables range of methods for integration with third-party software products. Choosing the method of integration depends on the needs of the client, the type and architecture of third-party software products and the developer's skills. A comparison of the main characteristics of the supported methods of integration with Creatio is given in Table 1.

Table 1. Comparison of main methods of integration with Creatio

DataService OData Configuration service Web-to-Object iframe

Supported formats of the data exchange
XML, JSON, JSV, CSV XML, JSON XML, JSON JSON No

Tasks are being solved
CRUD operations with Creatio objects, data filtering and use of built-in Creatio macros

CRUD-operations with objects, adding and removing links, obtaining metadata, collections, object fields, sorting, etc.

 All user tasks that can be solved within the open Creatio API Only adding objects Only interaction with user interface of the integrated third-party web application (web page).

Complexity
High Medium Medium Medium Low

Ways of authentication
Forms Basic, Forms Anonymous, Forms — depends on service implementation. Forms Forms (with Creatio)

Availability of auxiliary custom libraries
Creatio .dll libraries can be used only for .NET applications

Enabled

http://www.odata.org/libraries

 No need No need No need

Developer
Creatio Microsoft Creatio Creatio Creatio

A brief description and the main advantages and disadvantages of each of the methods are given below.

Integration with DataService

The DataService web service is the main link between the Creatio client and server parts. It helps to transfer the data that were entered by user via user interface to server side of the application for further processing and saving to the database. More information about the DataService web service can be found in the “DataService web service” article.

Key benefits and integration options

Disadvantages

  • High complexity of query building.
  • Required in-depth knowledge for development.
  • Auxiliary libraries for popular application and mobile platforms are disabled.

Example

An example of the source code of a simple application for sending adding data request to the DataService web service is given below. A request is made to create a new contact, for which the main columns are filled. Detail description of this example can be found in the “DataService. Adding records

using System;
using System.Text;
using System.IO;
using System.Net;
using System.Collections.Generic;
using Terrasoft.Nui.ServiceModel.DataContract;
using Terrasoft.Core.Entities;
using System.Web.Script.Serialization;

namespace DataServiceInsertExample
{
    class Program
    {
        private const string baseUri = @"http://userapp.creatio.com";
        private const string authServiceUri = baseUri + @"/ServiceModel/AuthService.svc/Login";
        private const string insertQueryUri = baseUri + @"/0/DataService/json/reply/InsertQuery";
        private static CookieContainer AuthCookie = new CookieContainer();

        private static bool TryLogin(string userName, string userPassword)
        {
            bool result = false;
            // TODO: Implementation of authentication.
            return result;
        }

        static void Main(string[] args)
        {
            if (!TryLogin("User1", "User1"))
            {
                return;
            }
            // Generate a JSON object for requesting the addition of data.
            // Use the InsertQuery data contract.
            var insertQuery = new InsertQuery()
            {
                RootSchemaName = "Contact",
                ColumnValues = new ColumnValues()
            };
            var columnExpressionName = new ColumnExpression
            {
                ExpressionType = EntitySchemaQueryExpressionType.Parameter,
                Parameter = new Parameter
                {
                    Value = "John Smith",
                    DataValueType = DataValueType.Text
                }
            };
            var columnExpressionPhone = new ColumnExpression
            {
                ExpressionType = EntitySchemaQueryExpressionType.Parameter,
                Parameter = new Parameter
                {
                    Value = "+12 345 678 00 00",
                    DataValueType = DataValueType.Text
                }
            };
            var columnExpressionJob = new ColumnExpression
            {
                ExpressionType = EntitySchemaQueryExpressionType.Parameter,
                Parameter = new Parameter
                {
                    Value = "11D68189-CED6-DF11-9B2A-001D60E938C6",
                    DataValueType = DataValueType.Guid
                }
            };
            insertQuery.ColumnValues.Items = new Dictionary<string, ColumnExpression>();
            insertQuery.ColumnValues.Items.Add("Name", columnExpressionName);
            insertQuery.ColumnValues.Items.Add("Phone", columnExpressionPhone);
            insertQuery.ColumnValues.Items.Add("Job", columnExpressionJob);
            var json = new JavaScriptSerializer().Serialize(insertQuery);
            byte[] jsonArray = Encoding.UTF8.GetBytes(json);
            
            // Sending an Http-request.
            var insertRequest = HttpWebRequest.Create(insertQueryUri) as HttpWebRequest;
            insertRequest.Method = "POST";
            insertRequest.ContentType = "application/json";
            insertRequest.CookieContainer = AuthCookie;
            insertRequest.ContentLength = jsonArray.Length;
            using (var requestStream = insertRequest.GetRequestStream())
            {
                requestStream.Write(jsonArray, 0, jsonArray.Length);
            }
            using (var response = (HttpWebResponse)insertRequest.GetResponse())
            {
                using (StreamReader reader = new StreamReader(response.GetResponseStream()))
                {
                    Console.WriteLine(reader.ReadToEnd());
                }
            }
        }
    }
}

Integration with OData

Open Data (OData) protocol is an open web protocol for data request and update based on the REST architectural approach using Atom/XML and JSON standards. Any third-party application that supports HTTP messaging and can process XML or JSON data can have the access to the Creatio data and objects. Data is available as resources addressed through a URI. Access to the data and modification are performed by standard HTTP commands (GET, PUT, MERGE, POST and DELETE). More information about OData protocol can be found in the “Possibilities for the Creatio integration over the OData protocol” article.

Key benefits and integration options

  • Data exchange with XML, JSON.
  • A lot of operations with Creatio objects, including CRUD operations.
  • Convenient functions for working with strings, dates and time.
  • A large number of custom libraries for working with OData for popular application and mobile platforms.
  • User authorization is required for access.

More information about OData integration can be found in the “Possibilities for the Creatio integration over the OData protocol” article.

Disadvantages

  • Complexity of query building.
  • Requires advanced skills for development.

Case example

Example of method source code for adding a new contact record using OData is given below. Detail description of this example can be found in the “Working with Creatio objects over the OData protocol using Http request” article.

// POST <Creatio URL>/0/ServiceModel/EntityDataService.svc/ContactCollection/

public static void CreateCreatioEntityByOdataHttpExample()
{
    // Create an xml message that contains information about the object being created.
    var content = new XElement(dsmd + "properties",
                  new XElement(ds + "Name", "John Smith"),
                  new XElement(ds + "Dear", "John"));
    var entry = new XElement(atom + "entry",
                new XElement(atom + "content",
                new XAttribute("type", "application/xml"), content));
    Console.WriteLine(entry.ToString());
    // Create a service request that will add a new object to the collection of contacts.
    var request = (HttpWebRequest)HttpWebRequest.Create(serverUri + "ContactCollection/");
    request.Credentials = new NetworkCredential("CreatioUserName", "CreatioUserPassword");
    request.Method = "POST";
    request.Accept = "application/atom+xml";
    request.ContentType = "application/atom+xml;type=entry";
    // Write an xml message to the request thread.
    using (var writer = XmlWriter.Create(request.GetRequestStream()))
    {
        entry.WriteTo(writer);
    }
    // Receiving a response from the service about the result of the operation.
    using (WebResponse response = request.GetResponse())
    {
        if (((HttpWebResponse)response).StatusCode == HttpStatusCode.Created)
        {
            // Processing the result of the operation.
        }
    }
}

Integration with custom configuration web service

Creatio enables to create custom web services in the configuration that can implement specific integration tasks. Configuration web service is a RESTful service implemented on the basis on WCF technology. More information about creation of custom configuration web service can be found in the “Creating a user configuration service” article.

Key benefits and integration options

  • Data exchange is implemented by developer in any convenient way.
  • Developer can implement any operation with Creatio objects, including CRUD operations.
  • User authorization is not required for access.

Disadvantages

  • The entire functionality of the service need to be developed.
  • Required in-depth knowledge for development.

Case example

The complete source code of the configuration service is available below: Service adds the "changed!” word to the incoming parameter and sends a new value in the HTTP answer. Detail description of this example can be found in the “Creating a user configuration service” article.

namespace Terrasoft.Configuration.CustomConfigurationService
{
    using System;
    using System.ServiceModel;
    using System.ServiceModel.Web;
    using System.ServiceModel.Activation;

    [ServiceContract]
    [AspNetCompatibilityRequirements(RequirementsMode = AspNetCompatibilityRequirementsMode.Required)]
    public class CustomConfigurationService
    {
        [OperationContract]
        [WebInvoke(Method = "POST", RequestFormat = WebMessageFormat.Json, BodyStyle = WebMessageBodyStyle.Wrapped,
        ResponseFormat = WebMessageFormat.Json)]
        public string GetTransformValue(string inputParam)
        {
            // Change the value of the incoming parameter.
            var result = inputParam + " changed!";
            return result;
        }
    }
}

Integration with Web-To-Object mechanism.

Web-to-Object is a mechanism of implementation of simple one-way integrations with Creatio. It enables you to create records of the Creatio sections (leads, cases, orders, etc.) by sending required data to the Web-to-Object service.

More common cases of using Web-to-Object service:

  • Creatio integration with custom landings and web forms. The service call is executed from a specifically configured user web page (lending) after the visitor sends the data of the filled form.
  • Integration with external systems that are involved in creation of Creatio objects.

More information about the Web-To-Object can be found in the “Web-To-Object. Integration via landings and web-forms

Key benefits and integration options

  • Data transfer with JSON.
  • Easy creation of Creatio objects.
  • To access you need only URL of the service and Id.
  • Required only basic knowledge for development.

Disadvantages

  • Data transfer only in the Creatio.
  • Limited number of objects to use. Service needs to be modified to use custom objects.

Case example

To use service, send the POST query by the address:

[Path to Creatio application]/0/ServiceModel/GeneratedObjectWebFormService.svc/SaveWebFormObjectData

Query content type – application/json. Insert required cookies and a JSON object that contains data of the web form, to the query content. Example of the JSON object that contains data for creation of a new contact:

{
    "formData":{
        "formId":"d66ebbf6-f588-4130-9f0b-0ba3414dafb8",
        "formFieldsData":[
            {"name":"Name","value":"John Smith"},
            {"name":"Email","value":"j.smith@creatio.com"},
            {"name":"Zip","value":"00000"},
            {"name":"MobilePhone","value":"0123456789"},
            {"name":"Company","value":"Creatio"},
            {"name":"Industry","value":""},
            {"name":"FullJobTitle","value":"Sales Manager"},
            {"name":"UseEmail","value":""},
            {"name":"City","value":"Boston"},
            {"name":"Country","value":"USA"},
            {"name":"Commentary","value":""},
            {"name":"BpmHref","value":"http://localhost/Landing/"},
            {"name":"BpmSessionId","value":"0ca32d6d-5d60-9444-ec34-5591514b27a3"}
        ]
    }
}

Integration of third-party sites via iframe

The most simple way to integrate external solutions to Creatio. The third-party web application can be implemented to Creatio with the iframe HTML element. This enables to view third-party web resources (web pages, video, etc.) from Creatio. Examples of integration via iframe can be found in the “Integration of third-party sites via iframe” and “Developing an advanced marketplace application” (Marketplace development documentation).

Key benefits and integration options

  • Convenience of viewing the third-party web resources directly from the Creatio.
  • Requires only basic skills for development.

Disadvantages

  • Needs to be modified for data transfer (or use another integration method).
  • Some sites prohibit uploading of their pages into the iframe element.

Case example

An example of the source code of the view model schema of Creatio edit page with the implemented iframe element is given below. On the page, the iframe element displays a web site which URL is specified in the object associated with the page. Detail description of this example can be found in the “Developing an advanced marketplace application” article. Another approach is described in the “Integration of third-party sites via iframe” article.

define("tsaWebData1Page", [], function() {
    return {
        entitySchemaName: "tsaWebData",
        diff: /**SCHEMA_DIFF*/[
            // ...
            // A container with an embedded HTML iframe element.
            {
                "operation": "insert",
                "name": "IFrameStat",
                "parentName": "TabData",
                "propertyName": "items",
                "values": {
                    "id": "testiframe",
                    "itemType": Terrasoft.ViewItemType.CONTAINER,
                    "selectors": {"wrapEl": "#stat-iframe"},
                    "layout": { "colSpan": 24, "rowSpan": 1, "column": 0, "row": 0 },
                    "html": "<iframe id='stat-iframe' class='stat-iframe' width='100%' height='550px'" +
                        "style = 'border: 1px solid silver;'></iframe>",
                    "afterrerender": {
                        "bindTo": "addUrl"
                    }
                }
            }
        ]/**SCHEMA_DIFF*/,
        methods: {
            // The event handler for the full data load.
            onEntityInitialized: function() {
                this.callParent(arguments);
                this.addUrl();
            },
            // The method of adding a URL to an HTML iframe element.
            addUrl: function() {
                var iframe = Ext.get("stat-iframe");
                if (!iframe) {
                    window.console.error("The tab with iframe element was not found");
                    return;
                }
                var siteName = this.get("tsaName");
                if (!siteName) {
                    window.console.error("The website name was not provided");
                    return;
                }
                var url = "https://www.similarweb.com/website/" + siteName;
                this.set("tsaURL", url);
                iframe.dom.src = url;
            }
        }
    };
});

© Creatio 2002-2020.

Did you find this information useful?

How can we improve it?