Business Services (Business Entities and Business Tasks) are the main business logic objects that build an application. Consumers are typically accessing business logic objects through the service interface or service adapter by specifying a name. The business service name can be specified with a few special options which are described here.

Business Services are required to implement the IBusinessService interface. The interface is used to express the intended use of a class as a business service. There are no methods, properties or events required when implementing this interface.

Class name

The most common way of referencing a Business Service is through its fully qualified class name, like “Consultingwerk.SmartComponentsDemo.OERA.Sports2000.CustomerBusinessEntity”.

In this case the Service Manager will provide an instance based on a DYNAMIC-NEW of that type.

{Consultingwerk/SmartComponentsDemo/OERA/sports2000/dsOrder.i} .
 
DEFINE VARIABLE oRequest AS Consultingwerk.OERA.FetchDataRequest NO-UNDO .
 
oRequest = NEW Consultingwerk.OERA.FetchDataRequest
              ("eOrder",
               SUBSTITUTE("for each eOrder where eOrder.SalesRep = &1", QUOTER (cSalesRep)),
               10) .
 
Consultingwerk.Framework.FrameworkSettings:ServiceAdapter:RetrieveData
              ("",
               "Consultingwerk.SmartComponentsDemo.OERA.Sports2000.OrderBusinessEntity",
               oRequest,                                                                       
               OUTPUT DATASET dsOrder BY-REFERENCE /* avoid deep copy */) .

Mapped Service Name (Short Name Mapping Service)

 Through implementing a Consultingwerk.OERA.IServiceNameMappingService customers can provide a mapping between a name provided by the consumer and the actual class name. This allows developers to support consumers to reference a Business Service Name through a short name (e.g. Customer) instead of the full class name (Consultingwerk.SmartComponentsDemo.OERA.Sports2000.CustomerBusinessEntity).

Consultingwerk provides a default implementation of the IServiceNameMappingInterface: ServiceNameMappingService. This implementation uses an XML representation of the Temp-Table  in Consultingwerk/OERA/ttServiceNameMapping.i for mapping supported short names into actual class names. The Temp-Table is imported from the XML file named .servicenamemapping

<?xml version="1.0"?>
<ttServiceNameMapping xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<ttServiceNameMappingRow>
    <SourceServiceName>Customer</SourceServiceName>
    <MappedServiceName>Consultingwerk.SmartComponentsDemo.OERA.Sports2000.CustomerBusinessEntity</MappedServiceName>
</ttServiceNameMappingRow>
</ttServiceNameMapping>

The Service Manager calls into the Service Name Mapping Service (when loaded on the Application Backend) to translate the Service Name into the class name. When the Service Name Mapping Service returns no mapped class name (unknown or empty value) the service name will be used as the class name (as if no Service Name Mapping Service would be present).

Providing a parameter to the Business Services Constructor

The consumer can provide a character parameter value to the constructor of the Business Entity or Business Task. This can be done by passing in the class name (or short class name) followed by a # or | delimiter and a character value:

• “Customer#ABC”

• “Consultingwerk.SmartComponentsDemo.OERA.Sports2000.CustomerBusinessEntity#ABC”

In this case the Service Manager will call the constructor of the Business Service with the parameter value (“ABC” in this sample). The Business Service with the parameter value ABC will be considered a separate instance managed by the Service Manager. For the life time of the Business Service clients can all into the Service Interface by providing the service name with the constructor parameter and call into that specific instance. Multiple instances of the Business Service with multiple (or no) parameter values passed to the constructor can be used in parallel.

The parameter value can be used by the Business Entity to influence its behavior, like different population of calculated fields etc..

We support both the # and the | sign as delimiters between class name and constructor parameter. The # delimiter should not be used when referencing the service name through REST or Web client interfaces, as the # is considered as a special character in the URI there and might not be passed to the backend properly.

Distinguishing between different Business Service instances using an instance key

There are rare situations where consumers will have to call into distinct instances of the same Business Service. This is in particular the case when from within a single Business Entity you have to call into another instance of the same Business Entity (to determine the ManagerName in an Employee Business Entity when the Manager is an Employee itself).

This can be achieved by adding a CHR(1) as a delimiter followed by a unique value (like a GUID) to the business service name:

DEFINE VARIABLE cServiceName AS CHARACTER NO-UNDO .
 
ASSIGN cServiceName = SUBSTITUTE ("Consultingwerk.SmartComponentsDemo.OERA.Sports2000.CustomerBusinessEntity&1&2":U, CHR(1), GUID)

The Service Manager will in this case launch a separate instance of the Business Entity.

As we cannot define a static life-time for those business services, the consumer is responsible for stopping them when no longer required:

FINALLY:
    Consultingwerk.OERA.ServiceManager:StopBusinessService (cServiceName, 
                                                            Consultingwerk.OERA.NotRunningServiceEnum:Ignore)
END FINALLY .