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.
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.
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.
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.
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 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.
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.
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.
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.
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.
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).
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. |
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.