Importing User Information into NetWare Directory Services with UIMPORT

Articles and Tips: article

PAUL CORRIVEAU
Technical Writer
NetWare Products Division

BRENT WING
Software Engineer
NetWare Products Division

01 Apr 1995

This AppNote discusses the practical issues involved in using UIMPORT to transfer user data from an application to NetWare 4's NetWare Directory Services (NDS). As many businesses upgrade and move production environments to NetWare 4.1, UIMPORT can help automate the transfer of user data to NDS. This utility is particularly valuable if you have hundreds (or thousands) of user records that you want to import into NDS, modify once in NDS, or delete from NDS, without having to manually re-create or delete each user record.

Introduction
The Import Process
Examples of How to Use UIMPORT
Control Parameters
Field Definitions
Summary

Introduction

UIMPORT can be a useful utility when working with large amounts of user data. You can use UIMPORT to automate the maintenance of NDS when you want to

Create User objects in NDS using records from an application (spreadsheet, word processor, or database).
Update User properties in NDS when records are changed in your original application.
Delete User objects when their accounts on the network are no longer needed.

This AppNote concentrates on providing tips and examples of using UIMPORT that network administrators may find useful as they transition to NetWare 4.1.

The Import Process

The process for importing records from your application to NDS is as follows:

Generate a data file (a delimited ASCII text file) from existing records in your application, or create the data file in a text editor.
Create an import control file to interpret the data file.
Use UIMPORT to transfer user data from the data file to NDS.

Figure 1: The three-step Import Process.

Generating the Data File

You generate a data file from within your 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.

You can also create a data file by using any text editor under DOS or OS/2, or by using a word processsor such as WordPerfect or Word and saving the file in ASCII format.

Here are some guidelines for creating a data file:

If you have quotation marks or commas embedded in any of the fields in your application, either delete the punctuation before generating the data file, or specify a different separator or delimiter in the import control file. Otherwise, UIMPORT won't be able to distinguish between field separators and the embedded punctuation.
To avoid problems importing user data, make sure the beginning of each new string of user data (in the data file) begins on a separate line.

Figure 2 shows a sample database table created in Paradox for Windows, and the data file generated from it.

Figure 2: Data file generated from a Paradox table.

Creating the Import Control File

The import control file contains two types of information:

Control parameters that define characteristics used in the data file and control how information in the data file will be imported into NDS.
Field definitions that determine which NDS properties the data are placed in.

Note: Control parameters and field definititions are explained in tables 1 and 2, at the end of this AppNote.

Here are some general guidelines for creating an import control file:

You can create the import control file using any text editor under DOS or OS/2.
The headings "Import Control" and "Fields" must be left aligned with the left margin.
Entries under the headings must be indented at least one space.
You don't have to specify import control parameters if you plan to use the defaults.
Control parameters and field definitions are not case-sensitive.
"Name" (login name) and "Last name" are the only required field definitions to create a user.
All fields in the data file must have a corresponding field definition in the import control file.
Saving the import control file in the same directory as the data file makes locating the files and running UIMPORT easier for you.
Import control parameters are initially set in the control file, but can be included in the data file at whatever point you want to change certain control parameters. If you include control parameters in the data file, the parameter should be preceded by an exclamation point (!).

When creating the import control file, you must enter control parameters first, followed by field definitions. For example, a simple import control file may look like this:

Import Control
   Separator=^
   User template=y
   Name context=.Engineering.Acme
   
Fields
   Last name
   Name
   Telephone
   Title

Using UIMPORT to Transfer User Data to NDS

Once you have generated a data file and created an import control file, run UIMPORT from the DOS command line. The syntax might look something like this:

UIMPORT control_file data_file[/C]

Consider these guidelines:

