---
title: "Historic Assay Loader v2.0.1 User Guide"
canonical: "https://servicedesk.maxgeo.com/space/mxAPI/2332950529/Historic%20Assay%20Loader%20v2.0.1%20User%20Guide"
format: markdown
---
> ℹ️ *This version of the Historic Assay Loader has been developed to support both ODBC connections (for local database loading) as well as API connectivity (for remote database loading).*
> ℹ️ 
> ℹ️ *To enable connectivity with mxAPI, users must first obtain an API license.*  
> ℹ️ *Once licensed, the following will be required:*
> ℹ️ 
> ℹ️ *The endpoint URL and the API Key. *
> ℹ️ 
> ℹ️ MDS database version 4.6.6 or newer

> Macro (toc)

# **mxAPI Endpoint for Historic Assay Loader (HAL)**

A dedicated endpoint for HAL is now available within the **mxAPI**, enabling seamless integration between the HAL Extension and the target database.

This enhancement allows data prepared by the HAL Extension to be **POSTed directly via the API** into the target database’s tables.

Refer to this link to enable the mxAPI and Licensing.[mxAPI and Licensing](https://servicedesk.maxgeo.com/space/mxAPI/1797455873/mxAPI+Licensing+and+User+Requirements)


# **Using DBA Tools for HAL Connectivity**

To begin, copy the HAL extension file **MDS_v466_Historical_Assay_Loading_V2.accdb**   
to your local system and ensure saved location is trusted within Microsoft Access.   
Refer to this link to set the trusted location.  
[Add, remove, or change a trusted location in Microsoft Office - Microsoft Support](https://support.microsoft.com/en-us/office/add-remove-or-change-a-trusted-location-in-microsoft-office-7ee1cdc2-483e-4cbb-bcb3-4e7c67147fb4)

Under Forms, open **DBA Tools** and select your preferred connection method — either **ODBC** or **API**.


## Connection via API in DBA Tools

If you choose **API**, you’ll be prompted to enter:

- The **API URL** provided by your system administrator
- An **API Key**, which you’ll generate in **DataShed5**

Once these details are entered, click the **API Populate** button. This will:

- Save your API key
- Load the necessary library data required for the HAL Extension to function properly

> 📝 **NOTE: Each client has a unique API URL configured.**
> 📝 
> 📝 For maxgeo cloud clients: [https://companynamemxapi.maxgeo.com/api/v1](https://companynamemxapi.maxgeo.com/api/v1)  
> 📝 For on premise clients: [https://mxapi.companyanme.com/api/v1](https://mxapi.companyanme.com/api/v1)

![Historic Assay Loader (HAL) Extension (version 2) (Copy) - Step 2 (1).png](media://0098464c-5ec3-49fa-a76d-8345f705d227)


## Connecting via ODBC in DBA Tools

When opting for ODBC connectivity in DBA Tools, simply enter your ODBC connection details and click the **'ODBC Populate'** button.

This will initiate the connection and load the necessary data to support HAL functionality.

![Historic Assay Loader (HAL) Extension (version 2) (Copy) - Step 3 (1).png](media://556b0d35-791b-41c6-9832-735ce71e4bff)



# **Launching Historic Assay Loader (HAL)**

HAL can be launched using the **‘Flat Assay’** button from either of the following forms:

- `extASS_AssayManagementTools`
- `extASS_HistoricLoaderSub`

This action initiates the Historic Assay Loader interface, enabling users to manage and process legacy assay data efficiently.

![Historic Assay Loader (HAL) Extension (version 2) (Copy) - Step 4.webp](media://922ddac9-4d32-4c6d-bdef-b0a80da9b966)


## **Loading Assays – Items 1 to 6**

To successfully load assay data into **HAL**, follow these steps:

- **Ensure external Access database is ticked on, then Select the Database File to Import**
  - Choose the appropriate file type:
    - `Microsoft Access (*.accdb)`
    - `Microsoft Access (*.mdb)`
- **Select the File**
  - Browse and choose the correct Access database file.
- **Select the Table**
  - Identify and select the table within the database that contains the assay data.
- **Set the Source File**
  - Confirm the source file path or name for reference and tracking.
- **Pick the Sample ID Field**
  - Choose the field that uniquely identifies each sample.
- **Select the Lab Code**
  - Assign the correct lab code associated with the assay data.
- **Select the Batch Number Field or Set a Fixed Value**
  - Either:
    - Select the field containing batch numbers, or
    - Manually enter a fixed batch number value.
- **Determine Detection Limits Application**
  - Decide whether detection limits should be applied and configure accordingly.

![Historic Assay Loader (HAL) Extension (version 2) (Copy) - Step 7.webp](media://24c419fc-9fe4-4c69-99a4-a990a40516ae)


## **Element Details and Populate Element Details**

- **Highlight the Elements**
  - Select the relevant elements from the list.
- **Click the "Populate Element Details" Button**
  - This action will begin the process of populating metadata for each selected element.
- **Populate Required Fields**
  - Ensure the following details are completed for each element:
    - **Repeat**
    - **Unit Code**
    - **Methods**
  - *Note:* Some fields may auto-populate based on existing configurations or previous selections.
- **Return to Import Historic Assays**
  - Once all element details are populated, switch back to the **Import Historic Assays** section to continue the workflow.

![Historic Assay Loader (HAL) Extension (version 2) (Copy) - Step 17.webp](media://a30d81ae-0bcc-4b3e-8d1e-4df397d4729e)


## **Libraries Data**

- **Review library values if needed** during the assay import process.
- **Important:**  
Changes to any library values **cannot** be made within **HAL** in **API** connectivity mode
- To update library values
  - **Log in to DataShed5**.
  - Make the necessary adjustments to the relevant library entries.
  - Return to HAL and **refresh the data** to reflect the updated values.

![Historic Assay Loader (HAL) Extension (version 2) (Copy) - Step 20.webp](media://f99e1bd3-d83e-44fc-ac90-371a24ae7bd0)


## **Refreshing Libraries**

### **When Connection Type is API:**

- **Note the Connection Type**
  - Ensure it is set to **API**.
- **Click "Library Refresh"**
- **Wait for Completion**
  - A popup will confirm:  
**API LIB Tables Refreshed**

### **When Connection Type is ODBC:**

- Library data **can be updated directly in the grid**.

![Historic Assay Loader (HAL) Extension (version 2) (Copy) - Step 23.webp](media://75a1bda1-431f-44fc-ba15-cc32fda770fb)


## **Appending Samples**

Once all required information has been provided:

- **Click the "Append Samples" Button**
  - This initiates the sample import process.
- **Monitor Progress**
  - A progress indicator will update as the data loads.
- **Wait for Completion**
  - The system will notify you once the sample data has been successfully appended.
  - Open DataShed5 Assay Manager to see the data loaded.

![Historic Assay Loader (HAL) Extension (version 2) (Copy) - Step 26.webp](media://619f3823-e8fa-4489-83c2-d06e43179c7b)


> ℹ️ # **Tip 1 - Microsoft Access Limitations with Large Databases**
> ℹ️ 
> ℹ️ - **File Size Growth**: Access databases grow over time and don’t automatically release unused space.
> ℹ️ - **Performance Impact**: This can lead to slow performance or even corruption if the file size approaches the 2GB limit.
> ℹ️ - **HAL Extension Usage**: Loading large datasets like historic assays via the HAL Extension can exacerbate these issues.
> ℹ️ 
> ℹ️ [Compact and repair a database - Microsoft Support](https://support.microsoft.com/en-us/office/compact-and-repair-a-database-6ee60f16-aed0-40ac-bf22-85fa9f4005b2)

> ℹ️ # **Tip 2 – Improve Loading Performance for Large Files**
> ℹ️ 
> ℹ️ To enhance performance when working with large assay files:
> ℹ️ 
> ℹ️ - **Open Windows Task Manager**
> ℹ️ - Locate the **Microsoft Access** process (`MSACCESS`)
> ℹ️ - **Right-click** on the task and select **"Go to details"**
> ℹ️ - In the **Details** tab, right-click again and choose **"Set priority"**
> ℹ️ - Change the priority from **"Normal"** to **"Above normal"**
> ℹ️   **NOTE:**  
> ℹ️ Depending on your **security login level**, you may **not be able to perform** this function. If access is restricted, please contact your system administrator.

![Historic Assay Loader (HAL) Extension (version 2) (Copy) - Step 30.webp](media://1a43e291-a86a-4fb4-a112-57d536761b57)

# Downloads

> ℹ️ It is recommended that this application is installed and configured by maxgeo. Any installation that is not performed by maxgeo is not covered by maxgeo’s standard support. Any support relating to the application will be quoted prior to support.

| **File Name** | **Version** | **Release Date** | **Download** |
| --- | --- | --- | --- |
| Historical_Assay_Loading_V2.0.1 | 2.0.1 | March 2026 |  |
| Historical_Assay_Loading_V2.0.0 | 2.0.0 | December 2025 |  |
|  |  |  |  |