IBM Notes Agent

NotesAgent is the DirX Identity agent that handles the import and export of entries to and from a public IBM Notes address book maintained on an IBM Domino server. NotesAgent can handle entries of any IBM Notes document type.

NotesAgent supports only IBM Notes server and client versions 7.03 or higher. Earlier versions are no longer supported. Use of additional functionality of the Notes APIs enforces this restriction. The agent runs on Windows and requires a co-located Notes Client. NotesAgent uses the Notes API to bind to a Notes server.

NotesAgent can:

Perform a full or delta export of Person or Group entries from a Notes address book, including multiple attribute values
Perform a full or delta import of Person or Group entries into a Notes address book, including multiple attribute values
Create a separate "modify/delete" file of modified and deleted entries as part of the export process
Create mailboxes and registered users in the Notes address book as part of the import process (includes support of mail replica servers)
Rename, re-certify and delete registered users in the Notes address book as part of the import process
Generate an import error file that records all entries that it fails to import
Generate a log file (for tracing)

The following figures illustrate the components of NotesAgent export and import operations.

Figure 1. NotesAgent Export Components

Figure 2. NotesAgent Import Components

The rest of this chapter describes:

NotesAgent command line format for export and import operations
NotesAgent configuration files for export and import operations
The export data file format that NotesAgent generates
The import data file format that NotesAgent recognizes
NotesAgent import error file format

These functions use AdminP functionality:

RecertifyUser - uses the AdminP function ADMINReqRecertify

RenameUser - uses the AdminP function ADMINReqRename

MoveUserInHierarchy - uses the AdminP functions ADMINReqMoveUserInHier and ADMINReqMoveComplete

DeleteUser - uses the AdminP function ADMINReqDeleteInNAB

RegisterNewUser - calls internally REGNewUser and sets the flag fREGCreateMailFileUsingAdminp if the parameter CreateMailDBNow is set in the ini-file

RegisterNewPerson - calls internally REGNewPerson and sets the flag fREGCreateMailFileUsingAdminp if the parameter CreateMailDBNow is set in the ini-file

Sample configuration files and scripts are provided in the \Samples\Notes directory of the DirX Identity installation. See the file NotesReadme.txt for a description of these files and scripts.

Password Handling

NotesAgent uses the password that grants the credentials to log into a Notes server from an installed Notes client. NotesAgent must use password authentication to a Notes server in order to export data from an address book or import data into it.

The password can be supplied at login:

Manually, at the user prompt
Automatically, through the use of password information in the Export and Import ini files.

Information for users of older version of NotesAgent:

In older releases, an Extension Manager for Notes was defined in notes.ini of the IBM Notes installation.

The section

[Notes]
ExtMGR_ADDINS=nextpwd.dll

in notes.ini is no longer needed because the NotesAgent directly connects to the IBM Domino server with the “Admin” ID file defined in the Password section.

For details, see “Password Section” in "Password Configuration File Formats".

Command Line Format

The command line format to invoke NotesAgent is as follows:

NotesAgent.exe sync_switch data_file configuration_file error_file>_initial_error_file_

Parameters

sync_switch

Specifies the type of directory synchronization that NotesAgent is to perform. Possible values are:

/e - Invokes the NotesAgent export function
/i - Invokes the NotesAgent import function

data_file

For export: specifies the pathname of the target export data file that is to contain the entries that NotesAgent extracts from a Notes address book. For delta exports, this file must already exist and is used as the delta base to generate delta information.*
For import:* specifies the pathname of the source file that contains the data to be imported into the Notes address book.

configuration_file

Specifies the name of the file that contains the specifications for the import or export procedure.

error_file

Specifies the name of the file to which NotesAgent is to write error messages about errors that occur during the import or export process, in the format:

error_code
error_message
[error_specific_information]

where error_code is the code for the error that occurred, error_message is a description of the error, and error_specific_information is additional information that can appear depending on the type of error. For example:

#ProcessAddress error:
#Find more as one document with the following ItemIdentityName(s):
LastName: Test00000
FirstName: Hugo
ShortName: hTest00000

In this example, the last three lines are specific for this error.

For an import operation, NotesAgent writes additional information about the entries that it cannot import into the Notes address book into the file specified in error_file. See "Import Error File Format" for more details about the contents of the error file on an import operation.

initial_error_file

Specifies the name of the file to which NotesAgent is to write error messages about errors that occur before it creates error_file. The error format is the same as that of error_file.

Configuration File Formats

NotesAgent uses the following configuration files:

Notes export configuration file - controls the export of data from a Notes address book
Notes import configuration file - controls the import of data into a Notes address book
Password configuration files - automates password authentication during NotesAgent login to a Notes server and enables the assignment of a default password for registered users

See "General Structure of a Configuration File" for a description of the basic organization.

Templates of these configuration files are provided with the NotesAgent installation. The filenames are:

NotesExport.ini
NotesImport.ini

In general, you must customize these files to support the requirements of your Notes import and export operations.

General Structure of a Configuration File

A NotesAgent configuration file consists of sections and fields defined within those sections. A configuration file has the following structure:

[*SectionName]*
<;comment>
sectionField*=fieldValue
.
.
. *
[*SectionName]*
<;comment>
sectionField*=*fieldValue
.
.
.

SectionName is a keyword enclosed in square brackets ([ ]) that identifies the purpose of the section. sectionField is a keyword that identifies the field and fieldValue is the value assigned to the section field, preceded by the equal sign (=). For example:

UpdateExportFile=1

Comments can be inserted anywhere in the configuration file and are identified by a semicolon (;) at the beginning of a line.

Export Configuration File Format

The NotesAgent export configuration file consists of these sections:

The Version section (required)
The Export section (required)
The Password section (optional)
The Export Items section (optional)

These sections are described below.

The Version Section

The Version section consists of a single field that specifies the export configuration file version. The syntax is:

*Version=*version_number

where version_number is the version number assigned to the configuration file, in the format n*.*nn. The current version is:

Version=1.03

This is a mandatory field. This document describes the latest version of the NotesAgent export configuration file. The NotesAgent is able to process configuration files with version number 1.00, 1.01, 1.02, 1.03 or "old" files that do not contain a Version section. The following table provides information about the differences between export configuration file versions and about the support of older export configuration file versions for compatibility reasons:

	"Old"	1.00	1.01	1.02, 1.03
FileForDeleteAddr	Supported	Not Supported	Not Supported	Not Supported
FileForModifiedAddr	Supported	Not Supported	Not Supported	Supported

"Old"

1.00

1.01

1.02, 1.03

FileForDeleteAddr

Supported

Not Supported

FileForModifiedAddr

Supported

Not Supported

Supported

If the version is greater than 1.02, the new field "TypeName" must be in the export configuration file.

The Export Section

The Export section consists of fields that define the parameters of an export operation for NotesAgent. The next sections describe these fields.

Server

The Server field specifies the name of the Notes server that contains the Notes address book from which entries are to be exported. The syntax is:

Server=[server_name]

where server_name is the name of a Notes server, in the format:

"CN=*server_name/O=organization_name[/…]"*

For example:

Server="CN=westford/O=IRIS/O=NOTES"

If server_name is not specified, the NotesAgent uses the local Notes address book (the address book that is present on the machine on which NotesAgent is running) as the export target.

This is a mandatory field.

AdrBook

The AdrBook field specifies the name of the Notes address book from which entries are to be exported. The syntax is:

AdrBook=*filename[.nsf*]

where filename is the name of a Notes address book managed by the Notes server specified in the Server field and .nsf is the file extension, which is automatically supplied by NotesAgent if you do not specify it explicitly. (You cannot use a different extension). A single Notes server can support multiple Notes address books. NotesAgent can export from only one Notes address book at a time.

This is a mandatory field.

FormName

The FormName field specifies the Notes form of a document. Forms allow users to create documents that store data.

The syntax is:

FormName=form_name

where form_name is a Notes form name. For example:

FormName=Person

This is a mandatory field.

TypeName

The TypeName field specifies the Notes document type to be extracted from the Notes address book. The syntax is:

TypeName=document_type

where document_type is a Notes document type. For example:

TypeName=Person

This is a mandatory field.

FirstDeltaIsFull

The FirstDeltaIsFull field controls weather NotesAgent writes all entries also in the "modify" file. The syntax is:

FirstDeltaIsFull=[switch]

where switch is one of the following values:

0 - Perform the first delta export only in the data file (default)
1 - Perform the first delta export in both files.

This is an optional field. If it is not specified (or the field is not present in the configuration file), the NotesAgent exports all entries only in the data file.

SMTPHostDomain

The SMTPHostDomain field controls the generation of Internet addresses for Person entries exported from a Notes address book. The syntax is:

SMTPHostDomain=[domain_name | None]

Notes address books do not store Internet addresses. You can use the SMTPHostDomain field to control:

whether or not Internet addresses are generated for Person entries that are exported from the Notes address book
the domain supplied in the generated Internet address for each Person entry

