Import Utility
Overview:
This utility allows you to import Users and Assets into your HelpSTAR database from an ASCII text file. The utility enables you to design a template that it will follow when reading your unique source text.
- If you are importing Internal Users then you must associate them with a default Organizational Unit, or import their Organizational Units from the Source File.
- If you are importing External Users then you must associate them with a default Company, or import their associated Companies from the Source File.
- If you have created User Defined Fields for Users, Companies, Organizational Units or Assets in your HelpSTAR database, you may also import data into these fields.
You may wish to use this utility when you are getting started with HelpSTAR, eliminating the data entry of information that is already stored elsewhere. In addition, the utility can be utilized on a continual basis, allowing you to periodically import User or Asset records from other management systems in your organization (e.g. accounting, contact management).
Note: If your organization has implemented Active Directory Services then you can configure HelpSTAR to import groups of users from Active Directory.
Import Requirements:
- The Import Utility can only import ASCII files (i.e. formatted as plain text).
- All of the HelpSTAR fields have a limited number of character spaces available (e.g. phone numbers are allowed a maximum of 20 characters). Any imported data exceeding the maximum field length will generate an error.
- Any headings, line spaces, etc. in your Source File will have to be removed or else they too will be imported or cause errors.
- The Import Utility automatically removes double quotation marks from imported fields. This is to deal with the problem that during a CSV (comma delimited) export from Excel, any fields in the resulting ASCII file that include a comma in the text are automatically saved with opening & closing double quotation marks around that field.
- *CRITICAL* If you set the Import Utility to overwrite any duplicate/existing users it encounters then you may very likely overwrite existing users in the database and their privileges will be changed (stripped away). In which case, no one may be able to log into HelpSTAR.
- The utility allows you to import data into the following predefined User fields and related Company or Organizational Unit fields:
- User.Name
- User.Location
- User.Workstation
- User.Network Address
- User.Telephone
- User.Extension
- User.Fax
- User.Internet Address
- User.Email Address
- User.Post Office
- User.Inventory
- User.Comments
- Company.Name
- Company.Telephone
- Company.Fax Number
- Company.Street1
- Company.Street2
- Company.City
- Company.State
- Company.Code
- Company.Country
- Company.Memo
- OrganizationalUnit.Name
You can import data into the following predefined Asset fields:
- Asset.Name
- Asset.Tag
- Asset.Serial Number
- Asset.Bar Code
- Asset.Cost
- Asset.Acquisition Date
- Asset.Memo
If you have created User Defined Fields for Users, Companies, Organizational Unit or Assets, you may also import data into these fields.
Running the Import Utility:
-
To run the utility, click the "Import" button on the Setup/Administration home page. Once you click on Import HelpSTAR will ask you to close all running HelpSTAR applications.
-
Once HelpSTAR has closed you will be asked to login again using your same HelpSTAR User Name and Password to run the import utility.
-
The Import Utility has the functionality to save settings from a previous import. If you have launched the Import Utility previously, you may receive the following prompt:
If you would like to use settings saved in a previous import, select yes.
Performing the Import:
The utility has been designed as a "Wizard", which will lead you through the following steps:
2. Mapping Source File Data to HelpSTAR Fields
Step 1: File Selection
This is the first step in configuring the utility to import field data into HelpSTAR.
- Source File: Browse to the location of the ASCII text file that contains the records to be imported. The Source File must be in the form of a flat file, containing one record for each User or Asset being imported. If you wish to import users" company or Organizational Unit information, then this data must also be contained in the user records.
- Field Separator: Formatted ASCII data may utilize various Field Delimiters. Select the appropriate delimiter (Comma, Tab, Semicolon, Space or Other) from the drop-down menu. If you select "Other" then you must enter the specific delimiter (e.g. $) in the text box to the right of the drop-down menu.
Note: A common form of delimited text contains commas as field delimiters with double quotation marks surrounding the text fields. You can disregard the double quotation marks because the Import Utility automatically removes them from imported fields.
- Import Type: It is important that you select the appropriate Import Type:
- Internal Users: Users that belong to your organization (generally your employees) and must either be associated with a default Organizational Unit in the HelpSTAR database, or the associated Organizational Units can be imported along with the Internal Users.
- External Users: Users that belong to outside organizations (generally your clients) and must either be associated with a default Company in the HelpSTAR database, or the associated Companies (and related information) can be imported along with the External Users.
- Assets: Assets only require the "Asset Name" to be in the source file, but other related fields can be included as well (e.g. Serial Number, Acquisition Date, etc.).
- User Type: If your organization has created User Defined Fields for users, then you may select an appropriate User Type and import data into the fields associated with that type.
- Organizational Unit, Company or Asset Type: When you select an "Import Type" (i.e. Internal Users, External Users or Assets) the bottom drop-down menu will change dynamically (i.e. to Organizational Unit Type, Company Type or Asset Type respectively).
- Internal Users: "Generic Organizational Unit" will be the only selection for "Organizational Unit Type" – unless your organization has created custom Organizational Unit types, in which case you may select one of these "Types" and import data into the User Defined Fields associated with it.
- External Users: You may select "Generic Company", "Vendor" or "Manufacturer" as the "Company Type". You can also choose a custom Company Type if you wish to import data into any User Defined Fields that are associated with that "Type".
- Assets: You may select "Generic Asset", "Hardware", "Software" or "Workstation" as the "Asset Type". You can also choose a custom Asset Type if you wish to import data into any User Defined Fields that are associated with that "Type".
Note: If you have selected a custom Organizational Unit, company or asset type, then any User Defined Fields associated with that type will be available for selection when you go to the next step of mapping file data to HelpSTAR fields.
Backing Up Your Database
Once you have finished choosing your import settings, HelpSTAR will ask you to make sure you have a backup of your database.
We strongly recommend that you Back up Your Database before running the Import utility. If you don’t correctly define your field mapping, the utility may overwrite existing data and you will need to Restore Your HelpSTAR Database.
Step 2: Mapping Source File Data to HelpSTAR Fields
Mapping the Source File data to the correct HelpSTAR fields is the most important step in the import process. When the mapping is complete, the source "File Data" will be displayed in a grid, with each column representing a field in the incoming Source File.
During the mapping process, you can examine the File Data to ensure that the Source File is correct.
Once you feel that the Source File is correct, you must click on the field's "Map To" Column header and select an appropriate HelpSTAR field. A drop Down Menu will show a list of available HelpSTAR fields. The specific fields listed will depend upon the Import Type you selected in the step.
Click on the "Map To" field for any column (shown below).
Once you have correctly mapped the columns to HelpSTAR fields, press the Next Button.
If your Source File contains information that doesn't belong in our HelpSTAR database then we simply won’t select a field mapping for that column. If we wish to remove a field mapping then we can select "[None]" from the drop-down menu at the head of the appropriate column.
Note: Each HelpSTAR field requires a specific "type" of data (e.g. alphanumeric, numeric, date, etc.). When you map fields, if the Source File data is not an appropriate "type" for the selected HelpSTAR field, then the File Data entries will be displayed in red.
Default Values:
We could enter default values for the "Company.Name", "User.Email Address", and "User.Telephone" fields. Whenever a "Default Value" is entered for a column then that value will be imported each time a null value is encountered for that field in the Source File. (If you are unable to enter text into a field, it is because those fields must contain unique values, ("User.Name"). In this example, entering default values for Organizational Unit Name, Email, and Telephone would not be appropriate so we will leave them empty.
Required Fields:
When we select the "Internal Users" or "External Users" Import type then our Source File must at the very least contain a "User.Name" field. (Later, we will discuss the situation where the user names in our Source File are split into two fields – i.e. First Name, Last Name.) If there is no "OU.Name" or "Company.Name" field in the Source File then we will be prompted to select a default value when we click the "Next" button.
When we select the "Assets" Import type then our Source File must at least contain an "Asset Name" field.
First Name + Last Name:
If our Source File contains user name information in the form of 2 fields (i.e. "First Name", "Last Name"), then we can map two columns to be imported. We can map the "First Name" column to the "User.Name" field, and the "Last Name" column to the "User.Last Name" field. During the import, the fields "User.Name" and "User.Last Name" will be spliced together to form the actual User.Name field in our HelpSTAR database (a space will be added between the fields).
After the Mapping is Complete:
Once we have finished with the field mapping we can click the "Next" button. Continuing with the example of importing Internal Users, if "OrganizationalUnit.Name" has been mapped then we will go immediately to the next step of Setting Default Values for users. However, if "OrganizationalUnit.Name" has not been mapped, then we will be prompted to select a Default Organization Unit for the new Internal Users.
We will be presented with a list of all available Organizational Units in the HelpSTAR database. We can either select a default Organizational Unit for all of the user records then click next, or we can click "Back” and map the appropriate column to the "OrganizationalUnit.Name" field. In the latter situation, if aOrganizational Unit in the Source File is not already in the HelpSTAR database then it will be created during the import.
Similarly, if we are importing External Users and "Company.Name" has not been mapped, then we can either select a default OU for all the user records and click "Next”, or we can click "Back” and map the appropriate column to the "Company.Name" field. In the latter situation, if a company in the Source File is not already in the HelpSTAR database then it will be created during the import.
Storing Your Import Settings
Note: Your Source File settings and Field Mapping can be saved for future use in an .xml file located locally on your current workstation.
Once you have completed your mappings, you will receive the following prompt:
To save your settings for a future import, select YES. You will then be prompted to enter a name of your settings in the following default location:
C:\ProgramData\HelpSTAR\12.0\Settings
The .XML file stores the settings that were last used for each import. Thus, whenever you reopen the Import Utility you will be able to use the previous settings.
Step 3: Setting Default Values
You are allowed to set default values for various fields during the import. Every imported User or Asset will automatically be assigned the default value you enter for a field. Note that when importing users, "HELPSTAR" is automatically assigned as the default password but you can change this to whatever you prefer. By default, the User Login is enabled and Email is disabled but you can change these settings if you wish.
A gray colored background is used to indicate fields for which data is being imported, therefore defaults cannot be set.
User Defined Fields
If you have created User Defined Fields for an object, they will be shown under the tab(s) you have created for them. You can click on the tab(s) if you wish to set default values for any of these fields during the import.
Note: A User Defined Fields will be grayed-out if it is mapped (data will be imported into it) or if it references data from another HelpSTAR object (a default value is not applicable).
Step 4: Preview Incoming Data
Prior to performing the import, you are given the opportunity to review the incoming data to ensure that your field mapping is working properly. For example, when importing Users, the top section of the form shows user information, while the bottom shows Organizational Unit or Company information.
Data to be imported from the Source File is shown in bold text and the default values to be imported are shown in regular text. If there are User Defined Fields associated with Users or the Company (or Companies) or the Organizational Unit, you can review their incoming data by clicking on the user defined tabs.
Navigation Buttons:
The Next Record and Previous Record buttons allow you to browse through the records in your Source File if desired.
When importing Assets you can review the incoming data in the same manner as for Users except that there are no Company or Organizational Unit records to be concerned with.
Step 5: Record Handling
Prior to starting the import, you must select the appropriate Record Handling options when existing records are encountered in the HelpSTAR database.
The record handling options shown above will be applied to every time an instance of "User.Name", "User.Email Address" or "Company.Name" in the Source File exactly matches an existing record in the HelpSTAR database. Other field information may differ although the records actually relate to the same User or Company. You can specify one of three options to handle such instances when they are encountered:
1. Auto Overwrite: The User and/or Organizational Unit fields in the Source File will overwrite the corresponding fields in the HelpSTAR database.
2. Keep Old Values: Data from matching records in the Source File will not be written to the HelpSTAR database.
3. Prompt to Confirm or Modify: You will be prompted to select an appropriate action. We recommend that you select this option unless you are certain that you want to overwrite existing records. When you select this option, the system will prompt you each time an existing User or Organizational Unit record is encountered in the HelpSTAR database. If a duplicate "User.Name" or "User.Email Address" is found then you will be presented with a form like the one shown below.
4. Auto Overwrite – Maintain Existing Unmapped Field Values: The User and/or Organization Unit Fields in the Source File will overwrite the corresponding fields in the HelpSTAR database. If they are other unmapped values in your Source File that exist within the HelpSTAR database, these values will be maintained and not cleared.
Existing Users
The form provides you with three options in dealing with duplicate Users: Add New, Update and Skip.
- Add New: This option adds a new User record to the HelpSTAR database. You will take this action when the record being imported is indeed a different User than the one currently existing in your database. As shown in the graphic above, the New User "Morne Botes" is not the same person as the existing "Morne Botes" – they are associated with different Organizational Units. But before you can add this new user you must modify her name since HelpSTAR does not allow duplicates. A second instance of "Morne Botes” could be added as "Morne Botes_2" or "Morne Botes – Shipping" to distinguish it from the existing record.
- Update: This option updates the existing User record with the data being imported.
- Skip: This User's record will be skipped and not added to the database.
Existing Organizational Units
If you have selected "Prompt to confirm or modify" for existing Organizational Units and a matching record is found then you will be presented with a form like the one shown below.
The form provides you with four options in dealing with duplicate Organizational Units: Rename New, Update Existing, Skip New and Import Users
- Rename New: This option allows you to change the name of the new Organizational Unit. This Organizational Unit will then be added to the HelpSTAR database.
- Update Existing: This option updates the existing Organizational Unit record with the data being imported.
- Skip New: This Organizational Unit's record will be skipped and not added to the database.
- Import Users: If the new Organizational Unit is the same as the existing one and you don"t need to update the existing Organizational Unit record, then you can select "Import Users" to import all of the new Organizational Unit"s users and associate them with the existing Organizational Unit in the HelpSTAR database.
Importing Assets
If you are importing Assets then the record handling is similar to that for Users but there are no Company or Organizational Unit records to be concerned with.
After you have selected the appropriate Record Handling options, click the Start button to commence the import.
Step 6: Import Summary
Once the import is complete, a summary screen will be displayed. The following example shows the summary of a User Import.
The contents are self-explanatory. The summary for an Asset Import will be similar (but with no reference to company or Organizational Unit records).
If any records are rejected during the import then an error file will be created on the network drive in the following folder:
HelpSTAR Test Drive: \HLPSTR\DATA
MS SQL versions of HelpSTAR: \HLPSTRCS\DATA
The file will be named according to the date and time it was created and be given the .err extension. This file will show all rejected records in ASCII format. If appropriate, you could correct the records in this file and then import the previously rejected data from it.
For any data errors, a different ASCII file will be created in the \DATA folder. This file will be named according to the version of the Import Utility that created it and will be given the .log extension – i.e. HS90IP.log, HS90IPDE.log or HS90IPCS.log.
See Also:
Adding a New Organizational Unit
Back up Your HelpSTAR Database
Restore Your HelpSTAR Database