Preparing to import user information into the NDS database

This topic gives some background information you should be familiar with before performing the import.

Generating the data file

You generate a data file from within your database application, or any other application, by saving the data as a delimited ASCII text file. Most applications use commas as the default field separator and quotation marks as the default delimiter.

If you need instructions on how to save your data as a delimited ASCII file, see the documentation accompanying your application.

Embedded punctuation

Before you generate a data file from within your database application, look for embedded punctuation in the data fields.

If you do, UIMPORT will not be able to distinguish between new fields and embedded punctuation.

Since embedded quotation marks and commas are the most commonly found punctuation in database fields, here are some guidelines, grouped according to four situations you might encounter, to help you avoid problems in generating a data file:

• You have both embedded quotation marks and embedded commas that you do not want to delete.

  We recommend that you export the data using a different character for the comma separator, and that you do not use quotation marks as delimiters.

  For example, you could export data with carets (^) in place of comma separators. As a result, carets would separate the fields in the data file you generate. You must specify in the import control file the replacement character you use. (See the listing in ``Control parameters''.)

  You should also export data without using quotation marks to delimit the fields. If your application uses quotation marks as the default delimiter, you must change the delimiter to a different character or choose to use no delimiter.

  If you use a different character, you must specify in the import control file the replacement character you use. (See the listing in ``Control parameters''.)

• You have neither embedded quotation marks nor embedded commas.

  We recommend that you export the data using commas to separate the fields.

  If your application inserts quotation marks as delimiters around each field, you can either accept this default or choose to use no delimiter.

• You have embedded commas, but no embedded quotation marks.

  We recommend that you export the data using a different character for the comma separator.

  For example, you could export data with carets (^) in place of comma separators. As a result, carets would separate the fields in the data file you generate. You must specify in the import control file the replacement character you use. (See the listing in ``Control parameters''.)

  If your application inserts quotation marks as delimiters around each field, you can either accept this default or choose to use no delimiter.

• You have embedded quotation marks, but no embedded commas.

  We recommend that you export data using commas to separate the fields and without using quotation marks to delimit the fields.

  However, if your application uses quotation marks as the default delimiter, you must change the delimiter to a different character or tell your application to use no delimiter.

  If you use a different character, you must specify in the import control file the replacement character you use. (See the listing in ``Control parameters''.)

Required ``Name'' Field

One of the fields required to create new user objects in the NDS database is name. If you do not have a field in your database that records each individual's login name, you have a few options:

• You can create a login name field within your application (and assign each individual a unique eight-character login name) before generating the data file. This option is recommended.

• You can generate the data file and then add a unique login name field to each string of user information in the data file.

• You can use an existing field in your application to represent the login name field. For example, you may have a field of employee or ID numbers. You can generate the data file and import the unique numbers into NDS as user login names. (Keep in mind that numbers are not as easy to recognize or manage as names.)

Creating the import control file

You can create the import control file using any text editor under DOS or OS/2.

This file controls how the information in the data file will be imported into the NDS database and determines which fields (called properties in NDS) the data will be placed in. The import control file contains two types of information:

• Control parameters define characters used in the data file and specify how data is updated.

  Control parameters are listed in ``Control parameters''; field definitions are listed in ``Field definitions''.

• Field definitions determine where data is put in the NDS database (which properties the fields are imported into).

• Enter control parameters first, followed by field definitions, as follows:

  Import control
     Separator=^
     User template=y
  Fields
     Last name
     Name
     Telephone
     Title
  

• Control and field parameters are not case-sensitive. The headings ``Import Control'' and ``Fields'' must be left aligned (you do not have to specify import control parameters if you use the defaults).

• Entries under the headings must be preceded by at least one space or a tab.

