TOC PREV NEXT INDEX

Wireless Data Server 3.0 Beta

Administrator's Guide

View in pdf format
Go to User's Guide


The calendar service

In order to use the calendaring features of Wireless Data Server, you must configure your calendar server and Wireless Data Server to communicate with each other. In addition, you should consider a number of other options for configuring your services.


Setting up the calendar server

When delivering notifications and reminders, the calendar server communicates with Wireless Data Server over SMTP using the smsnotify utility, available on Steltor's Web site at www.steltor.com. For full installation instructions, see the smsnotify readme.

You must provide the location and filename of this utility, as well as the name of the Wireless Data Server host, in the calendar server's unison.ini file, using the [CWS] smsnotifyprogram and smsnotifyprogramparam parameters. Use the syntax "-host <hostname>" to specify your Wireless Data Server host in the smsnotifyprogramparam parameter.

When the calendar server has a notification or reminder to send, it will construct and execute a command line using the values of the smsnotifyprogram and smsnotifyprogramparam parameters. For example, if smsnotifyprogram were set to /users/unison/smsnotify/smsnotify and smsnotifyprogramparam were set to "-host nebula", the resulting command line would include:

/users/unison/smsnotify/smsnotify -host nebula

You should also consider setting the unison.ini [CWS] noreqsleep parameter to a lower value, such as 5. This will cause the calendar server's Corporate-Wide Services daemon/service to sleep for a shorter time between checks for new notifications and reminders, potentially improving performance. This is especially useful when testing Wireless Data Server, as calendar notifications are processed more quickly.

Once you have set these values, enable the smsnotify utility by setting the unison.ini [NOTIFY] sms parameter to TRUE. This will turn notifications and reminders on for both Short Message Service and Instant Messaging delivery. For more details on all the parameters discussed, consult Reference Appendix B of your calendar server's Reference Manual, available on Steltor's Web site at www.steltor.com.


Setting up connections to the calendar server

In order to provide wireless calendaring services to a node or a number of nodes on a Steltor calendar server, you must set up Wireless Data Server with a separate connection to each node. Each of these connections is represented by a separate section within the etc/config/wds.ini file.

These sections can have any name you choose; for ease of management, try to select a section name descriptive of the connection configured in that section. For example, a section configuring a connection to node 34 of a calendar server on host "punch" might be titled [PUNCH34].

Within each section, you must include parameters to specify the node-ID, host name and SYSOP password of the node you want to connect to using the [<UNISON>] node, host and passwd parameters. The node and host parameters can be set directly in the wds.ini file, but you must use the cspassword utility to encrypt and set the SYSOP password. For more details on the cspassword utility, see Appendix B, "Server utilities."

In addition, you must include the name of the section configuring each node connection in the value of the [WDS] unisonconnections parameter. This parameter tells Wireless Data Server explicitly what connections it should instantiate at startup.

A sample wds.ini file configuring two connections, one to node 45 of a server called "scribe", and the other to node 2002 of a server called "groovy" listening on port 2143, might have the following sections and parameters:

[WDS]

unisonconnections = { SCRIBE45, GROOVY2002 }

[SCRIBE45]

host = scribe

node = 45

password = 04570f6f6638600865

[GROOVY2002]

host = groovy:2143

node = 2002

password = 04250f796b4a6818664a601e65


Configuring the calendar service

There are other configuration options you may wish to explore when setting up your Wireless Data Server's calendar service.

Accepting and declining new meetings

If you use Wireless Data Server in a group scheduling environment (as is typically the case with CorporateTime Server and Lexacom Enterprise Calendar Server), you will probably want to give users the ability to respond to notifications of newly created meetings.

If you enable this feature, all text notifications of newly created meetings will contain the string CAL M ? at the beginning of the message, and all vCalendar notifications will have a ? character at the beginning of the title. Users can accept or decline the new meeting by modifying the ? character to either a + character or a - character and sending the message back to Wireless Data Server. Users can also change their attendance status back to unconfirmed by changing the character back to a ? and sending the message back to Wireless Data Server.

