CMS Pro "TXT2PRO" User Guide

Table of Contents

Overview
Starting the Program
Step 1 - Select CMS Pro Database Directory
Step 2 - Select Text File and Delimiter Type
Step 3 - Set Column Order
Step 4 of 4 - Start the Import/Update Process
Running in "Silent" Mode


Overview

The CMS Pro "TXT2PRO" utility imports new CMS users and updates existing CMS users from an ASCII text file produced by a third-party application, such as a corporate Human Resource or Accounting system.

The utility provides a wizard-like user interface for establishing program settings. Once settings are saved, the program can run in "silent" mode where no user interaction is necessary.

In order to match the users listed in the exported text file with records in the CMS database, each record in the text file must include an employee ID, and each CMS Pro user must have an employee ID entered into the Employee ID field.

Table of Contents


Starting the Program

The TXT2PRO utility is a ToolBook II application, which requires the ToolBook II authoring or runtime files to operate. Be sure the appropriate version of ToolBook II is installed on the system where you plan to run the TXT2PRO utility. In addition, you must run the TXT2PRO.TBK file in a directory that also contains CMSPRO.SBK.

From Windows Explorer, double-click TXT2PRO.TBK, or set up a shortcut with a target such as the following:

"C:\Program Files\Asymetrix\Shared Tools\TBSystem\Tb60run.exe" "C:\CMSPro\Tools\Txt2Pro.tbk"

Note: Change the paths in the shortcut to represent your own directory structure to the ToolBook runtime executable and to the txt2pro.tbk utility.

Important! Be sure all CMS Pro students and administrators have closed all CMS Pro programs and any third-party database tools that have the CMS Pro databases files open, including reporting tools.

Click "Next" to proceed to the next screen.

Table of Contents


Step 1 - Select CMS Pro Database Directory

On this screen, specify the directory where the CMS Pro database tables reside. You can type the directory into the field, or use the Select button to locate and choose the directory. You should have full read/write access to the selected directory.

Note: You need not enter a backslash at the end of the directory name.

Click "Next" to proceed to the next screen.

Table of Contents


Step 2 - Select Text File and Delimiter Type

On this screen, type the name of the ASCII text file that contains the user records to insert and update. The file you export from the third-party application must separate records with a pair of Carriage Return and Line Feed (CRLF) characters. Most Windows-based applications end exported rows with CRLF characters, but pay particular attention to this requirement if you are exporting data from an application running under the Unix operating system since Unix typically ends each row with only a Line Feed character. The Carriage Return character must precede the Line Feed character at the end of each row.

Note: The text file should not include a "header" row. Be sure to turn off the header row option in the software you are running to export the user information.

Next, select "Tab delimited" if the individual data items, such as employee ID, first name, and last name are separated with a Tab character in the text file. Select "Comma delimited" if the data items are separated with commas.

The bottom-most option on this screen dictates how the utility should handle cases where a user is in the CMS Pro database but is not in the ASCII text file. Under such cases, you may want the utility to flag the users in the database as inactive if they are not found in the text file. To set the users to inactive in the CMS Pro database, select the "Set to Inactive" option. Otherwise, to preserve the current status (active or inactive) of users in the CMS Pro database regardless of whether the users are in the text file, select the "No change" option.

Note: A user marked as inactive will not appear in searches, on assignment screens, or in most reports in the CMS Pro Administration application. Refer to the CMS Pro User Guide for more details about how CMS Pro handles the records of inactive users.

Click "Next" to proceed to the next screen.

Table of Contents


Step 3 - Set Column Order

Use this screen to specify the order that the data items (such as employee ID, last name, first name) appear in the import text file for each record (row).

To move a column name from the Available columns list to the Selected columns list, highlight the column name in the Available columns list and click the triple-arrow (>>>) button that points to the right, toward the Selected columns list. Likewise, to remove a column from the Select columns list, highlight the column name in the Selected columns list and click the triple-arrow (<<<) button that points toward the Available columns list.

Use the Move Up and Move Down buttons to move the highlighted column name in the Selected columns list up or down.

Use the Reset button to set the field contents back to their default values.

