sympa-community.github.io

Incubating the new Sympa documentation site

List creation, editing and removal

The list creation can be done in two ways, according to listmaster needs:

Management of mailing lists by list owners is usually done through the web interface: when a list is created, whatever its status (pending or open), the owners can use WWSympa administration features to modify list parameters, to edit the welcome message, and so on.

WWSympa keeps logs of the creation and all modifications to a list as part of the list’s config file (old configuration files are archived). A complete installation requires some careful planning, although default values should be acceptable for most sites.

List creation

(Work in progress)

Data for list creation

To create a list, some data concerning list parameters are required:

In addition to these required data, provided values are assigned to vars being in the list creation template. Then the result is the list configuration file:

On the web interface, these data are given by the list creator in the web form. On command line, these data are given through an XML file.

Typical list profile

List profiles (list creation templates) are stored in $SYSCONFDIR/create_list_templates or in $DEFAULTDIR/create_list_templates (default of distribution) as directories with profile name. Directory of a profile should contain at least two files: config.tt2 and comment.tt2.

comment.tt2 is the descripion of list profile. It may contain tilte line(s) and HTML content. They are shown in list creation page of web interface.

config.tt2 is the template of list configuration. It will be formatted and save as config file when list is created.

You might want to hide or modify profiles (not useful, or dangerous for your site). If a profile exists both in the local site directory $SYSCONFDIR/create_list_templates and in the $DEFAULTDIR/create_list_templates directory, then the local profile will be used by WWSympa.

comment.tt2

Title line(s) are placed at beginning of config.tt2. They are separated from content by single newline. Below is an example.

title Liste de discussion publique
title.fr Liste de discussion publique
title.gettext Public discussion mailing list

<ul><li>[%|loc%]public archives[%END%]</li>
<li>[%|loc%]only subscribers can post[%END%]</li>
</ul>

Note:


XML file format

The XML file provides information on:

Here is an example of XML document that you can map with the following example of list creation template:

<?xml version="1.0" ?>
<list>
    <listname>example</listname>
    <type>my_profile</type>
    <subject>a list example</subject>
    <description/>
    <status>open</status>
    <shared_edit>editor</shared_edit>
    <shared_read>private</shared_read>
    <language>fr</language>
    <owner multiple="1">
        <email>serge.aumont@renater.fr</email>
        <gecos>C.R.U.</gecos>
    </owner>
    <owner multiple="1">
        <email>olivier.salaun@renater.fr</email>
    </owner>
    <owner_include multiple="1">
        <source>my_file</source>
    </owner_include>
    <editor multiple="1">
        <email>user@domain.org</email>
    </editor>
    <topic>Computing</topic>
    <sql>
        <type>Oracle</type>
        <host>sqlserv.admin.univ-x.fr</host>
        <port>1521</port>
        <user>stdutilisateur</user>
        <pwd>monsecret</pwd>
        <name>les_etudiants</name>
        <env>ORACLE_HOME=/[oracle_path]</env>
        <query>SELECT DISTINCT email FROM etudiant</query>
    </sql>
</list>

Here is an example of list creation template, $DEFAULTDIR/create_list_templates/discussion_list/config.tt2:

subject [% subject %]

status [% status %]

[% IF topic %]
topics [% topic %]

[% END %]
visibility noconceal

send privateoreditorkey

web_archive
  access public

subscribe open_notify

shared_doc
  d_edit [% shared_edit %]
  d_read [% shared_read %]

lang [% language %]

[% FOREACH o = owner %]
  owner
    email [% o.email %]
    profile privileged
    [% IF o.gecos %]
    gecos [% o.gecos %]
    [% END %]

[% END %]
[% IF moderator %]
  [% FOREACH m = moderator %]
    editor
      email [% m.email %]

  [% END %]
[% END %]

[% IF sql %]
  include_sql_query
    db_type [% sql.type %]
    db_port [% sql.port %]
    host [% sql.host %]
    user [% sql.user %]
    passwd [% sql.pwd %]
    db_name [% sql.name %]
    db_env [% sql.env %]
    sql_query [% sql.query %]

[% END %]

