A rights policy governs, for a certain workflow object, which users have permission to exercise which rights. The rights policy is configured for each process and for each task in the workflow definition.

The rights policy can be retrieved and accessed directly from the AccessControl service (though this is rarely necessary), and is also used for various internal purposes.

In order to avoid costly network round-trips, each connection to the workflow repository obtains a local copy of the rights policy configuration, and performs all rights computations using client-side code.

The default rights policy is described in the Workflow Developer Manual. In the following, you will learn how to deploy a custom rights policy.

A custom rights policy is often used to influence the "can do" work list, also known as "tasks offered". As described in Section 6.4, “The Work List Service”, the TASK_ACCEPT right forms the basis for the computation of the tasksOffered work list, which can therefore be customized by changing the rights policy.

Marshalling

Responsibility for computing work lists is split between server and client. It is therefore essential that both the server-side and client-side code behave exactly the same. The server-side implementation has to implement either the WfRightsPolicy interface as described in the Workflow Developer Manual, or the RightsPolicy interface of the Unified API. The client-side implementation in the Unified API has to implement RightsPolicy.

The server-side rights policy is created and configured when the workflow definition is uploaded and parsed, and is stored in the database in serialized form. Since Java serialization is unsuitable as a cross-platform network protocol, the rights policy needs to supply a marshaller implementation, which encodes the rights policy configuration into a portable format such as XML, together with an ID (the policy ID) identifying the format. This encoded form is transmitted to the client when the client loads the process or task definition.

On the Unified API client side, the policy ID is used to select a RightsPolicyMarshaller which parses the transmitted configuration, and creates the client-side counterpart as an instance of a class implementing RightsPolicy.

The code for the client-side rights policy and its marshaller must be deployed in a JAR file in the client's class path. The first implementation of RightsPolicyMarshaller with a matching policy ID is used. Names of implementing classes must be listed in a file called META-INF/services/com.coremedia.cap.workflow.plugin.RightsPolicyMarshaller inside the JAR file, as described in the "Service Provider" section of the JAR File Specification.

For example, the cap-client.jar contains a file with the above name, consisting of the following line:

com.coremedia.cotopaxi.workflow.authorization.
ACLRightsPolicyMarshaller

This instructs the Unified API implementation to consult the class ACLRightsPolicyMarshaller in the given package when unmarshalling rights policies. The method RightsPolicyMarshaler#getPolicyId of this class returns the string "coremedia:///cap/workflow-rights-policy/ACL", which is exactly the policy ID marshalled by the server side default rights policy.

When a rights policy with this policy ID is received on the client, the ACL rights policy marshaller is invoked and reads the ACL configuration sent from the server. The marshaller creates and returns an instance of ACLRightsPolicy interpreting this configuration. As the name suggests, ACLRightsPolicy is the implementation of the RightsPolicy interface for this rights policy.

Configuration

If you want to design a Unified API rights policy that can be used on the server side, your policy must be configurable from the XML definition. The rights policy is configured in the element <Rights> that may be included in the definition of any task of process. Traditionally, configuration is done by including <Grant> and <Revoke> subelements in the <Rights> element. If you want to support this configuration style, you should implement the interface ConfigurableRightPolicy instead of RightsPolicy.

That interface provides a number of grant and revoke methods that are called by the server while it parses the definition file. It also contains the method setRights(Set), which informs the policy about those rights that it is supposed to handle. Note that this set is different for tasks and processes.

Rights Computation

The interface RightsPolicy contains four mayPerform methods that must return true or false as a certain operation is allowed or forbidden. The getUsers methods allow the policy to determine those users who are allowed to perform a certain operation. Similarly, the getGroups methods return collections of groups. This is particularly useful when showing a selection of potential users or groups during user interaction.

The rights for a certain task may depend on more than just a set of groups and their membership relations, as is true for the default implementation. For example, the right for an approval task may depend on the documents that are about to be approved. Note that when accessing content in a rights policy, the "can do" work list will only be re-evaluated after changes to content that is directly referenced by the process. Therefore, it is not recommended to access other content from the rights policy.