Replace control_file and data_file with the appropriate file names.
Use /C to run UIMPORT with continuous output.
Use the DOS ">path" option if you want to redirect error messages to a file. For example, to route error messages to a file called UIMPORT.LOG, type UIMPORT control_file data_file /C >home\FRANK\uimport.log >Enter>.
If you don't run UIMPORT from a directory that contains both the import control file and the data file, you must specify the path to each file(UIMPORT <path< control_file <path< data_file /C)
Importing hundreds or thousands of users may take several hours, so you might want to run UIMPORT at night.

Note: When importing a large number of users (thousands), the performance of your server might degrade. The reduction in performance (processing speed) is related to the size of UIMPORT batches and available server memory.

If you will be importing a large number of users or experience decreased server performance while running UIMPORT, you can add server memory, process smaller batches of users, or process UIMPORT batches during periods of low server utilization.

Examples of How to Use UIMPORT

Each of the following examples shows a data file and a corresponding import control file, along with a brief explanation of how UIMPORT will interpret the data in the files. Although these examples contain only two or three user records, they should help you see the one-to-one correspondence between fields in the data file and in the import control file, and how to create, delete, or update user properties in NDS.

Example 1: Data File and Import Control File.

Data File

Import Control File

^Syoung^;^young^;^SY^;^Sean Young^; ^this field is skipped^;^Sean^; ^Sean-boy^; ^engineer^;^3500000^;^Y^; ^1200^;^login.scr^;^1-9-1995^;^5^;^5^; ^7^;^our#1eng^;^1-9-1997^;^Y^;^Y^;^Y^; ^60^;^4^;^N^; ^330 Novell Drive Provo Utah, 84000^; ^500 South NetWare Ave.^;^6A^; ^Provo^;^Utah^;^84000^; ^1-800-555-1234^;^engineering^;^english^; ^server2^;^engin2^; ^profile3.engineering.novell^; ^Sean's favorite phrase is "let's rock"^ !Separator=/ !Quote=* !Replace value=Y !Name context=.wp !Home directory path=engdir !Home directory volume=.execvol2.wp *Tking*/*King*/*TK*/*Tom King*/ *This field is skipped*/*Tom*/*VIP*/ *Vice President*/*2500000*/ *N*/*12*/*login.scr*/*1-9-1997*/ *6*/*6*/*4*/*Lion$heart*/*1-9-1997*/*Y*/*Y*/ *Y*/*60*/*4*/*N*/ *300 North Center St. Provo, Utah 84000*/ *500 South 200 East*/*12B*/ *Provo*/*Utah*/*84602*/*1-800-555-1212*/ *NPD*/*english*/*server3*/*execstaf*/ *profile2.npd.wp*/ *Tom's people develop "killer" stuff, so we like them*

Import control Separator=; Quote=^ Replace value=Y Import mode=C Name context=.novell Maximum directory retries=5 Create home directory=Y Home directory path=users Home directory volume=.vol3.novell Fields Name Last name Initials Full name Skip Given name Other names Title Account balance Allow unlimited credit Low balance limit Login script Account has expiration date Limit grace logins Remaining grace logins Maximum connections Password Date password expires Require a password Require unique passwords Allow user to change password Days between forced changes Minimum password length Account disabled Mailing label information Street address Post office box City State or Province Postal (zip) code Telephone Department Language Default server Group membership Profile Description

Each field in each of the user records (in the data file) corresponds to a property listed in the "Fields" section of the import control file. However, note that between the two user records in the data file are some control parameters preceeded by an exclamation point (!). Inserting Control parameters preceeded by a ! in the data file allows you to change those control parameters for every user record that follows.

Also note how the last field in each user record contains embedded quotation marks and commas. When fields in the data file contain embedded punctuation, you need to specify alternate characters as delimiters and separators in the Import control section of the import control file.

Example 2: Data File and Import Control File.

