Import Employee Configuration

Overview

The Import Employee Configuration feature allows administrators to configure how employee data is mapped and imported from Excel files. This configuration defines which columns in your Excel file correspond to which employee attributes in the system, ensuring accurate data import.

---

Accessing the Feature

1. Navigate to the Admin section in the main menu
2. Select Import Employee from the admin options
3. Scroll down to the Import Employee Configuration card section

---

Configuration List Overview

The configuration list displays all existing import configurations in a table format. Each row represents one configuration that maps an Excel column to an employee attribute.

Table Columns

Column

• Description: The Excel column letter (A, B, C, etc.) or "N_A" if not applicable
• Display: Shows the letter identifier that corresponds to the Excel file column
• Example: "A", "B", "C", "N_A"

Header Name

• Description: The user-friendly name that appears as the column header in the Excel file
• Display: The text label that identifies what data this column contains
• Example: "Employee ID", "First Name", "Last Name", "Pre-Employment"

Attribute

• Description: The system attribute name that the Excel column maps to
• Display:
  • For EMPLOYEE type: Shows the attribute name (e.g., "identification", "name", "location.code")
  • For TYPE_TEST or CUSTOM_COLUMN: Shows the type test value or custom column code
• Example: "identification", "name", "PRE_EMPLOYMENT", "CUSTOM_COLUMN_CODE"

Type Process

• Description: The type of data processing for this configuration
• Display:
  • "EMPLOYEE" - Standard employee data fields
  • "TYPE TEST" - Drug and alcohol test types
  • "CUSTOM COLUMN" - Custom column data
• Note: If the value is null in the system, it displays as "EMPLOYEE"

Required

• Description: Indicates whether this field is mandatory during import
• Display:
  • Green badge "REQUIRED" - Field must be filled in the Excel file
  • Gray badge "NOT REQUIRED" - Field is optional
• Purpose: Helps identify which columns must have data for successful import

Status

• Description: Whether this configuration is currently active and will be used during import
• Display:
  • Green badge "ENABLED" - Configuration is active and will be processed
  • Red badge "DISABLED" - Configuration is inactive and will be skipped during import
• Purpose: Allows you to temporarily disable configurations without deleting them

Options

• Description: Actions available for each configuration
• Actions:
  • Edit icon (pencil) - Opens the edit form to modify the configuration
    • Tooltip: "Edit configuration"
  • Delete icon (trash) - Removes the configuration permanently
    • Tooltip: "Delete configuration"
• Note: Icons are closely spaced for easy access

---

Search Functionality

The search bar allows you to quickly find configurations by:

• Header Name
• Column Letter
• Attribute Name

How to Search

1. Click in the search input field at the top of the configuration table
2. Type your search term (e.g., "Employee ID", "A", "identification")
3. Press Enter or wait for automatic filtering
4. The table will show only matching configurations
5. To clear the search, delete all text from the search field

Tooltip: "Search configurations by header name, column letter, or attribute"

---

Creating a New Configuration

Step-by-Step Guide

1. Click the "New Configuration" button

   • Located at the top right of the configuration table
   • Tooltip: "Create a new import employee configuration"
     

2. The configuration form modal will open

   • Title: "New Import Employee Configuration"
     

3. Select Type Process (First field - Required)

   • This determines what type of data this configuration handles
   • Options:
     • EMPLOYEE - Standard employee information (default)
     • TYPE TEST - Drug and alcohol test types
     • CUSTOM COLUMN - Custom column data
       

   • 

4. Based on Type Process selection, additional fields will appear:

   If "TYPE TEST" is selected:

   • Type Test field appears (Required)
   • Select from dropdown:
     • Pre Employment
     • Post Accident
     • Reasonable Susp Cause
     • Return To Duty
       

   If "CUSTOM COLUMN" is selected:

   • Custom Column field appears (Required)
   • Select from dropdown showing available custom column codes
   • Only the custom column name is displayed (not the code)
     

   If "EMPLOYEE" is selected (default):

   • Column Name Person field appears (Required)
   • Select from dropdown showing available person fields
   • System fields (id, created_by, etc.) are hidden
   • Attribute Name Entity field appears automatically (Read-only)
   • This field auto-fills based on your Column Name Person selection
   • For foreign keys (ending in _id), it shows the entity.code format
     

