Domino Connection


Understanding mail

Depending on the server configuration, Domino supports multiple mail protocols (like POP3 and SMTP) and supplies its own mailing facility. The VisualAge Smalltalk Domino Connection supports the built in mail system that is based on Domino databases. To integrate mail with the Domino Connection, make sure your Notes clients and the Domino servers are set up to support Notes Mail.

An important database in the Domino mail system is mail.box. If you want to send a document, you have to copy it to this database. The router task scans that database and delivers it to either the personal mail database of the recipient or to another server database for further routing. Depending on the mail setup (local or remote) the mail.box database is located on your Notes client or on a Domino server. To enable the router to determine the mail destination, you have to include a text field (either AbtLnItemText or AbtLnItemTextList) named "Recipients" in your document. The field must contain one or more valid mail addresses.

Note:In a typical mail document you will not find a Recipients field. This is because the Notes client software translates your entries from the SendTo, CopyTo and BlindCopyTo fields into an invisible Recipients field before the note is copied to the mail.box.

To find out which recipients can be reached from your mail domain, Domino utilizes the names and address book (usually called names.nsf). There are views in the names and address book which can be referenced to find valid recipients.

A third database is involved in a mail transfer: the users mail database. It serves as a message store and implements the mail applications when you use the Notes client. The personal mail database also serves as host database for the personal calendar and the user's ToDo list.

When you are disconnected from your mail server (this is the case when you use a "travel" or "island" setup), your mail.box is located on your Notes client installations data directory. On LAN based installations you will find your mail.box on the Domino mail server. If you are not sure about the mail server, ask your Domino administrator or look at your notes.ini. There is a entry named MAILSERVER which specifies the name of the server where your mail.box is set up.

Using the names and address book

The best source for valid address information is the names and address book. Typically you have a local names and address book on your workstation and one or more address books on the servers. Depending on your Domino installation's domain concept you may have access to one or more of those databases. There is a method to find out about the existence of names and address books on every machine you can connect to. Use the AbtLnConnection method addressBookNames to receive an OrderedCollection of database path names.

After selecting one address book, you can retrieve data from different views, depending on your addressing scheme. The following code sample gives you an impression on how to access mail addresses on a mail server.

Note:You have to have at least "reader" access to your names and address book to perform the following sample code successfully.
| connection namesAndAddressBook addressView
itemName columnDescription validNames viewNote |
"Startup runtime system"
AbtLnEnvironment startUp.
 
"Create a connection to your mail server"
connection := AbtLnConnection mailServer.
 
"Open the first of the available Name and Address books on the mailserver"
namesAndAddressBook := connection
openDatabase: (connection
addressBookNames first).
 
"Retrieve a view note"
viewNote := namesAndAddressBook viewNoteByName: 'People'.
 
"Open the corresponding view"
addressView := namesAndAddressBook openViewNoUpdate: viewNote title.
 
"Find the column that contains address information"
columnDescription := viewNote columnFormats detect: [ :column |
column title = 'E-Mail' ] ifNone: [nil].
 
"Find out the internal name of the item displayed in the address
column"
columnDescription isNil
ifFalse: [ itemName := columnDescription itemName ].
 
"Return a list of valid recipients, that is the contents of the
address column"
validNames := addressView root children collect: [ :pseudoNote |
pseudoNote pseudoNote at: itemName ].
 
"Print the names with domain information on the Transcript window"
validNames do: [ :name |
Transcript nextPutAll: name;cr.].
 
"Clean up open handles. Close view and database"
addressView close.
namesAndAddressBook close.
 
"Shut down runtime system"
AbtLnEnvironment shutDown.

The variable 'validNames' contains an OrderedCollection of Strings which represent full mail address definitions (First Name, Name, MailDomain). If you need an other address format you can select other columns from other views.

You do not have to pick your recipients from the names and Address book, you can set the recipients field to any String if you are sure about the address. Domino Connection offers a special class to access cached address information from the Domino names & address book to verify that certain recipients can be reached. The class is called AbtLnNameLocator. To operate the locator you have to get used to two more classes: AbtLnNameSpace and AbtLnLookupResult. The name locator is capable of finding out information which is present in certain views of names and address books on any server you can reach. The locator must be configured with one or more namespaces (which kind of represent views in a name and address book) and a domain (which represents a Domino server, not to confuse with Mail domains). You can then pass one or more intended recipients to the locator and send the lookup message. The locator returns a collection of AbtLnLookupResults which can be queried for some details about the found names and address book entries.

Here is a step-by-step example how to find out about your own names and address book entry on your mail server:

| locator nameSpace |
"Start runtime system"
AbtLnEnvironment startUp.
 
