Table of Contents Previous Next Index

Section 11 Using the Web Administration Interface

Section 11 Using the Web Administration Interface
LISTSERV has a completely revamped Web Administration Interface, making LISTSERV administration significantly easier. It is now possible to change many LISTSERV site configuration settings "on the fly", although some changes may still require a restart of the server before they are recognized.
Most sites will be able to upgrade to LISTSERV without losing local web customizations, although this is not optimal and will not generally expose new features to your users. To assist you in customizing the LISTSERV web interface, L-Soft has produced a Customization Guide, which is available in PDF format at the following location:
Since the comprehensive guide takes you through the whole gamut of interface customization, this section will concentrate solely upon a basic understanding of the new features of the interface.
The LISTSERV Web Interface requires JavaScript to be enabled by default. However, those who prefer not to use JavaScript can set their Navigation Style user preference to "Non-Script Navigation" in the Preferences menu.
11.1 The Default LISTSERV Home Page
The default home page for LISTSERV typically is reached by using the URL:
On unix: http://yourhost.domain/cgi-bin/wa
On VMS: http://yourhost.domain/htbin/wa
On Windows: http://yourhost.domain/scripts/wa.exe or
Of course this is not standardized; the location of the 'wa' script is determined by the value of WWW_ARCHIVE_CGI in LISTSERV's site configuration file. In any case, invoking 'wa' without any parameters returns the default home page.
11.2 Logging In
You can log into the list administration interface from any list's main web archive index page (assuming that this link has not been removed by the list owner; it exists in the WWW_INDEX mail template by default). The interface may also be reached by a link from the default LISTSERV home page mentioned in Section 11.1 The Default LISTSERV Home Page.
To access the list administration interface without a link, you point your web browser to the "wa" script. Typically the interface is accessed as follows:
On unix: http://yourhost.domain/cgi-bin/wa
On VMS: http://yourhost.domain/htbin/wa
On Windows: http://yourhost.domain/scripts/wa.exe or
and by default, users are directed to the main archives page for the server.
Figure 11-1 LISTSERV Archives Screen
To get to the administrative pages, you will have to log in. If you already have a personal LISTSERV password, then you will simply log in with your existing userid and password.
Figure 11-2 Login Screen
Note: The userid you use here must be associated with the personal password you have from LISTSERV. If you have registered a password as and try to log in here as with that password, LISTSERV will reject your login.
Logging in will cause LISTSERV to issue you a cookie that allows you to bypass this login screen (and incidentally to stay logged into the interface for longer than 15 minutes without having to log in again when your session expires). If your workstation is not physically secure, you will want to log out after each management session.
11.3 Setting a LISTSERV Password
If you do not already have a personal LISTSERV password (set with the PW ADD command or via the web interface) or cannot remember your password, you need to define one now. If you choose to do this via the web interface, simply click the hyperlink and you will get the following screen:
Figure 11-3 Registering a LISTSERV Password
When you hit the [Register password] button, you will be told that a confirmation has been emailed to you. You will have to activate your password by responding to the email (or clicking the link it contains).
11.4 Logging In and Setting Preferences
When you log in for the first time, you will be returned to the main list archives page, but with a difference: The top toolbar will have a lot more options.
Figure 11-4 Web Interface Toolbar
The interface tells you who you are logged in as, and what functions your logged-in address is entitled to perform. It also tells you what mode you're set to (the Basic Mode by default; there are two other modes, "Expert" and "Tutorial"). If you are entitled to edit the page, you can go straight to the page editing wizard by clicking Edit Page.
Clicking the LISTSERV logo icon at the left takes you to L-Soft's home page. Clicking "LISTSERV 15.5" takes you to your default start page.
Help pages are accessed by clicking the Help icon at the right hand side of the toolbar.
The Server Administration menu gives you access to the Server Dashboard, site configuration functions, mailing list creation and deletion, server reports, server customization (mail and web templates), and the ad-hoc LISTSERV command entry page.
The List Management menu gives list owners access to the List Dashboard, list configuration, customization, and subscriber management.
List Moderation centralizes the moderation function, and it will show all messages needing moderation from the userid@host under which you are logged in.
Email Lists takes you back to the main list archives page.
The first thing you may want to do is click Preferences. One of the things you can set is the default start page. Site administrators will probably want to start at the server administration dashboard, while list owners will probably want to start at the list owner dashboard. Or they may be perfectly happy to start at the list archives page. In any case, clicking on Preferences brings up the following page:
Figure 11-5 Preference Screen
More information can be found by clicking the Help icons associated with each preference.
11.5 List Maintenance via the Web Interface
Important: The LISTSERV 15 Web Interface cannot be used to manage lists that are coded Validate= Yes,Confirm,NoPW or Validate= All,Confirm,NoPW because passwords are not accepted for validation in those cases.
The Subscriber Management screen lets list owners examine, delete, and add subscribers to a specific list. To access this screen, select Subscriber Management from the List Management menu. From this screen, select the list you want to work with, and then select either the Single Subscriber or Bulk Operations tab. The Single Subscriber tab lets the list owner examine or delete a subscription and add a new subscriber to the list. To add or delete many subscriptions at a time, use the Bulk Operations tab.
Note: To examine, modify, or delete multiple subscriptions at once, you can also use the Subscriber Reports screen.
11.5.1 Examining or Deleting a Subscription
This works very much like the "SCAN" command. Simply enter your criteria in the text box and click the [Search in List] button.
Figure 11-6 Examining or Deleting a Subscription
If there is no match for your entry, then you will get back the same page but with a Scan: No match message at the top. If, on the other hand, your search is successful, one of two things will happen.
If there are multiple matches for your criteria, a screen will be displayed with a scrollable list box containing all of the matches
Figure 11-7 Select Subscriber to Examine or Delete
Next, simply choose the user you want to examine or delete and click on the appropriate button. If you did not find what you were looking for, you can press the [New Search] button to get a new search screen.
If there was only a single match to your query, then the preceding screen will be bypassed and you will go directly to the next screen, which is the Subscriber Management screen for the subscription. It displays the values of all the settings for that subscription, including the subscription date and name. From the account management screen, you can delete the subscription or change the name, the email address, or the subscription options associated with the subscription. A sample of the screen is shown below.
Figure 11-8 Subscriber Management Screen
11.5.2 Adding a New Subscriber to the List
To add a new subscriber, select the list you want to add the subscriber to. Then, in the Add New Subscriber section, enter the email address and name of the new subscriber, select whether or not to send an email notification to this subscriber, and click the [Add to List] button.
Figure 11-9 Adding a New Subscriber
Note: The full name of the subscriber is optional. If omitted, then the user will be added anonymously to the list.
11.5.3 Bulk Operations
The Bulk Operations tab allows a list owner to upload an input file containing email addresses and (optionally) names, one address per line, and either add all the email addresses in the file to the list (optionally replacing the current subscribers) or remove them from the list.
The input file is created on your own machine with an ASCII text editor. After clicking the [Import] button you will see a command response similar to the following:
If the Add the imported address to “List”; do not remove any subscribers option is selected:
ADD: no error, 202 recipients added, no entry changed, no duplicate, none forwarded.
If the Remove all subscribers from “List”, and add the imported address option is selected:
DELETE: 14 subscribers removed.
ADD: no error, 38 recipients added, no entry changed, no duplicate, none forwarded.
(If this option is selected, but no input file is specified, then you will only get the DELETE message.)
If the Remove the imported addresses from “List”; do not add any subscribers option is selected:
DELETE: 93 subscribers removed.
If the Remove the imported addresses from all lists option is selected:
DELETE: 243 subscribers removed.
DELETE: 109 subscribers removed.
Global deletion process complete, 352 entries removed.
If you do not supply an upload file where required, or if your browser does not support the RFC1867 file upload extension, you get the following message:
Your browser did not upload any file during the transfer. Assuming you did fill in the file input box, the most likely cause is that your browser does not support the file upload extension (RFC1867).
Figure 11-10 The Bulk Operations Tab
Notes: Bulk operations are not enabled by default. The site manager must enable this functionality explicitly. If you get an error 2 when you click on the [Import] button, this means that the "upload" directory has not been created. If you get an error 13 when you click on the [Import] button, this means that the "upload" directory has been created but the CGI program user does not have write permission in that directory. In addition, the input file must be a plain text file (not a word processor document or spreadsheet) and must contain one address per line, optionally followed with a space (or TAB) and the subscriber's name. In addition, the subscribers being added or deleted will not be notified.
11.6 List Configuration
Lists can be configured using a wizard, which guides you step-by-step through the configuration process, or manually.
To open the List Configuration Wizard, click on the List Management menu, select List Configuration, and then select List Configuration Wizard.
To configure a list manually, click on the List Management menu, select List Configuration, and then select Manual List Configuration.
Figure 11-11 The List Management Menu
For those of you who want to configure the list manually, you can edit the list header in its "raw" state. This is only recommended for people who are very comfortable with LISTSERV list header formats and know the keywords and their parameters very well.
The list header appears in a multi-line text box that can be scrolled up and down. You simply type in the changes or added lines just as if you were using a regular text editor. When you are finished, click the [Submit] button to submit the changes. If you want to start over, you can click the [Reload] button to reload the header information from the server.
When you submit your changes with the [Submit] button, you will get the same kind of feedback from LISTSERV as you would if you sent a PUT operation by mail. The next screen will either say that the header of the list has been successfully updated, or it will indicate that it has found errors and that the header has not been stored. The feedback page also has a text box containing the header information you've just stored (or tried to store) so if you need to make further corrections to the header, you don't have to back up and start over.
The list header keywords and their parameters are documented in the List Keyword Reference document, in the online help, or (when using the configuration wizard) by clicking the Help icon for each keyword.
11.7 Maintaining Mail and WWW Templates via the Web Interface
The template editor allows the site administrator and list owner to customize the majority of the Web Interface Pages and Administrative Messages sent out by LISTSERV. There are two types of templates you can customize – Web and Mail.
Web Templates (also referred to as Dynamic Web Templates) control the pages produced by the Web interface. These pages are produced dynamically when they are accessed. What gets displayed by the browser depends on the circumstances and may change depending on who is accessing the interface, which list they are accessing, the settings of that list, and so on.
Commands in Web Templates begin with a plus sign "+" and variables begin with an ampersand followed by a plus sign "&+".
Mail Templates control text produced by LISTSERV itself. Although generally categorized as mail templates, they actually fall into three different types:
Mail Templates control the contents of email messages sent by LISTSERV. A mail template is a complete email message. Formatting commands are available, substitutions that make sense in the context of the specific message are available, and while other templates may be imbedded with the .IM command, the message is in and of itself ready for LISTSERV to send.
Message Templates supply text that will ultimately be shown to the user. These messages may be included in a mail template; or they may be included in an email sent by LISTSERV in response to LISTSERV commands sent by email to the LISTSERV command address; or they may be returned to the Web interface in response to commands sent through the Web interface. Limited formatting is available.
Message Fragments templates are the lowest level of mail templates. Fragments are pieces of text produced by LISTSERV as parts of other messages or emails. For example, list digests must follow a certain format dictated by the Internet RFCs. Therefore, it is not possible to provide a complete mail template for digests. However, some of the text within the digest is not mandated by the RFCs, and so LISTSERV provides some fragment templates to control these parts, for example MSG_DIGEST_FRAGMENT_DATERANGE1 to control the date range and MSG_DIGEST_FRAGMENT_PREAMBLE1 to control the text preceding the table of contents. Formatting commands are generally not available in fragments.
Commands in Mail Templates begin with a period "." and variables begin with an ampersand "&".
To access the template editor, click on the List Management menu, select Customization, and then select either Web Templates or Mail Templates.
Once the template editor has opened, simply select the list and template you want to work with. The template editor also lets you create new template.
For more information about customization templates, see the Customization Manual for LISTSERV 15.5 or click on the link(s) located in the Tips section at the bottom of the editor.
11.8 Sending Interactive Commands via the Web
The LISTSERV Command Interface is used for submitting LISTSERV commands that are not otherwise facilitated by the Web interface. See Appendix A: Command Reference Card for a listing of all commands.
For some commands, the response is automatically displayed by the Web interface. For others, a special command parameter must be used in order to display the response in the browser, otherwise the response is sent by email. In addition, other commands are only able to respond by email.
To access the LISTSERV Command Interface, click on the List Management menu, and then select LISTSERV Command.
The Command Interface can only be used for single line commands. In particular, the PUT command will not work through the Web interface. Multi-line commands must be sent by email.
A selection of frequently used commands is available at the bottom of the screen.
11.9 Mail-Merge
Advanced mail-merge features are available and can be accessed either by sending specially-formatted DISTRIBUTE jobs to LISTSERV or by using the web administration interface. The web interface is not a "wizard" but simply an interface that allows you to "cut and paste" a mail merge message and select different standardized groups of list subscribers to whom the message is to be sent.
Notes: LISTSERV's mail-merge functionality REQUIRES the use of LISTSERV’s Embedded Mail Merge feature. For more information, see the EMM keyword in the Site Configuration Keyword Reference document. Mail-merge functions are documented fully in the Advanced Topics Guide for LISTSERV.
11.10 Server Administration Interface
LISTSERV also includes a maintainer-level server administration interface. From this interface it is possible to
Create lists
Change site configuration variable settings
Enter the list management (list owner) area
Customize the default LISTSERV home page
Customize the default web interface layout
Customize the site-wide web and mail templates
Send a mail-merge message using the DBMS back-end (requires a DBMS interface; see the section on DBMS features in the Advanced Topics Guide for LISTSERV for more information)
Execute an arbitrary LISTSERV command (as with LCMD). Note that certain commands will be answered by mail rather than through the interface.
To access the server administration interface, use the appropriate link from the LISTSERV home page described in Section 11.1 The Default LISTSERV Home Page.
Each feature of the administration interface is fully self-documented.
Important: When creating lists via the web interface under unix and VMS (with PMDF), it is still necessary to make the mail aliases required in 7.2.2 (for unix) or 7.2.3 (for VMS), above. The web interface will not make these aliases for you.
The main entry page for the administration interface is the Administration Dashboard. This Dashboard concentrates important information about the server, the current version you are running vs. the latest available version, license information, anti-virus information, and technical support information.
The bottom section shows monthly statistics for the server. The default set of statistics can be changed to show only those statistics you really want to see on a regular basis. To change the stat set, click the Edit Table link at the top left of that section. Columns are removed by clicking the [X] under the caption, and columns are added by choosing a statistic from the Columns drop-down text box and clicking the [Add Column] button at the right. When done editing, click the Stop Editing link at the top left.
Figure 11-12 The Administration Dashboard