5. Enter Header Name (Required)

   • The name that appears as the column header in Excel
   • Example: "Employee ID", "First Name", "Location Code"
   • This is what users will see in their Excel file
     

6. Select or Enter Column Letter (Required)

   • Option 1: Select from predefined list
     • Options include: N_A, A, B, C, D... Z, AA, AB... AI
     • Used letters (except N_A) are not available
     • N_A is always available
   • Option 2: Select "Custom..." to enter a custom letter
     • Enter letters only (e.g., "HG", "XY")
     • Automatically converts to uppercase
     • Numbers and special characters are not allowed
     • Click "Cancel" to return to predefined list

7. Select Cell Type (Optional, defaults to "STRING")

   • Available options:
     • Numeric
     • String
     • Blank
     • Local Date
     • Enum
   • Note: Some technical types are hidden from the list
     

8. Enter Default Value (Optional)

   • A default value to use if the Excel cell is empty
   • Text input field
   • Example: "N/A", "0", "Default Location"
     

9. Enter Constant Value (Optional)

   • A constant value that will always be used for this column
   • Text input field
   • Example: "ACTIVE", "USA"
     

10. Enter Cell Format (Optional)

    • Format specification for the cell data
    • Text input field
    • Example: Date formats, number formats
      

11. Set Mandatory (Checkbox, defaults to unchecked)

    • Check "Required field" if this column must have data in Excel
    • Unchecked = Optional field
    • Checked = Required field (will show error if empty during import)
      

12. Set Enabled (Checkbox, defaults to checked)

    • Check "Active" to enable this configuration
    • Unchecked = Configuration is disabled (skipped during import)
    • Checked = Configuration is active (used during import)
      

13. Click "Create" button

    • Button is disabled until all required fields are filled
    • Tooltip: "Create a new import employee configuration"
      

14. Success message appears

    • "Configuration was added successfully"
    • The modal closes automatically
    • The new configuration appears in the table
      

Field Validation

• Required fields are marked with a red asterisk (*)
• Invalid fields show a red border when you try to submit
• Create button is disabled until all required fields are valid
• Tooltips appear on hover for buttons (blue tooltips)

---

Editing a Configuration

Step-by-Step Guide

1. Locate the configuration in the table

   • Use search if needed

2. Click the Edit icon (pencil) in the Options column

   • Tooltip: "Edit configuration"
     

3. The edit form modal opens

   • Title: "Edit Import Employee Configuration"
   • All fields are pre-filled with current values
     