To enable the accept and decline feature, set the value of the wds.ini [WDS] confirmcalevent parameter to TRUE.

NOTE:

Nokia 90xx phones have an entirely different accept and decline mechanism, built into the phone itself. Upon receipt of the calendar notification, the phone will ask the user to indicate his or her attendance status, and will relay the result automatically to Wireless Data Server. The CAL M ? string is omitted.

The calendar user cache

Each time Wireless Data Server receives a mobile-originated message, it has to query the calendar server to determine which user account the request is from. To increase performance and avoid making a request on the calendar server every time, Wireless Data Server maintains a cache of the mapping between requesting MSISDN numbers and corresponding calendar server user accounts. See the documentation on the wds.ini [WDS] unisoncachesize parameter in Appendix A, "Server parameters."


Configuring output

Customizing message formats

When the calendar server sends a reminder or notification using smsnotify, Wireless Data Server first converts the content of the message into an XML structure, and then processes that XML using a stylesheet script. You can modify the output of Wireless Data Server's reminders and notifications by making the appropriate modifications to the stylesheet.

Calendar notification XML structure

The XML structure used by Wireless Data Server to represent calendar notifications is shown by a sample file, /etc/template/calendar_notif.xml.

Not all elements in the XML structure will always be present; if the calendar server has no values to put in the following elements, they will simply be omitted from the XML structure:

Some elements have a limited number of possible fixed values. These are:
Table 2.1 ·
XML element Possible values
<event type="meeting" status=""> created modified canceled
<access> Personal Confidential Normal Public
<importance> Highest High Normal Low Lowest
<confirmation> Tentative Accepted Declined

Calendar notification XSL template

The default script that Wireless Data Server uses to process the calendar notification XML structure into vCalendar, plain-text SMS and plain-text IM messages is /etc/template/calendar_notif.xsl. The script used can be specified using the /etc/config/wdstemplate.ini [CALENDAR] NOTIFICATION parameter.

The default calendar notification XSL template creates very different output depending on whether the message is to be delivered by SMS in plain text or vCalendar format, or by in Instant Messaging. For each different output format, the calendar_notif.xsl file imports another template file.

The next lines of the calendar_notif.xsl file import the different templates. You are free to modify the calendar_im.xsl template, which creates the output format for messages to be delivered by Instant Messaging, and you are free to modify the calendar_sms_text.xsl template within the display limits imposed by recipients' phones. However, it is strongly recommended that you not change the calendar_sms_vcal*.xsl files, as even small changes could make the resulting messages unusable to the recipients' phones.

The following section of the file determines which template to use based on the value of the Output-Media-Type, Mobile-Device-Type and Mobile-Content-Type parameters. These parameters are passed to Wireless Data Server by the calendar server according to the wireless notification preferences of the intended recipient of the notification.

Wireless Data Server provides you with a number of such parameters you can use in creating your own calendar notification templates:

Wireless Data Server also provides a number of proprietary functions that extend the capabilities of the XSL template processor. For more details on these functions, see Appendix D, "Wireless Data Server XSLT extension functions."

For more information on the language and syntax of XML stylesheets, see the standard documentation available at http://www.w3c.org. Wireless Data Server incorporates the Xerces C++ parser and Xalan C++ processor from the Apache Group; for more information, see http://xml.apache.org.

Testing output

Use the wdschkxsl utility provided with your Wireless Data Server package to test the output of your XML stylesheets. This utility allows you to check the output of any template, given any XML input document. For more details on the wdschkxsl utility, see Appendix B, "Server utilities."

Calendar reminders

In contrast to calendar notifications, which are processed using the script specified by the /etc/config/wdstemplate.ini [CALENDAR] NOTIFICATION parameter, Wireless Data Server processes calendar reminders as plain-text, using the script specified by the /etc/config/wdstemplate.ini [EMAIL] PLAINTEXT parameter. The modifications you can make to the output format of calendar reminders are correspondingly limited: any content may be inserted before and after the body of the reminder information sent by the calendar server, but that chunk of text may not be changed by the script.