Specify the name of a host in domain_name to generate an Internet address for each exported entry that uses this domain. For each exported entry, the NotesAgent generates an Internet address in the SMTP format:

name@domain_name

where name is the value of the ShortName attribute of the Notes entry and domain_name is the value supplied in domain_name. For example, if SMTPHostDomain is:

SMTPHostDomain=wstfd.ibm.us

and the value of ShortName for the entry is:

ShortName: Ray.Ozzie

the generated Internet address for the entry is:

Ray.Ozzie@wstfd.ibm.us

The Internet address is written to the export data file in this form:

InternetAddress: Ray.Ozzie@wstfd.ibm.us

Specify the keyword None to suppress Internet address generation for exported entries.

If no value is specified in this field, NotesAgent generates SMTP-format Internet addresses for the exported entries using the ShortName attribute for the name part of the address and the value of the SMTPFullHostDomain attribute of the Notes server entry ("document", in Notes terminology) in the hostname part of the address. It also updates the SMTPHostDomain field in the export configuration file with the retrieved Notes SMTPFullHostDomain attribute value.

This is a mandatory field.

ModifiedAddresses

The ModifiedAddresses field controls whether NotesAgent performs a full or delta export of the document type specified in the FormName field from the Notes address book. The syntax is:

ModifiedAddresses=[switch]

where switch is one of the following values:

0 - Export all entries of the selected document type (default)
1 - Export only those entries that have been added, deleted, or modified after the date specified in the ModifiedDate field

If 0 is specified, NotesAgent creates one file that contains all of the entries of the selected document type that are present in the address book. This file is called the "export data file" (or "full export data file") and is the file specified as an import data file to metacp. If 1 is specified, NotesAgent creates two files:

A file that contains all of the entries of the selected document type that are present in the address book (the full export data file); this is the file specified in data_file on the command line
A "modify and delete" file, which contains the entries that have been added, modified or deleted since the date specified in ModifiedDate (delta export data file). New and modified entries are identified by a "modify" changetype attribute. Deleted entries are identified by a "delete" changetype attribute. See the section "Delta Export data file Format" for further details about "modify/delete" file format.

NotesAgent creates the "modify/delete" file using the pathname specified in the FileForModifiedAddr field.

This is an optional field. If it is not specified (or the field is not present in the configuration file), NotesAgent exports all entries of the selected document type that are present in the address book.

ModifiedDate

The ModifiedDate field specifies the date to be used to select entries for export. The syntax is:

ModifiedDate=date_and_time

where date is one of the date and time formats supported by Windows. For example:

ModifiedDate=22.06.98 14:20:25

specifies the date in European date and time format. In this example, all entries added, deleted, or modified after the specified date are to be exported. After NotesAgent performs a delta export, it updates this field in the export configuration file with the current date and time to enable subsequent delta exports. The date and time format specified in this field must match the date and time format selected in the Windows Regional Settings Properties Date and Time tabs.

This is an optional field unless ModifiedAddresses is set to 1.

UpdateExportFile

The UpdateExportFile field controls (for delta exports only) whether or not the full export data file created by the NotesAgent can be updated. The syntax is:

UpdateExportFile=[switch]

where switch is one of the following values:

0 - Do not update the full export data file
1 - Update the full export data file (default)

If 0 is specified, NotesAgent creates a new full export data file on subsequent export operations and preserves the original full export data file it creates on the initial export. If 1 is specified, NotesAgent overwrites the original full export data file on subsequent export operations.

This is an optional field. If it is not specified (or is not present in the configuration file), NotesAgent preserves the original full export data file on subsequent export operations. NotesAgent evaluates this field only when performing a delta export (ModifiedAddresses set to 1).

CopyDeletedAdrInModFile

The CopyDeletedAdrInModFile field controls whether or not NotesAgent retrieves the contents of entries of the document type selected with the FormName field that have been deleted since a full export data file was last generated. The syntax is:

CopyDeletedAdrInModFile=[switch]

where switch is one of the following values:

0 - Do not retrieve the contents of deleted entries
1 - Retrieve the contents of deleted entries (default)

The Notes address book retains the identifiers of deleted entries, although their contents are removed. Specifying 0 in this field directs NotesAgent to write the identifiers of the deleted entries to the "modified/deleted" file that it creates if the ModifiedAddresses field is set to 1. Specifying 1 in this field directs NotesAgent to retrieve the entry contents associated with the deleted entry identifiers from the most recently generated full export data file, and write the contents and the identifiers into the "modify/delete" file. To use this functionality the field UpdateExportFile must be set to 1.

This is an optional field. If it is not specified (or is not present in the configuration file), NotesAgent retrieves the contents of deleted entries. NotesAgent evaluates this field only when performing a delta export (ModifiedAddresses set to 1).

FileForModifiedAddr

The FileForModifiedAddr field specifies the pathname of the file to which NotesAgent is to write modified (and deleted) entries during a delta export operation. The syntax is:

FileForModifiedAddr=pathname

where pathname is the name for the "modify/delete" file. For example:

FileForModifiedAddr=c:\ibmnotes\ModDelFile

This field is optional unless ModifiedAddresses is set to 1. NTAgent does not evaluate this field if ModifiedAddresses is set to 0.

ExportAllItems

The ExportAllItems field controls whether all of the attributes ("items", in Notes terminology) of entries of the document type selected with the FormName field are exported, or whether a specified subset of attributes is exported. The syntax is:

ExportAllItems=switch

where switch is one of the following values:

0 - Export only the entry attributes specified in the ExportItems section of the configuration file
1 - Export all of the entry attributes (default)

This is an optional field. If it is not specified in the configuration file, NotesAgent exports all entry attributes for entries of the selected document type.

SearchDocuments

The SearchDocuments field controls whether or not NotesAgent searches for and exports specific entries ("documents", in Notes terminology) of the document type specified in the FormName field. The syntax is:

SearchDocuments=switch

where switch is one of the following values:

0 - All entries are exported (no attribute selection criteria are established for entry export) (default)
1 - Export only the entries described by the SearchItemName and SearchItemValue fields

If SearchDocuments is set to 1:

The ModifiedAddresses field is ignored
Values must be supplied for the SearchItemName and SearchItemValue fields

This is an optional field. If it is not present in the configuration file, NotesAgent exports all entries of the selected document type.

SearchItemName

The SearchItemName field specifies an attribute within an entry to search for. The syntax is:

SearchItemName=attribute_name

where attribute_name is a Notes attribute name for an attribute ("item") that can be present in an entry of the document type specified in the FormName field. For example:

SearchItemName=Department

directs NotesAgent to search all entries of the selected document type for the Department attribute. The entry is exported if it has the value specified in the SearchItemValue field.

This field is optional unless SearchDocuments is set to 1.

SearchItemValue

The SearchItemValue field specifies a value to search for (case exact match), given an attribute name to search for that is specified in the SearchItemName field. The syntax is:

SearchItemValue=attribute_value

For example:

SearchItemName=Department SearchItemValue=Iris

directs NotesAgent to search all entries in the Notes address book for the Department attribute, and export entries whose value for the Department attribute is Iris.

This field is optional unless SearchDocuments is set to 1.

Separator

The Separator field specifies a value to be used to separate the individual attribute values of a multivalued attribute. The syntax is:

Separator=[character]

where character is a character or a string used as a multi-valued attribute separator.

This field is optional. If it is not specified (or not present in the configuration file), NotesAgent uses the comma (,) as the multi-valued attribute separator.

Trace

The Trace field controls whether NotesAgent performs program flow tracing on an export operation. The syntax is:

Trace=[switch]

where switch is one of the following values:

0 - Do not perform program flow tracing on the export operation (default)
1 - Perform program flow tracing on the export operation

If 1 is specified, NotesAgent writes information about the export operation to the pathname specified in the TraceFileName field. The type of information stored in the trace file depends upon the settings of the TraceLevel_1, TraceLevel_2, and TraceLevel_3 fields. If Trace is set to 1, one of the trace level fields must also be set to 1.

TraceLevel_1

The TraceLevel_1 field controls whether NotesAgent writes level 1 tracing information about the export operation. Level 1 tracing information includes a dump of the configuration file, number of documents, and other program flow variables.

The syntax is:

TraceLevel_1=[switch]

where switch is one of the following values:

0 - Do not write level 1 trace information (default)
1 - Write level 1 trace information

If 1 is specified, NotesAgent writes level 1 trace information about the export operation to the pathname specified in the TraceFileName field.

TraceLevel_2

The TraceLevel_2 field controls whether NotesAgent writes level 2 tracing information about the export operation. Level 2 tracing provides more detailed information about program flow than is provided in level 1 tracing.

The syntax is:

TraceLevel_2=[switch]

where switch is one of the following values:

0 - Do not write level 2 trace information (default)
1 - Write level 2 trace information

