Background operations

Introduction

In the process of developing solutions on bpm’online platform, it is often necessary to run operations that execute for extended periods of time, and at the same time do not cause UI-related delays. Starting with version 7.13.2, bpm’online has functionality for background operations.

To run background operations, two methods are implemented in the Terrasoft.Core.Tasks.Task class: StartNew() and StartNewWithUserConnection(). The specifics of the StartNewWithUserConnection() method is that it can run a background task that requires a user connection UserConnection.

The arguments of these methods can be base .NET types (such as string, int, Guid, etc.) as well as custom types.

The execution of an asynchronous operation is described in a separate class, which must implement IBackgroundTask<in TParameters> interface. If a user connection is required to execute the background action, the class must additionally implement the IUserConnectionRequired interface.

The IBackgroundTask<in TParameters> interface:

namespace Terrasoft.Core.Tasks
{
    public interface IBackgroundTask<in TParameters>
    {
        void Run(TParameters parameters);
    }
}

The IUserConnectionRequired interface:

namespace Terrasoft.Core
{
    public interface IUserConnectionRequired
    {
        void SetUserConnection(UserConnection userConnection);
    }
}

Example

Case description

Create a business process that registers a background operation. The process must complete almost immediately after it launches. The background operation must execute for about 30 seconds, after which a new record is added in the [Activities] section with the “Activity created by background task” subject.

Case implementation algorithm

1. Create a data class for the [Activity] object.

Create a [Source code] schema named “UsrActivityData” in the custom package (see “Creating the [Source code] schema”). Add the following source code to the schema:

namespace Terrasoft.Configuration
{
    using System;
    using Terrasoft.Common;
    using Terrasoft.Core;
    using Terrasoft.Core.DB;
    public class UsrActivityData
    {
        public string Title { get; set; }
        public Guid TypeId { get; set; }
    }
}

Save the schema.

2. Create a class for adding activity

Create a [Source code] schema named “UsrBackgroundActivityCreator” in the custom package (see “Creating the [Source code] schema”). Add the following source code to the schema:

namespace Terrasoft.Configuration
{
    using System;
    using Terrasoft.Common;
    using Terrasoft.Core;
    using Terrasoft.Core.DB;
    using Terrasoft.Core.Tasks;
     
    public class UsrBackgroundActivityCreator : IBackgroundTask<UsrActivityData>, IUserConnectionRequired
    {
        private UserConnection _userConnection;
        public void Run(UsrActivityData data) {
            // Forced 30-second delay.
            System.Threading.Tasks.Task.Delay(TimeSpan.FromSeconds(30));
            // Creating activity.
            var activity = new Activity(_userConnection){
                UseAdminRights = false,
                Id = Guid.NewGuid(),
                TypeId = data.TypeId,
                Title = data.Title,

                // Activity category is "To do"
                ActivityCategoryId = new Guid("F51C4643-58E6-DF11-971B-001D60E938C6")
            };
            activity.SetDefColumnValues();
            activity.Save(false);
        }
        public void SetUserConnection(UserConnection userConnection) {
            _userConnection = userConnection;
        }
    }
}

In the Run() method, after a forced delay of 30 seconds, an instance of the [Activity] object is created based on the provided instance of UsrActivityData.

Save the schema.

3. Create a business process for running a background task

1. Add a new business process.

2. Add a [Script task] element (Fig. 1).

Fig. 1. [ScriptTask] element properties

3. In the [Script task] element, add the following code:

var data = new UsrActivityData {
    Title = "Activity created by background task",
    TypeId = ActivityConsts.TaskTypeUId
};
Terrasoft.Core.Tasks.Task.StartNewWithUserConnection<UsrBackgroundActivityCreator, UsrActivityData>(data);

return true;

4 Save the business process and run it.

As a result, the business process will complete almost immediately after start, while the corresponding activity will be created after 30 seconds.