• To create a new user, two field definitions are required: ``Name'' (the user's login name) and ``Last name''.

• To update records for users who have already been created, only the ``name'' field is required. These fields are listed in ``Field definitions''.

• All fields in the data file must have a corresponding field definition in the import control file. To see a sample data file and its corresponding import control file, see ``Data file created from exported database fields''.

After generating the data file and creating the import control file, see ``Creating user objects with the UIMPORT utility'' to start the import process.

For more information about creating and managing User objects, see ``Setting up and managing NDS objects''. Details of starting the import process can be found in ``Creating user objects with the UIMPORT utility''.

Control parameters

Use the application control parameters in the following list to create the ``Import control'' section of the import control file. These can be changed by adding the control parameter in the data file. When doing so, add an exclamation point (!) before the control parameter in the data file. (See ``Data file edited to update user objects''.)

• Create home directory

  Allows you to create a home directory for User objects.

  If you create a home directory, users automatically receive filesystem rights to work in that directory. This option will not work unless you set the ``Home directory path'' and ``Home directory volume'' control parameters.

  (Also, this option will not work if you define a data field for ``Home Directory'', because that field will override Create home directory.)

  For example, if you want the users you are importing to have a home directory, type CREATE HOME DIRECTORY=Y.

  The default setting is ``N'', so if you don't want to create home directories, no parameter is needed.

  Note that if you don't set this parameter to ``Y'', you can still import Home Directory values through the control section of the import control file or through the data file. These values will be put into the object's Home Directory property, but the directory on the file system will not be created.

• Delete Mailbox Dirs

  Allows you to delete the mailbox directories when moving a user's mailbox from one messaging server to another or changing the mailbox ID of a user.

  To delete the mailbox directories, type DELETE MAILBOX DIRS=Y.

  The default is ``N''; so if you don't want to delete the mailbox directories, no parameter is needed.

• Delete property

  Allows you to delete values for a property of a User object.

  For example, to delete all titles from a User object's Title property, type DELETE PROPERTY=#DEL, and then edit the data file by putting ``#DEL'' in the Title field.

  If you delete a group membership, you also delete the security equivalents for the group.

  You cannot delete the following properties with the Delete property parameter:

  • Volume restrictions. To delete volume restrictions, enter the volume name and a negative integer such as -1 for the restrictions. For example: VOL1:-1

  • Password. To delete the password, enter "" (a null field) for the password field.

  • Home directory. You can delete the Home directory property, but the home directory path will not be deleted by UIMPORT. You must go manually to this directory and delete it.

  There is no default for this property, so if you don't want to delete properties, no parameter is needed.

  For more information, see ``Creating user objects with the UIMPORT utility''.

• Home directory path

  If you create a home directory for User objects, you must specify a path in the filesystem where you want the directories to be created. This and the Home directory volume must be entered as a pair. If you specify a Home directory volume, the path will be assumed to be null unless this field is also specified.

  If you want home directories created in the Users directory, type HOME DIRECTORY PATH="USERS". Do not include the volume name in the path.

• Home directory volume

  If you create a home directory for User objects, you must specify the name and context of the Volume object associated with the filesystem where the home directories are created.

  For example, if the file specified in ``Home directory path'' is on volume SYS:, enter the Volume object's complete DS name. For example: HOME DIRECTORY VOLUME="SYS.STUDENT RECORDS.UNIVERSITY".

  When creating users, the Home directory volume is set in the following order:

  1. Information in the data file. If the data file has a home directory specified, its value will be used.

  2. If there is no home directory specified in the data file, the home directory from the User Template object will be used. This happens regardless of whether or not you select to copy the user template properties when creating users.

  3. If the home directory is not found in the data file or the User Template, this control parameter (Home directory volume) will be used.

• Import mode

  Controls how the User objects will be created or updated. Options are:

  C

  create new objects only

  U

  update data for existing objects only

  B

  both create and update

  R

  remove objects

  The default is ``B'', so if you want new objects to be created and existing users updated, no parameter is needed.

  Note that you can use the same import control file for adding and deleting users by just changing the Import mode to R (Remove objects). This can be especially useful if you have just created some users with incorrect information and need to restart the entire process. Change the Import mode to R, run UIMPORT to delete the users, then change the Import mode back to C or B and rerun UIMPORT.

• Maximum directory retries

  Allows you to specify how many times UIMPORT should attempt to get the object ID of the user you have just added in order to create home directories and mailbox directories.

  For example, type MAXIMUM DIRECTORY RETRIES=5.

  If NDS creates your user on one server's replica and you create the home or mailbox directory on another server, the second server may not know about the user immediately. This option allows time for the network to catch up with the request to add the user on the other server.

  Initially this option is set to 5; but you should increase the number if you get the message 991: An error occurred in NWDSMapNameToID.

• Name context

  Specifies the NDS context where user objects will be created. You should always use this parameter.

  For example, if you are in the Organization Development.ACME and you want to create user objects in a different Organizational Unit (Engineering), type NAME CONTEXT=.ENGINEERING.ACME.

  The default is your current context (the context displayed when you type CX from the command line).

• Quote

  Specifies the character used to delimit fields when exporting data to the data file. You might want to change the delimiter from quotation marks to different characters if your data has embedded quotation marks and you don't want to delete them.

  For example, if you have any embedded quotation marks in fields in your database, you could export data using carets (^) as the delimiter. You would enter QUOTE=^ as the quote parameter.

  The default characters for delimiters are quotation marks (" "). If you don't have embedded quotation marks in fields in your database and you generate the data file with quote delimiters, no parameter is needed.

• Replace value

  Allows you to overwrite or add data to multivalue properties.

  For example, to import new telephone numbers to User properties without saving the existing numbers, type REPLACE VALUE=Y.

  The default is ``N'', so if you don't want data to be added to multivalued properties, no parameter is needed. You do not need to set this parameter for single-value fields, because the new value automatically overwrites the existing value.

• Separator

  Specifies the character used to separate fields when exporting data to the data file.

  If the fields in your database have embedded punctuation (such as commas), you should not use the same punctuation as field separators when you export the data to the data file. If you do, UIMPORT won't be able to distinguish between new fields and embedded punctuation. Instead, use a different character as the separator.

  For example, if you have any embedded commas in fields in your database, you could export the data using a semicolon (;) as the field separator. You would enter SEPARATOR=; as a control parameter.

  The default separator is a comma. If you have no embedded commas in fields in your database and you generate the data file with comma separators, no parameter is needed.

• User template

  Specifies whether you want user template defaults to be applied to the User objects being created. (User template defaults are explained in ``Managing user templates''.)

  To apply template properties to User objects, type USER TEMPLATE=Y. Template properties are applied first, and then properties from the data file are imported.

  The default is ``N'', so if you do not want the user template defaults applied to the new User objects, no parameter is needed.

  The following fields are copied from the user template: Account balance, Account has expiration date, Allow unlimited credit, Allow user to change password, City, Days between forced changes, Default server, Department, Description, Fax number, Foreign Email address, Foreign Email alias, Full name, Generational qualifier, Given name, Grace logins allowed, Group membership, Home directory, Language, Location, Login allowed time, Login script, Low balance limit, Mailbox location, Mailing label information, Maximum connections, Minimum password length, Network address restriction, Postal (ZIP) code, Postal office box, Profile, Remaining grace logins, Require a password, Require unique passwords, Security equal to, See also, State or province, Street address, Telephone, Title.

Field definitions

Use the applicable field definitions in the following table to create the import control file.

A single-value property can contain only one entry (property). If you put more than one entry for a single-value property in the control file, only the last one is saved.

A multiple-value property can contain more than one entry. If you want to replace existing values in existing users, make sure to set the Replace Value control parameter to ``Y''. By default, all values are added to those already in the user object.

• Account balance

  Single-value property. In the data file, enter the beginning account balance for the user. If accounting is not turned on, this field has no use.

• Account disabled

  Single-value property. In the data file, enter ``Y'' if you want to disable this account.

  If you enter ``Y'', you can't modify Password or Login script.

  The default is ``N''; so if you don't want the account disabled, no field is required.

• Account has expiration date

  Single-value property. In the data file, enter the date in the form MM/DD/YY. It will expire at 12:01 a.m. on that date.

• Allow unlimited credit

  Single-value property. In the data file, enter ``Y'' to allow unlimited credit. Enter ``N'' to not allow unlimited credit. If accounting is not turned on, this field has no use.

  The default is ``N''.

• Allow user to change password

  Single-value property. If you don't want the user to be able to change his or her password, enter ``N'' in the data file. The default is ``Y'', so if you want to allow the user to change the password, no parameter is needed.

• City

  Single-value property. In the data file, enter the name of the city.

• Date password expires

  Single-value property. In the data file, enter the date the password expires in the form MM/DD/YY. It will expire at 12:01 am on that date.

• Days between forced changes

  Single-value property. In the data file, enter the number of days before requiring the user to change the password.

  The default is 40.

  The possible values for this field are numbers 1 through 365. Do not set this value to 0.

• Default server

  Single-value property. In the data file, enter the name of the server from which the user gets messages when they are sent with the SEND utility.

  In the data file, enter the NDS name of the server, including the context if the server is not in the same context as the user.

• Department

  Multivalue property. In the data file, enter the department name, code, number, or other type of information.

• Description

  Single-value property. In the data file, enter any type of information about the user that you want to import. The field must be enclosed in quotation marks (or the delimiter defined in the control file) if it contains commas or new-line characters.

  This field is a string; all data from the opening to the closing quotation mark is considered part of the field.

• Fax number

  Multiple-value property. In the data file, enter the fax number for each user you want to import.

• Foreign email address

  Single-value property. In the data file, enter the foreign email address of the user, which specifies a mailbox that resides in a foreign email system.

  The format for this value is Type:Value, where Type is the type of messaging protocol and Value is the user's address (in the format required by the foreign email system).

  For example, in your data file you could enter a field such as SMTP:Jjones@Acme.com.

• Foreign email alias

  Multiple-value property. In the data file, enter the foreign email aliases of the user, which specify an object's aliases as known in a foreign messaging system.

  The format for this value is Type:Value, where Type is the type of messaging protocol and Value is the user's name (in the format required by the foreign email system).

  For example, in your data file you could enter a field such as the following:

  X400:g=joe;s=jones;ou=sales;o=acme;p=acmemd;a=att;c=us
  

• Full name

  Single-value property. In the data file, enter the user's full name.

  For example, in your data file you could enter a field such as ``Roland D Bruns''.

• Generational qualifier

  Single-value property. In the data file, enter the generational qualifier for the user's name. Usually this is Jr., Sr., II or III.

  For example, if the user's name is Bob Wilson III, enter III in the data file.

• Given name

  Single-value property. In the data file, enter the given name of the user. For example, for John Doe, enter John.

• Grace logins allowed

  Single-value property. In the data file, enter the number of grace logins allowed before the account is locked. 0 implies no limit.

• Group membership

  Multiple-value property. This field allows you to organize groups of users who need similar rights and access to network resources. In the data file, enter the names of the groups to which this user belongs. If the group object is in a different context from the user, enter the complete NDS name of the group, including its context.

• Home directory

  Single-value property. In the data file, enter the volume and path of the home directory in the following format: Volume Name:path. If the volume is in a different context from the user, enter the complete NDS name. Separate the volume name and the path by a colon (:). Include the full path, including the final directory.

  For example, for user ABC1, create the home directory on Volume object VOL1. VOL1 is in the same context as the user:VOL1:USERS\ABC1.

  This field in the data file will override the Home Directory field in the control section.

• Initials

  Single-value property. In the data file, enter the middle initial of the user. For John I. Doe, enter I here.

• Language

  Multiple-value property. In the data file, enter the language directories to be searched to find the message files for NetWare utilities for this user.

  If more than one language directory should be searched, enter multiple language fields. The order is important. The first entry is the first language directory to be searched, the second is the second language directory to be searched, and so on.

• Last name

  Single-value property. In the data file, enter the user's last name. A value is required for this field when you are creating new User objects.

• Location

  Multiple-value property. In the data file, enter any information about a user's work, department, or division location.

• Login script

  The value of the login script is the name of a file containing the ASCII text for the login script. You can use the same file for all users or have a separate file for each user. In the data file, enter the path to the file as a DOS path. For example, C:\DIR1\MYLOGIN.SCR. The maximum size of the login script is 16,384 bytes. If the file is larger than this, only the first 16,384 bytes are copied to the login script.

• Low balance limit

  Single-value property. If unlimited credit is not allowed, in the data file enter the lowest balance the user can have and still receive services that are chargeable.

  If accounting is not turned on, this field has no effect. Also, if Allow unlimited credit is set to Yes, this field has no effect.

• Mailbox ID

  Single-value property. This is a unique name that specifies the directory in which all the object's inbound mail is placed.

  In the data file, assign the user a mailbox ID using the user's login name. If the user's name has spaces in it or uses non-DOS characters, assign the user a mailbox ID using the user's login name, but eliminate the spaces and other illegal characters to form a legal DOS name.

  If you do not assign a user a mailbox ID, UIMPORT does so automatically.

• Mailbox location

  Single-value property. In the data file, enter the name of the messaging server on which the user's mailbox is located. If the messaging server is not in the same context as the user, enter the complete NDS name of the messaging server.

  For example, if the user's mailbox is located on a messaging server named SERVMAN_MSG and the context of SERVMAN_MSG is ``Publications.ACME'', enter the following:

  SERVMAN_MSG.Publications.ACME
  

• Mailing label information

  Multiple-value property. This is a single property with up to six lines of information. If you want a user's entire address imported as a single property, use Mailing label information for each field that contains a part of the address. The first field will be the first line of the postal address, the second field will be the second line, and so on.

  If you are going to define only four lines of the postal address in the data file, you need to include only four Mailing label information fields. Each line of the postal address in the data file must be a separate data string (that is, separated by a comma or other separator).

  To import four lines of the postal address, you would type the following in the Fields section in the Control file:

  Fields
    ... (other fields)
    Mailing label information
    Mailing label information
    Mailing label information
    ... (other fields)
  

  In the data file, you might enter a line similar to the following:

    ...,"1234 Any Street","Torrance","CA","98550",...
  

  You can use the Mailing label information field in place of Postal code, Post office box, State or province, and City.

• Maximum connections

  Single-value property. In the data file, enter the number of workstations the user can login from. For no limit, enter 0.

• Minimum password length

  Single-value property. In the data file, enter the minimum password length.

• Name

  Single-value property. A value is required for this field. In the data file, enter any unique username. For example, you can use a student or employee identification number as the login name. This field is the user's login name in NDS.

• Other names

  Multiple-value property. For example, if a user has two additional names that you want to import, enter both of them in the data file and enter two field definitions in the import control file called ``Other names''.

• Password

  Single-value property. In the data file, enter a unique password for the user. Numbers, letters, and special characters may be used.

• Post office box

  Single-value property. In the data file, enter the user's post office box.

• Postal (ZIP) code

  Single-value property. Enter in the data file the five- or ten-digit ZIP code. (84111 or 84111-1111). For a Canadian address, this is the postal code.

• Profile

  Single-value property. In the data file, enter the name of the profile object to which this user belongs. This must include the complete NDS name of the Profile object if the profile is in a different context than the user.

• Remaining grace logins

  Single-value property. Normally this field is not imported. This is the number of grace logins still remaining. It is set to the same value as in ``Grace logins allowed''. If you want this number to be different from the ``Grace logins allowed'' number, you must use the modify option in UIMPORT.

  For those users whose Remaining grace logins should be the same as the Limit grace logins, either don't import this field or set it to the same number you entered for Limit grace logins.

• Require a password

  Single-value property. In the data file, type ``Y'' if a password is required. If no password is required for this user, type ``N''.

• Require unique passwords

  Single-value property. If unique passwords are required, type ``Y'' in the data file. If unique passwords are not required (in other words the user can reuse passwords), type ``N''.

• Security equal to

  Multiple-value property. In the data file, enter the name of the objects to which this user is security equivalent. This name must include the complete NDS name of the object if the object is in a different context than the user.

• See also

  Multiple-value property. Enter in the data file any other related objects. Enter the complete NDS name of the object if it is not in the same context as the User object.

• Skip

  This is a unique processing option for UIMPORT. The values in the data file that correspond to Skip fields are ignored by UIMPORT.

  For example, if you exported into the data file users' birthdays and you do not want this information imported into NDS, enter ``Skip'' as the field definition. So if you export data that you don't want to import, rather than re-exporting the entire data file, you can simply specify ``Skip'' for the column that contains the information.

  Suppose you export to the data file a work and a home phone number, but you don't want to import the home phone number. Your data file may have a string like this:

    ...,"801-555-4141","801-555-8677",...
  

  Your import control file would correspond like this:

  Fields
    ...
    Telephone
    Skip
    ...
  

  The 801-555-8677 field in the data file is ignored.

• State or province

  Single-value property. In the data file, enter the State or province of the user.

• Telephone

  Multiple-value property. For example, if a user has three telephone numbers that you want to import, enter in the data file each of the three numbers. In the control file, you would need three ``Telephone'' field entries.

• Title

  Multiple-value property. In the data file, enter the user's title.

• Volume restrictions

  Single-value property. In the data file, enter the name of the Volume object and the space restrictions on that volume in the following format: Volume object name:Restriction amount. To remove volume restrictions, enter -1 (or any other negative number) for the restriction amount.

UIMPORT field name changes

UIMPORT data field names have changed in NetWare 4.1. Field names used in NetWare Services are listed in the left column of the following table and new NetWare 4.1 names are listed in the right column.

NetWare Services UIMPORT field name	4.1 UIMPORT field name
Facsimile telephone number	FAX number
Login disabled	Account disabled
Login expiration time	Account has expiration date
Login grace limit	Grace logins allowed
Login maximum simultaneous	Maximum connections
Minimum account balance	Low balance limit
Password allow change	Allow user to change password
Password expiration interval	Days between forced changes
Password expiration time	Date password expires
Password minimum length	Minimum password length
Password required	Require a password
Password unique required	Require a unique password
Postal address	Mailing label information
Security equals	Security equal to
Telephone number	Telephone
New field	Foreign email address
New field	Foreign email alias
New field	Full name
New field	Generational qualifier
New field	Initials
New field	Mailbox ID
New field	Mailbox location

 NetWare Services UIMPORT field name   4.1 UIMPORT field name
 Facsimile telephone number            FAX number
 Login disabled                        Account disabled
 Login expiration time                 Account has expiration date
 Login grace limit                     Grace logins allowed
 Login maximum simultaneous            Maximum connections
 Minimum account balance               Low balance limit
 Password allow change                 Allow user to change password
 Password expiration interval          Days between forced changes
 Password expiration time              Date password expires
 Password minimum length               Minimum password length
 Password required                     Require a password
 Password unique required              Require a unique password
 Postal address                        Mailing label information
 Security equals                       Security equal to
 Telephone number                      Telephone
 New field                             Foreign email address
 New field                             Foreign email alias
 New field                             Full name
 New field                             Generational qualifier
 New field                             Initials
 New field                             Mailbox ID
 New field                             Mailbox location