"Instantiate a locator on your mail server"
locator := AbtLnNameLocator new
domain: AbtLnConnection mailServer server.
 
"Configure the locator with the User namespace and specify details to
be checked"
locator addNameSpace:
(AbtLnNameSpaceUser new
fullName;
mailAddress;
mailFile;
shortName).
 
"Set your user name to be checked by the locator"
locator find: AbtLnEnvironment currentUserName.
 
"Run the locator and print results on the Transcript window"
locator lookup do: [ :lookupResult |
Transcript nextPutAll: lookupResult printString ].
 
"Shutdown runtime system"
AbtLnEnvironment shutDown.

This function is very useful if you want to have quick access to names and address information. It is much faster that opening a view and you can search on a number of address books on one server at a time.

Routing and domains

It is possible to send cross domain mail and even mail to non-Domino mail domains from Smalltalk and VisualAge if your Domino server is prepared to do that. See your Domino documentation and ask your administrator about mail routing and domains.

Smalltalk mail classes

Here is a step-by-step example showing how to send a mail document using the Smalltalk classes provided with VisualAge Smalltalk Domino Connection. For this example it is assumed that you have a Notes client workstation set up to server-based mail (which is the common setting for a LAN based installation).

As stated before, the mail system is based on standard Domino databases. You will not need to learn any new classes or techniques to send mail.

Sending mail

To send mail and store a mail document in your mail database, you need to have access to two databases: mail.box and yourmail.nsf (where yourmail is presumed to be the name of your mail file). For a LAN based setup you will find both databases on your Domino mail server.

Note:You must at least have depositor access to the mail box database to pass a document to the mail router.

You will create a new document in your mail file using the simple newNoteFromComputedForm: method implemented in AbtLnDatabase and then you will fill in the necessary information to send a mail. The document will be stored in the mail box. The mail router will take care to deliver the mail.

| mailServerConnection mailFileName mailFile mailBox
localMemo mailMemo locator |
"Startup runtime system"
AbtLnEnvironment startUp.
 
"Create a connection to your mail server"
mailServerConnection := AbtLnConnection mailServer.
 
"Initialize a locator on your mail server"
locator := AbtLnNameLocator new domain: mailServerConnection server.
 
"Set up the locator to find out about mail file names"
locator addNameSpace: (AbtLnNameSpaceUser new mailFile).
 
"Set your user name to be checked by the locator"
locator find: AbtLnEnvironment currentUserName.
 
"Get your mail file name from the locator result. As you have only one mail file,
using 'first' is convenient and will work"
mailFileName := locator lookup first at: 'MAILFILE' ifAbsent: [nil].
 
"Open your personal mail file"
mailFileName notNil
ifTrue: [
mailFile := mailServerConnection openDatabase: mailFileName.].
 
"Open the mail server's mail box file"
mailBox := mailServerConnection openDatabase: 'mail.box'.
 
"Create a new document based on the 'Memo' form. Use the default value
formulas, and inherit field definitions"
localMemo := mailFile newNoteFromComputedForm: 'Memo'.
 
"Create a new document on the mail box on the server"
mailMemo := mailBox newNote.
 
"Set field values for the memo"
"Set recipients"
localMemo addTextListNamed: 'Recipients'.
localMemo at: 'Recipients' put: AbtLnEnvironment currentUserName.
 
"Set sendTo field - to be displayed in mail views and forms"
localMemo at: 'SendTo' put: AbtLnEnvironment currentUserName.
 
"Set a subject"
localMemo at: 'Subject' put: 'Test mail from Smalltalk to Domino'.
 
"Set contents of the mail body"
localMemo at: 'Body' put: 'This text is the mail body converted from ASCII to RTF
 
format.'.
 
"Copy the contents of the local memo to the memo created in the remote mail box"
"Do not use the itemDic: method in another context"
 
mailMemo itemDic: localMemo itemDic.
 
"Store the document in the mail box. This will pass it to the mail router"
mailMemo store.
 
"Close both databases"
mailFile close.
mailBox close.
 
"Shutdown runtime system"
AbtLnEnvironment shutDown.

The code above is a very simple approach to sending mail, and it will not satisfy all requirements that are imposed by recent mail database templates. Since the introduction of the Drafts, the Sent and the Inbox views in the mail template, you need to supply additional fields to make the mail documents show up in the appropriate folders. What follows is a short description of what is needed to implement mail that works in conjunction with a mail database of Domino or Notes Version 4.5 or later (changes that applied to templates in later Domino versions may require additional effort).

The Sent view
A mail document that is displayed in the Sent view must be stored in the users mail file and contain a field named PostedDate. The field should contain the actual date when the document was copied to the mail box file. Also the field named DeliveredDate must be absent or empty.