If 1 is specified, NotesAgent writes level 2 trace information about the export operation to the pathname specified in the TraceFileName field.

TraceLevel_3

The TraceLevel_3 field controls whether NotesAgent writes level 3 tracing information about the export operation. Level 3 tracing provides more detailed information about program flow than is provided in level 2 tracing The syntax is:

TraceLevel_3=[switch]

where switch is one of the following values:

0 - Do not write level 3 trace information (default)
1 - Write level 3 trace information

If 1 is specified, NotesAgent writes level 3 trace information about the export operation to the pathname specified in the TraceFileName field.

TraceFileName

The TraceFileName field specifies the pathname of the trace file to which NotesAgent is to write information about the export operation. The syntax is:

TraceFileName=pathname

where pathname is the name for the trace file. For example:

TraceFileName=c:\ibmnotes\ExportTraceFile

This field is optional unless Trace is set to 1. NotesAgent does not evaluate this field if Trace is set to 0.

The Password (Password) Section

The Password section consists of fields that define the parameters for NotesAgent automated password authentication. The next sections describe these fields.

PathFilePassword: The PathFilePassword field is only used for the old password handling mechanism.

For a description of the old password handling mechanism, see the section "Password Configuration File Formats".

The syntax for this field is:

PathFilePassword=pathname

where pathname is the path to the password configuration file NotesPassword.ini. For example:

PathFilePassword=a:\NotesSync\NotesPassword.ini

For security reasons, it is recommended that the password configuration file not be stored on disk, since it contains human-readable representations of Notes address book administrator and registered user passwords.
AutomaticPW: The AutomaticPW field specifies the password that NotesAgent (in conjunction with a NotesAgent DLL) is to use to decode the admin.id certificate; this is the certificate that grants it the credentials to log in to the Notes server

The "PathAndFileOfNotesIDFile" field can alternatively be indicated.

If the field "PathAndFileOfNotesIDFile" is available for a ID file, it has higher priority.

The syntax is:

AutomaticPW=password

For example:

AutomaticPW=notes
PathAndFileOfNotesIDFile: The PathAndFileOfNotesIDFile field specifies the password that NotesAgent (in conjunction with a NotesAgent DLL) is to use to decode the admin.id certificate; this is the certificate that grants it the credentials to log in to the Notes server

For this Notes ID file the Notes Agent needs a pair of "Path and file name of ID file" and the "corresponding password".

Path and file Name of notes.id=password

For example:

C:\IBM\Notes\admin.id=notes

The "AutomaticPW" field can alternatively be indicated.

If the field "PathAndFileOfNotesIDFile" is available for a ID file, it has higher priority

The Export Items Section

The Export Items section is an optional section of the export configuration file that specifies a set of entry attributes to be exported from a Notes address book. The section is only present if the ExportAllItems field in the Export section is set to 1. The syntax is:

attribute_name=switch

where attribute_name is the name of an entry attribute and switch is one of the following values:

0 - Do not export the attribute value for attribute_name
1 - Export the attribute value for attribute_name

For example:

[ExportItems]

LastName=1
FirstName=1
Location=0

Use the switch parameter to select or exclude attributes in the list for export. See the installed NotesExport.ini file for a list of attribute names known to the NotesAgent.

Import Configuration File Format

The NotesAgent import configuration file consists of the following sections:

The Version section (required)
The Import section (required)
The Registered User (RegUser) section (optional)
The Password (Password) section
The EncryptedAttributes (EncryptedAttributes) section

The next sections describe these sections.

The Version Section

The Version section consists of a single field that specifies the import configuration file version. The syntax is:

Version=version_number

where version_number is the version number assigned to the configuration file, in the format n*.*nn. The current version is:

Version=1.02

This is a mandatory field. This document describes the latest version of the NotesAgent import configuration file. There are no differences between import configuration file versions.

The Import Section

The Import section consists of fields that define the parameters of the import operation for NotesAgent. The next sections describe these fields.

Server

The Server field specifies the name of the Notes server that contains the Notes address book to which entries are to be imported. It has the same syntax and default as the Server field in the export configuration file and is a mandatory field.

AdrBook

The AdrBook field specifies the name of the Notes address book to which entries are to be imported. It has the same syntax and default as the AdrBook field in the export configuration file and is a mandatory field.

FormName

The FormName field specifies the Notes document type to be imported into the target Notes address book. It has the same syntax as the FormName field in the export configuration file and is a mandatory field.

ItemIdentityName[1,2,3]

The ItemIdentityName fields control how NotesAgent matches entries in the target Notes address book with entries to be imported into the address book. The syntax is:

ItemIdentityName1=attribute_name | ViewSearchName
ItemIdentityName2=attribute_name
ItemIdentityName3=attribute_name

where attribute_name is the name of a Notes attribute in an import entry whose value NotesAgent is to use match against entries in the Notes address book. NotesAgent uses case-exact match unless the CaseSensitive field is set to 0. Specifying wildcards is not supported.

If the Update field is set to 1, at least one ItemIdentityName field must be specified. When multiple ItemIdentityName fields are specified, NotesAgent "ANDs" the fields; there is no "OR" function.

When the ItemIdentityName1 field contains the ViewSearchName value and ViewFolder specifies a Notes view, it indicates that the view specified in ViewFolder has been sorted by a composite attribute and that the entries in the import data file have a ViewSearchName attribute that contains the composite attribute value. For example, suppose the view specified in ViewFolder has been sorted by the composite attribute:

LastName , FirstName

The ItemIdentityName1 field must specify:

ItemIdentityName1=ViewSearchName

and each entry in the import data file contains a ViewSearchName attribute type. For example:

FirstName: Thomas
LastName: Diaz
ViewSearchName: Diaz , Thomas

The composite attribute format used in the import data file must match exactly with the format used in the sorted view. NotesAgent uses the sorted view and the ViewSearchName attribute values to match entries in the import data file against entries in the Notes address book. The ViewSearchName value is only relevant when the ViewFolder field is used.

Update

The Update field controls whether or not existing Notes entries are modified with imported information or whether a new entry with the imported information is created, even if a matching entry already exists in the address book. The syntax is:

Update=[switch]

where switch is one of the following values:

0 - Always create a new Notes entry for an imported entry (create a new Notes ID), even if a Notes entry that matches it already exists in the address book
1 - Modify matching Notes entries in the address book and create new Notes entries if there are no matches for them in the address book (default)

NotesAgent uses the values supplied in the ItemIdentityName fields to determine whether matching entries exist.

This is an optional field. If it is not specified (or not present in the configuration file) NotesAgent updates existing Notes entries and creates non-existent Notes entries.

ExactAction

The ExactAction field controls whether or not the ChangeType and the ItemType fields are used exactly as defined in the import data file.

Exact action for ChangeType means that the agent does not create an entry if ChangeType is set to modify but the entry does not exist. Otherwise a new entry is created.

Exact action for ItemType means also that the agent does not import an entry if the item in the import data file does not exist in the Notes database or has another ItemType as Text, Number or DateTime. Otherwise the item is created with item type "Text".

The syntax is:

ExactAction =[switch]

where switch is one of the following values:

0 - No exact action for ChangeType, no exact action for ItemType (default).
1 - Exact action for ChangeType, no exact action for ItemType.
2 - No exact action for ChangeType, exact action for ItemType.
3 - Exact action for ChangeType, exact action for ItemType.

This is an optional field.

ReplaceItem

The ReplaceItem field controls whether or not existing attribute values of Notes entries in the address book are overwritten with imported values. The syntax is:

ReplaceItem=[switch]

where switch is one of the following values:

0 - Add imported attribute values as multiple attribute values for the attribute (create a multi-valued attribute) (default)
1 - Replace existing attribute values with imported attribute values

This is an optional field. If it is not specified (or is not present in the configuration file), NotesAgent adds the imported attribute values to the existing attribute or performs operations on attributes as specified in a "modify" changetype entry.

If the ReplaceItem field is set to 1, NotesAgent reads the full entry and sorts it according to the attribute modification operations present in the entry. If an attribute has more than one attribute modification specified for it, NotesAgent performs a "replace" attribute modification operation, regardless of the attribute modification operation specified in the import data file.

SaveOrgDB

The SaveOrgDB field controls whether or not NotesAgent backs up the target Notes address book before performing the import operation. The syntax is:

SaveOrgDB=switch

where switch is one of the following values:

0 - Do not back up the target Notes address book before import
1 - Back up the target Notes address book before import

If SaveOrgDB is set to 1, NotesAgent writes the contents of the target Notes address book to the file specified by the SaveDBName field on the Notes server specified in the SaveServerName field.

This is an optional field. If it is not specified (or is not present in the configuration file), NotesAgent does not perform a backup.

SaveServerName

The SaveServerName field specifies the name of a Notes server that NotesAgent is to use as a storage target when backing up a Notes address book before an import operation. The syntax is:

SaveServerName=[server_name]

where server_name is the name of the Notes server to which the Notes address book is to be written, in the syntax:

