Sun Java System Calendar Server 6 2005Q4 Administration Guide

Notification Messages

Calendar Server sends the types of email messages described in Calendar Server Mail Parameters. The format of these messages is controlled by the associated format (.fmt) file listed in the table. Format files are located in specific directories for each locale (such as /en for English and /fr for French) in the following directory:

/etc/opt/SUNWics5/config

For example, the English version of the task (todo) alarm message format is specified in the file:

/etc/opt/SUNWics5/config/en/mail_todoalarm.fmt

This section describes:

Calendar Server Mail Parameters

The following table shows the message type, parameter name, default format file description, and recipient for each Calendar Server Mail parameter.

Table E–30 Calendar Server Email Formats in the ics.conf File

Message Type  

Parameter 

Format File (default)  

Description 

Recipients  

Event Publish 

calmail.imipeventpublish.fname

"mail_eventpublish.fmt"

Announces an event or a change to an existing event 

Those listed in Notification 

Event Cancel 

calmail.imipeventcancel.fname

"mail_eventcancel.fmt"

Announces an event cancellation 

Those listed in Notification 

Reply to Event 

calmail.imipeventreply.fname

"mail_eventreply.fmt" 

Replies to an event notification. 

Those listed in Notification 

Request Event 

calmail.imipeventrequest.fname

"mail_eventrequest.fmt" 

Subscribes to an event notification. 

Those listed in Notification 

Event Alarm 

calmail.eventreminder.fname

"mail_eventreminder.fmt"

Reminder for an upcoming event 

Those listed in Reminder 

Recurring Event Notification 

calmail.imipeventnotificationrecur.fname

“mail_eventnotificationrecur.fmt” 

Notifies of a recurring event 

Those listed in Notification 

Event Cancel Notification 

calmail.imipeventcancelnotification.fname

“mail_eventcancel notification.fmt” 

Notifies of a cancelled event 

Those listed in Notification 

Recurring Event Cancel Notification 

calmail.imipeventcancelnotificationrecur.fname

“mail_eventcancelnotificationrecur.fmt” 

Notifies of a cancelled recurring event 

Those listed in Notification 

Task Publish 

calmail.imiptodopublish.fname

"mail_todopublish.fmt"

Announces a task or a change to an existing task 

Those listed in Notification 

Task Cancel 

calmail.imiptodocancel.fname

"mail_todocancel.fmt"

Announces a task cancellation 

Those listed in Notification 

Reply to Task 

calmail.imiptodoreply.fname

"mail_todoreply.fmt" 

Replies to a task notification 

Those listed in Notification 

Todo Request 

calmail.imiptodorequest.fname

"mail_todorequest.fmt" 

Subscribes to a todo notification. 

Those listed in Notification 

Task Alarm 

calmail.todoreminder.fname

"mail_todoreminder.fmt"

Reminder for an upcoming task 

Those listed in Reminder 

Calendar Server generates notification messages by combining a particular event or task with the contents of a format file. The values of data fields within an event or task can be output to the message. The notification message can also include MIME header lines and associated special values. Using special character sequences (format notations), you can include the values of events, tasks, and MIME headers in the message. The lines in the format file are format strings comprised of special character sequences that are replaced with actual values from calendar data fields when the mail message is generated. Special character sequences consist of two characters, the first is the percent sign (%) and the second represents the specific format notation.

The following sections describe special character sequences:

Special Character Sequences for Events

The following table shows the format code and meaning for Special Character Sequences for Event Notifications.

Table E–31 Special Character Sequences for Event Notifications

Format Code  

Meaning  

%0 

Start time in localized format 

%1 

End time in localized format 

%A 

exdates in iCalendar format (semicolon-separated list of ISO 8601 date strings listing dates to exclude) 

%a 

rdates in iCalendar format (semicolon-separated list of ISO 8601 date strings listing recurrence dates) 

%B 

Start time (also see %Z) 

%b 

Output the start time and end time in iCalendar format. If the start time has the parameter value=date, only the month/day/year portion of the date is output. If end time has the same month/day/year value as the start time, only the start time is generated. 

%C 

Create time 

%c 

Event class 

%d 

Event description. (also see %F) 

%E 

End time (also see %Z) 

%e 

