Next: 19. Lists Families Up: Sympa Mailing Lists Management Software version Previous: 17. Mailing list definition Contents Index
Subsections

- 18.1 List creation
  - 18.1.1 Data for list creation
  - 18.1.2 XML file format
- 18.2 List families
- 18.3 List creation on command line with `sympa.pl`
- 18.4 Creating and editing mailing using the web
  - 18.4.1 List creation on the Web interface
  - 18.4.2 Who can create lists on the Web interface
  - 18.4.3 typical list profile and Web interface
  - 18.4.4 List edition
- 18.5 Removing a list

#
18. List creation, edition and removal

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

- instanciation family to create and manage large number of related lists. In this case, lists are linked to their family all along their life.
- command line creation of individual list with `sympa.pl` or on the Web interface according to privileges defined by listmasters. Here lists are free from their model creation.

Management of mailing lists by list owners is usually done via the Web interface : when a list is created, whatever its status (`pending` or `open`), the owner can use WWSympa admin features to modify list parameters, or 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.

#
18.1 List creation

Mailing lists can have many different uses. Sympa offers a wide choice of parameters to adapt a list behavior to different situations. Users might have difficulty selecting all the correct parameters to make the list configuration, so instead of selecting each parameters, list configuration is made with a list profile. This is an almost complete list configuration, but with a number of unspecified fields (such as owner e-mail) to be replaced by Sympa at list creation time. It is easy to create new list templates by modifying existing ones. (Contributions to the distribution are welcome...)

## 18.1.1 Data for list creation

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

- listname : name of the list,
- subject : subject of the list (a short description),
- owner(s) : by static definition and/or dynamic definition. In case of static definition, the parameter owner and its subparameter email are required. For dynamic definition, the parameter owner_include and its subparameter source are required, indicating source file of data inclusion.
- list creation template : the typical list profile.

Moreover of 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 by an xml file.

##
18.1.2 XML file format

The xml file provides information on :

- the list name,
- values to assign vars in the list creation template
- the list description in order to be written in the list file info
- the name of the list creation template (only for list creation on command line with sympa.pl, in a family context, the template is specified by the family name)

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@cru.fr</email>
    	   <gecos>C.R.U.</gecos>
    	</owner>
    	<owner multiple="1">
    	   <email>olivier.salaun@cru.fr</email>
    	</owner>
    	<owner_include multiple="1">
    	   <source>my_file</source>
    	</owner_include>
    	<sql>
    	   <type>oracle</type>
    	   <host>sqlserv.admin.univ-x.fr</host>
    	   <user>stdutilisateur</user>
    	   <pwd>monsecret</pwd>
    	   <name>les_etudiants</name>
    	   <query>SELECT DISTINCT email FROM etudiant</query>
    	</sql>
    </list>

    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 %]
      host [% sql.host %]
      user [% sql.user %]
      passwd [% sql.pwd %]
      db_name [% sql.name %]
      sql_query [% sql.query %]

    [% END %]
    ttl 360

The XML file format should comply with the following rules :

- The root element is `<list>`
- One XML element is mandatory : `<listname>` contains the name of the list. That not excludes mandatory parameters for list creation (`listname, subject,owner.email and/or owner_include.source`).
- `<type>` : this element contains the name of template list creation, it is used for list creation on command line with sympa.pl. In a family context, this element is no used.
- `<description>` : the text contained in this element is written in list `info` file(it can be a CDATA section).
- For other elements, its name is the name of the var to assign in the list creation template.
- Each element concerning multiple parameters must have the `multiple` attribute set to ``1'', example : `<owner multiple=''1''>`.
- For composed and multiple parameters, sub-elements are used. Example for `owner` parameter : `<email>` and `<gecos>` elements are contained in the `<owner>`element. An element can only have homogeneous content.
- A list requires at least one owner, defined in the XML input file with one of the following elements :
  - `<owner multiple=''1''> <email> ... </email> </owner>`
  - `<owner_include multiple=''1''> <source> ... </source> </owner_include>`

# 18.2 List families

See chapter 19, page

#
18.3 List creation on command line with `sympa.pl`

This way to create lists is independent of family.

Here is a sample command to create one list :.

> sympa.pl -create_list -robot my.domain.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 18.1.2, page .

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