Multiple language support

A single instance of Wireless Data Server can deliver messages in multiple languages, depending on the recipients' profiles set on the calendar server. When the calendar server sends a reminder or notification to a user, it specifies that user's preferred language (available to XSL templates through the Output-Language parameter, as described above).

Consult your calendar server documentation for details on setting user language preferences through the users/unison/misc/user.ini file and the uniuser utility.

If that language is supported by Wireless Data Server, the user will receive the message in the selected language. If not, Wireless Data Server will use its default language. The supported and default languages can be found in the /etc/config/wdslocale.ini file.

Customizing multiple language support

You can customize the text Wireless Data Server writes in mobile-terminated reminders and notifications, as well as the commands used for mobile-originated querying of calendar information through Wireless Data Server.

Mobile-originated commands

To modify the commands used for querying information from the calendar server, override the appropriate parameter in the /etc/config/callocale.ini file, within the section corresponding to the desired language. For example, by default a user would normally send an SMS with the command CAL S 1 to query the calendar server for a day's information. If you want French users to be able to use the command AGEN J 1 instead, simply add the following parameters:

[FRENCH]

SERVICE-KEY = "AGEN"

CMD-SNAPSHOT = "J"

The callocale.ini file lists the parameters available for customizing Wireless Data Server commands, with their default values.

Mobile-terminated messages -- SMS

All text written in SMS messages by Wireless Data Server is taken from localization files in the /etc/locale directory. The Wireless Data Server XSL templates include these values when processing outgoing messages by using the locale-string() function. This function returns a specified string from the localization file corresponding to the specified language. This allows Wireless Data Server to use the same template for all languages it supports.

For example, the stylesheet that generates plain-text SMS includes the lines:

<xsl:value-of select="wds:locale-string($Output-Language, 'GLOSSARY', 'CREATED-BY', 'Created by')"/>

<xsl:text>&#x20;</xsl:text>

<xsl:value-of select="/calendar/event/creator"/>

The locale-string() function in this case includes the value of the CREATED-BY parameter in the GLOSSARY section of the localization file that corresponds to the current user's specified output language. These lines render as follows for an English user:

Created by

Boris Pasternak

For an Italian user, on the other hand, the same lines render as:

Creato da

Boris Pasternak

For full details on the use and syntax of the locale-string() function, see Appendix D, "Wireless Data Server XSLT extension functions."

Mobile-terminated messages -- IM

The locale-string() function is not used for messages delivered through Instant Messaging. Because space is not limited as it is in phone displays, you have complete freedom to create your own templates for non-English messages.

To create your own Instant Messaging template for a given language:

  1. Copy the English template provided in the /etc/template/calendar_im.xsl file. This section begins with:
    <!-- **** English template **** -->

    and ends with:
    </xsl:template>

    Paste these lines back into the same file, following the last line of the English template.
  2. In the template you just pasted, change the first line to:
    <xsl:template name="generate-im-<language>"/>

  3. Replace the English strings (contained between <xsl:text> and </xsl:text> tags) with the desired strings in your language of choice, and update the template with any other modifications you want to make.
  4. Copy lines 8-10:
    <xsl:when test="$Output-Language = 'ENGLISH-US'">

    <xsl:call-template name="generate-im-english"/>

    </xsl:when>

    Paste the lines back in immediately following line 10.
  5. Change the ENGLISH-US value in line 10 to your language of choice, as specified in the /etc/config/wdslocale.ini [WDS] locales parameter.
  6. Change the generate-im-english value in line 11 to the name of the template you created in step 2.

Steltor
http://www.steltor.com
Voice: (514) 733-8500
Fax: (514) 733-8878
info@steltor.com
TOC PREV NEXT INDEX
 
Copyright information