Exception rules in iCalendar format 

%F 

Event description - folded line / iCalendar format (also see %d) 

%G 

The event's geographic location (latitude and longitude) 

%g 

Organizer's email address. (There is no guarantee as to the authenticity of this value.) 

%K 

Organizer email in the form of a mailto:url 

%k 

Alarm count 

%L 

Location 

%l 

Recurrence rules in iCalendar format 

%M 

Modify time 

%N 

New line 

%n 

The current time stamp used with DTSTAMP

%P 

Priority 

%r 

Recurrence id (blank if this event does not recur) 

%S 

Event sequence number 

%s 

Summary 

%t 

Event status 

%U 

Unique Event Identifier 

%Z 

Used in conjunction with the time field code to force the time to be rendered in UTC. (%B displays the start time in local time whereas %ZB displays the start time in UTC time.) 

%% 

Displays the percent (%) character 

% (sub-format code) 

Specifies a sub-format for the data identified by code. (For details, see Date Sub-Formatting.)

Date Sub-Formatting

Date-time values can be formatted in many different ways. Using a sub-format, you can provide additional information to describe how a date-time value should be formatted. If a sub-format is not specified, the server uses a default format to output the date. Using a sub-format field allows you to specify the exact format to be used.

For example, %B specifies that the output string includes the event's begin time. This default format prints out the date, time, the time zone, and everything possible about the date. The sub-format string for date values is a strftime format string (see Special Character Sequences for Dates). If you were only interested in the month and year of the start time, instead of %B, you would use: %(%m %Y)B.

Example

The following example:


The event begins: %B%N
 The event ends: %(%b %d, %Y %I:%M %p)E%N

produces output that resembles the following notification:


The event begins Feb 02, 1999 23:30:00 GMT Standard Time
 The event ends Feb 03, 1999 02:30 AM

Conditional Printing

Sometimes it is desirable to print a line only under certain conditions. For example, the following lines:


title: %S%N
 start: %B%N
 end: %E%N  

produce output that resembles the following notification:


title: Staff Meeting
 start: Feb 04, 1999 09:00:00
 end: Feb 04, 1999 10:00:00 

There are two conditions, however, where the above example would yield misleading or incorrect results:

In these situations, it is best not to print the end time at all. By default, only the year, month, and day are printed when a time stamp has the attribute of being all-day. Furthermore, if an event start time has the all-day attribute and the event ends on the same day as it starts, a special conditional flag is set. Use the ? modifier to print conditional values only when the special conditional flag is not set.

For example, if you change the lines in the above example to:


title: %S%N
 start: %B%N
 end: %?E%N 

The last line will not be printed for all-day events for which the start day and end day are the same. It produces the following output for typical all-day events (such as birthdays or anniversaries):


title: Staff Meeting
 start: Feb 04, 1999

The ? flag can be combined with other modifiers. For example:

The event ends: %?(%b %d, %Y %I:%M %p)E%N

Special Character Sequences for Task Notifications

The following table shows the format code and meaning for Special Character Sequences for Task Notifications.

Table E–32 Special Character Sequences for Task Notifications

Format Code  

Meaning  

%A

exdates in iCalendar format (semicolon-separated list of ISO 8601 date strings listing dates to exclude)

%a

rdates in iCalendar format (semicolon-separated list of ISO 8601 date strings listing recurrence dates)

%B

start time (also see %Z)

%C

create time 

%c

task class 

%D

due date and time. 

%d

task description. (also see %F)

%E

due date and time in IMIP format 

%e

exception rules in iCalendar format 

%F

task description - folded line, iCalendar format (also see %d)

%G

this task's geographic location, the latitude and longitude. 

%g

organizer's email address (cannot guarantee the authenticity of this value) 

%K

organizer’s email in the form of a mailto:URL

%k

alarm count 

%L

the location 

%l

recurrence rules in iCalendar format 

%M

modify time 

%N

a new line 

%n

"now" (the current time stamp and used with DTSTAMP)

%P

priority 

%r

the recurrence ID (blank if this task does not recur) 

%S

is the task’s Sequence Number 

%s

summary 

%t

the status 

%U

the UID

%Z

used in conjunction with time field code to force the time to be rendered in UTC (%Bdisplays the start time in local time whereas %ZB displays the start time in UTC time)

