Business Tasks are as a component of the OpenEdge Reference Architecture (OERA) documented on Progress Communities: https://community.progress.com/community_groups/openedge_architecture/w/openedgecloudarcade/854.definition-openedge-reference-architecture-business-task.aspx (Business Task.pdf)

The SmartComponent Library supports the definition and execution of Business Tasks following this model, however with a few specifics in the implementation.

Business Tasks can be invoked from the front end using the Service Adapter and using the Service Interface from the back end.

The OERA describes that Business Tasks may provide multiple service interfaces. In the terms of the SmartComponent Library this translates to the fact that Business Tasks may provide more than a single public method that is compatible with the generic Service Interface for Business Tasks.

When the caller of a Business Task does not provide a specific method name for the request, the default method name “Invoke” will be executed (when such a method has been created).

Implementing Business Tasks

The SmartComponent Library does not require any specific base class or functional Interface definition for Business Tasks. Business Tasks need to provide public methods with specific parameters to allow the invocation from the Service Adapter and Service Interface. As such delegates would be a better way to describe the requirements for Business Task methods (variable method name, known method parameters). Unfortunately the ABL has no support for delegates.

Business Tasks however need to implement the Interface Consultingwerk.OERA.IBusinessService, so that the ServiceManager may register them. The ServiceManager is registry and factory for both Business Entities and Business Tasks.

Business Tasks need to contain at least one single method with the signature required by the Service Interface. This signature consists of zero to five DATASET or DATASET-HANDLE parameters for INPUT-OUTPUT and a serializable parameter object (Consultingwerk.ISerializable). The DATASET or DATASET-HANDLE parameters are defined as INPUT-OUTPUT so that it obliges to the specification between caller and callee if the dataset’s are expected as input or output or both.

Signature for Business Task Methods

METHOD PUBLIC VOID TaskMethodName ([INPUT-OUTUT {DATASET-HANDLE hDataset1 | INPUT-OUTPUT DATASET dsDataset1} ,  
                                   [INPUT-OUTUT {DATASET-HANDLE hDataset2 | INPUT-OUTPUT DATASET dsDataset2} ,  
                                   [INPUT-OUTUT {DATASET-HANDLE hDataset3 | INPUT-OUTPUT DATASET dsDataset3} ,  
                                   [INPUT-OUTUT {DATASET-HANDLE hDataset4 | INPUT-OUTPUT DATASET dsDataset4} ,  
                                   [INPUT-OUTUT {DATASET-HANDLE hDataset5 | INPUT-OUTPUT DATASET dsDataset5} , ]]]]]
                                   poParameter as <Any type implementing Consultingwerk.ISerializable>)

The limitation of up to five dataset parameters was randomly chosen and can be extended quickly if needed.

Invocation from the front end

Business Tasks can be used from the client using the InvokeTask method of the Service Adapter. The InvokeTask method is defined in the Consultingwerk.OERA.IServiceAdapterWithInvokeTask Interface, so the reference provided by the Consultingwerk.Framework.FrameworkSettings class typically requires a CAST to this Interface.

The following parameters are required when calling InvokeTask of the Service Adapter

AppServer Partition (or blank for the default partition)
Class name of the Business Task
Name of the task method to be invoked (or blank for the default “Invoke”)
Zero to five DATASET or DATASET-HANDLE parameters
A single object instance implementing the Interface Consultingwerk.ISerializable, on OpenEdge 11 typically an Consultingwerk.JsonSerializable object
The handle of a specific context dataset for this request or ? for the global context dataset

Sample for the execution of a Business Task from the front end using the Service Adapter:

USING Consultingwerk.OERA.*      FROM PROPATH .

