...

Helper tools are tools that are designed to handle some smaller and common part of user interface that is found in many other tools. Examples include attachment choosers, options editors, and permissions editors.

Tools that want a helper tool to handle a particular request find the helper tool from the ActiveTool registry. They place information for the helper into the ToolSession, which is shared between the client and the helper. Then they invoke the helper tool with the ActiveTool's help() method.

A Tool can map the helper to a part of the tool's URL space. While requests come in to that space, the Tool can invoke the helper to handle the requests.

When a tool invokes a helper, the current tool PlacementId and ToolSession remain the same, that of the client tool. The client tool and the helper tool use the ToolSession to communicate. Before invoking the helper, the client places certain attributes into the ToolSession. During and after processing of the helper tool, the client can read other attributes from the ToolSession to get information back from the helper. The attributes understood by each helper are determined by each helper and documented with the tool code.
(Sakai Tools, Glenn Golden, p. 7)

Helper Lifecycle

Starting a Helper

Routing through the external tool's workflow is accomplished by registering a couple of variables in the user's ToolSession for the currently focused tool. This happens in the ToolServlet.startHelper method.

...