cmwmaild

NAME

cmwmaild - Communiware mail daemon

SYNOPSIS

        cmwmaild [-c config] [-d] [[-f] -t | -T N] [-s sendmail] PERIOD
        cmwmaild --period=name [--config config] [--debug] \
          [--addressee=items,list] [--variant=items,list] [--item=items,list] \
          [[--force] --timeback | --daysback=N] [--sendmail sendmail]

DESCRIPTION

cmwmaild is a program that sends items to users subscribed to mailing service. It should be started from cron.

OPTIONS

--config or -c
This option allows to specify an alternate Communiware configuration file. Thus you can use one machine as mailing server for several separate Communiware instances provided that this machine can connect to all neccessary databases. It is recommended to start cmwmaild under the same uid as your web server.

--period or -p or mandatory argument PERIOD (should be last)
Mandatory option that should be one of the values defined in SUBSCRIPTION_PERIOD table. Standard values for PERIOD are `HOURLY', `DAILY', `WEEKLY' and `MONTHLY' (they are case insensitive, so `DAILY', `daily' and `DaIlY' are equal values). Adding new values require manual editing of SUBSCRIPTION_PERIOD table.

--debug or -d
Run cmwmaild in debug mode. See DEBUGGING below.

--timeback or -t
Manually override start time of the period used for news selection. Use the default interval (a LENGTH field of SUBSCRIPTION_PERIOD table) for this period.

--daysback N or -T N
Same as --timeback, but the interval from start of the period is manually defined as N days (could be fractional).

--sendmail sendmail_program or -s sendmail_program
Sets alternare programm for sending mail. The programm must have interface similar to original sendmail. This feature can be used for debugging or testing purposes.

--forceback or <-f>
Without this option the start of the period will be overriden only if it is earlier than the time of the last mailing for this PERIOD.

--addressee or -A
Litf addressee. Manually override recipients list for this cmwmaild session.

--variant or -V
List of digest variant template ids. Manually override list of processed digest variants for this cmwmaild session.

--item or -I
List of item ids. Manually override list of items, subscription on which must be processed in this cmmaild session.

ERROR CODES

Exits with code 1 if wrong PERIOD argument specified in command line.

WHAT DOES IT DO

Subscription methods.

There are three different subscription methods (somewhere in the document and in commets in cmwmaild code they are named as 'subscription types'): public, personalized and maillist.

  1. Public subscription.
    2. All subscriber addresses will be written in 'Bcc' field of message, so none will see a list of subscribers. Into 'To' field special subscription address will be written (see below). Only items everyone allowed to see will be sent.

    Subscibers here are Communiware users.

  2. Personalized subscription.
    3. For each subscriber items he allowed to read will be selected and an individual message will be sent.

    As in previous method subscribers are Communiware users and thier mail addresses are taken from MAIL attribute of corresponding AUTHOR items.

  3. Maillist subscription.
    4. This method is used to a mailing to an externally managed mailing list. In such case an address of that list will be placed in 'To' field. Only items everyone allowed to see will be sent in list (we can not know who are subscribed on that list).

    See below for data structures and items related to these three methods.

Data structures related to sending mail

They are SUBSCRIPTION and SUBSCRIPTION_PERIOD tables as well as templates having as template type one of MAIL, MAILPERS and MAILLIST.

SUBSCRIPTION_PERIOD table

It contains data about possible subscription periods. Remember that names of these periods are cmwmaild arguments. Four subscription periods added to this table during Communiware database creating - HOURLY, DAYLY, WEEKLY and MONTHLY. If you want to have another period you should manually add new record into this table.

PERIOD field
An identifier of the period. Use this value as a command line argument of cmwmaild. cmwmaild ignores case of this field.

The same vaue must be used in the PERIOD field of the SUBSCRIPTION table (for public and personalized methods) and for the STATUS filed of the ITEM table for templates of maillist methods.

MSG_ID filed
As everywhere in the Communiware keeps number of the message describing this period.

LENGTH field
Length of the period (surprise?) in seconds. For example is is equal 3600 for HOURLY period.

LAST_SENT field
Date and time of the last posting for this period is stored here. cmwmaild selects items, published after LAST_SENT and updates LAST_SENT after posting unless -d option is used.

SUBSCRIPTION table

It keeps the list of all public and personalized subscriptions, not maillists!

Each single subscription is the fact: this Communiware user wants to get information about updating this Communiware item and some other related items.

The table has following fields.

ITEM_ID field
The ``main document item'' of the subscription. This means that user wants to get mail when items related to this are changed.

For example for the subscription on the discussion about some article it could be ITEM_ID of that article.

When cmwmaild makes the lettest it executes templates in the context of this item.

ADRESSEE field
A subscriber's ITEM_ID, i.e. item id of some AUTHOR item. Mail is sent to to this user.

DIGEST_VARIANT field
This field contains id of template. But the text of this template does not contain usual template. It contains instead filter expression. When cmwmaild sends the mail it uses this filter for to determine - which items related to main document item are taking part in sent mail.

For example this filter may select all replics about some article or all new materials are belong to some topic.

TEMPLATE_ID field
Template's ITEM_ID used for this subscription. Corresponding row of the TEMPLATE table must have 'MAIL' (for public mailing) or 'MAILPERS' (for personalized mailing) value of the TEPMLATE_TYPE field. This template defines how to show information for the user.

PERIOD field
Posting period's id for the subscription. All available values are listed in the SUBSCRIPTION_PERIOD table's PERIOD column.

FORMAT_ID field
Determines in which format the user wants to get mail. Possible formats are listed in MAIL_FORMAT table. There are at least two of them - TEXT/HTML and TEXT/PLAIN.

Summary for public and peronalized subscriptions

Thus for having public or personalized subsription there must be a record in SUBSCRIPTION table which defines who wants to receive mail (ADDRESSEE), how it must be formed (TEMPLATE_ID), which items will be sent (filter, stored as a text of template pointed by DIGEST_VARIANT), how often updates will be checked (PERIOD) and if which format - plain text or HTML the letter will be present (FORMAT_ID).

If the status of given TEMPLATE_ID id PERSONAL or this template has template type MAILPERS then this record defines personal subscription,\ otherwise - public subscription.

Maillists summary

The mechanism of creating maillist subscription is different from the one for public and personal subcription. In particularry the SUBSCRIPTION table does not play role in this.

Each maillist defined via item having type DIGEST_TEMPLATE. These items have Template content type, so maillist item must have template type equal MAILLIST. Some of this item's attributes have special meaning.

OLD_URL and PARAMS must not be emty. OLD_URL in such an template contains ``as is'' email address of this maillist. The PARAMS contains filter expression for selecting items to be sent into the list. This filter will be executed in the context of this DIGEST_VARIANT item.

How does it work

cmwmaild finds all subscriptions corresponding to the PERIOD. Each subscription variant defines an item defining context, a filter that fetches information for this variant and a template that presents this information to subscribers (for example, item may be some article, filter may fetch all the comments to that article, and template may format them in a tree-like form). cmwmaild runs each filter providing it with ITEM_ID, PERIOD_START and PERIOD_END context parameters. ITEM_ID is the ID of the document item. PERIOD_START is the starting time for current period, and PERIOD_END is its end.

cmwmaild finds all items which were modified after time written in a LAST_SENT field of the corresponding row of the SUBSCRIPTION_PERIOD table except of written in last few minutes (this time buffer allows an author to correct just-after-posting-noticed errors in his/her article). A length of this time buffer is specified by GRACE parameter of a communiware configuration. A default value of GRACE is 15 minutes.

All the found items cmwmaild sends to users which are subscribed to the updates with given period.

In the template itself ::Mail filter must be specified in place of the filter placed in PARAMS field since cmwmaild will check which of selected items the users are really allowed to read.

cmwmaild updates a LAST_SENT field of the corresponding row of the SUBSCRIPTION_PERIOD table writing ``current'' time (i.e. time GRACE before current) in it.

FOR DESIGNERS

This section is destined for template designers and describes what data cmwmaild uses and how.

Templates and filters.

Special templates must be prepared for subscriptions. For public and personalized subscription methods (on this methods see below) one template can be used for some different subscriptions (these subscriptions must have different ITEM_IDs), but each different maillist subscription requires special template (in fact - special item of DIGEST_VARIANT type).

A template determains a view of messages subscribers will receive.

Somewhere in a template you must use ::Mail filter. This filter selects a list of items which actually will be sent. It has no parameters. A data for will be prepared by cmwmaild using another filter which must be specified in a PARAMS attribute of the template.

This second filter must actually select a list of items from Communiware. In cases of public and personalized subscribtions it probably have to use ITEM_ID context attribute.

In all three methods filter have to use following context attributes.

SERVER
Specifies a name of a communiware server to use.

PERIOD_START and PERIOD_END
Specifies a period of posting. This attributes have type of DATE and can be compared with any date type attribute of item. Usualy they compares to PUBLISHED, LASTCHANGE or STATUS_UPDATE attributes.

Mail formats.

Field FORMAT_ID of SUBSCRIPTION table indicates which format of message is prefered by subscriber. Now cmwmaild suports only TEXT/HTML and TEXT/PLAIN values of this field (the supported values must be enumerated in the MAIL_FORMAT table). w3m program is required for text convertion from HTML (standard message format in communiware) to plain text. It can be downloaded from http://ei5nazha.yz.yamagata-u.ac.jp/~aito/w3m

cmwmaild will convert text only if content have text/html format (this format is default and will be implied if no format specified in template) and the user requests for a plain text message format.

Template designer is free to implement other formats (such as WML or something else) as long as he/she provides correct 'Content-Type' header field.

Message header fields processing.

By default cmwmaild generates these values for message header fields:

  Subject:      Server-name: Template-title "Item-title"
  From:         Server-name server <announce@hostname>
  To:           announce@hostname
  Content-Type: text/html

(See above on the values of 'TO' field for methods 2 and 3 and where real adresses are placed for a method 1.) 


Template designer can override these values using E<lt>:Header:E<gt> dynamic elements.

In case of mailing to mailing list there is no ``Item-title'' so default Subject field value is ``Server-name: Template-title''. Designer must write appropriate template title or override it by Header dynamic element ``Subject''. 


Cmwmaild strips out all subfields (such as 'charset') from Content-Type
field value defined by designer and adds it's own subfield 'charset', 
taking it's value from Communiware configuration.

Cmwmaild fills Length and Encoding fields ignoring their values defined in template. It uses thees values: Length: length of context prepared by communiware Encoding: 8bit

All other fields defined in template using Header dynamic elements will be written into the message too.

Attributes used

Some attributes of a template item used for subscription have special meaning.

TEMPLATE_TYPE
This attribute is used to specify a subscription method this template used for.

PARAMS
Here is filter for items selecting stored. cmwmaild uses this filter for pre-selecting items and, after an allowance checking, prepares a list of items for ::Mail filter (which is a perl module). Designers must use ::Mail filter in templates and specify real filter in PARAMS field.

TITLE
cmwmaild uses this field for default message subject creation. Designer can specify subject explicitly in template using Header dynamic element.

STATUS
In case of the maillist subscription method this field is used for the subscriprion period value.

OLD_URL
In case of the maillist subscription method this field is used for the E-mail adress of the mailing list messages are sending to.

DEBUGGING

You can use -d option to run cmwmaild in the debugging mode. In this mode you will see some more log-messages. Also all output will be placed in send_tmp file, not piped to sendmail, and LAST_SENT field of SUBCRIPTION_PERIOD table for given PERIOD will not be updated (so you can re-start cmwmaild again with the same items to send).

You can add -n option to -d if you wnat cmwmaild not to send prepared message.

You can ask cmwmaild to override the start time of mailing period (originaly taken from LAST_SENT field) by -t or -T option, and force this overriding by -f option. Look OPTIONS for more information.

You can override lists of recipients, digest variants and subscribed items by --addressee, --variant and --item accordingly (descriptions of these options see above). For example:

 cmwmaild -d -T 10 -A testuser1,testuser2 \
 -I somesite1,somesite2 \
 -V ss1_news_dv,ss2_announce_dv WEEKLY

This starts cmwmaild in debug mode, start time will be shifted back to 10 days, subscriptions will be processed only for sites somesite1 and somesite2, and only for testuser1 and testuser2. Also, will be processed only subscriptions which uses ss1_news_dv and ss2_announce_dv digest variants.

INTERNALS

process_user_subscriptions

Scans database for all subscriptions with period equial to current period and calls make_letter for each case where unique letter is required (i.e. each for each tuple (template_id, item_id, format) for non-personal subscription and each record in subscription table for personal ones.

make_letter

Arguments item_id, template, format filter, flag indicating that author_id should be in the context, and list of user item_ids.

Executes passed filter Checks whether letters are to be generated and sends a mail.

check_access

Recieves result of filters fethcall_arrayref and reference to list of users. Returns array of hashes each of which has element 'items' containing subset of filter results, visible for some group of users and element 'users' containing reference to array of those users.

process_maillists

process_maillists($period)

prepare_maillist_message

 prepare_maillist_message($item,$filter)

Executes filter and retains only public items in its result stores it for future use in ::Mail and returns true, if result is not empty

SEE ALSO

crontab(8), cmwcronctl(8), Communiware::Mail(3), Communiware::DE::Subscribe(3)``Communiware Database Format manual''

16 октябрь 2007 13:45