%%

displays the % character

% (sub-format code)

specify a sub-format for the data identified by code (for details, see Date Sub-Formatting)

Special Character Sequences for Dates

The following table shows the format code and meaning for Special Character Sequences for dates.


Note –

The special date format codes appear in this section only for convenience. Calendar Server does not rewrite any of the codes, but simply uses the operating system implementation.


Table E–33 Special Character Sequences for Dates

Format Code  

Meaning 

%a

Abbreviated weekday name 

%A

Full weekday name 

%b

Abbreviated month name 

%B

Full month name 

%c

Date and time representation appropriate for locale 

%d

Day of month as decimal number (01 - 31)

%H

Hour in 24 hour format (00 - 23)

%I

Hour in 12 hour format (01 - 12)

%j

Day of year as decimal number (001 - 366)

%m

Month as decimal number (01 - 12)

%M

Minute as decimal number (00 - 59)

%p

Current locale's A.M./P.M. indicator for 12 hour clock 

%S

Second as decimal number (00 - 59)

%U

Week of year as decimal number, with Sunday as first day of week (00 - 53)

%w

Weekday as decimal number (0 - 6; Sunday is 0)

%W

Week of year as decimal number, with Monday as first day of week (00 - 53)

%x

Date representation for current locale 

%X

Time representation for current locale 

%y

Year without century, as decimal number (00 - 99)

%Y

Year with century, as decimal number 

%Z

Time-zone name or abbreviation; no characters if time zone is unknown 

%%

Percent sign 

Simple Event Reminder Example

The following example shows the default event reminder message format:


1  EVENT REMINDER
 2  ~~MIME-Version: 1.0%N
 3  ~~Content-Type: text/plain; charset=%s%N
 4  ~~Content-Transfer-Encoding: %x%N%N
 5      Summary: %s%N
 6        Start: %(%a, %d %b %Y %I:%M %p)B%N
 7        End: (%a, %d %b %Y %I:%M %p)E%N
 8      Location: %L%N%N
 9  Description: %N%d%N

         

The description of each line in this example is:

The following sample resembles the notification message generated by the above example:


From: jsmith@sesta.com (James Smith)
 Date: Wed, 15 Nov 1999 19:13:49
 To: jsmith@sesta.com
 Subject: EVENT REMINDER
 MIME-Version: 1.0
 Content-Type: text/plain; charset=us-ascii
 Content-Transfer-Encoding: 7bit
   Summary: smtp_rig event 1
       Start: Tues, 16 Nov 1999 02:00 PM
       End: Tues, 16 Nov 1999 03:00 PM
   Location: Green Conference Room
   Description: This is the description for a randomly generated event.

Complex Event Reminder Example

The following example shows a more complex multipart message. This example has a text part and an IMIP PUBLISH part.


EVENT PUBLICATION
 ~~MIME-Version: 1.0%N
 ~~Content-Type: multipart/mixed; boundary="%b"%N%N
 This is a multi-part message in MIME format.%N
 ~~--%b%N
 ~~Content-Type: text/plain; charset=%s%N
 ~~Content-Transfer-Encoding: %x%N%N
     Summary: %s%N
       Start: %(%a, %d %b %Y %I:%M %p)B%N
       End: %(%a, %d %b %Y %I:%M %p)E%N
     Location: %L%N%N
    Description: %N%d%N%N
 ~~--%b%N
 ~~Content-Type: text/calendar; method=%m; component=%c; charset=%s%N
 ~~Content-Transfer-Encoding: %x%N%N
 BEGIN:VCALENDAR%N
PRODID:-//iPlanet/Calendar Hosting Server//EN%N
 METHOD:PUBLISH%N
 VERSION:2.0%N
 BEGIN:VEVENT%N
 ORGANIZER:%K%N
 DTSTAMP:%Zn%N
 DTSTART:%ZB%N
 DTEND:%ZE%N
 SUMMARY:%s%N
UID:%U%N
 %R
 %A
 %a
 %e
 %l
 SEQUENCE:%S%N
 LOCATION:%L%N
 GEO:%G%N
 %F
 STATUS:%t%N
 END:VEVENT%N
 END:VCALENDAR%N
 ~~--%b--