Lotus Connector Guide

You must accept the FirstClass License Agreement before you can use this product. If you do not accept the terms of the License Agreement, do not install the software and return the entire package within 30 days to the place from which you obtained it for a full refund. No refunds will be given for returned products that have missing components.

Information in this document is subject to change without notice. Certain features and products described in this document may not be currently available in all geographic regions. Distribution or reproduction of this document in whole or in part must be in accordance with the terms of the License Agreement.

All rights reserved. FirstClass is a registered trademark of a Centrinity Inc. subsidiary used under license. Centrinity, the Centrinity logo, and the FirstClass logo are trademarks of Centrinity Inc. All other trademarks are property of their respective owners.

This edition applies to Release 7.1 of FirstClass and to all subsequent releases and modifications until otherwise indicated in new editions. This document is bound by international copyright law and the FirstClass Software License Agreement and Limited Warranty included with every FirstClass product.

Technical support

Telephone technical support is available to registered administrators at the following numbers:

Toll free in North America: 1-800-346-9180

Toronto: 905-762-7060

International: +353-61-725-200.

Online support questions may be directed to support@centrinity.com.

Introduction

The FirstClass® Connector for Lotus Domino® Server (FirstClass Connector) is a transport mechanism for real-time communication between FirstClass Server (minimum version 6.2) and Lotus Domino® Server 4.6.1. It translates messages and user information into a readable format as they are transported to another server, and maintains Directory synchronization between the two servers.

Because the information transfer is performed in real time, the need for intermediate storage is eliminated. The connection to Lotus Domino® Server is implemented using Notes C API 4.6.2 for mail, calendaring and Directory synchronization. The connection to FirstClass is implemented using FCP/Internet Client for mail and calendaring, and using FirstClass batch administration for Directory synchronization.

Who should read this book

This book is intended for the FirstClass Server and Lotus Domino Server administrator(s) who will install and run this application.

What you will find in this book

This book describes how to install and use the FirstClass Connector. It also lists the installation requirements and discusses the current features and considerations about this application.

This book does not document how to use FirstClass or Lotus Domino Server features. For that information, see our online help and applicable product documentation.

What you should already know

This book is intended for administrators who want to establish a mail flow between their Lotus Domino Server and FirstClass Server systems. We assume you are familiar with your Windows® operating system, Lotus Domino Server, MS-DOS®, and FirstClass functionality.

Requirements

The FirstClass Connector runs on the same computer as Lotus Domino Server 4.6.1. This server machine must meet the following minimum requirements:

• Windows NT® Server 4.0 (SP6)

• minimum 128 MB RAM

• minimum 10 MB free HDD space

• connection to a LAN.

FirstClass Connector features and considerations

Mail features

• Basic mail transport (includes message body, subject, recipient list, copylist, subject, time sent, priority, and sensitivity).

• Mail transport containing one or more attachments.

• Mail delivery confirmation report upon request.

• Mail read confirmation report upon request.

• Automatic mail nondelivery report.

Mail considerations

• With the exception of the calendar form, all FirstClass forms will be delivered to Lotus Domino Server as mail messages. However, nonstandard form fields are omitted from the delivered mail message.

• Replying to a FirstClass message more than once within Lotus Notes will fail. To send the reply successfully, select Resend from the mail router NDN report.

Calendar features

• Single meeting requests are transported with the following attributes : message body, subject, participants, subject, time sent, start/end date and time, reminder, sensitivity, time display pattern, location, one or more attachments).

• Lotus Notes Server meeting requests delivered to FirstClass are inserted directly into participants’ calendars.

• FirstClass meeting requests delivered to Lotus Domino Server are delivered into the participants’ Inboxes as meeting requests.

• Meeting RSVP is supported in both directions for Accepted and Declined.

• Automatic meeting request nondelivery reports are sent when the meeting requests cannot be delivered.

• Recurring meetings are fully supported for the following recurring patterns only:

• daily

• weekly

• weekdays

• weekends

• monthly (same day)

• monthly (same weekday)

• annually (same date).

• Time zones are automatically adjusted for FirstClass Server and Lotus Domino Server.

Calendar considerations

Although recurring patterns are supported, note:

• scheduling a "weekends" recurring pattern from FirstClass to Lotus Domino Server will not insert the first occurrence into the series if it occurs on a weekday.

• scheduling a "weekdays" recurring pattern from FirstClass to Lotus Domino Server will not insert the first occurrence into the series if it occurs on a weekend.

• RSVP is not supported for recurring appointments by Lotus Domino Server.

