Infinity Process Platform Services

The IPP API is organized along the concepts of specific services needed to perform common usage scenarios. While typical workflow usage will mainly involve worklist introspection followed by process and activity execution, administrative operations or reporting tasks usually need a completely different set of APIs.

This chapter comprises the following topics:

Obtaining Service References

The initial entry point to the IPP API is the interface org.eclipse.stardust.engine.api.runtime.ServiceFactory. Implementations of that interface allow you to centrally obtain (and optionally release) service references. One benefit is the transparent use of credentials for authentication and authorization needs. Another benefit is the option to be able to always write client code as if it would use the plain Java APIs as the service factory will transparently adapt EJB remote interfaces to the local API if needed, thus enabling easy transition from local deployments to distributed EJB or Web deployments.

Service factory implementations are obtained from service factory locators:

The service factory obtained from the appropriate locator will ensure proper bootstrapping of IPP client code and install all necessary transparent treatment like EJB exception unwrapping or security context management.

While essential in plain Java environments, use of such service factories is optional in container environments like EJB or Web. As in the case of a plain Java usage, scenario service bootstrapping includes both client-side as well as implementation-side requirements (i.e. credential passing as well as resource binding), usage of a service factory is downright required. In managed environments the implementation-side setup is well served by the container itself, thus reducing the need for such extra efforts.
Depending on your needs you may safely continue directly using IPP Session Bean homes looked up via JNDI.

Establishing a Connection with the Runtime Environment

You will use the appropriate service factory to authenticate and establish a connection with the Infinity runtime environment. Assuming you authenticate and establish a connection with the Infinity runtime, you can get a reference to Infinity services via this initialized service factory. You can initialize the service factory in the following way:

ServiceFactory sf = ServiceFactoryLocator.get(user, pwd, properties);

Note
The ServiceFactory caches the authenticated Infinity services for the user. For use in a production environment it is important that you cache the ServiceFactory per user. Not caching the ServiceFactory means that a new login will be performed for every interaction with the engine.

Credential Passing

When using the ServiceFactoryLocator you have the option to pass one or more additional properties besides the user's name and password like the user's realm, partition and domain. Please refer to the Managing Multi Partition Infinity Process Platform Installations chapter of the Administrative Concepts part to receive more information on this credentials. The following keys in the properties map will be filled with the values passed as parameters, the following parameters are used:

In case partition, domain and realm are provided as credentials like user or password, the following keys in the properties map will be filled with the values passed as parameters:

If these parameters are empty, the default values residing in the carnot.properties file are used, if existing:

If no Security.DefaultRealm, Security.DefaultPartition or Security.DefaultDomain are set in the carnot.properties file, the following default values will be used:

The following code snippet shows how to fill the properties map:

import org.eclipse.stardust.engine.api.runtime.ServiceFactory;
import org.eclipse.stardust.engine.api.runtime.ServiceFactoryLocator;

    public ServiceFactory getTestService()
    {
        Map properties = new HashMap();
        properties.put(SecurityProperties.PARTITION, partition);
        properties.put(SecurityProperties.DOMAIN, domain);
        properties.put(SecurityProperties.REALM, realm);
        return ServiceFactoryLocator.get(user, password, properties);
    }

Providing Additional Fields for Login Screens

To provide the login screens for users with additional input fields to login with their partition, domain and realm, the following properties residing in the carnot.properties file have to be set to true respectively:

For more information about security properties residing in the carnot.properties file, please refer to the Security section of the Client Side Properties chapter.

Calling IPP Services without Authentication in Local Mode

The org.eclipse.stardust.engine.core.runtime.beans.EmbeddedServiceFactory class determines, whether an execution takes place in the engine context and returns an instance of the EmbeddedServiceFactory.

To return the EmbeddedServiceFactory in case of Infinity Process Platform Portal internal invocation and only start authenticating if the call is remote, pass a transaction constant to indicate the intent of working in the scope of the current transaction. The transaction constants provided by the EmbeddedServiceFactory are:

E.g. use:

ServiceFactory sf = ServiceFactoryLocator.get(CredentialProvider.CURRENT_TX);

User Session Settings

Disabling session tracking

You can determine for which user IDs (accounts) and user OIDs session tracking is disabled. Set a comma separated list of these users in the property Carnot.AuditTrail.Session.NoSessionTracking in your carnot.properties file. To disable session tracking for all users use *.

Setting the expiration interval

To determine the interval after a session is defined as expired, add a value in minutes to the property Carnot.AuditTrail.Session.ExpirationInterval in your carnot.properties file. The default value is 60 minutes.

Setting the activity update delay