###
18.3.0.1 typical list profile (list template creation)

The list creator has to choose a profile for the list and put its name in the XML element `<type>`.

List profiles are stored in `/usr/local/sympa-stable/etc/create_list_templates` or in `/usr/local/sympa-stable/bin/etc/create_list_templates` (default of distrib).

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 `/usr/local/sympa-stable/etc/create_list_templates` and `/usr/local/sympa-stable/bin/etc/create_list_templates` directory, then the local profile will be used by WWSympa.

#
18.4 Creating and editing mailing 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.

## 18.4.1 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 are then validated by the listmaster.

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

## 18.4.2 Who can create lists on the Web interface

This is defined by the `create_list` sympa.conf parameter (see 7.1.15, page ). This parameter refers to a create_list authorization scenario. It will determine if the create list button is displayed and if it requires a listmaster confirmation.

The authorization scenario can accept any condition concerning the [sender] (i.e. WWSympa user), and it returns `reject`, `do_it` or `listmaster` as an action.

Only in cases where a user is authorized by the create_list authorization scenario will the "create" button be available in the main menu. If the scenario returns `do_it`, the list will be created and installed. If the scenario returns "listmaster", the user is allowed to create a list, but the list is created with the `pending` status, which means that only the list owner may view or use it. The listmaster will need to open the list of pending lists using the "pending list" button in the "server admin" menu in order to install or refuse a pending list.

## 18.4.3 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 e-mail and the list subject together with a short description. But in this case, you don't need any XML file. Concerning these typical list profiles, they are described before, see 18.3, page . You can check available profile. 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 `/usr/local/sympa-stable/bin/etc` directory, and you may create your own customized version in `/usr/local/sympa-stable/etc`). This file controls which of the available list templates are to be displayed. Example :

    # Do not allow the public_anonymous profile
    public_anonymous hidden
    * read

##
18.4.4 List edition

For each parameter, you may specify (via the `/usr/local/sympa-stable/etc/edit_list.conf` configuration file) who has the right to edit the parameter concerned ; the default `/usr/local/sympa-stable/bin/etc/edit_list.conf` is reasonably safe.

    Each line is a set of 3 field
    <Parameter> <Population> <Privilege>
    <Population> : <listmaster|privileged_owner|owner>
    <Privilege> : <write|read|hidden>
    parameter named "default" means any other parameter

There is no hierarchical relation between populations in this configuration file. You need to explicitely list populations.

Eg: listmaster will not match rules refering to owner or privileged_owner

         examples :

    	# only listmaster can edit user_data_source, priority, ...
    	user_data_source listmaster write

    	priority 	owner,privileged_owner 		read
    	priority 	listmaster 			write

    	# only privileged owner can modify  editor parameter, send, ...
    	editor privileged_owner write

    	send 		owner 				read
    	send 		privileged_owner,listmaster 	write

    	# other parameters can be changed by simple owners
    	default 	owner 				write

Privileged owners are defined in the list's `config` file as follows :

    	owner
    	email owners.email@foo.bar
    	profile privileged

The following rules are hard coded in WWSympa :

- only listmaster can edit the "profile privileged" owner attribute

- owners can edit their own attributes (except profile and e-mail)

- the requestor creating a new list becomes a privileged owner

- privileged owners can edit any gecos/reception/info attribute of any owner

- privileged owners can edit owners' e-mail addresses (but not privileged owners' e-mail addresses)

Sympa aims to define two levels of trust for owners (some being entitled simply to edit secondary parameters such as "custom_subject", others having the right to manage more important parameters), while leaving control of crucial parameters (such as the list of privileged owners and user_data_sources) in the hands of the listmaster. Consequently, privileged owners can change owners' e-mails, but they cannot grant the responsibility of list management to others without referring to the listmaster.

Concerning list edition in a family context, see 19.2.8, page

#
18.5 Removing a list

You can remove a list either from the command line or using the web interface.

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

> sympa.pl -remove_list=mylist@mydomain

Privileged owners can remove a mailing list through the list admin 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 `subscribers.closed.dump` file.

Next: 19. Lists Families Up: Sympa Mailing Lists Management Software version Previous: 17. Mailing list definition Contents Index