Wednesday, February 29, 2012

Pentaho Admin/Enterprise Console in SUGAR

If you've grabbed a recent build of SUGAR you'll notice some obvious changes to the UI as well as a top-level directory structure which is totally missing. The "administration-console" (or "enterprise-console") folder has been removed. We are actively working to integrate PAC/PEC functionality in the Pentaho User Console as an Administration perspective.

The layout of the Administration perspective is defined in mantle.xul (pentaho/mantle/xul/mantle.xul). This will allow the possibility of changing the UI and/or removing UI elements. Presently, we have action-based security (ABS) and authentication (Pentaho/LDAP) implemented in this UI. In the upcoming weeks we'll be adding other missing parts from the admin console such as email/auditing.

Here's a recent screenshot of the Administration perspective:

How to Add New Admin Functionality

New functionality can be plugged into the admin perspective with a platform plugin. The plugin.xml of a platform plugin will have a XUL overlay section to add an item to the admin category tree. For example, if you want to add a new item to the "security" category you would do this to the plugin.xml:

<overlays>
    <overlay id="admin.perspective.overlay.ee" resourcebundle="content/my-admin/resources/messages/messages">
        <treechildren id="security">
            <treeitem command="mantleXulHandler.loadAdminContent('my-admin-panel', 'api/repos/myadmin/resources/my-admin.html')">
                <treerow>
                    <treecell label="${myadmin.label}" />
                </treerow>
            </treeitem>
        </treechildren>
    </overlay>
</overlays>

We are adding a new panel to the admin perspective with an ID of 'my-admin-panel' and we are specifying the location of the UI (by URL). At this point you have adding your content to the admin category tree. Just like any plugin, you can have back-end code in a JAR, eg my-admin/lib/my-admin-plugin.jar.
Even more interesting is the new capability of a platform plugin to easily register its REST services in the plugin.spring.xml. We're using Jersey (v1.12) for exposing these web services. For reference take a look at the echo-plugin.

Finishing the Job: JavaScript Integration

Whatever your choice of JavaScript library, you will be coexisting with PUC/admin perspective. While not required, you can improve the user experience by registering your UI for state changes, etc. To do this create an object with an id and activate/passivate methods. For example:

var myAdminPanel = {
    id : "my-admin-panel",
    activate : function() {
        refreshConfig();
    },
    passivate : function(passivateCompleteCallback) {
        if(isConfigDirty()) {
            passivateCallback = passivateCompleteCallback;
            dijit.byId("saveChangesDialog").show();
        } else {
            passivateCompleteCallback(true);
        }
    }
};

Now register this object with the admin perspective:
window.top.mantle_registerSysAdminPanel(myAdminPanel);

That's all there is too it, you will be notified when the user selects on/off of your panel so you can check for "dirty" and prompt for saving.

REST services

In order to support the new admin functionality added to PUC, we added several new REST services which might be generally useful to OEMs, integrators, and developers.

/pentaho/api/userrole/users
Using GET, will return a list of all users in the system.

/pentaho/api/userrole/roles
Using GET, will return a list of all runtime roles in the system.

/pentaho/api/userrole/roleAssignments
Using PUT, will set role bindings between roles and permissions (logical roles)

/pentaho/api/userrole/logicalRoleMap
Using GET, will return the list of roles and the permissions (logical roles) which are assigned to them

The following LDAP REST API calls are in the EE product

/pentaho/api/ldap/config/getAttributeValues
Using GET, returns all name/value pairs from applicationContext-security-ldap.properties, plus the current securityProvider

/pentaho/api/ldap/config/setAttributeValues
Using PUT, sets (merges) name/value pairs and saves them to applicationContext-security-ldap.properties as well as set the authentication type in pentaho-spring-beans.xml.

/pentaho/api/ldap/config/ldapTreeNodeChildren
Using GET, returns the list of

/pentaho/api/ldap/config/userTest
Using GET, simple test if a user can be found.

/pentaho/api/ldap/config/rolesTest
Using GET, tests if search for a user returns roleAttribute successfully.

/pentaho/api/ldap/config/userRolesTest
Using GET, will perform a populator test (check if granted authorities for the given user works)

/pentaho/api/ldap/config/providerTest