Grant hooks

This document describes the grant hooks that can be implemented to put some additional business logic at user session level.

None of these hooks needs to be implemented. You can implement one or several of these hooks if you want to apply out some dynamic business logic that goes beyond what can be configured.

These hooks are located in the singleton shared script named GrantHooks.

Authentication hooks

The customAuth (version 3.2+) and parseAuth (version 3.0+) can be used to implement/customize authentication flows.

Check this document about custom authentication, this document about OAuth2 authentication or this document about SAML authentication for details.

User rights hooks

preLoadGrant & postLoadGrant

Two hooks can be used to dynamically customize the user rights.

The preLoadGrant is called before actually loading the user rights (at that stage the user is authenticated and the platform only knows its login).

Example:

GrantHooks.preLoadGrant(g) {
    var login = g.getLogin();
    // e.g. load custom responsibilities and user profile
}

The postLoadGrant is called after the user rights are loaded (responsibilities, system parameters...).

Example:

GrantHooks.postLoadGrant(g) {
    console.log("Hello " + g.getFirststName() + "!");
    // e.g. add custom rights...
}

isMenuEnable

This hook can be used to dynamically disable a menu item.

It is called for each granted menu item for considered user.

Example:

GrantHooks.isMenuEnable(g, domain, item) {
    // Example to hide to group SIMPLE_USER the Product in the Marketing domain.
    if (g.hasResponsibility("SIMPLE_USER") && domain=="DomainMarketing" && item=="Product")
        return false;
    return true;
}

Fulltext search hooks

preSearchIndex & postSearchIndex

These hooks change the result of a fulltext search. The rows argument is a Vector of SearchItem.

Example:

GrantHooks.postSearchIndex = function(g, rows) {
    // Access to the default result
    for (var i=0; rows && i<rows.size(); i++) {
        var item = rows.get(i);

        // Change anything to display here...
        console.log("score "+item.score);   // Optional scoring
        console.log("object "+item.object); // Optional object name
        console.log("row_id "+item.row_id); // Optional row_id
        console.log("key "+item.key);   // Item unique key
        console.log("ukey "+item.ukey); // Default user key to display
        console.log("data "+item.data); // Default payload or summary to display
        if (item.values) {
            //... Optional object values as a List of String
        }   
    }

    // Sample to add an item on top
    var item = new SearchItem();
    item.score = "1000";
    item.ukey = "The best item";
    item.data = "This item is always returned...";
    if (rows) rows.add(0,item);

    return rows;
}

Other hooks

validatePassword

This hook is called when a password change is attempted, it can be used to implement custom rules for password fomat validation:

GrantHooks.validatePassword = function(g, pwd) {
    if (pwd.indexOf("_") < 0) return "A good password must include an underscore!";
};

It can returns either a single error message (like in the example above) or an array of error messages. An error message can either be a hard-coded label (like in the example above) or, better, the code of a configured static text (so as it is displayed in the user's language). Otherwise, it must either return nothing (like in the example above) or an explicit null value to indicate that the password is accepted.

The default system-level implementation for password validation is that a password must have at least 8 digits. The error(s) returned by the above hooks are added to the default error message returned when password length is less than 8 digits.

logout

This hook is called when an explicit or implicit logout occurs (it is called just before the session is dropped)

GrantHooks.logout = function(g) {
    console.log("Bye bye " + g.getLogin() + "!");
};

dowloadDocument

This hook is called when a document download has been requested and has been successfully checked (versions 3.2+):

GrantHooks.downloadDocument = function(g, doc) {
    if (doc.getObjectRef() == "MyObject")
        console.log("The doc " + doc.getId() + " from object " + doc.getObjectRef() + " has been downloaded by " + g.getLogin());
};