• when rescheduling recurring appointments from Lotus Notes to FirstClass, the update is entered as a new appointment on the first day of the recurring series with the same subject line.

• when rescheduling recurring appointments from FirstClass to Lotus Notes, the update is entered as a new recurring appointment series with the same subject line.

Lotus Domino Server has the following limitations on calendar appointments:

• appointment fields not supported are: sensitivity, time display pattern and location.

• appointment reminder cannot be set automatically by the FirstClass Connector.

• appointment cancellations are not transmitted to FirstClass.

FirstClass Connector has the following limitations on calendar appointments:

• appointment fields not supported are: resources.

• appointment cancellations are not transmitted to Lotus Notes.

• Single appointments can only be rescheduled twice from FirstClass. Subsequent attempts will fail. To reschedule the event successfully, select Resend from the mail router NDN report.

Directory synchronization features

• Upon startup, the FirstClass Connector synchronizes all mailboxes from Lotus Domino Server into FirstClass as Remote Names, and all Remote and Regular Users in FirstClass are synchronized into the Lotus Domino Server directory as users from a foreign domain.

• Full synchronization can be scheduled, performed automatically whenever a change occurs (incrementally), or performed manually. Incremental synchronization occurs whenever an addition, modification or deletion has been made in the FirstClass Directory or the Lotus Domino Server address book.

Note

The FirstClass Connector takes approximately one minute to check for changes to the Lotus Domino Server directory, so there might be a slight delay to see the changes reflected in the FirstClass Directory.

• A Lotus Domino Server user’s First Name, Last Name, Initials and Notes email address are mapped to a corresponding FirstClass Remote Name’s First Name, Last Name, Initials and Mail Aliases. The Mail Alias format is <first|initia|last@domain:NOTES>.

• A Regular or Remote FirstClass User’s First Name, Last Name and Initials are correspondingly mapped to a Lotus Domino Server foreign domain user's First Name, Last Name and Initials. The FirstClass email address of the foreign domain user has the following format: Display Name/SiteName:clientId.

• FirstClass downstream server directories can be selectively synchronized (see SORC_SYNC_SITE_NAME_XX configuration parameter).

Directory synchronization considerations

• Lotus Domino Server distribution lists, public folders and other foreign domain users are not synchronized.

• FirstClass Remote Names, conferences and mail lists are not synchronized.

• Supplemental attributes are not synchronized at this time (for example, addresses, phone numbers).

General considerations

• The Lotus Notes C API response becomes very slow once the server connection has been dropped, so the reconnect interval to Lotus Domino Server may be very long on occasion, such as five or ten minutes.

Configuring and installing the FirstClass Connector

Step 1: Create the Windows NT account for the FirstClass Connector

Create a Windows NT account that will be used by the FirstClass Connector. This account will be used:

• as a logon account for the FirstClass Connector running as a Windows NT service

Using the Windows NT User Manager for Domains:

1 Create a Windows NT account with an arbitrary name and password.

2 Assign the following Windows NT rights and permissions to the newly created account:

• Windows NT Logon as Service rights to the hosting server

• Windows NT Administrative rights to the hosting server.

Step 2: Create the "NotesConnector" object on FirstClass Server

You must install the NotesConnector object and create the Enterprise Services folder with the connector monitor on FirstClass Server. The created Enterprise Services folder will contain the connector monitor.

This NotesConnector object is the connection point for the FirstClass Connector on FirstClass Server. The values defined in this step will be required again in Step 9.

Create the NotesConnector object, Enterprise Services folder and the connector monitor

1 Log into FirstClass Server as the administrator.

2 optional

Edit the connector object creation script file notes.ags.

Note

This is recommended only for expert installations where customization is required. Normally, the following default values in the notes.ags file are sufficient:

connector name

NotesConnector

connector node id

600000000

connector user id

600000000

3 Submit the connector creation script to Batch Admin for processing.

The connector creation script is supplied in the file <connector name>.ags.

4 Verify that the Gateways folder contains the newly created NotesConnector object.

Configure the NotesConnector object

1 Open the Gateways folder.

2 Select the newly created connector object.

3 Open the Connection tab and set the connector object password. Make note of this password.

4 Open the Network tab and set the Server IP address.

5 Set Zone/Port to 510 on the Network tab.

6 Open the Multisite (Outbound) tab and select Export Directory names.

7 Select Directory and enter the connector object password again.

8 Close the Gateways folder.

Configure the connector monitor in the Enterprise Services folder

1 Select File > Upload from the FirstClass Server administrator's Desktop.

