There are two authorizations which are common to all documents. In both cases, the document presentation controller is called and then the authorizer if needed.

The first common authorization is the document initialization authorization. DocumentPresentationController has this method to be overridden for business logic about when a document can be initialized:

public boolean canInitiate(String documentTypeName);

The DocumentAuthorizer also has a:

public boolean canInitiate(String documentTypeName, Person user);

The DocumentAuthorizer checks the KR-SYS Initiate Document permission.

The second common authorization is handled by DocumentPresentationController#getDocumentActions:

public Set<String> getDocumentActions(Document document, Person user, Set<String> documentActions);

It passes its result to DocumentAuthorizer#getDocumentActions:

This authorization actually handles many common authorizations which need to be passed to the document presentation layer. The Set returned by the DocumentAuthorizer is converted into a Map, where each element in the Set becomes a key of the Map. That Map can then be accessed in any web page or tag through the KualiForm.documentActions variable.

org.kuali.rice.kns.document.authorization.DocumentPresentationControllerBase defines a number of protected methods which are inquired when the Set returned by getDocumentActions is built. Builders of client applications are far more likely to override one of those helper methods than override getDocumentActions from scratch.

DocumentAuthorizer also contains a number of methods which are not subject to document presentation controller input. These are:

A couple of authorizations are specific to maintenance documents. The document presentation controller and document authorizer diverge somewhat on which methods they support to control authorizations in documents, so each will be treated separately, save for the one method they do share.

That one method is canCreate. Here is MaintenanceDocumentPresentationController’s declaration of the method:

public boolean canCreate(Class boClass);

It takes the class of the business object, of which the end user is attempting to create a new record of through a maintenance document. Business logic can be written to determine if new records of the given class can be created through a maintenance document.

MaintenanceDocumentAuthorizerBase checks the KR-NS Create / Maintain Record(s) to see if a new business object of the type can be created for its corresponding check.

MaintenanceDocumentPresentationController has two methods which do not have parallels in the MaintenanceDocumentAuthorizer. They are:

public Set<String> getConditionallyReadOnlyPropertyNames(MaintenanceDocument document);

public Set<String> getConditionallyReadOnlySectionIds(MaintenanceDocument document);

To understand this, recall that if there is a field on a maintenance document which is unconditionally read only, that is set within the data dictionary file for that maintenance document. Of course, it brings up the question of what to do if a field or a section is read only some times based on certain business logic and editable at others.

The answer to this has been provided by the MaintenanceDocumentPresentationController. A Set of the property names of the fields or names of the sections which are, given the current condition of the MaintenanceDocument argument, currently read only is returned from the method.

MaintenanceDocumentAuthorizer’s separate methods are similar to canCreate. The first is canMaintain, which determines if the current user can edit an already existing business object. There is also canCreateOrMaintain, which combines the KIM permission checks when the document is routed to make sure the routing is valid.

Finally, MaintenanceDocumentAuthorizer has a method:

public Set<String> getSecurePotentiallyReadOnlySectionIds();

Unlike most methods in MaintenanceDocumentAuthorizer, this method was actually specified to be overridden. It returns a Set of the names of sections on a maintenance document which may be read only based on the user.

There is only one major authorization which is added to TransactionalDocumentPresentationController and TransactionalDocumentAuthorizer: getEditModes. Much like DocumentPresentationController#getDocumentActions(), TransactionalDocumentPresentationController#getEditModes() takes as an argument the document the authorization is being asked of and returns a Set of Strings.

Unlike DocumentPresentationController#getDocumentActions(), though, TransactionalDocumentPresentationController#getEditModes() does not have a set of standard actions it returns. Instead, it is designed specifically to allow any kind of action through the web presentation layer. There, the edit modes can be checked and acted upon in document specific ways.

How is this helpful? In maintenance documents, since the KNS handles the rendering in a standard way, it is easy to turn sections on and off; KIM permissions or work through the maintainable can accomplish. In transactional documents in the other hand, rendering is more manual. However, getEditModes provides a way for the business logic layer to communicate information to the presentation layer.

To get the presentation layer to not display a section, then, a presentation controller might be written as so:

public ExampleDocumentPresentationController extends TransactionalDocumentPresentationController {
    public Set<String> getEditModes(Document document) {
        final ExampleDocument exampleDocument = (ExampleDocument)document;
        Set<String> editModes = new HashSet<String>();
        if (exampleDocument.dontShowExtraSection()) {
            editModes.add("NO_EXTRA_SECTION");
        }
		return editModes;
    }

}

Then, in Example.jsp, we may have code that looks like this:

<c:if test="${!KualiForm.editingMode['NO_EXTRA_SECTION']}">
    <kul:tab tabTitle="Extra Section" defaultOpen="true" tabErrorKey="${Constants.EXTRA_SECTION_ERRORS}">
        ...
    </kul:tab>

</c:if>

Edit Modes also go through the document authorizer, meaning that there is a permission associated with them: KR-NS Use Transactional Document. Expected permission details are the document type and the name of edit mode (in this example, “NO_EXTRA_SECTION”).

Finally, there are two permissions which do not affect documents but only business objects. They are:

Document authorizers handle their calls to Kuali Identity Management in standard ways already. Because this side of authorizations mostly relies on KIM configuration, there is very little reason to override Document Authorizers. In fact, such overrides only occur to accommodate one of the two following situations.

The first situation is when a client application-specific KIM permission which affects documents is invoked. In this case, it is a best practice to give developers the ability to change this logic through the document presentation controller, and then do the actual KIM permission call in the document authorizer. Document authorizers were designed to be standard permission invocation contexts, and using them as such makes development much easier.

The second situation is to add extra attributes to permission detail attribute sets, role qualifier attribute sets, or to both. These extra attributes are sent on every KIM permission call performed by the authorizer. The reason for doing this is to make sure that permissions and roles can qualify properly when the document authorizer performs its call.

For example, imagine a role where the users are qualified by a client application specific field. The document authorizer does not know where or how to gather the data for that field, and yet it must be sent to KIM for the role members to be resolved correctly. Therefore, the

protected void addRoleQualification(BusinessObject businessObject, Map<String, String> attributes) 

method should be overridden, and the attributes argument should be filled with values from the businessObject (which may well be a document) to make sure the role is resolved correctly.

The same can be done for permission details:

protected void addPermissionDetails(BusinessObject businessObject, Map<String, String> attributes)

Finally, if a certain attribute is used both in finding the permission via the permission details and resolving the role, then the following method should be overridden; it will add the attribute to both:

protected void addStandardAttributes(Document document, Map<String, String> attributes)