4. Settings


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

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

Column

Header Name

Attribute

Type Process

Required

Status

Options

Search Functionality

image.png

The search bar allows you to quickly find configurations by:

  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

Step-by-Step Guide

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

  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

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

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

Understanding Type Process Options

EMPLOYEE (Default)

Purpose: Maps Excel columns to standard employee data fields

When to use: For basic employee information like:

Fields shown:

Example:

TYPE TEST

Purpose: Maps Excel columns to drug and alcohol test types

When to use: For test type columns like:

Fields shown:

Example:

CUSTOM COLUMN

Purpose: Maps Excel columns to custom column data

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

Fields shown:

Example:

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:

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

Field Descriptions

Header Name

Column Letter

Column Name Person

Attribute Name Entity

Cell Type

Default Value

Constant Value

Cell Format

Mandatory (Required Field)

Enabled (Active)

Validation Rules and Error Messages

Required Field Validation

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

Error indication:

Required fields:

Column Letter Validation

Rules:

Error messages:

Form Submission Validation

Rule: All required fields must be valid before submission

Behavior:

Success messages:

Error messages:

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:

New Configuration Button

Edit Icon

Delete Icon

Cancel Button (in form)

Create/Update Button (in form)

Best Practices

1. Naming Conventions

2. Column Letter Management

3. Required Fields

4. Testing Configurations

5. Organization

6. Maintenance

Additional Notes

Documentation Button

Table Sorting

Pagination

Filtering

Summary

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

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.

Access Management

The Access Management module is responsible for managing users, roles, and permissions within the portal. 

This section is used to manage each user's access and privileges according to their assigned role. 

Access Management

Permissions

The Permissions section shows a detailed list of all the permissions available on the portal, indicating which ones are active and which ones are disabled. 

IMPORTANT: If you want to create a new permission, you must notify the person in charge of NEXUS administration, as internal software development is required to associate that permission with specific elements of the portal. 

To search for a permission, click on the magnifying glass icon 🔍, and to clear the filter, use the “X” icon. 

Screenshot_1.png

Access Management

Roles

In the Roles section, you can create, edit, and list the roles that exist in the system. 

To create a role, you only need to provide the name and code. The code must be written in uppercase letters, and spaces must be replaced with underscores (_). 

Screenshot_2.png

Screenshot_3.png

📝 Note: Permissions are assigned to each role using the Edit Role option. 

In the Edit option, you can modify the information of an existing role, activate or deactivate its availability in the system, and assign the corresponding permissions according to the menu sections. 

image.png

The Menu Permissions section only displays menu options that have already been assigned permissions.
If you want to view options that do not yet have permissions, click Show Menus Without Permissions.

image.png

