A helper within SiteAction is actually a diversion to an external Tool implementation. Handling of helpers takes place in the org.sakaiproject.cheftool.ToolServlet class, which is a superclass of SiteAction. Examples of its use are available in other legacy CHEF tools.

See:
AnnouncementAction
AssignmentAction
CalendarAction
ChatAction
DiscussionAction
MailboxAction
ResourcesAction

Existing Helper Documentation

Helper Client

Helper clients act like dispatchers (or even aggregators). They recognize parts of their request space (certain modes, for instance) that can be handled by some helper tool. The helper tool is found from the registry and invoked to handle the response while in this mode. Information is shared between the two tools in the tool placement scoped ToolSession.
(Sakai Tools, Glenn Golden, p. 5)

Helper Tool

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.

protected void startHelper(HttpServletRequest req, String helperId, String panel)

//calls the above method with panel=ToolServlet.MAIN_PANEL
protected void startHelper(HttpServletRequest req, String helperId)

This method sets the following items in the ToolSession:

Next any parameters that need to be passed to the Helper tool can be added to the SessionState via SessionState.setAttribute(String name, String value). Other tool packages often contain an interface that defines static final Strings for each of the parameters the tool expects to find in the SessionState. For example, the Sakai authorization API contains a PermissionHelper that defines the following:

	/** Set this tool state attribute with the prefix for the permission functions to consider for editing (i.e. "content.") */
	static final String PREFIX = "sakaiproject.permissions.prefix";

	/** Set this tool state attribute with descriptive text for the editor. */
	static final String DESCRIPTION = "sakaiproject.permissions.description";

	/** Set this tool state attribute to the entity reference of the entity whose AuthzGroup is to be edited. */
	static final String TARGET_REF = "sakaiproject.permissions.targetRef";

	/** Set this tool state attribute to the entity reference of the entity which controls the role definitions, if different than the target_ref (leave it unset if target_ref has the roles needed). */
	static final String ROLES_REF = "sakaiproject.permissions.rolesRef";

These are set in the SessionState by SiteAction immediately after startHelper is called.

Processing Helper Actions

Every request that is processed by a ToolServlet undergoes two helper-related checks. First, a check is made for the <ToolServlet.HELPER_ID + <panel>> CGI parameter. If it is present it is assumed that the helper is finished (no check is made to see if the parameter is set to 'done'). If so the helper ID attribute is removed from ToolSession

Ending a Helper