2 Navigate to the installation directory and select the file "monitorform.fc".

After uploading the monitorform.fc file:

3 Double-click on the form file object that has been placed on the Desktop.

4 Select Update on the Resource Updater form that opens.

5 Open the Enterprise Services folder.

6 Open the Connector Monitor object.

7 Confirm the form is actually the monitor form and not a default mail form.

Step 3: Create the FirstClass Router Mailbox on Lotus Domino Server

This object is the connection point for the FirstClass Connector on Lotus Domino Server.

1 Open Domino Server Administrator.

2 Select File > Database->New from administrator's menu.

3 Select Server on which to create a router mailbox and enter Title for FirstClass router mailbox (for example, FirstClass).

4 Select type "Mail Router Mailbox" from the scroll down selection box below.

5 Click OK.

Step 4: Create the FirstClass domain on Lotus Domino Server

This domain is created on the machine running Lotus Domino Server.

1 Open Domino Server Administrator.

2 Select Servers > Servers View or open the server Address Book.

3 In the server Address Book expand Server tab and select Domains.

4 Click "Add Domain".

5 In the new Domain tab enter the following field values:

• Enter "Foreign Domain" for Domain type.

• Enter FirstClass Mail Router Title from previous step (for example, FirstClass) for Foreign domain name.

• Enter fully qualified Lotus Domino Server name (server name/organization) for Gateway server name.

• Enter FirstClass Mail Router database file name (for example, FirstClass.nsf) for Gateway mail file name.

6 Click "Save and Close".

Step 5: Associate Lotus Domino Server name with TCP/IP address

This step is necessary only if the Lotus Domino Server name cannot be resolved into a valid TCP/IP address. To test this at the DOS prompt type "ping serverName" where serverName is the Lotus Domino Server name. If there is no reply do the following:

1 Open file Hosts located in windows ..\system32\drivers\etc directory.

2 Add entry "127.0.0.1 serverName" to the file.

3 Save file Hosts.

Step 6: Customize the configuration file

The configuration file, ESCON.CFG, defines the required parameters for FirstClass Connector operation. This file must be located in the same directory as the ESCON.EXE file unless the FirstClass Connector is registered to run as a Windows NT service. If this is the case, the ESCON.CFG file must be located in the \\WINNT\system32\ directory.

Understanding channels

The server is configured into channels. A channel is a unidirectional stream of information. Hence, each channel has a source and a destination. A bidirectional connector would therefore have two channels, one in each direction. Each channel runs as a separate processing task (thread). However, all channels use the same connection to source and destination nodes.

Consequently, there is a section of configuration parameters for each channel in the ESCON.CFG file, and each channel consists of two sections defining the source node parameters and destination node parameters.

General format and syntax

The configuration file (ESCON.CFG) is an ASCII text file with the following general format and syntax:

[Common]

<Parameter keyword>=<Parameter value>CRLF

[Channel XX]

<Prefix><Parameter keyword>=<Parameter value>CRLF

where:

• [Common] is a common parameters heading

• XX is a two digit channel number starting with 01

• [Channel XX] is a channel XX heading

• Prefix can be SORC_ or DEST_ or CHANNEL_:

• DEST indicates channel destination node parameter

• SORC indicates channel source node parameter

• CHANNEL indicates a channel common parameter.

Guidelines

• Parameter keywords cannot contain blank spaces or an equal sign.

• Parameter values can contain any character and must be terminated with a carriage-return/line-feed sequence.

• Parameter line must not contain any other text other than the keyword and its value.

• Parameter lines may appear in any order in the file as long as they are within their applicable heading.

• Comments must be placed on separate lines. A comment is any text that does not adhere to the above syntax.

Common configuration parameters

Common parameters do not have a prefix. Common parameters that can be defined in the configuration file are:

NUMBER_OF_CHANNELS=2

Total number of channels to be configured

LOG_LEVEL=NORMAL

How to process log information:

QUIET: do not log information

BASIC: log errors only

NORMAL: log warnings and errors (default)

DETAILED: log information, warnings and errors

DEBUG: record all logs

Channel Parameters

Below is a list of parameters and identifiers that may appear in a configuration file, with explanations. Within a configuration file, these parameters are repeated for each channel that exists.

--------Channel 01 NOTES to FC-------- Comment

CHANNEL_TYPE=DIR-SYNC

Channel source information:

CONNECTOR: messaging transport channel

DIR-SYNC: directory synchronization channel

NODE_NAME=FirstClass

Lotus Domino Server: FirstClass Mail Router database file name (without extension)