📝 Note: To assign permissions to a menu option, you must enter the Menu permissions (https://wiki.nexus33.com/books/4-settings/page/menu-permissions) module. 

To assign permissions to a role, select the menu option; the available permissions will be displayed.
Check the box for the permission you want to assign and click Update Role to save the changes.

image.png

To search for a role, click on the magnifying glass icon 🔍, and to clear the filter, use the “X” icon. 

Screenshot_6.png

Access Management

Users

In the users section, you can create, edit, and list system users.

Creating users 

There are two ways to create users in the system: 

  1. Assign permissions to an existing employee: 
    • Select the “+” icon next to the employee. 

      image.png

    • A confirmation window will appear to validate whether you want to convert that employee into a portal user. image.png
    • Once the credentials have been successfully created, a temporary password will be generated and sent to the user's registered email address. 

      image.png

Creating multiple users

Select several employees using the checkboxes and click on the “Create User” button to generate multiple users simultaneously. 

image.png

A confirmation window will appear to validate whether you want to convert the selected employees into users. 

image.png

image.png

Editing users 

From the Edit option, you can: 

  • Enable or disable a user's access to the portal. 

  • Enable or disable multi-factor authentication (MFA). 

  • Enable or disable Show QR to embed the two-factor authentication app. 

  • Configure the roles associated with each user. 

  • Allows you to reset the password for portal users in case of forgotten or lost access. image.png

📝 Note: If the user has never enabled multi-factor authentication, a QR code will be displayed when they log in for the first time, which they must scan with the Scanner Authenticator app. 

image.png

To view the QR code again, click on the cell phone icon 📱.

image.png

If you lose or change your device, you can re-enable the “Show QR Code” option to reconfigure authentication with Google Authenticator.

image.png

To search for a user, click on the magnifying glass icon 🔍, and to clear

image.png

Access Management

Menu permissions

Menu Permissions is the module responsible for assigning permissions to the portal menu options.

image.png


Using the Search Menus field, you can search for the menu option to which you want to assign permissions.

image.png

Select the menu option and, in the right-hand panel, check the box for the permissions you want to assign.
Finally, click Save Changes to save the configuration.

image.png

image.png

Email Notification

Overview

The Email Notification module allows you to create and manage email notification templates that can be automatically sent based on service and form configurations. This guide will walk you through all the features and workflows available in this module.

Email Notifications List

Accessing the List

image.png

The Email Notifications list displays all available email notification templates in your system. You can access this list from the main navigation menu.

List Features

Search Functionality

image.png

The search bar at the top of the list allows you to search across multiple fields:

How to use:

  1. Type your search term in the search field
  2. Press Enter or click outside the field
  3. The list will automatically filter to show matching results
  4. To clear the search, delete all text from the search field

Table Columns

image.png

The list displays the following information:

Actions Available

image.png

  1. New Button: Located in the top right corner, allows you to create a new email notification
  2. Documentation Button: Located next to the "List of notification to send" title, provides access to additional documentation
  3. Edit Action: Each row has an edit icon (pencil) in the Options column that allows you to modify the notification

Pagination

The list supports pagination to navigate through multiple pages of notifications. Use the pagination controls at the bottom of the table to move between pages.

Creating a New Email Notification

Step 1: Access the Creation Form

image.png

  1. From the Email Notifications list, click the New button in the top right corner
  2. You will be redirected to the creation form

Step 2: Fill Required Fields

image.png

The following fields are required and must be filled before you can save:

Notification Name

Code

Subject

Template Body Email

Step 3: Fill Optional Fields

Description

For whom email

For whom email CC

For whom email BCC

For whom

Form Status

Enabled

Step 4: Save the Notification

image.png

  1. Review all entered information
  2. Ensure all required fields are filled
  3. Click the CREATE button
  4. A success message will appear confirming the notification was created
  5. After creation, the form will switch to edit mode and the Service/Form Type section will become available

Editing an Existing Email Notification

Step 1: Access the Edit Form

image.png

  1. From the Email Notifications list, click the edit icon (pencil) in the Options column for the notification you want to modify
  2. You will be redirected to the edit form with all current values pre-filled

Step 2: Modify Fields

image.png

Step 3: Save Changes

image.png

  1. Make your desired changes
  2. Click the EDIT button to save
  3. A success message will confirm your changes were saved

Important Notes for Editing

Configuring Service/Form Type

When Can You Configure Service/Form Type?

image.png

The Service/Form Type configuration is only available after you have saved the notification (either created or edited). This section appears below the main notification form.

Step 1: Select Service/Form Type

image.png

You must first select one of three types:

  1. Service: Select specific services that will trigger this notification
  2. Form: Select specific forms that will trigger this notification
  3. Service and Form: Select both services and their associated forms

Click on the desired type button. The button will highlight to show it's selected.

Step 2: Configure Based on Selected Type

If You Selected "Service"

image.png

  1. The system will display all available modules
  2. Click on a module name to expand it and see available services
  3. Click on service buttons to select/deselect them
  4. Selected services will be highlighted
  5. You can select services from multiple modules

If You Selected "Form"

image.png

  1. The system will display all available modules
  2. Click on a module name to expand it and see available forms
  3. Click on form buttons to select/deselect them
  4. Selected forms will be highlighted
  5. Result Test cards will appear below selected forms if:
    • Form Status is set to "Complete"
    • The form has associated Result Tests
    • (See Result Test Selection section for details)

If You Selected "Service and Form"

image.png

  1. The system will display all available modules
  2. Click on a module name to expand it
  3. You'll see services listed first
  4. Click on service buttons to select/deselect services
  5. For each selected service, expand it to see associated forms
  6. Click on form buttons to select/deselect forms for each service
  7. Use the All/None button to quickly select or deselect all forms for a specific service
  8. Result Test cards will appear below selected forms if:
    • Form Status is set to "Complete"
    • The form has associated Result Tests
    • (See Result Test Selection section for details)

Step 3: Save Service/Form Configuration

image.png

  1. After making your selections, scroll to the bottom of the Service/Form Type card
  2. Click the SAVE button (for new configurations) or EDIT button (for existing configurations)
  3. A success message will confirm your configuration was saved
  4. The system will reload to show your saved selections

Important Notes

Result Test Selection

When Do Result Test Cards Appear?

image.png

Result Test cards appear automatically when all of the following conditions are met:

  1. Form Status is set to "Complete" (not "Incomplete")
  2. Service/Form Type is set to either "Form" or "Service and Form" (not "Service")
  3. A form is selected in the Service/Form Type configuration
  4. The selected form has associated Result Tests in the system

If any of these conditions are not met, the Result Test card will not appear.

How to Use Result Test Cards

image.png

  1. When a form is selected and conditions are met, a Result Test card appears below the form button
  2. The card displays all available Result Tests for that specific form
  3. Click on Result Test buttons to select/deselect them
  4. Selected Result Tests will be highlighted (active state)
  5. You can select multiple Result Tests for each form
  6. Each form has its own independent set of Result Test selections

Saving Result Test Selections

Field Descriptions

Required Fields

Field Description Format/Notes
Notification Name A descriptive name for the notification Text, any characters
Code Unique identifier for the notification Uppercase letters and underscores only (e.g., DRIVER_LICENSE)
Subject Email subject line Text, appears in recipient's inbox
Template Body Email Email body content HTML format required (e.g., <p>Content</p>)

Optional Fields

Field Description Format/Notes
Description Additional information about the notification Text, optional
For whom email Primary recipient email addresses Multiple emails, comma or Enter separated
For whom email CC Carbon copy recipient email addresses Multiple emails, comma or Enter separated
For whom email BCC Blind carbon copy recipient email addresses Multiple emails, comma or Enter separated
For whom Recipient category Dropdown selection, default: "None"
Form Status Status that triggers the notification Options: Complete, Incomplete (default: Incomplete)
Enabled Enable/disable the notification Checkbox, default: Enabled (checked)

Validations and Rules

Field Validations

  1. Notification Name: Required, cannot be empty
  2. Code:
    • Required, cannot be empty
    • Only uppercase letters (A-Z) and underscores (_) allowed
    • Must be unique (cannot duplicate existing codes)
    • Automatically converts to uppercase
  3. Subject: Required, cannot be empty
  4. Template Body Email:
    • Required, cannot be empty
    • Plain text is sufficient

Email Address Validations

Service/Form Type Validations

Error Messages

Common error messages you may encounter:

Common Workflows

Workflow 1: Create a Complete Notification with Service Selection

  1. Click New from the Email Notifications list
  2. Fill in all required fields (Name, Code, Subject, Template Body Email)
  3. Set Form Status to "Complete" or "Incomplete" as needed
  4. Fill optional fields as desired
  5. Check Enabled if you want the notification active
  6. Click CREATE
  7. After creation, scroll to Service/Form Type section
  8. Select Service type
  9. Expand modules and select desired services
  10. Click SAVE in the Service/Form Type section
  11. Your notification is now fully configured

Workflow 2: Create a Notification with Form and Result Tests

  1. Click New from the Email Notifications list
  2. Fill in all required fields
  3. Important: Set Form Status to "Complete" (required for Result Tests)
  4. Fill optional fields
  5. Click CREATE
  6. In Service/Form Type section, select Form type
  7. Expand modules and select desired forms
  8. Result Test cards will appear below selected forms (if forms have Result Tests)
  9. Select desired Result Tests by clicking on them
  10. Click SAVE in the Service/Form Type section
  11. Both form selections and Result Test selections are saved

Workflow 3: Edit and Modify Service/Form Configuration

  1. From the list, click edit icon for the notification
  2. Modify any fields as needed (except Code)
  3. Click EDIT to save changes
  4. Scroll to Service/Form Type section
  5. Modify your service/form selections as needed
  6. If Form Status is "Complete" and you have forms selected, modify Result Test selections
  7. Click EDIT (or SAVE) in the Service/Form Type section
  8. Changes are saved

Workflow 4: Disable a Notification

  1. From the list, click edit icon for the notification
  2. Uncheck the Enabled checkbox
  3. Click EDIT
  4. The notification status will change to "Disabled" in the list
  5. The notification will not be sent even if conditions are met

Tips and Best Practices

Naming Conventions

Email Content

Service/Form Selection

Result Test Selection

Testing

Troubleshooting

Result Test Cards Not Appearing

Possible causes:

  1. Form Status is set to "Incomplete" → Change to "Complete"
  2. Service/Form Type is set to "Service" → Change to "Form" or "Service and Form"
  3. No form is selected → Select a form first
  4. The selected form has no Result Tests associated → Result Tests may not exist for this form in the system

Cannot Save Service/Form Configuration

Possible causes:

  1. Notification hasn't been saved yet → Save the notification first (CREATE button)
  2. No Service/Form Type selected → Select Service, Form, or Service and Form first
  3. No selections made → Select at least one service or form

Code Already Exists Error

Template Body Email Not Saving

Summary

The Email Notification module provides a comprehensive system for creating and managing email notifications. Key points to remember:

For additional support or questions, refer to the documentation button in the Email Notifications list or contact your system administrator.