To plug in to the managed settings framework, the back-end management system that populates the Eclipse preference store with the settings for the application must have a corresponding managed settings provider.
A managed settings provider is a plug-in that knows how to pull settings from an associated back-end management system and format them appropriately for the framework to read them. Lotus
® Expeditor Client provides providers for settings specified by the Portal Policy Manager and for settings that are specified in XML files. If your application gets its preference settings from a back-end system other than WebSphere
® Portal or an XML file, you can create a custom provider for it. See Adding a managed settings provider
You must configure the file provider associated with settings specified in XML files. For details, see Configuring the XML file provider .
You do not need to configure the provider for the Portal Policy Manager, which is the back-end administrative system used by the WebSphere
Portal-administered client. Instead, you must create an account that identifies the WebSphere
Portal Server and stores authentication information for connecting to it. See Managing accounts
for more information.
Configuring the XML file provider
The XML file provider is responsible for getting the preference settings from an XML file. The file provider needs to have an XML file containing the managed setting data and must know the location of that XML file.
To configure the file provider:
- Format the XML file as follows:
Set the initial location of the XML file in the plugin_customization.ini file using a key of com.ibm.rcp.managedsettings.provider.file/URL.
- It must contain a <ManagedSettings> element that contains one or more <settingGroup> elements. Each <settingGroup> element must contain one or more <setting> elements.
- Each <settingGroup> tag must have the following attributes:
- name – Use the same name as the qualifier (typically the plug-in name, but it can be anything) that its settings are associated with.
- lastModDate – Specify the date using the java.text.SimpleDateFormat format. The syntax is YYYYMMDDThhmmssZ, where YYYY=year, MM=month, DD=day, hh=hours, mm=minutes, ss=seconds. The values to the right of the T are optional.
- Every change to a setting group must be accompanied by a change to the lastModDate attribute, or the new values are not updated. If no lastModDate is specified, the values are always updated, even if they are not new.
- Each <setting> tag must have the following attributes:
- name – Use a name that identifies what the setting does.
- value – Provide a default value for the setting.
- Each <setting> tag might also have the following attributes:
- isLocked – Boolean. The default value is true. If true, the setting is read-only and any changes that a user or application makes to the value set by you, the administrator, are prevented or later overwritten. If this attribute is set to false, the administrator setting is treated as a default value that can be changed.
- overwriteUnlocked - Boolean. The default value is false. By default, a setting that is specified as being unlocked is treated as a default and does not overwrite any existing value on the client. This approach avoids undoing changes that the user might have legitimately made. If this setting is set to true, however, the unlocked value is overwritten with this new value even if it means clearing the existing value of the user.
- For example:
<settingGroup name="com.ibm.workplace.mail.policy" lastModDate="20060131">
<setting name="alwaysEncryptEmail" value="true" isLocked="true"/>
<setting name="saveCopyinSentFolder" value="false" isLocked="false"/>
<settingGroup name="desktop_settings" lastModDate="20060131">
<setting name="logOffAfter" value="30" isLocked="true"/>
<setting name="autoSaveAfterNMinutes" value="5" isLocked="true"/>
- See the com.ibm.rcp.managedsetttings.provider.file plug-in to see the schema.
If you would like to later change the URL for the file provider, you can update the existing XML file to add a new setting group of com.ibm.rcp.managedsettings.provider.file and a setting of URL. The next update runs on the existing URL, but the update after that runs with the new URL. If the new URL is unreachable at the time of the update that is setting it, it is not saved and the original URL continues to be used. The URL is not changed until it is updated at a time that the URL is reachable.
You can update the plugin_customization.ini file in the desktop/deploy/ directory on a CD-structure or the one provided with the download applet or portlet using the instructions provided with it.
If the XML file is being hosted by an HTTP server on which authentication has been enabled and there is no associated account set up for the server, the user is prompted for a name and password the first time that the provider runs. Because the provider runs in the background, the user is likely to be confused by this display. You can prevent the authentication prompt from displaying by including code in the application that creates an account for this URL during its setup. See Managing accounts
for more information.
During communication with the portal, the default policy provider assumes that the portal is configured with the default custom directory. When retrieving updates for the specified user, the default provider uses the default dn
(Distinguished Name) suffix for the default directory.
If the portal is configured with a different user directory, however, the default dn
might not work. To provide a directory-specific dn
suffix, you can update the plugin_customization.ini file using a key of com.ibm.rcp.managedsettings.provider.portal/dnSuffix
Managed settings allow for the simultaneous use of more than one provider.
For instance, you could specify the setting values for one plug-in in the Portal Policy Manager and for another in the XML file provider. The potential exists, though, that the same setting group or qualifier can be defined on both the Portal Policy Manager and in the XML File. This approach is highly discouraged, both because of the ambiguity and for efficiency reasons. If you determine that this approach is happening, fix it as soon as possible. To handle this situation, framework forces the results to be deterministic by using the weight of the provider to determine which setting value is applied. The lowest weight wins. You can determine the default weight of the providers by looking in the ManagedSettingProvider extension point in their plugin.xml files. The default weight of the file provider is set to 300. The default weight of the Portal provider is 200. If necessary, you can change the weight by creating a managed setting for it, using a qualifier of com.ibm.rcp.managedsettings and a setting name of <provider_id (typically plug-in ID)>-weight
Parent topic: Configuring managed settings