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.

 

 

 

 

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:

 

 

 

 

 

 

 

 

You can import data into the following predefined Asset fields:

 

 

 

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:

 

  1. 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.

     

     

  2. Once HelpSTAR has closed you will be asked to login again using your same HelpSTAR User Name and Password to run the import utility.

     

     

     

  3. 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:

 

1.  File Selection 

2.  Mapping Source File Data to HelpSTAR Fields 

3.  Setting Default Values 

4.  Previewing Incoming Data 

5.  Record Handling 

6.  Import Summary 

 

 

Step 1:  File Selection

 

This is the first step in configuring the utility to import field data into HelpSTAR.

 

 

 

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.

 

 

 

 

 

 

 

 

 

 

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.

 

 

 

 

 

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

 

 

 

 

 

 

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.

Back to top 

See Also:

Adding a New Company

Adding a New Organizational Unit

Adding a New User

Adding a New Queue

Assigning Reps to Queues

Adding a New Category

User Defined Fields

Back up Your HelpSTAR Database

Restore Your HelpSTAR Database

Scheduling Import Utility