Data File	Import Control File
23745,Jones,Adam,J, 5275 St Catherine Street, Montreal,Quebec,2123-1232, 8236-373-8829,Sophomore, Electrical Engineering, 3.4,Engineering Sciences 20999,Peterson,Kelly,A, 232 Aspen Lane, Aspen,Colorado, 23222,802-236-8352, Senior,English,3.7,Humanities 22232,Hall,Clarence,B, 34 West Ivy Street,Chicago, Illinois,34993, 359-283-8255,Junior,Finance, 3.9,Business Management	Import Control Name context=.administration.students User template=Y Create home directory=Y Home directory path=@students/home@ Home directory volume=@.SYSVOL.Students@ Fields Name Last name Given name Middle Initial Mailing label information Mailing label information Mailing label information Mailing label information Telephone Description Skip Skip Department

The user records in the data file have been generated with comma separators and no delimiters. Since there is no embedded punctuation in any of the fields in the user records, there is no need to specify alternate separators or delimiters. (Delimiters are not required in the data file.)

Since User template=Y, the values specified in the User template (the master template in the container in which the users are being created) will be applied to every new user imported from the data file.

Suppose that, after running UIMPORT, you want to undo the operation - and remove the User objects from NDS. You could add Import mode=Rto the control section of the import control file and run UIMPORT.

On the other hand, suppose that, after running UIMPORT, you want to change some of the values of the user properties that were imported into NDS. For example, if you wanted to change the value of a user's telephone number, simply make the change in the field in the data file, and add Import mode=U to the Import Control section of the import control file.

Control Parameters

Use the applicable control parameters in the following table to create the Import Control section of the import control file.

Table 1: UIMPORT Control Parameters.

Control Parameter	Explanation
Create home directory	Allows youto create a home directory for User objects.This option requires that you set the "Homedirectory path" and "Home directory volume"control parameters. If you want the usersyou are importing to have a home directory,enter CREATE HOME DIRECTORY=Y. The default is No.
Delete mailbox dirs	Allows youto delete the mailbox directories only whenmoving a user's mailbox from one messagingserver to another or changing the mailboxID of a user. To delete users' mailbox directories,enter DELETE MAILBOX DIRS=Y. The default is No.
Delete property	Allows youto delete values for a property of a Userobject. For example, to delete all titlesfrom a User object's Title property, enterDELETE PROPERTY=#DEL and then edit the datafile by putting #DEL in the Title field.
Home directory path	If you createa home directory for User objects, you mustspecify a path in the file system where youwant the directories to be created. Homedirectory path and Home directory volumemust be entered as a pair. If you specifya Home directory volume, but don't specifya home directory path, the home directorieswill be placed by default at the root ofthe volume. For example, if you want homedirectories created in the Users directory(under the root of the volume), enter HOMEDIRECTORY PATH="USERS". Do not include thevolume name in the path.
Home directory volume	If you createhome directories for User objects, you mustspecify the context name of the Volume objectassociated with the file system where thehome directories are created. If the filespecified in "Home directory path" is onvolume SYS:, enter the Volume object's contextname. For example: HOME DIRECTORY VOLUME="SYS.STUDENTRECORDS.UNIVERSITY".
Import mode	Controls whetherUser objects will be created or removed,or whether User properties will be updated.Options are C (create new User objects only),R (remove User objects), U (update existingUser object properties), and B (both createand update). The default is B.
Maximum directory retries	Allows youto specify how many times UIMPORT shouldattempt to get the object ID of the useryou have just added in order to create homedirectories and mailbox directories. Thisparameter allows time for the network tocatch up with the request to add the useron a server. For example, enter MAXIMUM DIRECTORYRETRIES=5. The default is 5.
Name context	Specifies theNDS context where User objects will be created.For example, if you are in the OrganizationUnit DEVELOPMENT.ACME and want to createUser objects in the Organizational Unit ENGINEERING.ACME,enter NAME CONTEXT=.ENGINEERING.ACME. Thedefault name context is your current context.
Quote	Specifies thecharacter used to delimit fields in your data file. The default character for delimiters is quotes ("").
Replace value	Allows youto overwrite or add data to multivalue properties.For example, to import new telephone numbersto User properties without saving the existingnumbers, enter REPLACE VALUE=Y. The default is N.
Separator	Specifies thecharacter used to separate fields in thedata file. The default separator is a comma.
User template	Specifies whetheryou want User Template defaults to be appliedto the User objects being created. To applytemplate properties to User objects, enterUSER TEMPLATE=Y. Template properties areapplied first, then properties from the datafile are imported. The default is No.

