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

[![image.png](https://wiki.nexus33.com/uploads/images/gallery/2026-01/scaled-1680-/image.png)](https://wiki.nexus33.com/uploads/images/gallery/2026-01/image.png)

---

## 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

[![image.png](https://wiki.nexus33.com/uploads/images/gallery/2026-01/scaled-1680-/9lmimage.png)](https://wiki.nexus33.com/uploads/images/gallery/2026-01/9lmimage.png)

#### 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

[![image.png](https://wiki.nexus33.com/uploads/images/gallery/2026-01/scaled-1680-/7ZUimage.png)](https://wiki.nexus33.com/uploads/images/gallery/2026-01/7ZUimage.png)

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

[![image.png](https://wiki.nexus33.com/uploads/images/gallery/2026-01/scaled-1680-/bM9image.png)](https://wiki.nexus33.com/uploads/images/gallery/2026-01/bM9image.png)

### Step-by-Step Guide

[![image.png](https://wiki.nexus33.com/uploads/images/gallery/2026-01/scaled-1680-/Vywimage.png)](https://wiki.nexus33.com/uploads/images/gallery/2026-01/Vywimage.png)

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
    - [![image.png](https://wiki.nexus33.com/uploads/images/gallery/2026-01/scaled-1680-/hvEimage.png)](https://wiki.nexus33.com/uploads/images/gallery/2026-01/hvEimage.png)
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.