The Drafts view
A mail document is displayed in the Drafts view under the following conditions: The field named PostedDate is empty or not present, the field named $MessageType is empty or not present and the field named ExcludeFromView contains other values than the string "D".

SendTo, CopyTo and BlindCopyTo
Usually the Memo form displays values for To, cc and bcc (SendTo, CopyTo and BlindCopyTo). You have to supply the values for theses fields.

The following code sample shows you how to create a mail document that will comply with these requirements:

| mailServerConnection localMemo mailFile mailBox 
  mailMemo theRecipient theCopyRecipient theBlindCopyRecipient | 
 
"Start runtime system"
AbtLnEnvironment startUp. 
 
"name the recipients"
"change the names according to your requirements"
theRecipient := 'Rachel Hunter'. 
theCopyRecipient := 'Hendrik Hoefer'. 
theBlindCopyRecipient := 'Morgan Shrap'. 
 
"Create a connection to the default mail server"
mailServerConnection := AbtLnConnection mailServer. 
 
"open the router mail box file"
mailBox := mailServerConnection openDatabase: 'mail.box'. 
 
"open the mail file of the sender - that is the person who executes this
code"
"change that to your mail file if you want to execute the code"
mailFile := mailServerConnection openDatabase: 'mail\tester.nsf'. 
 
"create a new mail document in the mail box"
mailMemo := mailBox newNote.
 
"Add sender information"
mailMemo addTextNamed: 'FROM'. 
mailMemo at: 'FROM' put: AbtLnEnvironment currentUserName. 
 
"Create and set the sendTo field"
mailMemo addTextListNamed: 'SENDTO'. 
mailMemo at: 'SENDTO' put: (OrderedCollection with: theRecipient ).
 
 
 
"Create and set the copyTo recipient"
mailMemo addTextListNamed: 'COPYTO'. 
mailMemo at: 'COPYTO' put: (OrderedCollection with: theCopyRecipient ). 
 
"Create and set the blindCopyTo recipient"
mailMemo addTextListNamed: 'BLINDCOPYTO'. 
mailMemo at: 'BLINDCOPYTO' put: (OrderedCollection with:
theBlindCopyRecipient ). 
 
"Take care the mail router gets to know every intended recipient"
mailMemo addTextListNamed: 'Recipients'. 
mailMemo at: 'Recipients' put: 
   (OrderedCollection with: theRecipient 
        with: theCopyRecipient 
        with: theBlindCopyRecipient ). 
 
"Set the subject of the mail"
mailMemo addTextNamed: 'SUBJECT'. 
mailMemo at: 'SUBJECT' put: 'Here We Go...Again'. 
 
"Set the mail body"
mailMemo addTextNamed: 'BODY'. 
mailMemo at: 'BODY' put: 'Here we go '. 
 
"take care of the *draft* folder" 
mailMemo addTextNamed: 'ExcludeFromView'. 
mailMemo at: 'ExcludeFromView' put: 'D'. 
 
"Store the note in the router mailbox"
mailMemo store. 
 
"Take care of the *sent* folder, copy the note to the users mail file" 
localMemo := mailFile newNote. 
localMemo itemDic: mailMemo itemDic. 
 
"Fix the PostedDate field"
localMemo addTimeDateNamed: 'PostedDate'. 
localMemo at: 'PostedDate' put: (Array with: Date today with: Time now). 
 
"Store the document in the local mail file"
localMemo store. 
 
"Shutdown runtime system"
AbtLnEnvironment shutDown. 
 

Mail parts

To make sending mail easy and convenient for you, Domino Connection offers two non-visual parts: The Mail part and the Address Book part. If you run Notes Version 4.5 or later or Domino 4.5 or later, you should also review the section named Domino Connection Using mail. It contains information about how to create a mail applications that works in conjunction with version 4.5 and later mail databases.

Mail part (AbtNotesMailPart)

In principle, the mail part is a special kind of form part. The difference is, that it is connected to two databases, the mail file and the mail box. Depending on your system, you configure the mail part using the settings pages to connect to local or remote databases using the appropriate connection aliases. You also have to select a form definition for your mail document. In addition to that you might specify additional, user defined fields for the document to be created.

Address Book part (AbtNotesAddressBookPart)

The address book part is a convenient tool to find out valid recipients for your mail. It is not needed to have an address book part in every mail application, because if you are sure about mail addresses you do not have to double-check them with the address book contents. On the other hand it is a good practice to offer address book support for less experienced users.

Sending mail using the mail parts

Here is a step-by-step example showing how to create a simple mail application. For this example it is assumed that you have a Notes client workstation set up to server based mail (which is the common setting for a LAN based installation).