Field Definitions

Use the applicable definitions in the following table to create the "Fields" section of the import control file. A single-value property can contain only one entry (value). Multivalue properties can contain several entries. By default, all values will be added to those already specified. If you want to replace existing values in existing users, set the Replace Value control parameter to Y.

Table 2: UIMPORT Field Definitions.

Property	Property Description
Account balance	Single-valueproperty. In the data file, enter the beginningaccount balance for the user.
Account disabled	Single-valueproperty. In the data file, enter Y if youwant to disable that user's account. Thedefault is No. Note:If you set ACCOUNT DISABLED=Y,UIMPORT will not update or create users untilthe account is enabled again.
Account has expiration date	Single-value property. In the data file, enter the date in the form MM/DD/YY. The user's accountwill expire at 12:01 am on that date.
Allow unlimited credit	Single-valueproperty. In the data file, enter Y to allowunlimited credit. The default is No.
Allow user to change password	Single-value property. If you don't want the user to be able to change his/her password, enter Nin the data file. The default is Y.
City	Multivalueproperty. 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.The user's password 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 changehis/her password. The range is 1-365, and the default is 40.
Default server	Single-value property. In the data file, enter the name of the server that the user is going to authenticateto (make a connection to) when he or she logs in to NetWare Directory Services. Ifthe server is not in the same context as the user, make sure to enter the contextname of the server.
Department	Multivalue property. In the data file, enter the departmentname, code, number, or other type of informationthat you want to associate with the user's department.
Description	Multivalue property. In the data file, enter any typeof information about the user that want toimport. The field must be enclosed in quotes(or the delimiter defined in the controlfile) if it contains commas or new-line characters.
Fax number	Multivalue property. In the data file, enter the faxnumber for each user you want to import.
Foreign Email address	Single-value property. In the data file, enter the foreignEmail address of the user. This address specifiesa mailbox that resides in a different Emailsystem. This field is used by NetWare MHS Services.
Foreign Email alias	Multivalue property. In the data file, enter the ForeignEmail alias of the user. This alias is theuser's name in a different Email system.This field is used by NetWare MHS Services.
Full name	Multivalue property. In the data file, enter the user'sfull name. For example, enter HARVEY J SMITH.
Generational qualifier	Single-value property. In the data file, enter the generationalqualifier for the user's name. Usually, this is a JR., SR., II or III.
Given name	Single-value property. In the data file, enter the user'sgiven name. For example, for Paul Smith, enter PAUL.
Grace logins allowed	Single-valueproperty. In the data file, enter the numberof grace logins allowed before the accountis locked. 0 implies no limit.
Group membership	Multivalueproperty. 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 you want this user to belong to. If the group object is in a different context than the user, you must specify the group object's complete name. For example, enter WRITERS.PUBLICATIONS.NOVELL. Note: Groupmembership will also make the user securityequal to the group.
Home directory	Single-valueproperty. In the data file, enter the volumeand path of the home directory in the formatVOLUME NAME:PATH. If the volume is in a differentcontext than the user, enter the volume'scomplete name. For example, to create thehome directory for user JSMITH on volumeobject VOL1 (if VOL1 is in the same contextas JSMITH), enter VOL1:USERS\JSMITH.This field in the data file will overridethe Home Directory field in the control section.
Language	Multivalue property. In the data file, enter the languagedirectories to be searched to find the massagefiles for NetWare utilities for this user(i.e., If the user speaks only English, enterENGLISH.) If no language is specified, UIMPORTwill use the value specified in the UserTemplate.
Last name	Single-value property. In the data file, enter the user'slast name. A value is required for this field when you are creating new User objects.
Location	Multivalue property. In the data file, enter any informationabout a user's work, department, or division location.
Login script	The value of the login script is the name of a file containingthe ASCII text for the login scriopt. Youcan reuse the same file for all users orhave a separate file for each user. In thedata file, enter the path to the file asa DOS path. For example: C:\DIR1\MYLOGIN.SCR.
Low balance limit	Single-value property. If unlimited credit is not allowed,in the data file, enter the lowest balancethe usre can have and still receive servicesthat are chargeable.
Mailbox ID	Single-value property. This is a unique name that specifiesthe directory in which all of the object'sinbound mail will be placed. You can usethe user's login name as the unique name.This information is used by NetWare MHS Services.If you do not assign a user a mailbox ID,UIMPORT will do so automatically, using theuser's name.
Mailbox location	Single-valueproperty. In the data file, enter the nameof the messaging server on which the user'smailbox is located. If the messaging serveris not in the same context as the user, enterthe complete name of the messaging server.For example, if the user's mailbox is locatedon a messaging server named SERVMAN_MSG andthe context of SERVMAN_MSG is PUBLICATIONS.NOVELL,enter SERVMAN_MSG.PUBLICATIONS.NOVELL.
Mailing label information	Multivalue property. This property contains up to sixlines of information. If you want a user'sentire address imported as a single property,use "Mailing label information" for eachfield that contains a part of the address.
Maximum connections	Single-valueproperty. In the data file, enter the numberof workstations the user can log in from.For no limit, enter 0.
Middle Initial	Single-valueproperty. In the data file, enter the middleinitials of the user. For Jim H. Bobbit, enter H.
Minimum password length	Single-valueproperty. In the data file, enter the minimum password length.
Name	Single-valueproperty. In the data file, enter any uniqueuser name. For example, you can use a studentor employee identification number as thelogin name. This field will be the user'slogin name in NDS. A value is required for this field.
Other names	Multivalue property. For example, if a user has twoadditional nicknames that you want to import,enter both of them in the data file, andenter two field definitions in the importcontrol file called "Other names."
Password	Single-valueproperty. In the data file, enter a uniquepassword for the user. Numbers, letters,and special characters may be used (and arerecomended).
Postal code	Multivalue property. Enter in the data the five or tendigit zip code. (84111 or 84111-1111). Fora Canadian address, this is the postal code.
Profile	Single-value property. In the data file, enter the nameof the profile object to which this userbelongs. If the profile is in a differentcontext than the user, include the contextname of the profile object.
Remaining grace logins	Single-value property. This field represents the numberof grace logins still remaining, but thisfield is usually not imported. This fieldis automatically set to the same value asin "Grace logins allowed."
Require a password	Single-value property. In the data file, enter Y if apassword is required. The default setting is N.
See also	Multivalue property. Enter in the data file any other related objects. Enter the context name of the object if it is not in the same context as the user.
Skip	This is a unique processing option for UIMPORT. The values in the data file that correspond to Skip fields are ignored by UIMPORT. In other words, if you have fields in your data file that you don't want to import, enter Skip as the field definition.
Security equal to	Multivalue property. In the data file, enter the name of the objects to which this user is security equivalent. For the objects that are in a different context than the user, enter the context name.
State or province	Multivalue property. In the data file, enter the State or province of the user.
Telephone	Multivalue property. Enter in the data file each of the user's telephone numbers you want to import. For each telephone number in the data file, there must be a corresponding "Telephone" entry in the control file.
Title	Multivalue 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 (in kilobytes) on that volume in the following format: VOLUME OBJECT NAME:RESTRICTION AMOUNT.

Summary

UIMPORT is a powerful utility that lets you automate the creation and maintenance of User objects in NDS. By using UIMPORT to create, delete, or update User objects, you avoid having to manually work with each User object.

* Originally published in Novell AppNotes

Disclaimer

The origin of this information may be internal or external to Novell. While Novell makes all reasonable efforts to verify this information, Novell does not make explicit or implied claims to its validity.