 |
by
James
Nevins
Level: All
Works with: QuickPlace, Domino Off-Line Services
Updated: 01/02/2003
Inside this article:
Troubleshooting
The developer's experience
The end user's experience
Related links:
Going (Quick)Places with Charlie Hill
Ten things you need to know about deploying QuickPlace 3.0
Selectively replicating DOLS subscriptions: One customer's story
QuickPlace documentation
Domino Administrator Help
Get the PDF:
 (411 KB)
|
 |
With QuickPlace 3, not only is it integrated with Sametime, it's also integrated with Domino Off-Line Services (DOLS). Now a QuickPlace user can install and use DOLS for offline services. Mobile QuickPlace users can receive Sametime scheduled online meeting email notices from their QuickPlace with their Lotus iNotes Web Access client (while offline using DOLS). QuickPlace 3 and DOLS integration means that QuickPlace users can work with other offline Web applications like Lotus iNotes Web Access, which can receive scheduled online Sametime meeting email notices.
This article describes how to integrate QuickPlace 3 and DOLS from the perspective of the administrator, application developer, and end user. For administrators, it covers enabling DOLS on the QuickPlace server, creating a DOLS security policy for users authenticated by an external LDAP directory, and creating a QuickPlace offline CD. For developers, it covers setting up Placebots for offline use with DOLS. And for end users, it covers setting up Member records, installing an offline copy of a QuickPlace on a client, using iNotes Sync Manager, and working with a QuickPlace and other DOLS-enabled applications, such as iNotes Web Access.
This article assumes familiarity with QuickPlace and Domino Off-Line Services. It also assumes knowledge of Domino Web server features, such as passthru server.
The administrator's experience
As the QuickPlace administrator, your primary responsibility is DOLS-enabling QuickPlaces by configuring DOLS on the QuickPlace/Domino server. After you enable DOLS on your QuickPlace server, your other tasks may include:
- Setting up QuickPlace 3 servers for the types of configurations/environments that DOLS will be used in
- Setting up the DOLS Security Policy documents for users
- Moving Places
- Turning off DOLS during server maintenance
- Creating a QuickPlace 3.0 Offline CD
- Troubleshooting QuickPlace/DOLS issues
Enabling DOLS on the QuickPlace 3/Domino 5.0.10 server
As the QuickPlace administrator, the first thing that you must do to DOLS-enable your QuickPlaces is to set up DOLS on the Domino server. QuickPlace 2.x and earlier releases used their own version of an offline server, but QuickPlace 3 uses DOLS to enable users to take a Place offline. To DOLS-enable your QuickPlaces, you must install the QuickPlace server on a Domino 5.0.10 server—a configuration referred to as an overlay. In addition, you must install the Domino 5.0.10 CF1 fixpack on the Domino server because it includes several important fixes for DOLS.
To enable DOLS, select the DOLS option during first time Domino server setup. For more information about setting up the Domino server, see the Domino Administrator Help. If you're upgrading the Domino server and you did not enable DOLS during the initial install/setup of the Domino server, you can still enable DOLS. If the Domino server is on a Win32 operating system, then enter ndolextn in the DSAPI filter file names field in the Internet Protocols - HTTP tab of the Server document. If the Domino server is on a UNIX operating system—AIX or Solaris—then enter libdolextn in this field. If the Domino server is on an iSeries system, then enter libdolextn.srvpgm in this field. If the server is on a zSeries system, then enter dolextn in this field.
After enabling DOLS, set up the QuickPlace Extension Manager. Put the following setting in the Domino server Notes.ini file according to your platform:
| Platform | Setting |
| Win32 | EXTMGR_ADDINS=nqpextmgr.dll |
| AIX | EXTMGR_ADDINS=libqpextmgr_r.a |
| Solaris | EXTMGR_ADDINS=libqpextmgr.so |
| iSeries | EXTMGR_ADDINS=qpexmgr |
| zSeries | EXTMGR_ADDINS=libqpexmgr |
Setting up QuickPlace 3 servers for the types of configurations/environments that DOLS will be used in
If you've set up QuickPlace 3 to work with IBM Network Dispatcher, Sun ONE Portal Server (formerly iPlanet Portal Server), a passthru server, or an alternate download Web site, then you need to complete additional steps to configure your QuickPlace servers to work properly. The following sections describe the steps that you need to take.
If you are not using Network Dispatcher, Sun ONE Portal server, a passthru server, or an alternative download Web site for downloading DOLS, you can skip the following sections and continue with the section "Setting up the DOLS Security Policy documents for users."
QuickPlace/DOLS cluster with IBM Network Dispatcher 3.6
A QuickPlace 3 cluster typically contains two to six servers. End users use the URL of the Network Dispatcher (which sends pages back from one of the QuickPlace servers in the cluster) to access the QuickPlace servers. For DOLS to work in this configuration, each server in the cluster must have the following Notes.ini setting:
$DOLS_TCPIPAddress=serverhostname.yourcompany.com or the IP address
Where serverhostname.yourcompany.com is the name of one "real" (not virtual) server in your cluster. You can also use the server IP address. This Notes.ini setting must be set on all servers in your cluster. For example, if the Network Dispatcher (the virtual server) is named http://colors.acme.com and the QuickPlace servers in the cluster are named http://blue.acme.com, http://red.acme.com, and http://white.acme.com, then you can add the following to the Notes.ini file of each of the three QuickPlace 3 servers for DOLS to work in this setup:
$DOLS_TCPIPAddress=blue.acme.com
Alternatively, you can use the TCPIP address of blue.acme.com.
QuickPlace/DOLS with Sun ONE Portal server
The Sun ONE Portal server serves as a reverse proxy server to handle inbound requests. When QuickPlace 3 is used with a Sun ONE Portal server, you must set up the server's Notes.ini file with the following setting:
NoWebFileSystemACLS=1
Without this setting, the end user is prompted to reauthenticate during the DOLS download stage.
QuickPlace/DOLS with a passthru server
To use a passthru server between the offline Place and your QuickPlace 3 server, you must do the following in the QuickPlace administration area of your server:
- In your QuickPlace, sign in as QP Administrator, and then click Server Settings in the sidebar.
- Click Other Options on the sidebar.
- Click the Edit Options button that appears.
- Complete the following fields, and then save the page:
QuickPlace/DOLS and alternate download Web site
If you want users to download DOLS from another site, you can specify an alternate download Web site. To use an alternate download Web site for the download of DOLS, you must enter a setting in the QuickPlace server's administration area:
- In your QuickPlace, sign in as the QP Administrator, and then click Server Settings in the sidebar.
- Click Other Options on the sidebar.
- Click the Edit Options button that appears at the top of the page.
- Complete the following field, and then save the page:
Setting up the DOLS Security Policy document(s) for users
For DOLS to work, the DOLADMIN.NSF must be set up with Security Policy document(s) for each type of user who will install offline from your QuickPlace 3 server. QuickPlace 3 with DOLS supports two types of users:
- External users who are added as members via LDAP
- Local users who are added as members, but who only exist in this one Place to which you add them
The following sections describe how to set up DOLS for external and local users.
Setting up DOLS for external users
In QuickPlace 2.x and earlier, all users—external and local—were scoped to one Place. Now with QuickPlace 3, they are scoped to as many Places as they are members of. However, local users remain scoped to one Place. Follow these steps for setting up external users:
- Create a hierarchical cert.id, if you do not have one already. For example, let's use a hierarchical cert.id that was created for the Acme Marketing department. This cert ID has the hierarchy /Marketing/ACME.
- In the DOLADMIN.NSF create a New Security Policy document and enter the domain in the Security Domain field. In our example, we enter /Marketing/ACME.
- Choose the Automatically generate user IDs option.
- On the Automatic tab, attach your Marketing.ID to the Certifier ID to use field and enter the ID's password in the Password for certifier ID field.
Note: If you haven't used a Domino Administrator client before, go to the updated QuickPlace Install/Upgrade Guide. There you will find detailed steps to guide you through the use of the Domino Administrator client in using, creating, or setting up the Certifier IDs in the DOLS Security Policy document(s).
Setting up DOLS for local users
The process for setting up DOLS for local users is similar to the process for setting up DOLS for external users. If your Place includes both external and local users, then you need to create two Security Policy documents: one for your external users and one for your local users. Follow these steps for creating a Security Policy document for your local users:
- Create a QuickPlace Certifier ID (QP.ID). Do this from the Domino Administrator client and use your server domain cert.id to create a QuickPlace org unit (OU) cert ID file. Your cert.id is /QP/YourOrganization, for example, we use /QP/Acme.
- In the DOLADMIN.NSF create a New Security Policy document and enter your domain in the Security Domain field.
- Choose the Automatically generate user IDs option.
- On the Automatic tab, attach your QP.ID to the Certifier ID to use field and enter the ID's password in the Password for certifier ID field.
Note: DOLS does not support users who are added via external groups. DOLS requires that users be explicit members of a Place. Members of an external group are implicit members. DOLS also requires Room Security to be set up with explicit members and not with external groups. If Room Security for a Place is setup with external groups, then DOLS does not allow the user to enter a room while offline.
Moving Places
We know what you're going to say: "If I move a Place from one QuickPlace server to another QuickPlace server, I am going to have to manually reset the DOLS profile document after I've moved the Place." But for QuickPlace 3 the nifty developers of the QuickPlace team have created a qptool program that programmatically deletes the profile document for you (as well as several other items) after you've moved a Place. The next time you install a Place offline from this moved Place, the profile document for your Place is automatically set up for you.
Moving a Place is optional. If you want to move a Place from one QuickPlace 3 server to another, here are the steps you need to take. Note that unlike earlier versions of QuickPlace, you do not need to shutdown the QuickPlace 3 servers to move a Place.
- At the file system level, copy the directory of the Place you want to move from your QuickPlace (source) server to the QuickPlace (destination) server.
- After the Place directory copy has completed, start the destination QuickPlace server, and then go to the destination QuickPlace server console and enter:
load qptool register -install -p placename
Wait for the qptool to complete running and voila! Your Place is ready to be used again both online and offline, though you do have to have your users reinstall offline to their clients because your Place is now located on a different server.
Turning off DOLS during server maintenance
There may be instances in which you need to turn off DOLS, for example server maintenance. To turn off DOLS, you don't need to disable DOLS, you only need to hide the Work Offline link from your users. To hide this link in the Places on your QuickPlace server, add the following setting to your QuickPlace server's QPCONFIG.XML file and then restart your server:
<!--
Offline
=======
All offline related settings
attribute | value | default | description
enabled | true | yes | enables the offline feature
false | no | disables the offline feature
-->
<offline enabled="false"/>
Creating a QuickPlace 3 offline CD
If you have users who connect to your QuickPlace over a slow low bandwidth connection, it takes these users a long time to complete the initial download of the DOLS offline components. To speed up this download process for these users, you need to create a QuickPlace offline CD. In QuickPlace 3 (unlike previous versions) you can create your own QuickPlace offline CD by following these steps:
- Download a copy of the DOLS R5.0.10 CF1 Pre-Installer from a Lotus Software distribution Web site.
- Create two directories on the CD:
- A /DOLS directory where you put the R5.0.10 CF1 DOLS Pre-Installer file
- A /QP directory
- Copy the following files from the QuickPlace server's data directory to the /QP directory on the CD.
- <data directory>\domino\html\download\filesets\n_QuickPlace.exe
- <data directory>\domino\html\download\filesets\n_QuickPlace.inf
- Burn the CD-ROM and distribute it to your low bandwidth users.
Instruct users to do the following to use the QuickPlace 3 offline CD:
- Run the DOLS Pre-Installer from the /DOLS directory on the CD.
- Copy the two QuickPlace files from the /QP directory on the CD to the DOLS Pre-Installer directory on the local client.
- Open a Web browser and enter the URL of the Place that they initially want to install QuickPlace 3 offline from and then initiate the install. The install will skip over the download step, and the Place will be setup offline automatically on their client.
After first time sync is completed, users can use the Place offline on their client.
Note: Macintosh users and anonymous users cannot install DOLS.
Troubleshooting
There are several tools that can assist you in debugging offline problems. To troubleshoot problems on the server, do the following:
- Check the server console for errors when the user tried to install offline.
- Check the server log. Look in the Miscellaneous view for errors.
To troubleshoot problems on the client, do the following:
- If it's a sync issue, check the Dol.log file that gets created on the client's file system. Make sure that the Dol.log is collected after the user has a sync error.
- Check the last sync status message by clicking the subscription in the iNotes Sync Manager offline and choosing properties.
- Check the Miscellaneous view in the offline log.nsf using the URL when the user is signed in to offline: http://127.0.0.1:89/log.nsf.
Common errors
The following table lists some of the most common problems that can occur with offline usage, and actions you can take to correct these problems.
| Problem | Solution |
| External/local Authors and Readers are unable to sign in to offline. | You may have forgotten to put EXTMGR_ADDINS=nqpextmgr.dll in the QuickPlace server's Notes.ini. If this variable was added as the last line of the Notes.ini, make sure that you press ENTER after entering the line, and then save the Notes.ini file. |
| User is unable to sign in to offline. | Make sure that the user has added an offline password to her Member record. |
| User never sees the Download control appear. | If the user is using Microsoft Internet Explorer, then the most likely cause is that ActiveX support is turned off. If the user is using Netscape, then he needs to install the plug-in. The user should follow the directions that appear when the user clicks on the Work Offline link that details how to install offline. |
| User is unable to complete first time sync on a cluster. | Make sure to add:
$DOLS_TCPIPAddress= ...
to the server's Notes.ini file. |
| User installing offline via Sun ONE is prompted to reauthenticate. | Make sure that the QuickPlace server has the following Notes.ini setting:
NoWebFileSystemACLS=1 |
| A Placebot does not run offline. | Make sure the Placebot is not a scheduled agent. DOLS does not support scheduled agents. Check that the two groups (DOLS_Restricted_Agents and DOLS_Unrestricted_Agents) that were setup for DOLS and are set correctly and make sure that their security settings are correct. |
| User can't enter a room when offline. | Make sure that the user is explicitly listed in the Room Security because external groups are not supported in offline. |
| Users have problems installing and receive an ERROR 500 -- problems downloading Offline Configuration data. | Check the server document and verify that the ndolextn on Win32 (or libdolextn on UNIX) is correctly entered in the DSAPI filter field. |
| Users cannot send email to external groups. | Sending email to external groups when offline is not supported. |
| User has a problem installing offline after having installed from the offline CD. | Check that the user copied the two QuickPlace files (n_QuickPlace.exe and n_QuickPlace.inf) from the offline CD to the correct directory, namely: <data directory>\domino\html\download\filesets on the local client. |
The developer's experience
The developer's experience with regard to QuickPlace 3 and DOLS is limited to the setup of Placebots for offline (DOLS) use. For any QuickPlace that uses Placebots (whether restricted or unrestricted), the Place developer needs to set up the Placebots for offline use with DOLS. Follow these steps to set up your Placebots:
- Create two groups in your Domino Directory named DOLS_Restricted_Agents and DOLS_Unrestricted_Agents.
- As members of this group, add the names of users who are the agents signers. Agents signers are users who are allowed to make design element changes in the databases (QuickPlace rooms), which include agents.
- Add these two groups (DOLS_Restricted_Agents and DOLS_Unrestricted_Agents) to the Agent Restriction section in the Server document.
- Edit the Server document and select the Security tab.
- In the Agent Restrictions section, add these groups to the fields Run restricted LotusScript/Java agents and Run Unrestricted LotusScript/Java Agents.
- Cross-certify your QuickPlace server's cert.id with the DOLCERT.ID that is located in your QuickPlace server's Domino Directory. Verify that the cross-certification was successful by going to the Certificates view in your Domino Directory and making sure there is a cross-certificate for /DOLSCERT.
You are now ready to run QuickPlace Placebots offline with DOLS.
Note: DOLS does not support scheduled agents.
The end user's experience
End users have a richer experience with QuickPlace 3 offline than they did with earlier QuickPlace offline offerings. To take a QuickPlace offline, users need to complete at least some of the following tasks:
- Setting the offline password in the Member record
- Installing QuickPlace 3 (DOLS) offline for the first time
- Using iNotes Sync Manager
- Installing QuickPlace 3 (DOLS) from the QuickPlace offline CD
- Installing QuickPlace 3 (DOLS) offline via Sun ONE Portal Server
- Setting offline security
- Setting up iNotes Sync Manager to use a proxy server
- Using DOLS with other applications
Setting the offline password in the Member record
You must edit your Member record and complete the offline password field before you can install offline. If you forget to set this password, you cannot sign in to the offline Place. To edit your Member record, follow these steps:
- Sign in to the QuickPlace that you want to take offline.
- Click Members.
- Select your Member record, then click Edit.
- Complete the Offline Password field, then click Done.
Installing QuickPlace 3 offline for the first time
To install the QuickPlace offline, follow these steps:
- Sign in to the Place that you want to install offline.
- Click the Work Offline link.
- Follow the directions on the Work Offline Web page.
- Click Begin Install.
The download control appears. When the download completes, the iNotes Sync Manager is launched. After the first time setup for the Place being taken offline completes, you're done! You can now work with your Place offline on your client.
You can also install DOLS from a QuickPlace pre-installer CD provided by your QuickPlace administrator. The following steps describe how to install the DOLS offline components from the CD:
- Run the DOLS Pre-Installer from the /DOLS directory on the CD.
- Copy the two QuickPlace files from the /QP directory on the CD to the DOLS Pre-Installer directory on the client.
- Open a Web browser and enter the URL of the Place that you want to install, and then click the Work Offline link on the sidebar to initiate the install. The install skips the download step, and the Place is setup offline on the client.
After you download and install DOLS for the first time, you will find that for future installs the download step is skipped, thus all subsequent installs happen a lot more quickly.
Using the iNotes Sync Manager
The iNotes Sync Manager is the offline control center for managing offline DOLS-enabled Web applications, including your offline QuickPlace and offline iNotes Web Access. The iNotes Sync Manager appears after the download control completes the download step and just before the first time setup of the offline Web application.
The iNotes Sync Manager is installed when you either initiate a first time install from a DOLS-enabled Web application or install from a DOLS pre-installer CD. The following screen shows the iNotes Sync Manager:
Installing QuickPlace 3 (DOLS) offline via Sun ONE Portal Server
If an end user installs a Place via Sun ONE Portal Server (a reverse proxy server), then she will use a URL like:
https://SunOne1.acme.com/http://yourQuickPlaceServerName.acme.com/YourPlace
Otherwise, the offline install is the same as from a server that is not behind a Sun ONE Portal Server. The user will log in to her Place, and then click Work Offline to initiate the offline install. After the offline Place is installed, the user can work offline.
Setting offline security
The iNotes Sync Manager has several security features useful for blocking spying eyes from seeing your offline applications, including the Master Password and the DOLS offline Synchronization Password. The Master Password, once set, blocks any user from launching the iNotes Sync Manager from your desktop and accessing it. To set the Master Password, follow these steps:
- Open the iNotes Sync Manager, and choose Options - Master Password.
- In the Set Master Password dialog box, enter your password twice, first in the New Password field and again in the Confirm Password field.
- Click OK to save the password.
If the offline Synchronization Password is deselected, users are prompted to enter a password each time synchronization of a particular subscription is initiated. You can deselect the Synchronization Password for a subscription. To do so, select the subscription you want to secure, click Properties, and in the Properties box deselect the Remember Password option. You will be prompted for the password before synchronization of the subscription will occur.
To restore the Synchronization Password, select the Remember Password option, and then enter the correct offline password in the associated field.
Setting up iNotes Sync Manager to use a proxy server
QuickPlace 3.0 and DOLS can be used with proxy server. If it is an authenticated proxy server, you can also set up a login name and password in iNotes Sync Manager to authenticate with your proxy server. To set up iNotes Sync Manager to use a proxy server, follow these steps:
- After installing the QuickPlace offline via a proxy requiring authentication, open the iNotes Sync Manager and choose Options - Proxy Settings.
- In the Proxy Settings dialog box, select the "Use a proxy server to synchronize" option.
- Complete the Address and Port fields, and then select either HTTP or SOCKS for the Type field.
- Enter your login name and password.
You are now ready to use QuickPlace 3.0 offline with your proxy server.
Using DOLS with other applications
Because QuickPlace 3 is integrated with DOLS, you can use other DOLS applications along with QuickPlace when working offline in DOLS. One of these Web applications could be iNotes Web Access. iNotes Web Access is a Web mail database that includes powerful calendar & scheduling capability. You can set your Member record to receive any calendar events in your iNotes Web Access client. Select the Yes option to Subscribe to calendar events, then select your calendar.
In addition, if your QuickPlace 3 server is Sametime enabled, you can schedule online Sametime meetings, and receive the email meeting notice in your offline iNotes Web Access client. See the following screen:
Conclusion
Taking a QuickPlace offline provides advantages to all users, not just your remote or mobile ones. With support for DOLS in QuickPlace 3, your users have a more robust experience when working offline. We hope this article helps you to get started using DOLS with your QuickPlace.
ABOUT THE AUTHOR
James Nevins has worked on several projects as a Staff Software Engineer (in a Quality Engineering role) while in IBM's Lotus Software Group, including QuickPlace, Notes C API, Domino Off-Line Services, Weblicator, Domino Intranet Starter Pack, and the Alpha RISC port of Notes R4.1. He has a B.S.E.E. from Northeastern University. His outside interests include long distance walking/hiking, swimming (he once was a New England Masters Swimmer), and reading about software while listening to a partially digital radio. |
|