"CN=server_name/O=organization_name[/…]"

For example:

SaveServerName="CN=Cambridge1/O=Notes/O=IBM"

If no value is specified for this field, NotesAgent writes the contents of the Notes address book to the Windows system on which it is running.

This is a mandatory field.

SaveDBName

The SaveDBName field specifies the name of the file to which NotesAgent is to write the contents of a target Notes address book before an import operation. The syntax is:

SaveDBName=[filename[.nsf]]

When specifying a filename, you can omit the .nsf file extension; it is automatically supplied by NotesAgent if you do not specify it explicitly. (You cannot supply a different extension, or Notes will be unable to open the saved file). For example:

SaveDBName=namessave.nsf

This is a required field if SaveOrgDB is set to 1.

DeleteEntries

The DeleteEntries field controls whether or not entries that exist in the Notes address book are to be deleted if matching entries exist in the import data file. The syntax is:

DeleteEntries=switch

where switch is one of the following values:

0 - Do not delete entries in the Notes address book that match entries to be imported (default)
1 - Delete entries in the Notes address book that match entries to be imported

NotesAgent uses the ItemIdentityName field(s) to determine whether entries in the address book match entries to be imported. If you plan to set DeleteEntries to 1, it is strongly recommended that you use all three ItemIdentityName fields and that you back up the Notes address book before performing the import.

The DeleteEntries field takes precedence over the Update field. That is, if Update is set to 0, and DeleteEntries is set to 1, NotesAgent will delete entries from the Notes address book that match entries to be imported. This field has a higher precedence than any per-entry "changetype" operations specified in the import data file.

This is an optional field. If it is not specified (or is not present in the configuration file), NotesAgent does not delete any entries in the Notes address book when it performs the import.

CreateTestAddresses

The CreateTestAddresses field is used to implement a test function on the import process. The syntax is:

CreateTestAddress=number | 0

You can append a 5-digit "test" address to one or more attributes in a Notes import data file. Initially, the number is set to 0. For example:

LastName: Kawell00000

Specifying a number in number directs NotesAgent to process the import data file that number of times. On each processing cycle, NotesAgent increments the 5-digit test addresses you have inserted. You can use the test address function to distinguish the imported entries from the entries that exist in the Notes address book.

This is an optional field. If it is not specified (or is not present in the configuration file), NotesAgent does not increment test addresses.

Separator

The Separator field specifies a value to be used to separate the individual attribute values of a multi-valued attribute. It has the same syntax as the Separator field in the export configuration file.

RegisterUser

The RegisterUser field controls whether or not NotesAgent registers imported entries as Notes users. The syntax is:

RegisterUser=switch

where switch is one of the following values:

0 - Do not register imported entries as Notes users (default).
1 - Register imported entries as Notes users and create corresponding mail files immediately. (Internally the C++-API is called: LNCertifier.RegisterUser.)
2 - Register imported entries as Notes users and create requests for the Administration Process to create corresponding mail files. (Internally the API is called: REGNewWorkstationExtended.)
3 - Register imported entries as Notes users and select whether mail files shall be created immediately or only requests to create corresponding mail files for the Administration Process shall be created. In this mode you can set the mail template and quota for mail files. (Internally the API is called: REGNewUser.)
4 - Register imported entries as Notes users and select whether mail files shall be created immediately or only requests to create corresponding mail files for the Administration Process shall be created. In this mode you can set the mail template and quota for mail files. Furthermore mail replica servers can be defined. (Internally the API is called: REGNewPerson.)

If the RegisterUser field is set to 1, 2, 3 or 4 and the Update field is set to 0, NotesAgent always registers all imported entries as Notes users. If the RegisterUser field is set to 1, 2, 3 or 4 and the Update field is set to 1, NotesAgent only registers an entry as a Notes user if the entry has not already been registered.

Notes uses a distributed architecture and so several Notes servers participate in the user registration operation. If RegisterUser is set to 1, the operation is synchronous and completes successfully only if all of the required Notes servers are available. NotesAgent receives a response about successful or unsuccessful completion.

If RegisterUser is set to 2, the user registration operation is asynchronous: NotesAgent registers the users and then submits request documents (to create the mail files) to the Notes Administration Process (adminp) request database. When the Administration Process starts (the administrator specifies a time interval for startup), it consults its database and attempts to perform the request. If one of the necessary Notes servers is not available, the Administration Process tries the operation again the next time it starts up. NotesAgent does not receive a response about successful or unsuccessful completion.

If RegisterUser is set to 3, you can select wether mail files shall be created immediately or only requests to create corresponding mail files (CreateMailDBNow) for the Notes Administration Process shall be created. In this mode you can set the mail template (MailTemplate), quota for mail files (DbQuotaSizeLimit, DbQuotaWarningThreshold), the SMTP Host Domain for the internet address of the user (SMTPHostDomain), and the mail parameters (MailOwnerAccess, MailSystem, MailACLManager, MailForwardAddress).

If RegisterUser is set to 4, the same options as for option 3 apply. Furthermore you can define the following additional attributes: MailReplicaServer, PreferredLanguage, AltLanguage, OnDuplicate, .PasswordKeyWIdth, KeyWidth, InetKeyWIdth, PasswordQuality. Note that this option should be used if you want to define mail replica servers. Calling the API REGNewPerson sets the mail replica servers. The API REGNewPerson internally requires the additional attributes listed above.

You can use the Notes Client user interface to configure the Notes Administration Process. You will find the configuration parameters in the section "Administration Process" in the Server/Servers document of the address book.

This field can be in each entry in the import data file. If it is specified it acts as a default value. This means that the value in the import data file can override this default setting.

PathFileTargetCertId

The PathFileTargetCertId field specifies the pathname to the certificate ID file of a target organizational unit. The file contains the certificate that grants NotesAgent the right to create registered users for the organizational unit. The syntax is:

PathFileTargetCertId=pathname

where pathname is the pathname to the certificate ID file. For example:

PathFileTargetCertId=a:\German.id

This is a required field if the import operation is to process the "MoveUserInHier" changetype operation. See the section "Import Data File Format" for further details about these operations.

This field can be in each entry in the import data file. If it is specified it acts as a default value. This means that the value in the import data file can override this default setting.

Trace

The Trace field controls whether NotesAgent performs program flow tracing on an import operation. The syntax is:

Trace=[switch]

where switch is one of the following values:

0 - Do not perform program flow tracing on the import operation (default)
1 - Perform program flow tracing on the import operation

If 1 is specified, NotesAgent writes information about the import operation to the pathname specified in the TraceFileName field. The type of information stored in the trace file depends upon the settings of the TraceLevel_1, TraceLevel_2, and TraceLevel_3 fields.

TraceLevel_1

The TraceLevel_1 field controls whether NotesAgent writes level 1 tracing information about the import operation. It has the same syntax as the TraceLevel_1 field in the export configuration file and is an optional field.

TraceLevel_2

The TraceLevel_2 field controls whether NotesAgent writes level 2 tracing information about the import operation. It has the same syntax as the TraceLevel_2 field in the export configuration file and is an optional field.

TraceLevel_3

The TraceLevel_3 field controls whether NotesAgent writes level 3 tracing information about the import operation. It has the same syntax as the TraceLevel_3 field in the export configuration file and is an optional field.

TraceFileName

The TraceFileName field specifies the pathname of the trace file to which NotesAgent is to write information about the import operation. It has the same syntax as the TraceFileName field in the export configuration file and is an optional field unless the Trace field is specified.

TraceItemTypes

The TraceItemTypes field controls whether NotesAgent writes all item types of all items of the data base (AddrBook ) in trace file.

The syntax is:

TraceItemTypes=[switch]

where switch is one of the following values:

0 - Do not write item types in trace file (default)
1 - Write item types in trace file

For example:

Item data types:
==========================
PhoneNumber = TEXT
Form = TEXT
PasswordChangeInterval = NUMBER
PasswordChangeDate = TIME

AdminReqDB

The AdminReqDB field specifies the name of the Notes Administration Process (adminp) request database to which NotesAgent is to send request documents during "DeleteUser" changetype processing. The syntax is:

AdminReqDB=[filename[.nsf]]

AdminReqDB=admin4.nsf

This is a required field if the import data file to be processed contains "DeleteUser" changetype entries.

AdminReqAuthor

The AdminReqAuthor field specifies the author name of the Notes Administration Process (adminp) request database to which NotesAgent is to send request documents during "DeleteUser" changetype processing. The syntax is:

AdminReqAuthor=name

where name is the author name in canonical format. For example:

AdminReqAuthor=CN=Thomas Diaz/OU=USA/O=Iris

This is a required field if the import data file to be processed contains "DeleteUser" changetype entries.

SearchUniversalID

The SearchUniversalID field controls whether NotesAgent uses the Universal identifier to match entries to be updated in the target Notes address book with entries to be imported into the address book. The syntax is:

