IM Developer Guide – View Extension

About this guide

This document gives an overview of the installation of PhenixID Identity Manager. Additional information is found on PhenixID web site or through PhenixID support.

Summary

This document explains View extensions in PhenixID Identity Manager. It is assumed reader is familiar with both the Identity Manager and Identity Manager Configurator. The document is a part of a collection of documents explaining how to extend and customize Identity Manager. In addition there is also Javadoc and sample code.

Mentioning of abstract base class assumes these are used when developing custom code.
First time readers are recommended to read overview document, IM Developer Overview.

Definition

Write your own view to add anything you like to the standard functionalities of the PhenixID Identity Manager (IM).

Requirements

IM is written in Java and any extension, including view extensions, must be written in Java.

The current IM version requires Java 1.8.

Tomcat has been used for testing the view mechanism but any web container supported by IM may be used.

Views where the presentation layer is coded with HTML or in a Java Server Page (JSP) are most common, but anything that Tomcat can render may be used.

Configuration and installation of a view

A view consists of a java component and a presentation component.

In its simplest form, a view consists of a Java class file and a JSP file, but if you want the view to make any asynchronous HTTP POST request to the backend, two Java class files are needed.

This guide assumes that the view java code is packaged in a jar file, which is recommended, but class files can be used as well.

Configuration

Configuration is done by adding the view to the policy LOAD_VIEW in the file DSEditor.properties.

LOAD_VIEW=mypackage.MyView

IM Web Edition

To run a view, the web container (IM Web Edition) must have access to both the java component and the HTML/JSP presentation code.

This is done by copying the jar file containing the java component into the customer/extension/lib directory.

The presentation component must be placed in such a way that IM can find it, for example: customer/extension/web/jsp/myView.jsp.

Note: To re-start Tomcat is required.

To Develop a View

A view consists of at least two components:

• An instance of a java interface that is the main handle to the view.
• A presentation component providing the visual part, often a jsp file.

The presentation component

IM will tell the web container to render the content of the presentation component within a DIV-tag that represents this views pane. Thus the presentation can be anything that the web container can render. Usually, a JSP or an HTML page but other web technologies may work as well.

For the purpose of demonstrating this mechanism a JSP page will be used.

If the frontend page wants to send a request to the backend for the view, this can be done by asynchronous HTTP POST requests. In the example below, dojo is used for this.

var kw = {
    url:    "nelinkcontrol",
    headers: {"Content-Type":"application/x-www-form-urlencoded; charset=utf-8" },
    content:{
        action:"myPackage.MyViewProvider",
        myParam:"AnyData"
    },
    handleAs: 'text',
    sync: false,
    load:    function(response, ioArgs) {
        // Do something with the response
    },
    error: function(response,ioArgs){
        // Handle the error
    }
};
dojo.xhrPost(kw);

In the content, the parameter ‘action’ should have the value of the class that you want to handle the request in the backend. Besides the parameter ‘action’, any parameter that you want to send to the backend can be added.

The java view component

The Java component is the interface that IM will use to decide which views that should be visible for the user.

The base class providing this interface is se.nordicedge.view.ViewBase. It is strongly recommended to use this base class, and it provides the following members access to subclasses.

public HttpServletRequest request;
public NEIDMgmtSession userSession;

The request is the current http context for the view.

The userSession object is the current IM context.

The base class provides a number of public member methods that can be overridden by the component. The mandatory ones are described here.

Methods

public boolean isSelected();

Return true if this view is to be selected at login, else false.

public String getLabel()

The name of the view that will be visible for the user.

To make the label multi language translational, use this example:

@Override
public String getLabel() {
    return MultiLanguage.getString(userSession,"My view");
}

public String getOnClickAction()

The javascript to run when the view gets focus. Usually this example can be used:

@Override
public String getOnClickAction() {
    return setContainerContentURI(getViewURI());
}

public String getViewURI()

The URI to the web page to show. Typically a .jsp file.

public boolean isLegacyView()

Return false, since this is not one of the standard views provided with IM.

The java backend component

If the view wants to send requests to the backend, a second java class is needed. This class should extend the class se.nordicedge.servlets.actions.ActionProcessorBase.

The base class provides a number of public member methods that can be overridden by the component.

public void execute(HttpServletRequest request, HttpServletResponse response)

The method that will be called when a request comes from the frontend.

From the HttpServletRequest, any parameters that where sent from the frontend can be fetched.

String param = request.getParameter("myParam");

Any data that should be sent back to frontend should be sent in the HttpServletResponse. A method called writeToResponse in the base class can be used to send any string information back to frontend.

writeToResponse(response, "Data to frontend");

To send an 400 error to the frontend, the method writeErroToResponse in the base class can be used.

writeErroToResponse(response, "Error message");

Sample application

An example of a view can be found in the sample code.