Introduction

Bpm’online service model implements the base set of web services which you can use for integration of bpm’online with external applications and systems. The example of system services are: the EntityDataService.svc which provides the ability to exchange data with bpm'online over the OData protocol and the ProcessEngineService.svc which provides the launch of bpm’online business process from external applications.

Bpm’online enables to create custom web services that can implement specific integration tasks.

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

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

Example:

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

ATTENTION Custom service is available after user authentication via the AuthService.svc (see “The AuthService.svc authentication service”).

To create 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.
3. Add the implementation of methods corresponding to the service endpoints in the class. Each method off the service should be marked with the [OperationContract] и [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. Perform publication of the source code schema.

After publication of the schema, the created web service will be available for call from the source code of the configuration schemas and from the external applications (see “ How to call configuration services with ServiceHelper ”).

Case description

Create custom configuration service that returns Id of the contact of the given name. If there are several contacts found, then return the Id of only the first contact found. If the contact is not 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.

ATTENTION It is not necessary to inherit the class of the service from other classes. In this example, the class is inherited from the BaseService only to be able to access the AppConection property.

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 to 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.UsrCustomConfigurationService
{
    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
    {
        // Link to the UserConnection instance required to access the database.
        private SystemUserConnection _systemUserConnection;
        private SystemUserConnection SystemUserConnection {
            get {
                return _systemUserConnection ?? (_systemUserConnection = (SystemUserConnection)AppConnection.SystemUserConnection);
            }
        }
        
        // A method that returns the contact's ID by its name.
        [OperationContract]
        [WebInvoke(Method = "GET", RequestFormat = WebMessageFormat.Json, BodyStyle = WebMessageBodyStyle.Wrapped,
        ResponseFormat = WebMessageFormat.Json)]
        public string GetContactIdByName(string Name){
            // The default result.
            var result = "";
            // An EntitySchemaQuery instance that accesses the Contact table of the database.
            var esq = new EntitySchemaQuery(SystemUserConnection.EntitySchemaManager, "Contact");
            // Adding columns to the query.
            var colId = esq.AddColumn("Id");
            var colName = esq.AddColumn("Name");
            // Filter the query data.
            var esqFilter = esq.CreateFilterWithParameters(FilterComparisonType.Equal, "Name", Name);
            esq.Filters.Add(esqFilter);
            // Get the result of the query.
            var entities = esq.GetEntityCollection(SystemUserConnection);
            // If the data is received.
            if (entities.Count > 0)
            {
                // Return the value of the "Id" column of the first record of the query result.
                result = entities[0].GetColumnValue(colId.Name).ToString();
                // You can also use this option:
                // result = entities [0]. GetTypedColumnValue <string> (colId.Name);
            }
            // Return the 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.

Note Pay attention to the format of the call result. In the server response, the object that contains property with the name combined from the name of the called method and the “Return” suffix, will be passed. Value of the object property contains the value of the contact Id (or an empty string) returned by the service.

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

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

ATTENTION If the service is called without logging to the application, the authorization error will be displayed (Fig. 4).

Fig. 4. Request result No authorization