Creating a user configuration service

Introduction

Bpm’online 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: the EntityDataService.svc, which enables exchanging data with bpm'online via the OData protocol and the ProcessEngineService.svc, which you can use to launch bpm’online 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 bpm’online 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.bpmonline.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 [AspNetCompatibilityRequirement] 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 ”).

Case description

Create a custom configuration service that returns Id of the contact of the given name. If there are several contacts found, return the Id of the first contact only. If no contacts are found, the service should return an empty string.

Source code

You can download the package with case implementation using the following link.

Case implementation algorithm

1. Creating a [Source code] schema

Perform the [Add] – [Source code] action on the [Schemas] tab of the [Configuration] section.

Fig. 1. Adding the [Source Code] schema

Sett following properties for the schema:

• [Name] – UsrCustomConfigurationService.
• [Title] – UsrCustomConfigurationService.

2. Create class of the service

On the [Source code] tab:

• The namespace nested in the Terrasoft.Configuration. The name can be random, for example, the UsrCustomConfigurationService.
• Namespaces whose data types will be used in your class. For this, use the using directive. A complete list of namespaces is provided in the source code below.
• Class, for example, the UsrCustomConfigurationService class inherited from the Terrasoft.Nui.ServiceModel.WebService.BaseService. Mark the class with the [ServiceContract] and [AspNetCompatibilityRequirements(RequirementsMode = AspNetCompatibilityRequirementsMode.Required)] attributes.

The source code with a class declaration is available below:

3. Implement the methods that match the service endpoints

To implement the endpoint of the return of the contact Id by its name, add the GetContactIdByName(string Name) public string to the class. The Name parameter should receive the name of the contact. After accessing the database via the EntitySchemaQuery the method will return the Id of the first found contact (or empty string) casted to string.

Full source code with the implementation of the service:

namespace Terrasoft.Configuration.UsrCustomNamespace
{
    using System;
    using System.ServiceModel;
    using System.ServiceModel.Web;
    using System.ServiceModel.Activation;
    using Terrasoft.Core;
    using Terrasoft.Web.Common;
    using Terrasoft.Core.Entities; 

    [ServiceContract]
    [AspNetCompatibilityRequirements(RequirementsMode = AspNetCompatibilityRequirementsMode.Required)]
    public class UsrCustomConfigurationService: BaseService
    {
        
        
        // Method returning contact identifier by name.
        [OperationContract]
        [WebInvoke(Method = "GET", RequestFormat = WebMessageFormat.Json, BodyStyle = WebMessageBodyStyle.Wrapped,
        ResponseFormat = WebMessageFormat.Json)]
        public string GetContactIdByName(string Name) {
            // Default result.
            var result = "";
            // The EntitySchemaQuery instance, addressing the Contact database table.
            var esq = new EntitySchemaQuery(UserConnection.EntitySchemaManager, "Contact");
            // Adding columns to query.
            var colId = esq.AddColumn("Id");
            var colName = esq.AddColumn("Name");
            // Filtering query data.
            var esqFilter = esq.CreateFilterWithParameters(FilterComparisonType.Equal, "Name", Name);
            esq.Filters.Add(esqFilter);
            // Receiving query results.
            var entities = esq.GetEntityCollection(UserConnection);
            // If the data are received.
            if (entities.Count > 0)
            {
                // Return the "Id" column value of the first record of the query result.
                result = entities[0].GetColumnValue(colId.Name).ToString();
                // You can also use the below variant:
                // result = entities[0].GetTypedColumnValue<string>(colId.Name);
            }
            // Return result.
            return result;
        }
    }
}

After making changes, save and publish the schema.

As a result, the new configuration service UsrCustomConfigurationService will be available in the bpm’online. When the GetContactIdByName endpoint of this service is called, for example, out of web browser, the contact Id (Fig. 2) or the empty string (“”) value (Fig. 3) will be returned.

Fig. 2. Request result: The contact Id is found.

Fig. 3. Request result: The contact Id is not found.

Fig. 4. Request result No authorization