It is very common for business objects to have fields which are not viewable to all users. The KNS provides very easy ways to mask fields throughout client applications.

Naturally, since certain end users can see the field unmasked, certain other users can see the field partially masked, and a final group of users views a fully masked field, KNS data masking it integrated with KIM permissions. Specifically, there are two KIM permissions which are consulted by KNS data masking: KR-NS Full Unmask Field and KR-NS Partial Unmask Field. Both of these permissions have two related permission attribute records: one for the field name, and one for the business object component name. That masking will automatically be applied to every use of the business object’s field: on inquiries, lookups, maintenance documents, transactional documents, and screens.

<bean id="IdentityManagementPersonDocument-taxId-parentBean" parent="AttributeDefinition" abstract="true" p:name="taxId" p:forceUppercase="true" p:label="Tax Identification Number" p:shortLabel="Tax Id" p:maxLength="100" p:required="false">
    <property name="control">
        <bean parent="TextControlDefinition" p:size="20"/>
    </property>
    <property name="attributeSecurity">
        <bean parent="AttributeSecurity">
            <property name="mask" value="true"/>
            <property name="maskFormatter">
                <bean parent="MaskFormatterLiteral" p:literal="*********"/>
            </property>
        </bean>
    </property>
</bean>

Having a KIM permission set up is not enough, however. Client application developers also have to associate masking with the field of the business object in the business object’s data dictionary. That is accomplished by specifying the an attribute security object with the attribute. IdentityManagementPersonDocument’s taxId attribute has an example of an attribute security declaration:

The taxId field has a TextControlDefinition for the control, and that is followed by the attribute security declaration.

The attribute security declaration has a parent of the “AttributeSecurity” bean. There are several boolean properties available within the AttributeSecurity bean, but the mask and partialMask properties are the most interesting. This declaration quite simply turns masking on – if the AttributeSecurity is left null or if masking or partialMask are false, then no masking will be applied to the attribute.

Also specified in the example is the maskFormatter. There is also a partialMaskFormatter which can be set. A bean of any class which implements org.kuali.rice.kns.datadictionary.mask.MaskFormatter can be used for this declaration. The KNS also provides two default implementations: org.kuali.rice.kns.datadictionary.mask.MaskFormatterLiteral, which simply replaces a value which should be masked by a literal String (in the example above, “*********”), and org.kuali.rice.kns.datadictionary.mask.MaskFormatterSubString, which replaces all but a substring of the masked value as a String (this would be useful in partial mask situations).

The final piece of the puzzle is to get the KNS to consult the KIM permission and the business object’s data dictionary when deciding whether or not to mask the field. Of course, the KNS renders maintenance documents, inquiry pages, and lookups automatically – it is expected that masking will be consulted in those situations.

This leaves only the issue of transactional documents and screens, where a client application developer has to build JSP manually. The KNS provides a number of helper functions to do permission checks.

Of course, calling these functions – especially those which do KIM permission checks – can be computationally expensive. It is always better to check if masking has been turned on by checking the data dictionary attribute for the field first, like so:

<c:if test="${!empty attributeEntry.attributeSecurityMask && attributeEntry.attributeSecurityMask == true  }">
    <c:set var="displayMask" value="${kfunc:canFullyUnmaskField(className, fieldName,KualiForm)? 'false' : 'true'}" />
</c:if>

Alternatively, application developers can simply use the kul:htmlControlAttribute tag – as is the recommended practice under any circumstance – to draw the field. kul:htmlControlAttribute already utilizes the functions described above to make sure the field is properly masked, and as such represents the easiest way to apply masking to fields in transactional documents and screens.

Further information about KIM permissions will be covered in KNS Authorizations. The kul:htmlControlAttribute tag will be covered in the section on Tag Libraries.