SearchUniversalID=switch

where switch is one of the following values:

0 - Do not use the Universal identifier to search for a matching entry (default)
1 - Use the Universal identifier to search for a matching entry

If SearchUniversalID is set to 1, NotesAgent uses the Universal identifier (UniversalIDPart1: to UniversalIDPart4:) of an entry in the import data file as a search key for finding a matching entry in the Notes address book. Using the Universal identifiers to match import data file entries with their counterparts in the Notes address book results in faster import operations.

This is an optional field. If it is not specified (or is not present in the configuration file), NotesAgent uses the SearchNoteID functionality to match entries. If SearchNoteID is not specified, NotesAgent uses the ViewFolder field to match entries. If ViewFolder is not specified, NotesAgent uses the ItemIdentityName fields to match entries.

SearchNoteID

The SearchNoteID field controls whether or not NotesAgent uses the Notes identifier to match entries to be updated in the target Notes address book with entries to be imported into the address book. The syntax is:

SearchNoteID=switch

where switch is one of the following values:

0 - Do not use the Notes identifier to search for a matching entry (default)
1 - Use the Notes identifier to search for a matching entry

If SearchNoteID is set to 1, NotesAgent uses the Notes identifier of an entry in the import data file as a search key for finding a matching entry in the Notes address book. Using the Notes identifiers to match import data file entries with their counterparts in the Notes address book results in faster import operations.

This is an optional field. If it is not specified (or is not present in the configuration file), NotesAgent uses the ViewFolder field to match entries. If ViewFolder is not specified, NotesAgent uses the ItemIdentityName fields to match entries.

ViewFolder

The ViewFolder field controls whether NotesAgent uses a Notes view sorted by the Notes attribute specified in the ItemIdentityName1 field to match entries to be updated in the target Notes address book with the entries to be imported into the address book. The syntax is:

ViewFolder=[view_name]

where view_name is a Notes view. For example:

ViewFolder=People

The specified Notes view must contain the sorted column that has been sorted by the attribute specified in the ItemIdentityName1 field. For example, if ViewFolder specifies "People", and ItemIdentityName1 specifies "LastName", the "People" view must contain a column that has been sorted by the "LastName" attribute. The ItemIdentityName1 field can also specify the value ViewSearchName to indicate that the view has been sorted by a composite attribute, for example, FirstName , LastName. See the ItemIdentityName field description for further details.

NotesAgent uses the view specified in ViewFolder sorted by the Notes attribute specified in ItemIdentityName1 to match the entry when SearchNoteID is set to 0, or when SearchNoteID is set to 1 but a Notes identifier does not exist for the entry.

This is an optional field. If it is not specified (or is not present in the configuration file), and the SearchNoteID field is set to 0, NotesAgent uses the values specified in ItemIdentityName1, ItemIdentityName2, or ItemIdentityName3 fields to match entries.

CaseSensitive

The CaseSensitive field controls whether or not NotesAgent uses case-exact match when using a sorted Notes view to match entries in the target Notes address book with entries to be imported. The syntax is:

CaseSensitive=switch

where switch is one of the following values:

0 - Do not use case-exact match
1 - Use case-exact match (default)

When CaseSensitive is set to 0, NotesAgent uses case-insensitive matching when matching the values in the sorted view against Notes address book entries. When CaseSensitive is set to 1, NotesAgent uses case-sensitive matching.

This is an optional field and is only relevant if the ViewFolder field is used. If it is not specified (or is not present in the configuration file), NotesAgent uses case-sensitive matching.

ComputeWithFormIgnoreErrors

The ComputeWithFormIgnoreErrors field specifies the way the Notes-API “ComputeWithForm” is called before the Notes document is saved. (“ComputeWithForm” calculates computed fields and evaluates validation formulas defined in the form used by the Notes document.)

The syntax is:

ComputeWithFormIgnoreErrors=switch

where switch is one of the following values:

0 - if you want the function to stop at the first error
1 - if you do not want the function to stop executing if a validation error occurs

This field can be in each entry in the import data file. If it is specified in the configuration file it acts as a default value. This means that the value in the import data file can override this default setting. ++ If ComputeWithFormIgnoreErrors is not defined then the Notes-API “ComputeWithForm” is not called.

The Registered User (RegUser) Section

NotesAgent can register entries that it imports into a Notes address book as Notes users with their own mailboxes during the import process. The Registered User section provides the information that NotesAgent needs in order to perform this task and is only required if the RegisterUser field in the Import section is set to 1, 2, 3 or 4. The next sections describe the fields of the Registered User section.

MailboxName

The MailboxName field specifies the mailbox name. The syntax is:

MailboxName=mailbox_name

where mailbox_name is the name of the mailbox. For example:

MailboxName=mail/thcook,nsf

If the MailboxName field is specified then it is used to setup the mname of the mailbox; in this case the ItemMailboxName field is ignored.

ItemMailboxName

The ItemMailboxName field specifies the attribute to use as the mailbox name. The syntax is:

ItemMailboxName=attribute_name

where attribute_name is the name of a Notes attribute whose value NotesAgent should use as a mailbox name when registering the entry as a Notes user and creating a mailbox for it. For example:

ItemMailboxName=ShortName

If the ItemMailboxName field is specified, the entries in the import data file must contain values in the attribute specified in attribute_name.

Internally the following value for the mailbox name is generated:

Mail/value_of_attribute_name.nsf

The ItemMailboxName field is ignored if the MailboxName field is specified.

ItemUserId

The ItemUserId field specifies the attribute to use as the User ID. The syntax is:

ItemUserId=attribute_name

where attribute_name is the name of a Notes attribute whose value NotesAgent should use as a user ID when registering the entry as a Notes user and creating a mailbox for it. For example:

ItemUserId=ShortName

If the ItemUserId field is specified, the entries in the import data file must contain values in the attribute specified in attribute_name.

PathFileCertId

The PathFileCertId field specifies the pathname to the certificate ID file cert.id, which is a binary file that is supplied with the Notes Server installation software. This file contains the certificate that grants NotesAgent the right to create registered users. The syntax is:

PathFileCertId=pathname

where pathname is the pathname to the certificate ID file. For example:

PathFileCertId=a:\cert.id

This is a required field if the import operation is to process the "RenameUser" and "RecertifyUser" changetype operations or if the RegisterUser field is set to 1, 2, 3 or 4. This is a required field that must specify the pathname to the certificate ID file of the source organizational unit if the import operation is to process the "MoveUserInHier" changetype operation.

See the section "Import Data File Format" for further details about these operations.

PathFileCertLog

The PathFileCertLog field specifies the pathname to the certifier logging file certlog.nsf on the server. This file contains the certifier logging entries of the registered users. The syntax is:

PathFileCertLog=pathname

where pathname is the pathname to the certifier logging file. For example:

PathFileCertLog=d:\ibm\domino\data\certlog.nsf

This is a required field if the RegisterUser field is set to 1, 2, 3 or 4.

PathUserId

The PathUserId field specifies the directory in which NotesAgent is to store Notes user IDs created during the user registration process. The syntax is:

PathUserId=directory

where directory is a directory pathname. For example:

PathUserId=e:\notes\data

Notes User IDs are binary user certificate files that NotesAgent creates during the registration process if CreateIdFile is set to 1. NotesAgent writes these user ID files to the directory specified in the PathUserId field if SaveIdInFile field is set to 1.

RegistrationServer

The RegistrationServer field specifies the name of the Notes registration server that is to register the users in the Notes server address book. The syntax is:

RegistrationServer=server_name

where server_name is a the name of a Notes server in the format:

"CN=server_name/O=organization_name[/…]"

For example:

RegistrationServer="CN=Cambridge3/O=Notes/O=IBM"

MailServer

The MailServer field specifies the name of a Notes server on which NotesAgent is to create user mailboxes during the user registration process. The syntax is:

*MailServer=/server_name

where server_name is a the name of a Notes server in the format:

"CN=server_name/O=organization_name[/…]"

For example:

MailServer="CN=Cambridge4/O=Notes/O=IBM"

Entries in the import data file can also specify (as an attribute of the entry) the name of the Notes server on which to create user mailboxes. Mailboxes specified in import entries override the specification in the MailServer field.

MinPasswordLength

The MinPasswordLength field specifies the minimum number of characters that a user password must have. The syntax is:

MinPasswordLength=number

For example:

MinPasswordLength=5

NotesAgent sets the specified value as an attribute of the registered user entry.

If the value is set to 0 the SaveIdInAddressBook field also must be set to 0.

CreateAddressBookEntry

The CreateAddressBookEntry field controls whether NotesAgent creates Notes entries in the target Notes address book for Notes users that it registers during the import process. The syntax is:

CreateAddressBookEntry=switch

where switch is one of the following values:

0 - Register Notes users, but do not create Notes entries for them
1 - Register Notes users and create Notes entries for them

CreateMailDatabase

