LISTSERV’s Web Administration Interface makes LISTSERV administration significantly easier, and lets you 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 15.5 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 15.5 web interface, L-Soft has produced a Customization Manual, which is available in PDF format at the following location:
http://www.lsoft.com/resources/manuals.asp
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 15.5 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.
Note: This 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.
•
On unix: http://yourhost.domain/cgi-bin/wa•
On VMS: http://yourhost.domain/htbin/wa•
On Windows: http://yourhost.domain/scripts/wa.exe or
http://yourhost.domain/cgi-bin/wa.exeOf 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.
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.
If you login with the "save my password in a cookie" method, LISTSERV will 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). This option is, however, only recommended for people who have physically secure machines (for instance, on your machine at home or in your office) or who are able to otherwise keep unauthorized users from logging in since LISTSERV cannot tell who is using the cookie. Specifically, if your browser does not support separate configurations or bookmark files for different users, you should not use the cookie method in a workplace environment.
Notes: There is a known bug in Netscape prior to version 4.0 that allows you to see the userid and password typed into the text boxes if you back up to the login page using the "Back" arrow.
The userid you use here must be associated with the personal password you have from LISTSERV. If you have registered a password as joe@unix.host.com and try to log in here as joe@host.com with that password, LISTSERV will reject your login.
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
Get a New LISTSERV Password link. The Register LISTSERV Password screen opens.
Enter your email and password. Confirm the password by entering it again, and then click the
[Register password] button. When your password registration is accepted, a confirmation email will be sent to you. You will have to activate your password by responding to the email (or clicking the link it contains).
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.
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:
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 List Management Dashboard is divided into two sections, providing information and reports about your technical support and lists. Each section uses icons to indicate its status and available actions:
•
Green Shield with a Checkmark – This icon means that you are current. Note that in the Moderation section this icon mean that there are no messages pending moderation.
•
Life Buoy – This icon is used if the Server Administrator has enabled technical support, making it easy and convenient to send requests to the Server Administrator. Once you click on this icon, an email message opens. Enter any information describing your problem. Please be as detailed as possible.
The Technical Support section shows whether or not the Server Administrator has enabled technical support. If it is enabled, then the
Life Buoy icon is shown, making it easy and convenient to send requests to the Server Administrator. Once you click on this icon, an email message opens. Enter any information describing your problem. Please be as detailed as possible.
The Moderation section lists any messages that are awaiting moderation. The messages displayed here are those that belong to a list for which you are listed as a moderator.
Note: This section is only displayed if you are a moderator on one or more lists. In addition, only two icons are used in this section. The green icon indicates that there are no messages pending moderation; the orange icon indicates that there are messages pending moderation.
The reports table at the bottom of the screen shows list configuration and list activity (changelog) data, which is a combination of the List Report and the List Activity reports. (Note that the list activity data is only visible if a list has changelogs enabled.) By default, the changelog data is not automatically calculated because of the time it takes to process the log files, especially if you have many lists or if they have large log files. To calculate the data, just click on one of the plus signs,
[+]. If you would like the changelog numbers to be loaded automatically every time you access the page, you can change the
Owner Dashboard Changelogs setting in the Preferences section.
To add or remove columns from the table, click the Edit Table option. This option is a great way to customize the information shown in the table, making sure only the information you want to see is visible. If you customize the table, then your changes will be saved in your preferences and will be automatically loaded every time you log in.
The Lists Per Page parameter controls how many lists will be displayed on a single page. The default is 10. If you want to break the list into 20 lists (for example), then simply enter "20" in the box and click
[Update].
The Changelog Period parameter lets you select the date range for the changelog columns in the report. The default is 1 day. If you want to change this period, simply choose a different option from the drop-down menu, such as 14 days, and then click
[Update].
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.
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 the format of the LISTSERV list header 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.
The Administrator Task Wizard allows you to review and modify which email addresses handle each aspect of administering your list. There can be any number of people involved in running a list. You might have the same person taking on all administrative roles alone, or you may assign several different people to each role.
To open the Administrator Task Wizard, click on the List Management menu, select
List Configuration, and then select
List Configuration Tasks.
Make desired changes to each of the keywords on any of the tabs, and then press the [Submit] button. Alternatively, you can click on each keyword to follow the links to the Wizard pages for each keyword – these include lengthy explanations about the keywords.
Owners are the primary administrators of the list. Email addresses with "owner" privileges may change the configuration and templates of the list, add and delete subscriptions, and change the settings on subscriptions.
Owners also receive email sent to the official list owner address. Unless otherwise specified, they receive notifications of subscriptions, signoffs, and error messages related to the operation of the list.
Some owner addresses may be designated as "quiet" owners. These addresses have all the owner privileges but do not receive any of the owner messages. Each list must have at least one non-quiet owner.
If you are replacing an owner, start by adding the new owner address. Next, make sure that the new address is able to function as an owner before removing the old address from the list of owners. If you make a mistake by first removing the old working address and then discovering the new address does not work, you may have to get the site administrator to fix your list for you.
On lists set to Send=Editor, editors are those addresses that are allowed to post directly to the list without moderation (that is, approval from a moderator).
On moderated lists where the Moderator keyword is not defined, the first editor listed in the
Editor keyword acts as sole moderator.
On all lists, regardless of the value of the Send keyword, editors are not subject to limitations on the number of daily posts to the list, as set by the
Daily-Threshold keyword.
The first editor listed in the Editor keyword must be an email address pointing to an individual. Other editors can point to lists on the same server including the current list; in that case, all the subscribers on the list have "editor" privileges. To enter the name of a list, you must enclose just the list name (not the list address) in parentheses.
If you do not specify the Editor keyword, the primary editor is the first listed Owner address.
When a list is fully or partially moderated, all messages from "moderated" addresses are sent to the moderator(s) for approval. You can set up your list so that incoming messages go to each moderator in turn in a "round-robin" fashion, or so that all incoming messages go to all moderators.
If you do not specify the Moderator keyword, moderated messages get sent to the primary Editor address.
Occasionally, problems occur on a list, and LISTSERV needs to know where to send error notifications. If you do not specify the
Errors-to keyword, error messages will be sent to all non-quiet owners.
•
If the list is set to Auto-Delete=Yes, and there have been any delivery errors ("bounces") within the set time period, a "Daily Monitoring Report" is sent every morning.
Whenever someone subscribes or is added to the list, or someone signs off or is removed from the list, a notification is sent to the non-quiet owners (if
Notify=Yes) or to the address(es) specified in the Notify keyword.
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.
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.
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.
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.
Note: The full name of the subscriber is optional. If omitted, then the user will be added anonymously to the list.
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.
•
If the Add the imported address to “List”; do not remove any subscribers option is selected:
•
If the Remove all subscribers from “List”, and add the imported address option is selected:
•
If the Remove the imported addresses from “List”; do not add any subscribers option is selected:
•
If the Remove the imported addresses from all lists option is selected:
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.
The List Configuration Task Wizard guides you through providing digest and index versions of the list, in addition to the usual individual postings. To access this wizard, click on the
List Management menu, select
List Configuration, and then select
List Configuration Tasks. Click on the Digest tab to setup digest or index versions of the list.
Normally, LISTSERV sends messages out to subscribers as soon as it receives them, so that the subscribers receive the mailing list messages throughout the day. Some may prefer to get all of the messages at the same time, combined into a single piece of email. Such a collection of messages is called a digest.
Another option, similar to the digest, is for LISTSERV to send the subscriber a list of what messages have been distributed to the mailing list recently, along with information about when the message was posted, how big it is, and who sent it. This is referred to as an index.
LISTSERV allows subscribers to get digests in three formats: HTML, MIME, and NOMIME NOHTML. Subscribers can individually choose the format that works best in their email clients. Each email client is different, so subscribers should experiment with the different digest styles to find the one they prefer.
An index, similar to the digest, is another option for receiving one message that summarizes a collection of messages from LISTSERV. LISTSERV sends the subscriber a list of what messages have been distributed to the mailing list recently, along with information about when the message was posted, how big it is, and who sent it.
Indexes are available in HTML and NOHTML formats. If HTML is used, the index includes a link to each message in the Web archive interface. If NOHTML is used, the index includes instructions on how to retrieve the messages the subscriber wants.
Plain text is the simplest form of digest. All email programs should be able to read plain text digests without difficulty. The basic form of this type of digest is given in RFC 1153.
Note: If the mailing list is used for discussions, typically there will be multiple messages for each subject.
Since the digest is plain text, any HTML messages will appear uninterpreted (the raw HTML code will appear) and any attachments will appear in their encoded form. Additionally, any special characters (smart quotes or accented letters, for example) may not display correctly in plain text digests.
Recipients of an HTML digest who have email programs that are programmed to handle such digests will see an index of the day's messages followed by the contents of the DIGEST-H template (if any).
Clicking on a subject in the table of contents takes you down to the relevant message or messages in the index. Clicking on any of the messages will then take you to the message in question.
A special note: Since the digest includes all of the messages as MIME attachments, all of the links in the HTML digest index are of the form: "cid: content-id" (see RFC 2111 for more information about this type of URL). Unfortunately, some email clients, even some that otherwise support HTML, do not handle such references correctly. For this reason, some subscribers may not be able to use HTML digests.
Each message in the digest is included as a MIME attachment. The subscribers access the messages as they would any other type of attachment. And, since MIME standards require that the type of content of each attachment is identified, all messages should appear normally, without the sort of display problems that plain text digests can have.
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.
Mail Templates control text produced by LISTSERV itself. Although generally categorized as mail templates, they actually fall into three different types:
•
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.
To access the template editor, click on the List Management menu, select
Customization, and then select either
Web Templates or
Mail Templates.
The Web Administration Interface makes it possible for server administrators or for those list owners with multiple lists to obtain reports on their lists and search these lists for specific characteristics.
To access, click on the List Management menu, select
List Reports, and then select either
List Reports,
Subscriber Reports, or
List Activity Reports.
To create a report, select the list or lists to generate the report for. By default, you will see all of the lists you own. Next, select the columns you want to include in the report. Finally, click
[Submit].
Note: Each column heading is a clickable link that will sort the column in ascending or descending order. A small arrow pointing up or down will appear indicating the order. Each list name in the report is a clickable link to the list configuration page for that particular list.
To create a report, select the list or lists to generate the report for. By default, you will see all of the lists you own. Next, select the columns you want to include in the report. Finally, click
[Submit].
The report generated is not just a simple report. It also provides the means of manipulating the reported data. Once the list owner has generated a report, it is possible to change subscription settings or delete one or more subscribers. It is also possible to add subscribers to the list.
The Subscriber Report also lets you add a subscriber to a list. To add a new subscriber to the list, type the user's email address followed by the full name. Then, choose whether or not to notify the user that he has been added and click on the
[Add Subscriber] button.
The Subscriber Report also lets you change subscriber setters. Once the report has been generated, it becomes possible to change any subscriber's settings (except for the subscription date):
•
Click the [Submit] button to save your changes. If you would like your subscribers to receive an email notification that their options have been changed, check the
Send email notification of changes box. Otherwise, no notification will be sent.
To view and make changes to the subscription options of individual subscribers, click on the subscriber name. If a name is not available, click on the
No Name Available link. The Subscriber Management screen will open for the selected individual. Make any changes and then click
[Update].
Each column heading is a clickable link that will sort the column in ascending or descending order. A small arrow pointing up or down will appear indicating the order.
Two types of activity reports can be generated using this interface. The first report is a history report. This report simply displays the changelog records that match the selection criteria, one record per line, similar to reading the changelog yourself. The second report is a statistics report. This table allows you to reduce the changelog records to numbers, based on several different criteria. This is where you can determine (for instance) how many postings were made to a given list on a range of specified dates, how many times a particular LISTSERV command was issued, and so forth.
You should generally choose only one report column on which to report statistics (Event or Email Address or Details) as each value of the text field is counted independently and sorted in alphabetical order, and rows could then include unrelated values and cause some confusion.
Changelog reports are only available for lists where the Change-Log listheader keyword is set to
Yes, and only for the time span it was enabled. Enabling Changelogs in the list header will not suddenly make it possible to view past list activity. If Changelogs are enabled, but set to rotate over time (for example, monthly changelogs), the reports are only available for the current report.
•
Define Report Type to create a historical or statistical report or both. If you check both report fields, you will get two reports. The historical report shows the actual changelog entries. The statistical report shows counts and averages.
•
Define Report Entries to determine which events to include in the report.
•
Define Report Interval to set the date range for the report.
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.
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.
The existing RSS support in LISTSERV's web archive interface has been improved by the addition of RSS abstracting, which is available in LISTSERV RSS feeds by default starting with LISTSERV 15.5.
Note: Existing (that is, pre-15.5) web indexes must be recreated to add the abstracts. This is a one-time operation that could take a while on a large site and is better left to be scheduled by the administrator. (See the documentation for the REINDEX command in the
Site Manager’s Operations Manaul for LISTSERV.) The abstract is either generated implicitly from the existing text of the message, or it may be specified explicitly by the use of a tag in the message.
In order to properly specify the explicit abstract, a mail client that supplies a plain-text part that matches the message is REQUIRED. Most if not all modern mail clients fit this specification.
For those using plain text messages: An explicit abstract is specified by using <abstract> and </abstract> tags in the body of the message - typically at the very end, but the explicit abstract may in theory appear anywhere in the message. The closing tag is optional but recommended.
For those using HTML-capable mail clients: If the mail client is unable to provide a user-specified plain-text alternative and instead sends a "canned" message to the effect that mail clients that do not support HTML will not be able to read the message, the "canned" message will be the abstract. If the mail client is not capable of providing a plain-text alternative message part at all, and provides HTML only, no abstract will be available.
For those posting messages using the web interface: A dedicated text box for entering explicit abstracts can also be enabled in the message posting interface. List owners can set the RSSINPUT variable to 1 in the list-specific SKIN template. To enable the dedicated text box for all lists, the server administrator should set the RSSINPUT variable to 1 in the site-wide SKIN template.
There are two parameters: a maximum abstract size and a minimum abstract size. The second parameter is optional, and if left unset, defaults to 50% of the maximum size. The basic syntax is:
•
VMS: DEFAULT_DIST_BACKGROUND "500 250"•
unix: RSS_ABSTRACT_WORDS="500 250"•
Win: RSS_ABSTRACT_WORDS=500 250LISTSERV stops at the first paragraph boundary after which it has collected at least 'min' words, adding an ellipsis if there is more text (compliant signatures are ignored). If there is an explicit abstract, then the min and max parameters are ignored and the abstract is whatever the user entered. If the stop-on-paragraph-end feature is not desired, simply set "min" to the same value as "max".
In all cases, RSS_ABSTRACT_WORDS and/or RSS-Abstract-Words may be changed at will, with the change taking effect "from now on." In order to make the new value take effect retroactively, the indexes must be rebuilt manually. Because of the resource-intensive nature of the REINDEX command, this will NOT happen automatically.