The import text file must include data for the following CMS Pro user table columns: EmpID, LastName, and FirstName. You may reorder these columns in the Selected columns list but the utility prevents the removal of these columns.

Login (name) column
If the import text file includes a Login name for each user record, this value becomes the login name for new users added to the CMS Pro database. However, the utility does not update login names that are already in the CMS Pro database.

If the import text file does not contain a Login column, the utility will use the EmpID value as the login for each new user added to the CMS Pro database.

Password column
If the import text file includes a Password value for each user record, this value becomes the password for new users added to the CMS Pro database. However, the utility does not update passwords that are already in the CMS Pro database.

If the import text file does not contain a Password column, the utility will use the EmpID value as the password for each new user added to the CMS Pro database.

Note: You can use the CMS Pro Administration application to change login names and passwords if necessary.

Click "Next" to proceed to the next screen.

Table of Contents


Step 4 of 4 - Start the Import/Update Process

Click the Start Process button to start the import and update process.

Note: The information in this section regarding messages that may appear applies only to the interactive use of the TXT2PRO utility. When the TXT2PRO utility runs in "silent" mode (discussed below), the program suppresses the message boxes and instead write the information to the TXT2PRO.LOG file, which is described below.

After clicking the Start Process button, the program first verifies the entries and selections made on the previous screens. If an entry is invalid, an appropriate error message appears, the utility stops and displays the screen where the error was encountered.

If the import text file does not include a login name for each record in the file, a message appears as shown below.

This dialog box indicates that, when importing new users to the CMS Pro database, the utility will use each user's employee ID as the user's login to the CMS Pro system. Click OK to accept this default behavior, or click Cancel to stop the import/update process.

If the import text file does not include a password for each record in the file, a message appears as shown below.

This dialog box indicates that, when importing new users to the CMS Pro database, the utility will use each user's employee ID as the user's password to gain access to the CMS Pro system. Click OK to accept this default behavior, or click Cancel to stop the import/update process.

As the utility runs, it writes the results of various operations to a file located in the same directory as the utility. The name of the file is TXT2PRO.LOG. Check this file after running the utility to determine whether the utility complete successfully, and to reveal error messages, if any.

Note: The import and update process runs in a "transaction", which means that all database operations must succeed in order for the utility to make changes to the CMS Pro database files. Thus, if an error occurs during processing, all pending changes to the CMS Pro databases are rolled back.

After processing all rows in the text file, the utility displays a message box with the total number of users added to CMS Pro, the total number of CMS Pro user records updated, and the total number of user records set as inactive (if this "Set to Inactive" option was selected on the screen titled "Step 2".

To save the entries and selections made while progressing through the utility's screens, click the Save Settings button. The program writes the settings to a file named TXT2PRO.INI. When running the utility in "silent" mode, as described below, the program reads from this settings file to run the program without user interaction.


Running in "Silent" Mode

The TXT2PRO utility does not require user interaction to operate. After saving settings with the Save Settings button on the screen titled "Step 4 of 4", the program will run in "silent" mode if the word "silent" is passed as a command line parameter when running the TXT2PRO program. This will suppress all message boxes and divert the message to the TXT2PRO.LOG file.

You can manually run the TXT2PRO.TBK in silent mode by typing in the filename, along with the "silent" parameter, into the Windows Run box or by creating a Windows shortcut (see sample command line below). Alternatively, you can utilize a wide variety of programming languages or utilities to run TXT2PRO.TBK as part of a batch, or overnight, process. An example of a utility that enables automatic launching of files is the Windows Schedule Task utility, which is typically located in the Accessories section in the Start menu.

Below is a sample shortcut target that will run the TXT2PRO.TBK utility in silent mode.

"C:\Program Files\Asymetrix\Shared Tools\TBSystem\Tb60run.exe" "C:\CMSPro\Tools\Txt2Pro.tbk" silent

Note: Change the paths in the shortcut to represent your own directory structure to the ToolBook runtime executable and to the txt2pro.tbk utility.

After the program completes the user importing and updating, open the TXT2PRO.LOG file to determine whether the program completed successfully or whether an error occurred.

Table of Contents


CMS Pro TXT2PRO User Guide
Copyright © 2000 Vision Infosystems, LLC