The CreateMailDatabase field controls whether NotesAgent creates user mailboxes for Notes users that it registers during the import process. The syntax is:

CreateMailDatabase=switch

where switch is one of the following values:

0 - Register Notes users, but do not create mailboxes for them
1 - Register Notes users and create mailboxes for them

CreateIdFile

The CreateIdFile field controls whether NotesAgent creates a user ID file for Notes users that it registers during the import process. The syntax is:

*CreateIdFile=+switch

where switch is one of the following values:

0 - Register Notes users, but do not create a user ID file for them
1 - Register Notes users and create a user ID file for them

If CreateIDFile is set to 1, either the SaveIdInAddressBook field or the SaveIdInFile field (or both) must be set to 1 to specify where NotesAgent is to store the user ID files it creates.

SaveIdInAddressBook

The SaveIdInAddressBook field controls whether or not NotesAgent saves the user ID files it creates as attachments of the Notes entries for the registered users. The syntax is:

SaveIdInAddressBook=switch

where switch is one of the following values:

0 - Do not save user ID files as attachments of the Notes entries for the registered users
1 - Save user ID files as attachments of the Notes entries for the registered users in the Notes address book

If SaveIdInAddressBook is set to 1, NotesAgent creates the user ID file and stores it as an attachment of the corresponding Person entry for the registered user. If SaveIdInAddressBook is set to 1, the registered user must have got a password.

SaveIdInFile

The SaveIdInFile field controls whether or not NotesAgent saves the user ID files it creates in individual files. The syntax is:

SaveIdInFile=switch

where switch is one of the following values:

0 - Do not save user ID files in individual files
1 - Save user ID files in individual files

If SaveIdInFile is set to 1, NotesAgent creates the user ID files and stores them in the directory specified in the PathUserId field.

SaveInternetPassword

The SaveInternetPassword field controls whether or not NotesAgent saves the user ID password also for use as an Internet password. The syntax is:

SaveInternetPassword=switch

where switch is one of the following values:

0 - Do not save user ID password also as Internet password
1 - Save user ID password also as Internet password

If SaveInternetPassword is set to 1, NotesAgent saves the user ID password also in the field for the Internet password.

This field can be contained in each entry in the import data file. If it is specified in the configuration file it acts as a default value. This means that the value in the import data file can override this default setting.

CreateNorthAmericanId

The CreateNorthAmericanId field controls whether or not NotesAgent creates United States security encrypted User ID files. The syntax is:

CreateNorthAmericanId=switch

where switch is one of the following values:

0 - Do not create U.S.-encrypted user ID files
1 - Create U.S.-encrypted user ID files

If CreateNorthAmericanId is set to 1, the Notes registered user can only be used within the United States. This field is disabled for NotesAgent installations outside the United States.

ClientType

The ClientType field specifies the type of Notes client that NotesAgent is to associate with the registered users it creates during the import process. The syntax is:

ClientType=number

where number is one of the following values:

1 - Create registered users of client type "desktop"
2 - Create registered users of client type "complete"
3 - Create registered users of client type "mail"

The client types correspond to the different kinds of licenses available for Notes clients.

SMTPHostDomain

The SMTPHostDomain field specifies the domain name of the internet addresses of the user. The syntax is:

SMTPHostDomain=domain name

MailTemplate

The MailTemplate field specifies the name of the mail template database. The syntax is:

MailTemplate=name of the template data base

DbQuotaSizeLimit

The DbQuotaSizeLimit field specifies the size limit of the mail file. The syntax is:

DbQuotaSizeLimit=number

where number is the size in MB.

DbQuotaWarningThreshold

The DbQuotaWarningThreshold field specifies the size of the mail file at which a warning is displayed. The syntax is:

DbQuotaWarningThreshold=number

where number is the size in MB.

CreateMailDBNow

The CreateMailDBNow field specifies that the mail file is created during the registration. The syntax is:

CreateMailDBNow=number

where number is one of the following values:

0 - Create mail file later with the administration process
1 - Create mail file during the registration

MailOwnerAccess

The MailOwnerAccess field specifies the mail owner’s ACL privileges. The syntax is:

MailOwnerAccess=number

where number is one of the following values:

0 - Manager (default)
1 - Designer
2 - Editor

MailSystem

The MailSystem field specifies the type of the mail system. The syntax is:

MailSystem=number

where number is one of the following values:

0 - NOTES (default)
1 - CCMAIL
2 - VINMAIL
99 - NONE

MailACLManager

The MailACLManager field specifies the manager name of the access control list of the mail file. The syntax is:

MailACLManager=name

where name is the manager name in canonical format. For example:

MailACLManager=CN=Administrator/O=MyCompany

MailForwardAddress

The MailForwardAddress field specifies the forwarding address of a Domino domain or foreign mail gateway. The syntax is:

MailForwardAddress=name of the forwarding address

CreateMailFullTextIndex

The CreateMailFullTextIndex field specifies that a full text index is created when creating the mailbox. The syntax is:

CreateMailFullTextIndex=number

where number is one of the following values:

0 - Do not create mail full text index
1 - Create mail full text index

If absent, then the mail full text index is created. (That default behavior is compatible with older releases of the NotesAgent where that parameter was not configurable.)

CreateMailReplicas

The CreateMailReplicas field specifies that the mail replicas should be created with the administration process. The syntax is:

CreateMailReplicas=number

where number is one of the following values:

0 - Do not create mail replicas
1 - Create mail replicas with the administration process

If absent, then no mail replicas are created. (That default behavior is compatible with older releases of the NotesAgent where that parameter was not configurable.)

MailReplicaServer

The MailReplicaServer field specifies the Notes servers that holds a mail replica. The syntax is:

MailReplicaServer=server_name 1 | server_name 2 | … | server_name n

where server_name is a the name of a Notes mail server in the format:

"CN=server_name/O=organization_name[/…]"

For example:

MailReplicaServer="CN=Cambridge4/O=Notes/O=IBM | "CN=New York/O=IBM"

In the INI file, the mail replica servers are defined on a single line and are separated by "|". A "|" at the end of the definition will be accepted, but ignored.

This field is an optional field and will only be evaluated if the RegisterUser field is set to 4.

In the import data file, the definition looks a little bit different. Each mail replica server is defined in a seperate line. The syntax is as follows:

MailReplicaServer:server_name 1

MailReplicaServer:server_name 2

…

MailReplicaServer:server_name n

PreferredLanuage

The PreferredLanguage field specifies the user’s language. The syntax is:

PreferredLanguage=language

where language is the user’s preferred language. For example:

PreferredLanguage=de

AltLanguage

The AltLanguage field specifies a user’s alternate language. The syntax is:

AltLanguage=language

where language is the user’s alternate language. For example:

AltLanguage=de

OnDuplicate

The OnDuplicate field specifies the action to execute in case the new user is already available. The syntax is:

OnDuplicate=option

where option is one of the following values:

0 - terminate without creating the user (REG_FILE_DUP_STOP); default
1 - create a unique user (?) (REG_FILE_DUP_UNIQUE)
2 - overwrite the existing user (REG_FILE_DUP_OVERWRITE)

For example:

OnDuplicate=0

This field can be in each entry in the import data file. If it is specified in the configuration file it acts as a default value. This means that the value in the import data file can override this default setting. If this attribute is neither specified in the import data file nor in the configuration file, then the default value 0 applies.

PasswordKeyWidth

The PasswordKeyWidth specifies the encryption strength of the user’s password in bits. The syntax is:

PasswordKeyWidth=encryption_strength

where encryption_strength is one of the following values:

0 - default; (means 64 bits for PasswordKeyWidth < 1024 else 128 bits)
64
128

For example:

PasswordKeyWidth=0

This field can be in each entry in the import data file. If it is specified in the configuration file it acts as a default value. This means that the value in the import data file can override this default setting. If this attribute is neither specified in the import data file nor in the configuration file, then the default value 0 applies.

KeyWidth

The KeyWidth field specifies the key width in bits. The syntax is:

KeyWidth=width

where width is one of the following values:

0
630 - Compatible with all releases
1024 - Compatible with R6 and later
2048 - Compatible with R7 and later

For example:

KeyWidth=0

This field can be in each entry in the import data file. If it is specified in the configuration file it acts as a default value. This means that the value in the import data file can override this default setting. If this attribute is neither specified in the import data file nor in the configuration file, then the default value 0 applies.

InetKeyWidth

The InetKeyWidth field specifies the width of the internet key in bits. The syntax is:

InetKeyWidth=width

where width is one of the following values:

0 - default width
1024

For example:

InetKeyWidth=0

This field can be in each entry in the import data file. If it is specified in the configuration file it acts as a default value. This means that the value in the import data file can override this default setting. If this attribute is neither specified in the import data file nor in the configuration file, then the default value 0 applies.

PasswordQuality

The PasswordQuality field specifies the quality of the user’s password required for this server. The syntax is:

PasswordQuality=quality

