Configuration Workflow

If you develop a web application intended to be downloaded and installed by users, most probaly you'll have to provide some tools for that the users can configure the application they installed. For example, if the web application stores data in a database, the users have to configure the access to the database.

The Ripla plattform provides the possibility to create a configuration workflow that runs the first time the user invokes the installed application. This offeres an easy approach for initial application configuration.

To install a configuration workflow, you have to override the method RiplaApplication.beforeLogin(). In this method, you can initiate the workflow, e.g.:

protected boolean beforeLogin(final Window inMain, final IWorkflowListener inWorkflowListener) {
    try {
        MyWorkflow.createWorkflow(inMain, inWorkflowListener).startWorkflow();
    }
    catch (final WorkflowException exc) {
        LOG.error("Error encountered during application configuration!", exc);
    }
    return false;
}

Note the workflow listener instance passed to the worklow.

public interface IWorkflowListener {
    void workflowExit(int inReturnCode, String inMessage);
}

The listener instance in this case is RiplaApplication. You, therefore, have to override the callback method RiplaApplication.workflowExit():

public void workflowExit(int inReturnCode, String inMessage) {
    switch (inReturnCode) {
    case 1: // OK
        setMainWindow(getLoginView());
        break;
    default:
        getMainWindow().showNotification(inMessage);
    }
}

The workflow class could look as follows:

private static class MyWorkflow {
    private IWorkflowItem workflowItem;
    private IWorkflowListener workflowListener;
 
    private MyWorkflow(final IWorkflowItem inWorklowItem,
            final IWorkflowListener inListener) {
        workflowItem = inWorklowItem;
        workflowListener = inListener;
    }
 
    public void startWorkflow() throws WorkflowException {
        workflowItem.run(this);
    }
 
    public int getReturnCode() {
        return workflowItem.getReturnCode();
    }
 
    protected void nextStep() {
        try {
            if (workflowItem.hasNextStep()) {
                workflowItem = workflowItem.getNextStep();
                workflowItem.run(this);
            } else {
                workflowListener.workflowExit(workflowItem.getReturnCode(), "");
            }
        }
        catch (final WorkflowException exc) {
            workflowListener.workflowExit(-1, workflowItem.getErrorMessage());
        }
    }
 
    public static MyWorkflow createWorkflow(final Window inWindow, final IWorkflowListener inListener) {
        // instantiate the workflow steps we need
        final IWorkflowItem step1 = new WorkflowStep1(inWindow);
        final IWorkflowItem step2 = new WorkflowStep2();
        final IWorkflowItem step3 = new WorkflowStep3();
 
        // wire the workflow steps
        step1.registerSuccessItem(step2);
 
        step2.registerSuccessItem(step3);
        step2.registerFailureItem(step1);
 
        final MyWorkflow workflow = new MyWorkflow(step1, inListener);
        return workflow;
    }
}

The workflow configuration is done in the factory method MyWorkflow.createWorkflow(). This example consists of three workflow steps. Each step implements the interface IWorkflowItem:

public interface IWorkflowItem {
    void run(MyWorkflow inWorkflow) throws WorkflowException;
    boolean hasNextStep();
    IWorkflowItem getNextStep();
    void registerSuccessItem(IWorkflowItem inItem);
    void registerFailureItem(IWorkflowItem inItem);
    int getReturnCode();
    String getErrorMessage();
}

With the workflow controller MyWorkflow and the workflow steps set up, the workflow is startet by MyWorkflow.createWorkflow(inMain, inWorkflowListener).startWorkflow(). This runs the first workflow step which will display e.g. a form where the user can enter some configuration information. When the user clicks the form's save button, the workflow controller's nextStep() method is called which looks up the next workflow item and, if available, runs it by calling its IWorkflowItem.run() method. This sequence will be iterated for any configured workflow step.