A list can have from three parameters to many tens of them. Some listmasters need to create a set of lists that have the same profile. In order to simplify the apprehension of these parameters, list families define a lists typology. Families provide a new level for defaults : in the past, defaults in Sympa were global and most sites using Sympa needed multiple defaults for different group of lists. Moreover families allow listmaster to delegate a part of configuration list to owners, in a controlled way according to family properties. Distribution will provide defaults families.
A family provides a model for all of its lists. It is specified by the following characteristics :
Here is a list of operation performed on a family :
Examples:
/home/sympa/etc/families/my_family /home/sympa/etc/my_robot/families/my_familyIn this directory you must provide these files :
Example:
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
WARNING : Some parameters cannot be constrained, they are : msg_topic.keywords
(see 20.4.12, page ),owner_include.source_parameter
(see 20.1.6, page
), editor_include.source_parameter (see 20.1.2, page
). About digest parameter (see 20.4.8, page
) , just days can be constrained.
Example:
lang fr,us archive.period days,week,month visibility conceal,noconceal shared_doc.d_read public shared_doc.d_edit editor
Instantiation permits to generate lists.You must provide an XML file that is
composed of lists description, the root element is family and is only
composed of list elements. List elements are described in section
18.1.2, page . Each list is described
by the set of values for affectation list parameters.
Here is an sample command to instantiate a family :
sympa.pl --instantiate\_family my_family --robot \samplerobot --input\_file /path/to/my\_file.xmlThis means lists that belong to family my_family will be created under the robot my_robot and these lists are described in the file my_file.xml. Sympa will split this file into several xml files describing lists. Each list XML file is put in each list directory.
Example:
<?xml version="1.0" ?> <family> <list> <listname>liste1</listname> <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> <list> <listname>liste2</listname> <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> ... </family>
Each instantiation describes lists. Compared to the previous instantiation, there are three cases :
After list creation or modification, parameters constraints are checked :
diagram
In case of modification (see diagram), allowed customizations can be preserved :
Notes :
Closes every list (installed under the indicated robot) of this family : lists status are set to family_closed, aliases are removed and subscribers are removed from DB. (a dump is created in the list directory to allow restoration of the list).
Here is a sample command to close a family :
sympa.pl --close_family my_family --robot \samplerobot
Adds a list to the family without instantiate all the family. The list is created
as if it was created during an instantiation, under the indicated robot. The XML file
describes the list and the root element is <list>. List elements are described in section
18.3, page .
Here is a sample command to add a list to a family :
sympa.pl --add\_list my\_family --robot \samplerobot --input\_file /path/to/my\_file.xml
Closes the list installed under the indicated robot : the list status is set to family_closed, aliases are removed and subscribers are removed from DB. (a dump is created in the list directory to allow restoring the list).
Here is a sample command to close a list family (same as an orphan list) :
sympa.pl --close_list my_list@\samplerobot
Modifies a family list without instantiating the whole family. The list (installed under the indicated robot)
is modified as if it was modified during an instantiation. The XML file
describes the list and the root element is <list>. List elements are described in section
18.3, page .
Here is a sample command to modify a list to a family :
sympa.pl --modify\_list my\_family --robot \samplerobot --input\_file /path/to/my\_file.xml
array
Note : In order to preserve list customization for instantiation, every modified parameter (via the Web interface) is noted in the config_changes file.