FirstClass: connector name on FirstClass Server

LOGIN_ID=FirstClass.nsf

Lotus Domino Server: FirstClass Mail Router database file name (with or without extension)

FirstClass: connector user id

LOGIN_PASSWORD=

Lotus Domino Server: N/A

FirstClass: connector user ID password on FirstClass Server

AUX_CONFIG_FILE=connector.fc

Lotus Domino Server: N/A

FirstClass: optional client fc file used for login

CONNECT_ADDRESS=NotesServer@NotesDomain

Lotus Domino Server: server name and domain in format: serverName@domainName

FirstClass: IP address or name of FirstClass Server

CONNECT_PORT=500

Lotus Domino Server: N/A

FirstClass: if present will override default port number 510

CONNECTOR_OUTBOUND_FOLDER=Mail

Lotus Domino Server: set to Mail

FirstClass: not used - defaults to Mailbox

CONNECTOR_INBOUND_FOLDER=Mail

Lotus Domino Server: set to Mail

FirstClass: not used - defaults to Desktop

ADDRESS_TYPE=NOTES

Lotus Domino Server: set to NOTES

FirstClass: set to FC

ADDRESS_BOOK_00=names.nsf

Lotus Domino Server: server master Address Book. Additional address books can be specified as:

ADDRESS_BOOK_01=sales.nsf

ADDRESS_BOOK_02=marketing.nsf

FirstClass: not used - defaults to _FC_DirSync for SORC_ and to DeskTop for DEST_

INSTANCE_ID=0

Connector channel set identifier.

A set of connector and channel sources and dirsync channel sources and destinations with the same instance ID that share common Lotus Domino Server and FirstClass Server connection points.

Default is zero. Any set of channels with an instance of 1 or greater would connect to an entirely different Lotus Domino Server connection point and/or FirstClass Server connection point. This enables the FirstClass Connector to service multiple, unconnected Lotus Domino Server installations and/or multiple FirstClass Server installations.

SORC_SYNC_SITE_NAME_00=SITE_2

Downstream FirstClass site name which is to be a part of directory synchronization.

This parameter should be defined only on DIR-SYNC type channels on the FirstClass SOURCE side. Additional sites can be specified as:

SORC_SYNC_SITE_NAME_01=SITE_7

SORC_SYNC_SITE_NAME_02=SITE_9

Step 7: Configure the connection to Lotus Domino Server

Note

These steps must be repeated for each channel in the ESCON.CFG file.

Lotus Domino Server parameters that need to be known are listed below with sample values.

Configuration parameter: FirstClass Mailbox Router file name

Sample: FirstClassRouter

Configuration parameter: Lotus Domino Server name

Sample: NotesServer

Configuration parameter: Lotus Domino Server domain name

Sample: NotesDomain

Configuration parameter: Lotus Domino Server Address Book

Sample: names.nsf

Setting Lotus Domino Server as the DIR-SYNC source

SORC_NODE_NAME=FirstClassRouter

SORC_LOGIN_ID=FirstClassRouter

SORC_CONNECT_ADDRESS=NotesServer@NotesDomain

SORC_ADDRESS_TYPE=NOTES

SORC_ADDRESS_BOOK_00=names.nsf

Setting Lotus Domino Server as the DIR-SYNC destination

DEST_NODE_NAME=FirstClassRouter

DEST_LOGIN_ID=FirstClassRouter

DEST_CONNECT_ADDRESS=NotesServer@NotesDomain

DEST_ADDRESS_TYPE=NOTES

DEST_ADDRESS_BOOK_00=names.nsf

Setting Lotus Domino Server as the CONNECTOR source

SORC_NODE_NAME=FirstClassRouter

SORC_LOGIN_ID=FirstClassRouter

SORC_CONNECT_ADDRESS=NotesServer@NotesDomain

SORC_CONNECTOR_OUTBOUND_FOLDER=Mail

SORC_CONNECTOR_INBOUND_FOLDER=Mail

SORC_ADDRESS_TYPE=NOTES

Setting Lotus Domino Server as the CONNECTOR destination

DEST_NODE_NAME=FirstClassRouter

DEST_LOGIN_ID=FirstClassRouter

DEST_CONNECT_ADDRESS=NotesServer@NotesDomain

DEST_CONNECTOR_INBOUND_FOLDER=Mail

DEST_ADDRESS_TYPE=NOTES

Step 8: Configure the connection to FirstClass Server

Note

These steps must be repeated for each channel in the ESCON.CFG file. The setup is same for either DIR-SYNC or CONNECTOR type channels.