You can determine a delay until cached changes on user session entries are added to the database. Set this value in seconds via the property Carnot.AuditTrail.Session.UserActivityUpdateDelay in your carnot.properties file. The default value is 10 seconds.

Provided Services

IPP provides the following services:

For detailed information on the methods of these services, please refer to the according JavaDoc.

WorkflowService

The WorkflowService provides all functionality for workflow enactment for a IPP runtime environment such as:

The following classes are provided for this service:

In case of an EJB deployment the RemoteWorkflowService bean is designed to be deployed as a stateless Session Bean.

QueryService

The QueryService provides functionalities for introspecting a Infinity Process Platform runtime environment such as:

The following classes are provided for this service:

In case of an EJB deployment the RemoteQueryService bean is designed to be deployed as a stateless Session Bean.

AdministrationService

The AdministrationService provides special functionalities to administer a IPP runtime environment such as:

The following classes are provided for this service:

Use of the administration service requires the user to be granted the predefined role Administrator.

In case of an EJB deployment the RemoteAdministrationService bean is designed to be deployed as a stateless Session Bean.

UserService

The UserService provides user management functionalities needed in case of deployments using the Infinity Process Platform integrated security such as:

In case of deployments using third-party security infrastructure such user and user group management functions usually have to be performed using tools of the external system. In such a scenario it might even make sense to omit deployment of the user service at all.

The following classes are provided for this service:

In case of an EJB deployment the RemoteUserService bean is designed to be deployed as a stateless Session Bean.

DocumentManagementService

The DocumentManagementService provides all functionality for Document Management operations in an Infinity Process Platform runtime environment. This includes the following:

The following classes are provided for this service:

In case of an EJB deployment the DocumentManagementService bean is designed to be deployed as a stateless Session Bean.

Service Command

Infinity Process Platform provides a service command interface ServiceCommand as a client side wrapper around a series of service invocations that have to be performed in a single server side transaction. The execute method serves to execute the service command:

Serializable execute(ServiceFactory sf);

The parameter is a ServiceFactory provided by the engine that will ensure that all service calls will be performed in the parent transaction. The method returns the result of the service call execution, which will be returned to the client. For example, WorkflowService.execute(ServiceCommand) returns the Serializable object produced by the execution of the ServiceCommand.

Use the ServiceCommand in the following way:

  1. Provide a ServiceFactory defining a call sequence definition.
  2. Pass the ServiceCommand with this ServiceFactory to the server.
  3. The server executes the call sequence defined in the ServiceCommand in one transaction and stores the return values as defined.
  4. The server returns the ServiceCommand.
  5. Now you are able to retrieve the return value of each executed call in the defined call sequence from the ServiceCommand.

Specifying Options for ServiceCommand

A generic interface Configurable exists for objects that supports client-side configuration. It allows to specify extra behavior options to the ServiceCommand. Your ServiceCommand implementation class may implement the Configurable interface and provide the engine with options regarding execution. For details of the supported options please check the relevant Service API methods.

Note that currently the only supported option is autoFlush. If you set it to Boolean.TRUE, which is the default value, it will cause the engine to flush the audit trail changes after every service call.

AutoFlush effect on service calls

AutoFlush must be called if your service calls in your service command depends on the result of the previous service calls in the same service command. Please note that flushing will not commit the transaction. The transaction will be committed as expected at the end of the service call. In general, using autoFlush will have an impact on the performance of the service call, because after flushing, objects you are reusing will have to be refetched from the database. If your service calls you perform in the service command are independent on each other, e.g. when completing an activity and then starting another process, or starting several processes in the same transaction, you may not enable autoFlush.

Example implementation for setting the autoFlush

public class MyServiceCommand implements ServiceCommand, Configurable
{
   public Serializable execute(ServiceFactory sf)
   {
      // do something here
      return result;
   }

   public Map<String, Object> getOptions()
   {
      return Collections.<String, Object>singletonMap("autoFlush", Boolean.TRUE);
   }
}

Service Security Check

In specific cases you can switch of the security check for a service via the Infinity Process Platform property (xxxService.Guarded).

Per default this property is set to true and the grants set in the Infinity Process Platform Modeler are active. Please refer to chapters Setting Authorization in Model Element Property Pages of the The Modeling Guide and Setting Authorization in Model Element Property Pages of the Business Process Modeling Handbook respectively for detailed information on how to set grants in the modelers.

If set to false, anyone has the grant to use the Workflow Service, but needs to be an administrator to use the Administration, Query or User Service.

Note
It is not recommended to change this property. Changing the value to false introduces a high risk of executing services without having a permission and hence might cause a severe security hole in the deployment!