/* Call into Business Task using Service Adapter */
CAST (FrameworkSettings:ServiceAdapter,
      IServiceAdapterWithInvokeTask):InvokeTask ("",                                        /* AppServer Partition */
                                                 "Samples.BusinessTask.SampleBusinessTask", /* Task Class Name */
                                                 "SampleTaskMethod",                        /* Task Method Name */
                                                 INPUT-OUTPUT DATASET dsCustomer,           /* First Dataset Parameter */
                                                 poParameter,                               /* Serializable Parameter Object */
                                                 ?) .                                       /* Use Default Context Dataset */

Invocation from the back end

Code already executed on the backend can invoke task methods using the InvokeTask method of the Service Interface. This method is implemented in the Consultingwerk.OERA.ServiceInterface Class.

The following parameters are required when calling InvokeTask of the Service Interface

Class name of the Business Task
Name of the task method to be invoked (or blank for the default “Invoke”)
Zero to five DATASET or DATASET-HANDLE parameters
A single object instance implementing the Interface Consultingwerk.ISerializable, on OpenEdge 11 typically an Consultingwerk.JsonSerializable object

Sample for the execution of a Business Task on the back end using the Service Interface:

USING Consultingwerk.OERA.*      FROM PROPATH .


/* Call into Business Task using Service Interface */
Consultingwerk.OERA.ServiceInterface:InvokeTask ("Samples.BusinessTask.SampleBusinessTask", /* Task Class Name */
                                                 "SampleTaskMethod",                        /* Task Method Name */
                                                 INPUT-OUTPUT DATASET dsCustomer,           /* First Dataset Parameter */
                                                 poParameter) .                             /* Serializable Parameter Object */

Life time of a Business Task instance

The life time of a Business Task instance on the backend is like the life time of Business Entities controlled by the Service Manager. The Service Manager creates the instance of the Business Task class when the task is called for the first time.

Business Task instances remain loaded as Service Provider instances, until they are actively removed using the StopBusinessService or StopAllBusinessServices methods of the Service Manager.

Optionally not a singleton

By default Business Tasks and Business Entities are considered singletons. As typically they should not keep any context between two calls all requests for a task are delegates to the same instance of the task class within the ABL session. Thus Business Tasks are de facto singleton instances through how they are handled by the factory or registry.

There may however be cases in which more than a single instance of a Business Tasks should be used: When a task calls into itself or when it should in contrast to the norm keep context between two requests (which in particular opens additional use cases for business tasks from OpenEdge 11.5 and the PASOE AppServer).

In this case it is possible to communicate with multiple task instances. In order to achieve this a developer has to append CHR(1) and an instance identifier to the task class name parameter.

In this case you should however ensure that additional business task instances are stopped using the StopBusinessService method of the Service Manager when no longer needed.

Registering of Services as Business Tasks

Business Tasks may allow when the method signature matches the requirements the execution of service side “services” registered in the Service Container from the client. In these cases it is not required to create a task as a façade to a service instance. It is enough to register the same instance of a service class in the service container and as a Business Task in the Service Manager.

Typically services are started when the AppServer is started (using the ServiceLoader) and Business Tasks are started with the first request. A service instance however can immediately when started register itself with the Service Manager as a Business Task instance.

For this purpose the service instance may use the method

Consultingwerk.OERA.ServiceManager:RegisterBusinessService (pcServiceName AS CHARACTER,
                                                            poInstance AS IBusinessService) .

After this the Business Service Instance will be registered as the given service name in the Service Manager.

Typically THIS-OBJECT is passed as the poInstance parameter.

Sample

Consultingwerk.OERA.ServiceManageR:RegisterBusinessService ("Samples.BusinessTask.SampleBusinessTask", /* Task Class Name */
                                                            THIS-OBJECT) .

Developers need to pay attention that the service needs to implement the IBusinessService interface in order to be used as a Business Task as well.

Using Business Entities from Business Tasks

As Business Tasks are already executed on the back end Business Entities may be used using the Service Interface. The Business Task may provide an outer transaction to multiple calls into (multiple) Business Entities. Alternatively DatasetModel classes can be used to interact with Business Entities.