Creating a user configuration service

Introduction

Creatio service model implements the base set of web services, which you can use for integration with third-party applications and systems. Examples of these system web services are:

• EntityDataService.svc — exchanging data with Creatio via the OData 3 protocol.
• odata — exchanging data with Creatio via the OData 4 protocol.
• ProcessEngineService.svc — launch Creatio business processes from external applications.

These services are implemented based on the WCF technology and are managed at IIS level.

There are also configuration web services in Creatio that can be called from the client part of the application. You can implement specific integration tasks via configuration web services.

Configuration web service is a RESTful service developed on the WCF technology. The web service is available at following address:

[Application Address]/0/rest/[Custom Service Name]/[Custom Service Endpoint]?[Optional Options]

For example:

http://mysite.creatio.com/0/rest/UsrCustomConfigurationService/GetContactIdByName?Name=User1

Starting from version 7.14.1, we have changed the approach to developing web services. The service class must be inheritor of Terrasoft.Web.Common.BaseService.

The UserConnection and AppConnection, properties are already defined in Terrasoft.Web.Common.BaseService, so you do not have to receive these objects from HttpContext.Current. The latter also defines the HttpContextAccessor property, which provides access to context.

HttpContextAccessor grants unified access to HttpContext in both frameworks: ASP.NET Framework and ASP.Net Core. You can receive context in two ways:

• (Not recommended) Using the HttpContext.Current static property. To make the migration from ASP.NET Framework to ASP.Net Core easier, add the Terrasoft.Web.Http.Abstractions namespace to the source code of your service (apply the using directive). This namespace grants unified access to HttpContext that has been implemented using the HttpContext.Current static property. When adapting the old code to the new framework, replace the System.Web namespace by Terrasoft.Web.Http.Abstractions
• (Recommended) Using IHttpContextAccessor registered in DI (ClassFactory). Enables implementing test coverage of the code.

Example of using the Terrasoft.Web.Common.BaseService parent class properties.

namespace Terrasoft.Configuration.UsrCustomNamespace
{
    using Terrasoft.Web.Common;

    [ServiceContract]
    [AspNetCompatibilityRequirements(RequirementsMode = AspNetCompatibilityRequirementsMode.Required)]
    public class UsrCustomConfigurationService: BaseService
    {
        // Service method.
        [OperationContract]
        [WebInvoke(Method = "GET", RequestFormat = WebMessageFormat.Json, BodyStyle = WebMessageBodyStyle.Wrapped,
        ResponseFormat = WebMessageFormat.Json)]
        public void SomeMethod() {
            ...
            var currentUser = UserConnection.CurrentUser; // UserConnection - the BaseService property.
            var sdkHelpUrl = AppConnection.SdkHelpUrl; // AppConnection - the BaseService property.
            var httpContext = HttpContextAccessor.GetInstance(); // HttpContextAccessor - the BaseService property.
            ...
        }
    }
}

Example of adapting to the ASP.Net Core service

namespace Terrasoft.Configuration.UsrCustomNamespace
{
    using Terrasoft.Web.Http.Abstractions;  // Use instead of System.Web

    [ServiceContract]
    [AspNetCompatibilityRequirements(RequirementsMode = AspNetCompatibilityRequirementsMode.Required)]
    public class UsrCustomConfigurationService
    {
        // Service method.
        [OperationContract]
        [WebInvoke(Method = "GET", RequestFormat = WebMessageFormat.Json, BodyStyle = WebMessageBodyStyle.Wrapped,
        ResponseFormat = WebMessageFormat.Json)]
        public void SomeMethod() {
            ...
            var httpContext = HttpContext.Current;
            ...
        }
    }
}

To create a custom web service in the configuration:

1. Create a schema of the [Source code] type in the development package.
2. Create a class of the service in the schema source code. Use the namespace in the Terrasoft.Configuration or any namespace embedded in it. Mark the class with the [ServiceContract] and [AspNetCompatibilityRequirements] attributes with necessary parameters. The service class must be inheritor of Terrasoft.Web.Common.BaseService.
3. Add the implementation of methods corresponding to the service endpoints in the class. Each method of the service should be marked with the [OperationContract] and [WebInvoke] attributes with necessary parameters. If you need to send the data of complex type (object instances, collections, arrays, etc.) you can implement additional classes which instances will receive and return the method of your service. Each class of that type should be marked with the [DataContract] attribute and the fields of the class should be marked with the [DataMember] attribute.
4. Publish the source code schema.

After you publish the schema, the created web service will become available for calling from the source code of the configuration schemas as well as from the external applications (see “Calling configuration services with ServiceHelper”).

See also:

• Creating a user configuration service