where quality is a value between 0 and 16.

For example:

PasswordQuality=0

This field can be in each entry in the import data file. If it is specified in the configuration file it acts as a default value. This means that the value in the import data file can override this default setting. If this attribute is neither specified in the import data file nor in the configuration file, then the default value 0 applies.

The Password (Password) Section

The Password section consists of fields that define the parameters for NotesAgent automated password authentication. The next sections describe these fields.

PathFilePassword: The PathFilePassword field is only used for the old password handling mechanism.

For a description of the old password handling mechanism, see the section "Password Configuration File Formats".

The syntax for this field is:

PathFilePassword=pathname

where pathname is the pathname to the password configuration file NotesPassword.ini. For example:

PathFilePassword=a:\NotesSync\NotesPassword.ini

For security reasons, it is recommended that the password configuration file not be stored on disk, since it contains human-readable representations of Notes address book administrator and registered user passwords.
AutomaticPW: The AutomaticPW field specifies the password that NotesAgent (in conjunction with a NotesAgent DLL) is to use to decode the admin.id certificate; this is the certificate that grants it the credentials to log in to the Notes server.

The "PathAndFileOfNotesIDFile" field can alternatively be indicated.

If the field "PathAndFileOfNotesIDFile" is available for a ID file, it has higher priority.

The syntax is:

AutomaticPW=password

For example:

AutomaticPW=notes
PathAndFileOfNotesIDFile: A certifier Notes ID can be protected with up to three passwords. The standard is the protection with just one password. For each certifier Notes ID file the Notes Agent needs a pair of "Path and file name of ID file" and the "corresponding password". The syntax is:

Path and file Name of notes.id{[_1|_2|_3]}=password{[1|2|3]}

For example:

C:\IBM\Notes\certs\cert.id=notes
to protect the certifier Notes ID with just one password

or

C:\IBM\Notes\certs\cert.id_1=notes1
C:\IBM\Notes\certs\cert.id_2=notes2
to protect the certifier Notes ID with two passwords.
UserPassword: The UserPassword field specifies the default password that NotesAgent is to assign to any registered user it creates during the import process. The syntax is:

UserPassword=password

For example:

UserPassword=notes

NotesAgent uses the default password supplied in this field for entries in an import data file that do not contain a Password attribute value. If an entry in an import data file contains a Password attribute value, NotesAgent assigns this value as the user password when it creates the registered user.

This is an optional field unless the NotesAgent is to create registered users (the RegisterUser field is set to 1 or 2).

The EncryptedAttributes (EncryptedAttributes) Section

The EncryptedAttributes section is an optional section that lists attributes which are encrypted in the import data file and have to be decrypted by the agent before they are passed to the Notes Interface. This functionality only works correctly in an appropriate security environment like in the DirX Identity environment configured in security mode. (See DirX Identity Connectivity Administration Guide). The attributes are listed in the format:

attribute=1

where attribute specifies the attribute names to be imported.

For example:

[EncryptedAttributes]
Password=1

Password Configuration File Formats

This chapter is provided only for compatibility reasons. It describes the old password handling mechanisms of the NotesAgent.

NotesAgent uses password configuration files to:

Supply the password that grants it the credentials to log in to a Notes server from an installed Notes client. NotesAgent must use password authentication to a Notes server in order to export data from an address book or import data into it. The password can be supplied at login:
- Manually, at the user prompt
- Automatically, through the use of password configuration files
Supply the password that grants it the credentials to register users during an import operation
Provide a default password for registered users created during an import.

Templates of the password configuration files are provided with the NotesAgent installation. The filenames are:

NotesPathPWIni.ini
NotesPassword.ini

The next sections describe the password configuration file formats.

Notes Password Pathname Configuration File

The Notes password pathname file specifies the pathname to the password configuration file that contains:

The password that NotesAgent is to use to automate the granting of credentials to log in into a Notes server
The password(s) that NotesAgent is to use to obtain the credentials required to register users
The default password that NotesAgent is to assign to any registered users that it creates during an import. NotesAgent must be able to assign a password to a registered user in order to create a user ID file for it in the Notes address book.

The Notes Password Pathname configuration file consists of one section - Password - which contains one field-PathFilePassword. The syntax for this field is:

PathFilePassword=pathname

where pathname is the pathname to the password configuration file NotesPassword.ini. For example:

PathFilePassword=a:\NotesSync\NotesPassword.ini

For security reasons, it is recommended that the password configuration file not be stored on disk, since it contains human-readable representations of Notes address book administrator and registered user passwords.

Password Configuration File

The Password configuration file stores passwords used by NotesAgent. It contains two sections - Password and certifierPW (only up to version 1.03). The next sections describe the fields within these sections.

The Password Section (up to Version 1.03)

AutomaticPW

The AutomaticPW field specifies:

The password that NotesAgent (in conjunction with a NotesAgent DLL) is to use to decode the admin.id certificate; this is the certificate that grants it the credentials to log in to the Notes server
The password that NotesAgent is to use to decode the cert.id certificate; this is the certificate that grants it the credentials to register users

The password to decode the cert.id certificate must be the same as the password to decode the admin.id certificate in order to be able to use the AutomaticPW field for automating authenticated login. There are also steps that must be followed during the NotesAgent installation to enable automatic password authentication at login; see the DirX Identity Release Notes for details.

The syntax is:

AutomaticPW=password

For example:

AutomaticPW=notes

CertifierPW

The CertifierPW field specifies the password that NotesAgent is to use to decode the cert.id certificate (the certificate that grants it the credentials to register users) during RenameUser, RecertifyUser, DeleteUser and MoveUserInHier operations and during user registration where the RegisterUser field is set to 2, 3 or 4. The syntax is:

CertifierPW=password

For example:

CertifierPW=notes

This is an optional field. If it is not specified (or is not present in the configuration file), the agent uses the password from the CertifierPW section (see below). If there the password for the cert.id is also not specified, the user is prompted for the password.

TargetCertifierPW

The TargetCertifierPW field specifies the password that NotesAgent is to use to decode the cert.id certificate (the certificate that grants it the credentials to register users) of the target organizational unit during "MoveUserInHier" operations. The syntax is:

TargetCertifierPW=password

For example:

TargetCertifierPW=notes

UserPassword

The UserPassword field specifies the default password that NotesAgent is to assign to any registered user it creates during the import process. The syntax is:

UserPassword=password

For example:

UserPassword=notes

NotesAgent uses the default password supplied in this field for entries in an import data file that do not contain a Password attribute value. If an entry in an import data file contains a Password attribute value, NotesAgent assigns this value as the user password when it creates the registered user.

This is an optional field unless the NotesAgent is to create registered users (the RegisterUser field is set to 1 or 2).

The CertifierPW Section (only up to version 1.03)

If the agent registers users in several organizational units and each unit uses an own cert.id (with password), the agent needs for each cert.id a password.

In this section each line is a pair of "Path and file name of cert.Id" and the "corresponding password".

Path and file Name of cert.id=password

For example:

[CertifierPW]
C:\IBM\Notes\certs\cert.id=notes

This is an optional field. If it is not specified (or is not present in the configuration file), the user is prompted for the password.

The Password Section (version 1.04 and newer)

The Notes Agent needs to provide ID files and the corresponding passwords so that it enables the Notes client to decode the certificates that are stored in the relevant ID files.

The following ID files and passwords are needed:

Full path name of administrator ID file for connecting to the IBM Domino Server and its relevant password
Full path name of cert.id and its relevant password
Full path name of other certifier ID files and their relevant passwords

These certifier ID files are needed if you plan to move users to different organizational units.

That information is stored in the bind profiles of a Notes target system.

The Notes Agent needs to know which one of the ID files is the one it could use for connecting to the Domino server. Therefore the display name of bind profile is part of the entries in the password section. The Notes Agent uses the entry with display name “Admin” for connecting to the Domino Server.

The format of the Password section is as follows:

[Password]

display_name|full_path_name_of_ID_files=password

Example:

[Password]
Admin|c:\Program Files\ ibm\notes\data\ids\admin.id=pwd1
Certifier| c:\Program Files\ ibm\notes\data\ids\cert.id=pwd2
Sales-OU| c:\Program Files\ ibm\notes\data\ids\sales.id=pwd3

Export and Import Data File Format

The NotesAgent import and export data files use a tagged file format. The next sections describe the:

General characteristics of export and import data file formats
Delta export data file format
Import data file format

General Data File Format

The NotesAgent export and import data files have the following characteristics:

Each entry attribute is contained on one line; line continuation is not permitted.
The representation of each attribute is:

attribute_name:attribute_value(s)
Leading and trailing whitespace between attribute_name and attribute_value is ignored. For example, in the attribute:

FullName: Timothy Michael Halvorsen

The white space between the colon (:) and the start of the attribute value is ignored, but the white space within the attribute value is returned
The form-feed character (0x0c) is used as a record (entry) separator
The form-feed character can optionally appear as the first line in the file
There is no special character processing (there is no "escaping" mechanism)