FirstClass Server parameters that need to be known are listed below with sample values.

Setting FirstClass Server as source (DIR-SYNC or CONNECTOR type channel)

SORC_NODE_NAME=NotesConnector

SORC_LOGIN_ID=600000000

SORC_LOGIN_PASSWORD=pass

SORC_CONNECT_ADDRESS=TANGO

SORC_ADDRESS_TYPE=FC

Setting FirstClass Server as destination (DIR-SYNC or CONNECTOR type channel)

DEST_NODE_NAME=NotesConnector

DEST_LOGIN_ID=600000000

DEST_LOGIN_PASSWORD=pass

DEST_CONNECT_ADDRESS=TANGO

DEST_ADDRESS_TYPE=FC

Step 9: Register the connector

Running as a Windows NT registered server

To register the FirstClass Connector for operation as a Windows NT registered server:

1 Open the command prompt.

2 Navigate to the installation directory.

3 Type

escon /RegServer

4 Start the FirstClass Connector by running escon.exe.

To unregister the server:

1 Open the command prompt.

2 Navigate to the installation directory.

3 Type

escon /UnregServer

Running as a Windows NT service

To register the FirstClass Connector for operation as a Windows NT service:

1 Copy the configuration file (ESCON.CFG) to the \WINNT\System32 directory, since this is the current system directory for all services.

2 Open the command prompt.

3 Navigate to the installation directory.

4 Type

escon /Service

5 Open the Services tab on the Windows Control Panel.

6 Select the service: FirstClass Sync Connector.

7 Click Startup.

8 Select This Account and input the account ID and password created for the connector service in Step 2.

9 Click Start service.

To unregister the connector service:

1 Open the command prompt.

2 Navigate to the installation directory.

3 Type

escon /UnregServer

Starting the connector

To launch the FirstClass Connector, click the FirstClass Connector icon:

When the FirstClass Connector application starts, you will see the FirstClass Connector console screen:

This screen displays the current status of the application, synchronization results, and debugging information.

To force a full Directory synchronization from this screen choose Directory > Force Full Sync.

To increase or decrease the amount of information that displays on the console, choose Log Level and highlight one of the listed options: Quiet, Basic, Normal, Verbose, or Debug.

Connector monitor

The purpose of the connector monitor is to display the status of the synchronization.

To view the connector monitor, open the Enterprise Services folder on the FirstClass administrator’s Desktop, and double-click Connector Monitor.

This screen indicates the number of active channels, the type of connector, the software version, the last time the FirstClass Connector was started, and displays the current status of any synchronization that is occurring. The Activity field indicates the current processing stage. If the field is blank, as in the above image, this means the FirstClass Connector is idle. The progress bar at the bottom of the screen will always be moving, to indicate the FirstClass Connector is still active.

There are also two buttons on this screen: Reset Monitor, which lets you reset the current values on the screen, and Full Dir-Sync, which forces a Directory synchronization.

Performing Directory synchronization

Warnings

• A Directory synchronization takes time. The amount of time required depends on the speed of your machine and the amount of information to synchronize.

• A synchronization cannot be halted once it has started.

Every time the FirstClass Connector is launched, it automatically performs a full Directory synchronization. To force a Directory synchronization at any time, choose Directory > Force Full Sync from the connector console, or click Full Dir-Sync from the connector monitor.

The console must always be running to maintain synchronization after the initial Dir Sync. When a change is made in FirstClass, the foreign mail system server is updated immediately. This is called incremental synchronization based on notifications from FirstClass. When a change is made on the foreign mail system server, FirstClass is updated within a few minutes, based on a set timeframe (hardcoded number of minutes). This is called incremental synchronization based on polling of the foreign mail system server. This is due to the difference in available incremental synchronization mechanisms between the foreign mail system server and FirstClass.

If the information is required immediately, you can force a full Directory synchronization, but see the Warnings above before you do this.

Understanding the log file

The log file ESCON.LOG is located in the same directory as the FirstClass Connector executable. This file is recreated every time the FirstClass Connector is started, and is automatically backed up at midnight by saving the current file as ESCON_YYYY_MM_DD_HH_MM_SS.LOG, where YYYY_MM_DD_HH_MM_SS represents year_month_day_hour_second.

Note

If the FirstClass Connector is abnormally terminated (such as a power outage), you will need to rename, move, or copy the ESCON.LOG file before restarting the application, because the log file will not be automatically renamed from ESCON.LOG.

At startup, the entire configuration is written to the log file. There is a sample log file on your installation CD called SAMPLELOG.TXT.