What is Assisted Configuration?
When a designer adds a proxy tool to a course, the standard settings page appears so that she can assign values to the proxy tool's settings. This is probably fine for most proxy tools, but what if you need to do something different when the proxy tool is added?
For example:
- Instead of the designer entering the setting values, you want the proxy tool to get its values automatically by sending an HTTP request to a server script on the Internet.
- You want to provide an alternative user interface for configuring the proxy tool's settings. Maybe you want to configure a geographical setting, like a country/province/state/city setting in your proxy tool. Wouldn't it be nice if you could display an image map so the designer just needs to click on an area to set the value?
This is where assisted configuration (or assisted config) can come in handy. Assisted config lets you send an outbound request to your authentication module during the proxy tool's initial configuration. Your auth mod can then redirect to an external application or dynamically generate HTML to display to the user.
The external app or web page then sends a request back to the auth mod (or another auth mod) containing the setting values you want to assign to the proxy tool.
NOTE: assisted configuration is a one-time operation; once the assisted config proxy tool's settings are set, they cannot be changed.
How Does It Work?
When a designer adds an assisted config proxy tool to a course, the settings page appears as usual, but it only contains the title setting and a button. When the designer clicks the button, assisted config begins.
The authentication module handles assisted config requests similar to other outbound (proxy tool) requests. The difference is the assisted config request is assigned a unique ID (GUID). The auth mod includes the GUID as a parameter when it sends the request to the external application. The external app does whatever it needs to do to get the values and sends the GUID and values back to the auth mod. The auth mod uses the GUID to find the proxy tool that sent the config request and assigns the values to the proxy tool's settings.
How Do I Do It?
First you need to add assisted config settings to your DeployableComponentConfig.xml file:
<\!-\- Required Settings for Assisted Configuration \-->
<setting-element name="assistedConfig"
label="Assisted Config"
data-type="Boolean"
presentation-type="RadioGroup"
inheritable="true"
optional="false"
read-only="false">
<setting-value key="true" default="false" label="true"/>
<setting-value key="false" default="true" label="false"/>
</setting-element>
<setting-element name="assistedConfigButtonName"
label="Assisted Config Button Name"
data-type="String"
presentation-type="TextField"
inheritable="true"
optional="true"
read-only="false"
default-value="Set My Setting">
</setting-element>
The first setting allows the administrator to enable/disable assisted configuration. When it is set to false, the proxy tool behaves like a normal proxy tool (the settings are displayed in a normal settings page). The second setting defines the button that will appear when assisted config is enabled.
Also, if you are using the same auth mod for both the outbound requests and the inbound request containing the proxy tool values, you must also set the mode as dual (to handle incoming and outgoing requests):
<setting-element name="mode"
label="security.authNModule.mode"
data-type="String"
presentation-type="ComboBox"
inheritable="true"
optional="false"
read-only="false">
<setting-value key="incoming" default="false" label="security.authNModule.mode.incoming" />
<setting-value key="outgoing" default="false" label="security.authNModule.mode.outgoing" />
<setting-value key="both" default="true" label="security.authNModule.mode.both" />
</setting-element>
Next, you need to add code to your auth mod to handle the assisted config request. Your auth mod will need to handle both regular proxy tool requests (when students click the proxy tool link) and the assisted config request (when the designer adds it to the course). How do you tell when it is assisted config? Check for the GUID. When getGUID() returns null, it is a regular proxy tool requests. When it contains a value, it is assisted config.
The GUID is the identifier of the proxy tool that is being configured. When you send the request to get the values, you must include the GUID. So the code in the commit() method might look similar to this:
if(super.getCurrentMode().equals(super.OUTGOING_MODE))
{
String guid = super.getGUID();
if(guid\!=null)
{
String user = super.getUserId();
String returnUrl = super.getSSOUrl(this.getSettingsGroupName(), null);
Map params = new HashMap();
params.put(ProcessCallback.PROXY_TOOL_CALLBACK_GUID, guid);
params.put("user", user);
params.put("returnUrl", returnUrl); super.setResponseContent(this.getCustomSettingsForm(params));
commitSucceeded = true; }
else
{
super.setResponseContent(this.getResponseString());
commitSucceeded = true; }
}
In this case, a custom HTML form is displayed to the user. When the user sets the values and clicks the form's Submit button, the request is sent back to this auth mod. The incoming request contains the GUID and the proxy tool setting values. The auth mod calls the setProxyToolConfiguredValues() method to find the proxy tool and set it's values. The code in the commit() method might be similar to this:
else if(super.getCurrentMode().equals(super.INCOMING_MODE))
{
String mySetting = _request.getParameter("mySetting");
HashMap settings = new HashMap();
settings.put("mySetting", mySetting);
super.setUserId(_user);
super.setProxyToolConfiguredValues(_guid, settings);
commitSucceeded = true;
}
The values are put in a HashMap?. The key of each value must match the proxy tool setting name.
NOTE: The GUID is not a permanent identifier. It only exists during the assisted config operation.
If you want to see how this example works, download the authentication module jar and the source code.
 | This article originally authored by Paul Monk on the WebCT DevNet
|
This page
Other pages
Account