Here is an example of a person entry:

NoteID: 8453
Form: Person
Type: Person
Department: ENG,eng3
FullName: Alan Eldredge
City: Westford
ShortName: aeldredge
FirstName: Alan
LastName: Eldredge
Password: secret
State: MA
CompanyName: Iris Associates
InternetAddress: aeldredge@eng.iris.com
(0x0c is here as the record (entry) separator)
NoteID: 8454
Form: Person
Type: Person
…

Here is an example for a group entry:

NoteID: 8498
Form: Group
Type: Group
GroupType: 0
Form: Group
ListName: IrisAdminGroup
LocalAdmin: CN=Alan Eldredge/O=ENG3
$UpdatedBy: CN=Alan Eldredge/O=ENG3
GroupTitle: 0
Members: Ian Gillan,Roger Waters
ListOwner: CN=Alan Eldredge/O=ENG3
DocumentAccess: [GroupModifier]
AvailableForDirSync: 1

The following group attributes have numeric values:

GroupType - specifies the use of the group and can have the values:
0 (multi purpose)
1 (mail only)
2 (access control list only)
3 (deny list only)
GroupTitle - specifies the title of the group and can have the values:
0 (group)
1 (mailing list)
2 (access list)
3 (deny access list)
AvailableForDirSync - specifies whether the group is available for synchronization (so that NotesAgent can export it) and can have the values:
0 (not available for synchronization)
1 (available for synchronization)

Delta Export Data File Format

The delta export data file ("modify/delete") generated when ModifiedAddresses is set to 1 uses LDIF per-entry "changetype" attributes to indicate the type of modification made to the entry since the last full export. The "modify" changetype attribute is applied to new or modified entries, and the "delete" changetype attribute is applied to entries that have been deleted. For example:

Changetype: delete
NoteID: 5430
Form: Person
Type: Person
Department: ENG,eng3
FullName: Jack Ozzie
City: Westford
ShortName: jozzie
FirstName: Jack
LastName: Ozzie
Password: secret
State: MA
CompanyName: Iris Associates
InternetAddress: jozzie@eng.iris.com
(0x0c is here as the record (entry) separator)
Changetype: modify
NoteID: 5478
Form: Person
Type: Person
Department: ENG,eng2
FullName: Len Kawell
City: Westford
ShortName: lkawell
FirstName: Len
LastName: Kawell
Password: secret
State: MA
CompanyName: Iris Associates
InternetAddress: lkawell@eng.iris.com
...

Import Data File Format

An entry in an import data file can contain the following optional attributes:

An optional (text format) attribute UniqueOrgUnit, whose value is used as an additional value for OrganizationUnit to distinguish between entries with identical names; that is, identical values for the FirstName, MiddleInitial, LastName attributes.
An optional (integer) attribute Validity, whose value specifies the lifetime, in days, for which the user certificate is valid (the default is 730 (2 years)).

The import data file format supports the LDIF per-entry "changetype" attribute that indicates the type of modification to be made to the entry in the Notes address book. The value for "changetype" is one of "add", "modify", "delete", "RenameUser", "RecertifyUser", "DeleteUser" or "MoveUserInHier". The changetype attribute name and its values are case-insensitive.

The attributes for a multivalued attribute specified in a "modify" changetype operation appear on separate lines. For example:

add: OfficeFaxPhoneNumber
OfficeFaxPhoneNumber: 123458
OfficeFaxPhoneNumber: 345892
-

Entries with a "modify" changetype contain attributes that indicate one or more "add", "delete", or "replace" attribute value modifications. The "replace" modification has a higher precedence than the "add and "delete" modifications; if it is present for an attribute, it is the only modification evaluated. For the "modify" changetype, NotesAgent adds a new entry in the Notes address book if it does not find a matching entry.

The "RenameUser" changetype renames a registered user. The user may need to confirm renaming when he logs on to Notes the next time. The entry must contain the OldUserName (in canonical format) and LastName attributes. The FirstName, MiddleInitial, UniqueOrgUnit. and Validity attributes are optional. For example:

OldUserName: CN=Armen Varteressian/OU=USA/O=MyCompany
LastName: Varteressian
Validity: 365

To perform this operation, the PathFileCertId field in the RegUser section of the import configuration file must be specified.

The "RecertifyUser" changetype re-certifies a registered user. The re-certification is completed when the user logs on the next time using the new certificate. The entry must contain the UserName (in canonical format) attribute and the PathFileCertId field in the RegUser section of the import configuration file must be specified.

The "DeleteUser" changetype deletes the user in "Person Documents", "Access Control List" and in "Reader/Author" fields and deletes his mail file subject to confirmation in the request database (approve file deletion) by the Notes Administrator. The following attributes must be present in the import entry:

UserName (in canonical format)
MailServer (in canonical format)
MailFile (mail file name including path relative to the Notes data directory)
DeleteMailFile (0=don’t delete mail file;1=delete just mail file specified in person record;2=delete mail file specified in person record and all replicas)

For example:

UserName: CN=Armen Varteressian/OU=USA/O=MyCompany
MailServer: CN=Neptune/O=MyCompany
MailFile: mail\Varteres
DeleteMailFile: 2

In order to perform this operation, the AdminReqDB and AdminReqAuthor fields in the Import section of the import configuration file must be specified, and the DeleteEntries field must be set to 0. If DeleteEntries is set to 1 or a "delete" changetype entry is processed, the user is deleted in the Notes address book only and his mail file is retained.

The "MoveUserInHier" changetype moves a user to a different organizational unit and renames the full username. In order to perform this operation:

The Notes Client V5.0 must be installed
The source and target organizational units must have different certificate ID (cert.id) files
The PathFileTargetCertID field specifies the pathname to the certificate ID file of the target organizational unit, for example:

PathFileTargetCertID: a:\German.id
The PathFileCertID field specifies the pathname to the certificate ID file of the source organizational unit, for example:

PathFileCertID: a:\cert.id
The password configuration file must contain the passwords for both source and target organizational unit certificate IDs in the Password section, for example:

CertifierPW=*password_for_source_organization
TargetCertifierPW=*password_for_target_organization

or in the CertifierPW section, for example:

C:\IBM\certs\source_cert.id=password_for_source_organization C:\IBM\certs\target_cert.id=password_for_target_organization
The FullName and TargetCertifier attributes must be present in the import entry in canonical format. For example:

FullName: CN=Armen Varteressian/O=MyCompany TargetCertifier: OU=Germany/O=MyCompany

The values in the relevant fields in the import configuration file have a higher precedence than the changetype operations specified in the import data file. For example, if DeleteEntries is set to 1, NotesAgent deletes entries that match entries in the import data file from the Notes address book regardless of the change types specified for the entries in the import data file.

The import data file can contain comments, which are identified by a # character at the beginning of a line.

For Person entries, the LastName attribute must be the first attribute for the entry, the FirstName attribute must be the second attribute, and the MiddleInitial attribute must be the third attribute. For Group entries, the ListName attribute must be the first attribute for the entry. The ordering for all other attributes for Person and Group entries is arbitrary.

Import Error File Format

During the import process, NotesAgent writes the original attributes and values of entries that it is unable to import into the error file specified on the command line along with an error message that describes the error. Each line in the import error file generated by NotesAgent on an import operation has the following format:

source_entry
#error_code
#error_message

where source_entry is the original entry that NotesAgent was unable to import, error_code is the code for the error that occurred, and error_message is a description of the error. For example:

FirstName: Armen
LastName: Varteressian
CompanyName: Digital
Type: Person
FullName: Armen Varteressian
ShortName: avart
City: Nashua
Department: PUBS,VMSpubs
State: New Hampshire
#ProcessAddress error:
#Find more as one document with the following ItemIdentityName(s): FirstName, LastName

Any entry that cannot be imported into the Notes address book is written into the import error file. Consequently, you can use the file as an input file and re-run the import operation, after first fixing the errors reported in the file.

Notes Agent Import Procedure

If NotesAgent encounters a single-valued attribute in an import data file that has more than one value defined, it takes the first value.

The order of operation on attributes is arbitrary. An import entry should not contain inconsistent attribute operations for the entry.

NotesAgent creates groups with GroupType 0-2 in the Groups folder of the Notes address book. It creates groups with GroupType 3 in the Server/Deny Access Groups folder.

The import configuration fields RegisterUser, ClientType, PathFileCertId and PathFileTargetCertId can be present as attributes of an entry to be imported. The syntax is:

field_name*:* field_value

The colon character (:) is the name and value separator. For example:

RegisterUser: 1
ClientType: 1
PathFileCertId: d:\notes\data\certs\cert.id
PathFileTargetCertId: d:\notes\data\certs\sales.id

When present in the entry, the values in these attributes override the values specified in the fields of the import configuration file. When absent from the entry, NotesAgent uses the fields' default values from the configuration file.