4. Modify the fields as needed

   • Same fields and rules as creating a new configuration
   • Note: Column Letter shows current value (even if it was custom)
   • Used column letters are updated (current configuration's letter remains available)

5. Click "Update" button

   • Tooltip: "Update the import employee configuration"
     

6. Success message appears

   • "Configuration was updated successfully"
   • The table refreshes with updated data
     

Important Notes

• You can change the Type Process, but this may affect which fields are required
• Changing Column Letter to a used letter will show an error
• The current configuration's column letter is always available for editing

---

Deleting a Configuration

Step-by-Step Guide

1. Locate the configuration in the table

2. Click the Delete icon (trash) in the Options column

   • Tooltip: "Delete configuration"
     

3. Confirmation dialog appears

   • Title: "Are you sure?"
   • Message: "Do you want to delete the configuration for column [LETTER]?"
   • Options:
     • "Yes, delete it!" - Confirms deletion
     • "Cancel" - Cancels the action
       

4. If confirmed:

   • Configuration is permanently deleted
   • Success message: "Deleted! Configuration has been deleted."
   • Table refreshes automatically
     

5. If cancelled:

   • Dialog closes
   • No changes are made
   • Configuration remains in the table

Important Notes

• Deletion is permanent and cannot be undone
• After deletion, the column letter becomes available for new configurations
• Make sure the configuration is not needed before deleting

---

Understanding Type Process Options

EMPLOYEE (Default)

Purpose: Maps Excel columns to standard employee data fields

When to use: For basic employee information like:

• Employee ID
• First Name
• Last Name
• Email
• Phone Number
• Organization
• Location
• Work Group

Fields shown:

• Column Name Person (Required) - Select from person fields
• Attribute Name Entity (Auto-filled, Read-only) - Shows automatically

Example:

• Header Name: "Employee ID"
• Column Letter: "A"
• Column Name Person: "identification"
• Attribute Name Entity: "identification" (auto-filled)

TYPE TEST

Purpose: Maps Excel columns to drug and alcohol test types

When to use: For test type columns like:

• Pre-Employment tests
• Post-Accident tests
• Reasonable Suspicion/Cause tests
• Return to Duty tests

Fields shown:

• Type Test (Required) - Select from:
  • Pre Employment
  • Post Accident
  • Reasonable Susp Cause
  • Return To Duty

Example:

• Header Name: "Pre-Employment"
• Column Letter: "H"
• Type Process: "TYPE TEST"
• Type Test: "PRE_EMPLOYMENT"

CUSTOM COLUMN

Purpose: Maps Excel columns to custom column data

When to use: When you have custom fields defined in the system

Fields shown:

• Custom Column (Required) - Select from available custom columns
• Shows the custom column name (not the code)

Example:

• Header Name: "Custom Field 1"
• Column Letter: "J"
• Type Process: "CUSTOM COLUMN"
• Custom Column: "Emergency Contact Name"

ADDITIONAL_DATA

Purpose: For additional data that doesn't fit standard categories

When to use: For special data fields not covered by other types

Fields shown:

• Additional Data (Required) - Text input field

Note: This option is hidden from the Type Process dropdown but can be edited if it exists in existing configurations.

---

Field Descriptions

Header Name

• Type: Text input
• Required: Yes
• Purpose: The user-friendly name that appears as the Excel column header
• Example: "Employee ID", "First Name", "Location Code"
• Validation: Cannot be empty

Column Letter

• Type: Dropdown or Custom text input
• Required: Yes
• Purpose: Identifies which Excel column (A, B, C, etc.) this configuration maps to
• Options:
  • Predefined: N_A, A-Z, AA-AI
  • Custom: Any letter combination (e.g., "HG", "XY")
• Rules:
  • Letters only (automatically converted to uppercase)
  • Used letters are not available (except N_A)
  • N_A is always available
• Validation: Cannot be empty, must be letters only for custom values

Column Name Person

• Type: Dropdown
• Required: Yes (only when Type Process is EMPLOYEE)
• Purpose: Selects which person field this Excel column maps to
• Options: All available person fields (system fields are hidden)
• Behavior: When selected, automatically fills Attribute Name Entity
• Example: "identification", "name", "lastName", "organization_id"

Attribute Name Entity

• Type: Read-only text input
• Required: No (auto-filled)
• Purpose: Shows the system attribute name (automatically set based on Column Name Person)
• Behavior:
  • Auto-fills when Column Name Person is selected
  • For foreign keys (ending in _id), shows format: "entityName.code"
  • Example: "organization_id" → "organization.code"
• Cannot be edited: This field is read-only

Cell Type

• Type: Dropdown
• Required: No (defaults to "STRING")
• Purpose: Defines the data type expected in the Excel cell
• Options:
  • Numeric - For numbers
  • String - For text (default)
  • Blank - For empty cells
  • Local Date - For dates
  • Enum - For enumerated values

Default Value

• Type: Text input
• Required: No
• Purpose: Value to use if the Excel cell is empty
• Example: "N/A", "0", "Default Location"
• Use case: When you want to provide a fallback value for empty cells

Constant Value

• Type: Text input
• Required: No
• Purpose: A constant value that will always be used for this column
• Example: "ACTIVE", "USA", "2024"
• Use case: When the column should always have the same value regardless of Excel content

Cell Format

• Type: Text input
• Required: No
• Purpose: Format specification for how the cell data should be interpreted
• Example: Date formats, number formats
• Use case: When you need specific formatting rules for the imported data

Mandatory (Required Field)

• Type: Checkbox
• Required: No (defaults to unchecked)
• Purpose: Indicates if this field must have data in the Excel file
• Options:
  • Unchecked = Optional (gray "NOT REQUIRED" badge)
  • Checked = Required (green "REQUIRED" badge)
• Behavior:
  • If checked and Excel cell is empty, import will show an error
  • If unchecked, empty cells are allowed

Enabled (Active)

• Type: Checkbox
• Required: No (defaults to checked)
• Purpose: Controls whether this configuration is used during import
• Options:
  • Checked = Active (green "ENABLED" badge) - Configuration is used
  • Unchecked = Inactive (red "DISABLED" badge) - Configuration is skipped
• Use case: Temporarily disable a configuration without deleting it

---

Validation Rules and Error Messages

Required Field Validation

Rule: Fields marked with red asterisk (*) must be filled

Error indication:

• Red border around the field
• Create/Update button remains disabled

Required fields:

• Type Process (always)
• Header Name (always)
• Column Letter (always)
• Type Test (when Type Process is TYPE_TEST)
• Custom Column (when Type Process is CUSTOM_COLUMN)
• Additional Data (when Type Process is ADDITIONAL_DATA)
• Column Name Person (when Type Process is EMPLOYEE)

Column Letter Validation

Rules:

• Cannot be empty
• For custom values: Letters only (numbers and special characters are automatically removed)
• Automatically converted to uppercase
• Used letters (except N_A) cannot be selected again

Error messages:

• "Column Letter is required" - If left empty
• Column letter not available in dropdown if already used

Form Submission Validation

Rule: All required fields must be valid before submission

Behavior:

• Create/Update button is disabled until form is valid
• Red borders appear on invalid required fields
• Tooltip on disabled button explains why it's disabled

Success messages:

• Create: "Configuration was added successfully"
• Update: "Configuration was updated successfully"

Error messages:

• Create: "Failed to add configuration"
• Update: "Failed to update configuration"
• Delete: "Failed to delete configuration"

Common Use Cases

Use Case 1: Setting Up Basic Employee Import

Scenario: You need to import employee data with standard fields (ID, Name, Email)

Steps:

1. Create configuration for Employee ID

   • Type Process: EMPLOYEE
   • Header Name: "Employee ID"
   • Column Letter: "A"
   • Column Name Person: "identification"
   • Mandatory: Checked
   • Enabled: Checked

2. Create configuration for First Name

   • Type Process: EMPLOYEE
   • Header Name: "First Name"
   • Column Letter: "B"
   • Column Name Person: "name"
   • Mandatory: Checked
   • Enabled: Checked

3. Create configuration for Email

   • Type Process: EMPLOYEE
   • Header Name: "Email"
   • Column Letter: "C"
   • Column Name Person: "email"
   • Mandatory: Unchecked (optional)
   • Enabled: Checked

Use Case 2: Adding Test Type Columns

Scenario: You need to import pre-employment and post-accident test information

Steps:

1. Create configuration for Pre-Employment

   • Type Process: TYPE TEST
   • Header Name: "Pre-Employment"
   • Column Letter: "H"
   • Type Test: "PRE_EMPLOYMENT"
   • Mandatory: Unchecked
   • Enabled: Checked

2. Create configuration for Post-Accident

   • Type Process: TYPE TEST
   • Header Name: "Post-Accident"
   • Column Letter: "I"
   • Type Test: "POST_ACCIDENT"
   • Mandatory: Unchecked
   • Enabled: Checked

Use Case 3: Using Custom Column Letters

Scenario: Your Excel file uses column "HG" for a special field

Steps:

1. Create configuration
   • Type Process: EMPLOYEE
   • Header Name: "Special Field"
   • Column Letter: Select "Custom..." then enter "HG"
   • Column Name Person: Select appropriate field
   • Enabled: Checked

Use Case 4: Temporarily Disabling a Configuration

Scenario: You want to skip a column during import without deleting the configuration

Steps:

1. Find the configuration in the table
2. Click Edit icon
3. Uncheck "Active" (Enabled field)
4. Click Update
5. Configuration now shows red "DISABLED" badge
6. This column will be skipped during import

Use Case 5: Making a Field Optional

Scenario: A field that was required should now be optional

Steps:

1. Find the configuration
2. Click Edit icon
3. Uncheck "Required field" (Mandatory)
4. Click Update
5. Configuration now shows gray "NOT REQUIRED" badge
6. Empty cells in this column will no longer cause import errors

Tooltips and Helpful Hints

Throughout the interface, you'll find helpful tooltips (blue information boxes) that appear when you hover over elements:

Search Bar

• Tooltip: "Search configurations by header name, column letter, or attribute"
• Location: Search input field

New Configuration Button

• Tooltip: "Create a new import employee configuration"
• Location: Orange button with plus icon

Edit Icon

• Tooltip: "Edit configuration"
• Location: Pencil icon in Options column

Delete Icon

• Tooltip: "Delete configuration"
• Location: Trash icon in Options column

Cancel Button (in form)

• Tooltip: "Cancel and close the form"
• Location: Cancel button in modal

Create/Update Button (in form)

• Tooltip:
  • "Create a new import employee configuration" (when creating)
  • "Update the import employee configuration" (when editing)
• Location: Create/Update button in modal

Best Practices

1. Naming Conventions

• Use clear, descriptive Header Names
• Match Header Names to your Excel file column headers exactly
• Example: "Employee ID" not "Emp ID" or "ID"

2. Column Letter Management

• Use standard letters (A-Z) when possible
• Reserve custom letters (like "HG") for special cases
• Keep track of which letters are used

3. Required Fields

• Mark fields as Required only when data is essential
• Too many required fields can cause import failures
• Consider making optional fields that might not always have data

4. Testing Configurations

• Create test configurations with Enabled unchecked first
• Test with a small Excel file before full import
• Verify data mapping is correct before enabling

5. Organization

• Use consistent Header Names across similar configurations
• Group related configurations together (they'll be sorted by Column Letter)
• Document any special configurations for your team

6. Maintenance

• Review configurations periodically
• Disable unused configurations instead of deleting (if you might need them later)
• Delete only when certain they're no longer needed

---

Additional Notes

Documentation Button

• A documentation button (orange circle with document icon) appears next to the "Import Employee Configuration" title
• Clicking it opens the full user documentation in a new tab
  

Table Sorting

• Configurations are automatically sorted by Column Letter (ascending)
• A-Z, then AA-AI, then custom letters
• N_A appears first if used

Pagination

• If you have many configurations, use pagination at the bottom of the table
• Use the page numbers or next/previous arrows to navigate

Filtering

• The search bar filters all visible columns
• Search is case-insensitive
• Clear search to see all configurations again

---

Summary

The Import Employee Configuration feature provides a flexible way to map Excel columns to employee data fields. By understanding:

• Type Process options and when to use each
• Field requirements and validation rules
• How to create, edit, and delete configurations
• Best practices for naming and organization

You can efficiently set up and maintain your employee import configurations, ensuring accurate data import from Excel files.

For additional help, use the documentation button or contact your system administrator.