default_user_options
  reception urlize|mail|digest

ttl 360

The XML file format should comply with the following rules:

List families

See chapter List families.

List creation on command line with sympa.pl

This way to create lists is independent of family. The list creator has to choose a profile for the list and put its name in the XML element <type>.

Here is a sample command to create one list:.

# sympa.pl --create_list --robot mail.example.org \
 --input_file /path/to/my_file.xml

The list is created under the my_robot robot and the list is described in the file my_file.xml. The XML file is described before, see XML file format.

By default, the status of the list created is open.

Creating and editing mailing lists using the Web

The management of mailing lists is based on a strict definition of privileges which pertain respectively to the listmaster, to the main list owner, and to basic list owners. The goal is to allow each listmaster to define who can create lists, and which parameters may be set by owners.

List creation on the web interface

Listmasters are responsible for validating new mailing lists and, depending on the configuration chosen, might be the only ones who can fill out the create list form.The listmaster is defined in sympa.conf and others are defined at the virtual host level. By default, any authenticated user can request a list creation, but newly created lists are then validated by the listmaster.

The list rejection message and list creation notification message are both templates you can customize (list_rejected.tt2 and list_created.tt2).

Who can create lists on the web interface

(Work in progress)

Typical list profile and web interface

As on command line creation, the list creator has to choose a list profile and to fill in the owner’s email and the list subject together with a short description. But in this case, you do not need any XML file. Concerning these typical list profiles, they are described before, see “Typical list profile”. You can check available profiles. On the web interface, another way to control publicly available profiles is to edit the create_list.conf file (the default for this file is in the $DEFAULTDIR directory, and you may create your own customized version in $SYSCONFDIR). This file controls which of the available list templates are to be displayed. Example:

## This sample hides the public_anonymous create_list template
public_anonymous hidden
defaults read

customize create_list_request.tt2

The list creation form is in a template named web_tt2/create_list_request.tt2. You may modify this template in order to some other input that will be used to modify the created list. Any new input variable will be catched by wwsympa.fcgi and available in the tt2 hash [% custom_input %] when using the list template to create teh list.

Example:

## This is an html part added in create_list-request.tt2
<input type="text" name="custom_input.ldap_group" />

In config.tt2 you may use

… 
include_ldap_query
  host ldap.foo.edu
  suffix ou=accounts,dc… 
  filter (&(isMemberOf=[% custom_input.ldap_group %]))

…

For more details on tt2 customization, templates path and so on, see “Templates”.

List editing

(Work in progress)

Parameter can be any list config parameter or the name of a template (thus controlling the edition of the template through the customize web admin feature. You can refer to a subentry of a structured list parameter using the “.” as a separator (examples: owner.email or archive.quota). default is a reserved parameter name that means any other parameter.

(Work in progress)

Using edit_list.conf, you can define privileges on the following lists parameters:


Notes:

Starting Sympa 6.1.10, a unique exception exists in the matching between file names and edition rights in the edit_list.conf: the “info” term.

“info” represents both a list parameter and a list file:

Obviously, there is no reason why the exact same people would have the same rights on these two informations. But as they have the same name, one must use differetn keys in the edit_list.conf file to discriminate them.

In the following example, an owner and a privileged owner can both edit the info file, but only the privileged owner can change the info scenario to be used (the owner is only allowed to read it):

info.file    owner,privileged_owner        write
info        privileged_owner        write
info        privileged_owner        read

(Work in progress)

Concerning list editing in a family context, see “Editing list parameters in a family context”.

Removing a list

You can remove (close) a list either from the command line or by using the web interface.

sympa.pl provides an option to remove a mailing list, see the example below:

# sympa.pl --close_list=mylist@mydomain

Privileged owners can remove a mailing list through the list administration part of the web interface. Removing the mailing list consists in removing its subscribers from the database and setting its status to closed. Once removed, the list can still be restored by the listmaster; list members are saved in a member.dump file.

CC BY-SA 4.0 Unless otherwise specified, the contents of this document are licensed under the Creative Commons - Attribution - ShareAlike license. For more details see LICENSE and AUTHORS.

Theme originally designed by orderedlist