If you are using Domino Version 4.5 or later or Notes Version 4.5 or later, you should consider building the mail sample according to the description named Domino Connection Using Mail - additional version specific featured are added to ensure proper execution of that mail sample.

Depending on the settings in your Visual Organizer you will be prompted with either the notebook style settings pages (like in the example) or with the generic property list style window when you edit the part's settings. You will achieve similar results with both methods of configuring the part. If you cannot open the notebook style settings, you have to load the AbtEditNotesSettingsPagesApp using the Application Manager or the Visual Organizer.

  1. Create a application and a new visual part using the Visual Organizer.
  2. Create a connection alias to your personal mail file and name it ConToSampleMail. (If you do not know how to create a connection alias, see Domino Connection specification of this documentation). You will need a second connection alias to the mail server's mail.box file. Set up this connection as well and name it ServerMailBox.
  3. Select the mail part from the parts palette and drop it on the free from surface. Now set up the mail part's properties. The first notebook settings page sets up the connection to a mail database. The mail database is needed not only to store a document as a reference when it is sent, but also to retrieve form definitions for the mail. Open the mail file's settings page. Select the newly created alias and set Memo as the form to use.
  4. Now click the "Mail Settings" tab to continue configuring the mail part. On the second settings page, the connection alias for the mail.box file is specified. Use your newly created connection alias and set the other option on the settings page to your desire. The "Save in Mail File" option specifies whether a mail document produced with the mail part will be saved in the user's mail file when it is sent. Use the Add button to select those fields from the form which contain valid recipient names. On a normal Memo form select: SendTo, CopyTo, BlindCopyTo.
  5. If you want to add other fields to your mail, you can use the "User Defined Fields" tab to do so.
  6. Select the OK button to update the part and return to the Composition Editor.
  7. Now connect the openendWidget event of your application window to the open action of the mail part. Also connect the openendWidget event of your application window to the newMail action of the mail part to create a new mail document each time the window is opened.
  8. Now add two push buttons to your application window:
  9. Then tear off the currentNote attribute from the mail part and drop it on the free-form surface. The current note represents the actual mail document to be processed. There is a quickform feature for the current note. As an alternative to selecting the self attribute for quick form, which would create entry fields for every field specified in the Memo form, use some of the fields presented in the pop-up window:

Save the part and run the application. Send a mail to yourself an look into your personal mail file using the Notes client. You may notice that some of the elements of a regular memo are missing -- that is due to the fact that you have set up the mail part with a limited set of fields. When you use the mail part, you will also note that there is default behavior for some fields. For example, the From field is automatically set to the value returned from the class AbtLnEnvironment when you send the message currentUserName. You can override the default values. Send a mail to yourself and check the result with your Notes client.

In the next step you will expand the mail application and supply a list of valid recipients. To achieve this goal, you will add an address book (AbtAddressBookPart) to the free form surface.

The address book part is a special kind of view part. It must be connected to a names and address book database. Create a connection alias to your names and address book (or to the sample name and address book provided with the demo applications).

  1. Add an address book part to the free form surface for your application.
  2. Select the address book part and open the settings pages. On the General tab, you specify the connection for the address book and the view which provides the list of valid names. If you want to use the sample address book provided with Domino Connection, select the ConToAddressBook connection and the view named People.
    Note:Usually you can choose from a number of address books. You probably have a local name and address book on your workstation and one or more address databases on your mail server. Ask your system administrator which of the address books suites your needs.
  3. Use the second tab named Address Book to select a column from the Name and Address book view. If you use the sample database provided with Domino Connection, select the $16 column. If you are not sure which column to select, use the Notes client or Domino Designer to find out about the column names or analyze the view structure with the Smalltalk methods provided with the Domino Connection. Close the settings pages.
  4. Add an additional window to the free form surface of the composition editor. Drop a single list part into the new window and add a button labeled Close. Connect the clicked event of the button to the closeWidget action of the window and to the close action of the address book part. Connect the aboutToOpenWidget event of the window with the open action of the address book part.
  5. Connect the names attribute of the address book part with the items attribute of the list in the new window.
  6. Add a third button to the first window (which represents the memo form) and label it Find address. Connect the clicked event of that button with the openWidget action of the window containing the list.
  7. Finally connect the selectedItem attribute of the list to the object attribute of the memo forms entry field with the SendTo label. Save the part.

When you test the part, you will be able to open up the second window using the Find address button. It will display a list for recipients you can select from. Double-click the selection and the SendTo field of your memo is set to the selected value.


[ Top of Page | Previous Page | Next Page | Table of Contents ]