Retrieving and Using Permission States

This chapter describes methods provided by Infinity Process Platform to retrieve permission states as well as the usage of the class PermissionHelper.

For an overview over existing permissions and their usage refer to chapter Declarative Security Usage in Infinity Process Platform Services API.

Retrieving Permission States

The client-side ActivityInstance and ProcessInstance objects provide a method IntKey getPermission(String permissionId) for retrieving information about the permission state of the given permission Id for the current user.

The return value is of one of the following values:

Please note that momentarily only the following permissionIds, giving the permission to abort activity and process instances respectively, are supported as parameters for the getPermission method:

For the time being all other permissions will result in the return value UNKNOWN.

Please refer to the JavaDoc of org.eclipse.stardust.engine.api.runtime.ActivityInstance and org.eclipse.stardust.engine.api.runtime.ProcessInstance respectively for details.

Using the PermissionHelper Class

This section describes the usage of the PermissionHelper class in the following cases:

Please refer to the PermissionHelper description in the Infinity Process Platform API reference for more information on this class.

Checking for Permissions to invoke service specific methods on a given element

To check, whether the user is allowed to invoke a method on the service argument that requires the given permission that is defined on a given element, the PermissionHelper class provides the following method:

boolean hasPermission(Service service, String permissionId, <model element> element)

The parameter model element can be an Activity, a ProcessDefinition or a DeployedModelDescription object. Please note that when using a DeployedModelDescription you must use the active model description.

Only instances of WorkflowService, AdministrationService or QueryService are accepted as service argument.

This method uses the service method <service>.getPermissions(), which is described in the section Retrieving Permission States, according to the given service to retrieve the user permissions for that service.

For information on the specific services provided by Infinity Process Platform, refer to chapter Infinity Process Platform Services.

Retrieving all elements the user has access to

To get a list of all elements, to which the user has access to (e.g. processes the user is allowed to view as he has the permission to "Read Process Instance" for or he participates in), use the filterXXXAccess method:

List<xxx> filterXXXAccess(WorkflowService service, List<xxx> elements)

Here, the <xxx> could be either a process definition or an activity. The filter method takes the raw list of elements to filter from.

public List<Activity> filterActivityAccess(WorkflowService service, List<Activity> activities)
public List<ProcessDefinition> filterProcessAccess(WorkflowService service, List<ProcessDefinition> processes)

Caching and Usage

The PermissionHelper class is designed to work in the following two modes:

  1. without caching: Each time the information needed that is not present in the method arguments will be retrieved from the engine.
  2. in caching mode: The information will be retrieved only once and then stored in the instance variables. For the caching mode, it is required that each user must use it's own instance of the PermissionHelper (per client login), otherwise mixing the PermissionHelper for different users will produce incorrect results.

The default constructor assumes that caching is enabled and no information is yet available, so caches are created on demand, depending on usage. Once a method is invoked, the corresponding cache will be created Thus, subsequent invocations of the same method (with the same service object) will be significantly faster.

Another constructor accepts a boolean value.

public PermissionHelper(boolean useCaches)

If this value is false, then caching is completely disabled and information will always be freshly retrieved from the engine.

The arguments of the third constructor are a User object and a set of strings containing the IDs of the startable processes.

 public PermissionHelper(User user, Set<String> startableProcesses)

These objects are stored in the instance and used in filterXXXAccess methods. Both of them are optional. If the IDs of the startable processes are null, the PermissionHelper may issue a WorkflowService.getStartableProcessDefinitions() to get the IDs, if needed, only once, and cache the result. If the IDs are provided, then the helper will use the provided IDs and never request them from the engine.

The User object however is not cached. If the PermissionHelper is not constructed with a User object, then the User will be retrieved from the engine each time the filterXXXAccess is invoked.