This document describes installing and using our (still preliminary) Drupal implementation of FLOSS-Dgroups. The FLOSS-Dgroups project is an open-source version of the proprietary Dgroups.org platform. The core requirements for the project involve tying web-based forums to e-mail lists, thereby allowing discussion to take place simultaneously in both media, and enabling web users and email users to interact seamlessly. The project is described in much more detail here:
The FLOSS-Dgroups system is built on Drupal and Sympa as its core components. These applications require, and this recipe assumes, a working LAMP (GNU/Linux [or other unix-like OS], Apache, MySQL, PHP) environment.
In order to send mail, php_imap support is required; in order to run Drupal, the default amount of memory available to PHP should be increased (setting memory_limit = 24M in php.ini should be sufficient).
This tutorial assumes assumes that the Sympa mailing list manager is installed and functioning. For more details on installing and using Sympa, please see www.sympa.org.
Both Sympa's web and soap servers must be installed; these require that Apache be configured to use fastcgi. The installation of fastcgi is described at www.fastcgi.com and in the Sympa documentation.
Note that the soap server handles authentication by means of the file trusted_applications.conf, which is typically located in /home/sympa/etc (which allows it global scope; install it in a robot/etc directory for per-robot permissions control). For example, the following stanza in trusted_applications.conf will allow the username 'og2mlm' access to the server with the password 'password' (its md5 hash is '5f4dcc3b5aa765d61d8327deb882cf99'); this soap user is empowered to specify an email identity that will be used by sympa for permissions checking:
name og2mlm md5password 5f4dcc3b5aa765d61d8327deb882cf99 proxy_for_variables USER_EMAIL
See the following documents for notes on configuring the soap server and trusted_applications: http://wikis.bellanet.org/floss-dgroups/index.php/Sympa_Work_%28Stage_1%29
Drupal retrieves messages from Sympa by using an email "drop box." This can be a local or remote account (a Gmail or Yahoo account, for example), but should be reliable and used only for the purpose of passing og2mlm messages. You will need to provide the POP server address, username, and password to the og2mlm module (described below). For the moment the address must be pop3 on port 110 (default).
This tutorial assumes that Drupal 4.7 is installed and running on a web server. If assistance is required with this step, please refer to the Handbooks available on drupal.org. The FLOSS-Dgroups modules were written for Drupal 4.7, so this recipe will not work for older versions of Drupal.
The following Drupal modules are required to create the full functionality of FLOSS-Dgroups:
basicevent event fileshare flexinode front_page i18n i18nblocks i18nmenu og og_calendar roleassign translation
Many of the above modules can be configured as desired. Configuration specific to or needed by the FLOSS-Dgroups system is detailed below. The following custom modules provide special FLOSS-Dgroups functionality:
og2mlm og2mlm_basic og2mlm_message og2mlm_sympa [assuming you are using Sympa] og_hierarchy og_translate
Enable the core Drupal modules before adding these custom features. Activate the og2mlm, og2mlm_messages, and og2mlm_basic modules as usual (from admin > modules). If you are using sympa as your MLM, activate og2mlm_sympa. Next, visit the admin > settings > og2mlm page and fill out the required settings:
- Hostname: hostname of the email address. Probably something like "mail.og2mlm.com"
- Email dropbox: email address of the dropbox. e.g. "firstname.lastname@example.org"
- Password: Password for the email dropbox.
- Min. Polling Interval: og2mlm polls the email dropbox whenever a user views an organic group, but only if it hasn't been checked too recently. You can set this interval here. To cut down strain on og2mlm and the email dropbox, it is recommended you set this value somewhere above 10 seconds.
Max # of messages to retrieve: If there is a lot of mailing list activity, set this to a reasonable number to cut down wait times when viewing groups. Between 10 and 50 should be reasonable if the Min. polling interval is around 30 seconds.
- MLM Hostname: The hostname of your mailing list manager. For example if one of your mailing lists is "email@example.com", you would enter "bar.com" as the hostname.
Although not necessary, it is advisable to set up a regular cron job to poll the mail drop box for messages. This will prevent all the message processing from happening 'just in time.' How often the cron job should run depends on the amount of traffic you expect, and on what other dupal modules you have installed (which will have their own cron requirements). See http://drupal.org/cron for details.
This module does the work of letting Sympa and Drupal communicate with one another. Enable and configure og2mlm before working with og2mlm_sympa. Once og2mlm_sympa is enabled, proceed to admin > settings > og2mlm_sympa:
- Sympa SOAP server address: This is the wsdl file that tells og2mlm how to make rpc calls to sympa using SOAP. Sympa's demo wsdl file is located is at http://demo.sympa.org/sympa/wsdl; yours will probably look something like http://yourdomain.com/sympa/wsdl
- Sympa administrator: This is the name of the trusted application that is defined in trusted_applications.conf. In the case of the above example, this would be set to 'og2mlm'.
- Sympa administrator password: This is the password for the trusted application. In the case of the preceding example, this would be set to 'password'.
The og_translate module allows group owners to translate their groups' names and descriptions. Using this module requires applying a patch to the organic groups module. Assuming the modules are located in /home/drupal/modules, the following commands will patch the organic groups module:
cd /home/modules/og_translate patch ../og/og.module og_translate_og.patch
There are no admin settings for og_translate: it just needs to be enabled in admin > modules. It provides a new menu item, described below in "Using FLOSS-Dgroups."
The og_hierarchy module allows a group of users to be empowered as organic group "creators" by a "head creators" who retain authority over their creators' groups. This module assumes that the role assign module is active, and that organic groups access control is enabled (admin > settings > og). Using this module requires applying a patch to the organic groups module. Assuming the modules are located in /home/drupal/modules, the following commands will patch the organic groups module:
cd /home/modules/og_hierarchy patch ../og/og.module og_hierarchy_og.patch
Set up og_hierarchy as follows:
- Under admin > roles, reate two roles: "Creator" and "Head Creator" and give them permission to create organic groups
- Configure the role assign module (admin > settings > role assign): allow "Creator" and "Head Creator" to be assigned
- Apply the og_hierarchy_og.patch to og.module
- Enable the og_hierarchy module
- Give Head Creators the following additional permissions: assign roles, administer users, is head creator
- Turn off the default "Published" option for the og_hierarchy admin groups (admin > settings > content types)
SECURITY ALERT: The og_hierarchy feature is not fully functional. Although the og_hierarchy changes will take effect in Drupal, there is currently no mechanism to mirror those changes in Sympa. Sympa's SOAP server should ultimatlely provide this functionality. Until then, do not use this module unless you don't care about its inherent insecurity.
We have made a FLOSS-Dgroups Drupal theme available that mimics the current look of the Dgroups web site. If you are using the Dgroups theme, go to admin>blocks and replace the 'Group details' with the 'Group details (og2mlm)' block, or the display will look very odd.
Set up an og_hierarchy group (note the security warning above)
In order to empower Creators and Head creators, the site administrator should create a new og_hierarchy ("OG Admin") group (create content > OG hierarchy admin group). Set the following options
- Subscription requests: closed
- Do not list this group in either the registration form or the groups directory
- Uncheck "Published" under "publishing options" if it is checked
Take the following steps to empower a user as a Head Creator:
- add a user to the og_hierarchy group
- make them an admin of that group
- assign them to the "Head Creator" role
Take the following steps to empower a use to act as a group
- add a user to the og_hierarchy group
- assign them to the "Creator" role
Repeat as necessary to create additional organizational units. Note that once a Head Creator has been empowered, they can add Creators and Head Creators in turn. (They can be restricted to creating only Creators by changing the Role Assign configuration.) Site admins can thus create og_hierarchy organizational units by creating a new og_hierarcgy group and empowering a Head Creator who can empower other users in turn.
Create and use groups
Now you can create your first MLM-associated organic group by going to node/add/og (create content > group)
Set your usual og settings; note that there is now an extra field, 'Mailing list name:' which must be filled in order to relate that group to a mailing list. The name of the list can be the same as the group name, but note that:
- mailing list names are used in email messages, and so should be easy to understand and type
- the maximum length of the list name is 45 characters
- only letters and numbers are allowed; all other characters will be replaced by _
Thus, the name "dgroups testing" would become the mailing list firstname.lastname@example.org; "Steve's extra-special cool group about extraordinarily important things" would become the unpleasant Steve_s_extra_special_cool_group_about_extrao@example.com.
If the events and fileshare modules have been enabled, then a calendar and a fileshare will be automatically created for the new group.
You should now be able to select 'create message' for that organic group. Once that message is submitted it will be sent to the mlm, and from there to the dropbox. It will take at least 'Min interval' until that message is loaded into the group.
If you are using i18n and have installed the og_translate module, then users empowered to create groups will see an "OG transate" menu option in the main navigation menu. Clicking this link will present a list of group titles and descriptions that have not been translated and for which you are empowered to provide translations. Click on the "translate" link to use Drupal's translation tools to provide translated text for each additional language.
You are now using FLOSS-Dgroups!