LLImporter
Imports linelist data from external workbooks into the source linelist. Supports importing HList/VList data, custom dropdowns, show/hide state, editable labels, single metadata values, and geobase data. Tracks which sheets and variables were imported, and builds a report of items not imported or not touched. Consumers interact through the ILLImporter interface.
Depends on: ILLdictionary, IPasswords, ICustomTable, IDataSheet, IShowHideManager, ILLGeo, ILLChoices, ILLVariables, IDropdownLists, IHiddenNames
Factory
Create #
create
Create an importer from the source linelist workbook
Signature:
Public Function Create(ByVal sourceWkb As Workbook) As ILLImporter
Factory method that validates the workbook is not Nothing, then constructs and returns a new LLImporter instance through the ILLImporter interface. Called on the predeclared instance.
Parameters:
sourceWkb: Workbook. The linelist workbook that will receive imported data.
Returns: ILLImporter. A fully initialised instance ready for import operations.
Throws:
- vbObjectError When the workbook is Nothing.
Data Checks
HasData #
has-data
Whether the workbook contains user-entered data
Signature:
Public Property Get HasData() As Boolean
Scans all HList sheets for non-empty rows beyond the blank count threshold stored in cell(1,6). Returns True as soon as a single row has user data. Used to warn the user before clearing or overwriting.
Returns: Boolean. True when at least one HList row has user data.
HasSameLanguage #
has-same-language
Check whether the import workbook language matches
Signature:
Public Function HasSameLanguage(ByVal impwb As Workbook) As Boolean
Reads the language tag from the import workbook Metadata sheet and compares it with the source workbook dictionary language via LLTranslations. Stores the result internally so that ImportShowHide, ImportEditableLabels, and ImportSingleValues silently skip when languages differ. Returns False when the Metadata sheet is missing.
Parameters:
impwb: Workbook. The opened import workbook.
Returns: Boolean. True when languages match.
Data Operations
ClearData #
clear-data
Clear all user-entered data from HList and VList sheets
Signature:
Public Sub ClearData()
Iterates over all worksheets in the source workbook. For HList sheets, clears non-formula column values from the ListObject data body. For VList sheets, clears non-formula named range values. Unprotects and re-protects each sheet via IPasswords.
ImportData #
import-data
Import data from HList and VList worksheets
Signature:
Public Sub ImportData(ByVal impwb As Workbook, ByVal pasteAtBottom As Boolean)
Iterates over the import workbook worksheets, matching them to source workbook sheets by name. For HList sheets, delegates to ImportHListSheet. For VList sheets, delegates to ImportVListSheet. Tracks imported sheets and variables, and builds "not imported" report entries for sheets and variables not found in the current workbook.
Parameters:
impwb: Workbook. The opened import workbook.pasteAtBottom: Boolean. When True, appends data below existing rows.
ImportCustomDropdown #
import-custom-dropdown
Import custom dropdown choices from the import workbook
Signature:
Public Sub ImportCustomDropdown(ByVal impwb As Workbook, ByVal pasteAtBottom As Boolean)
Reads custom dropdown ListObjects from the source workbook custom dropdown sheet, matches them to choices in the import workbook Choices sheet, and updates each dropdown with the imported values. Silently exits when the import workbook has no Choices sheet or the custom dropdown sheet does not exist.
Parameters:
impwb: Workbook. The opened import workbook.pasteAtBottom: Boolean. When True, appends choices below existing entries.
Migration Metadata
ImportShowHide #
import-show-hide
Import show/hide visibility state from a migration workbook
Signature:
Public Sub ImportShowHide(ByVal impwb As Workbook)
Reads the show_hide_migration ListObject from the import workbook and applies visibility and column/row sizes to each data sheet via ShowHideManager.ImportForMigration. Silently skips when HasSameLanguage returned False, when the import workbook lacks the required Metadata or show_hide__ sheets, or when the metadata tag is not set to "update on import".
Parameters:
impwb: Workbook. The opened migration workbook.
ImportEditableLabels #
import-editable-labels
Import editable label values from a migration workbook
Signature:
Public Sub ImportEditableLabels(ByVal impwb As Workbook)
Reads the import workbook dictionary for editable label values and updates both the worksheet cells and dictionary entries in the source workbook. Silently skips when HasSameLanguage returned False, the import dictionary is not prepared, or the metadata tag is not set to "update on import".
Parameters:
impwb: Workbook. The opened migration workbook.
ImportSingleValues #
import-single-values
Import single metadata values from a migration workbook
Signature:
Public Sub ImportSingleValues(ByVal impwb As Workbook)
Reads the epiweek start value from the import workbook Metadata sheet and updates the RNG_EpiWeekStart named range in the source workbook. Silently skips when HasSameLanguage returned False or the Metadata sheet is missing.
Parameters:
impwb: Workbook. The opened migration workbook.
ImportGeobase #
import-geobase
Import geobase data from a workbook
Signature:
Public Sub ImportGeobase(ByVal impwb As Workbook, Optional ByVal histoOnly As Boolean = False)
Delegates to LLGeo.Import to load geobase data. When not histoOnly, also updates geobase headers in HList worksheets via geo.Update, dictionary geo labels via geo.UpdateDict, and show/hide tables for geo variables via geo.UpdateShowHide.
Parameters:
impwb: Workbook. The opened geobase workbook.histoOnly: Optional Boolean. When True, imports only historic geobase data. Defaults to False.
Import Report
NeedReport #
need-report
Whether the last import had issues
Signature:
Public Property Get NeedReport() As Boolean
Returns True when at least one report entry exists, meaning some sheets or variables were not imported or not touched during the last import.
Returns: Boolean. True when the import report has entries.
FinalizeReport #
finalize-report
Build the "not touched" part of the import report
Signature:
Public Sub FinalizeReport()
Compares source workbook sheets and variables against the imported items tracked during ImportData. Identifies sheets not touched and variables not touched, skipping formula-type variables (case_when, formula, choice_formula). Call after ImportData to complete the report.
ReportSheets #
report-sheets
Report sheet names for the given scope
Signature:
Public Function ReportSheets(ByVal scope As Byte) As BetterArray
Returns a BetterArray of sheet names that were either not imported (ImportReportNotImported) or not touched (ImportReportNotTouched). Returns an empty BetterArray when no entries exist for the scope.
Parameters:
scope: Byte. ImportReportNotImported or ImportReportNotTouched.
Returns: BetterArray. Sheet names matching the scope, or empty.
ReportVariables #
report-variables
Report variable entries for the given scope
Signature:
Public Function ReportVariables(ByVal scope As Byte) As BetterArray
Returns a BetterArray where each entry is a Variant array of Array(variableName, sheetName). Returns an empty BetterArray when no entries exist for the scope.
Parameters:
scope: Byte. ImportReportNotImported or ImportReportNotTouched.
Returns: BetterArray. Variant arrays of (variableName, sheetName), or empty.
ClearReport #
clear-report
Reset report state
Signature:
Public Sub ClearReport()
Clears all report tracking arrays and resets the needReport flag. Call before starting a new import session to ensure a clean report.
Internal members (not exported)
Public Accessors
Self #
self
Current object instance
Signature:
Public Property Get Self() As ILLImporter
Returns: ILLImporter. The current instance cast to the interface.
SourceWorkbook #
source-workbook
Source linelist workbook
Signature:
Public Property Get SourceWorkbook() As Workbook
Returns: Workbook. The linelist workbook bound to this importer.
SourceWorkbook #
source-workbook-set
Assign the source linelist workbook
Signature:
Public Property Set SourceWorkbook(ByVal wb As Workbook)
Parameters:
wb: Workbook. The workbook to store.
Private - Source Object Accessors
SourceDictionary #
source-dictionary
Get the dictionary from the source workbook
Signature:
Private Function SourceDictionary() As ILLdictionary
Returns: ILLdictionary. Dictionary instance from the Dictionary sheet.
PasswordsObject #
passwords-object
Get passwords from the source workbook
Signature:
Private Function PasswordsObject() As IPasswords
Returns: IPasswords. Passwords instance from the __pass sheet.
GeoObject #
geo-object
Get the geo object from the source workbook
Signature:
Private Function GeoObject() As ILLGeo
Returns: ILLGeo. Geo instance from the Geo sheet.
Private - Import Helpers
InitializeTracking #
initialize-tracking
Initialize tracking state for a new import session
Signature:
Private Sub InitializeTracking()
IsReservedSheet #
is-reserved-sheet
Check if a sheet name is reserved (metadata/infrastructure)
Signature:
Private Function IsReservedSheet(ByVal sheetName As String) As Boolean
Parameters:
sheetName: String. The sheet name to check.
Returns: Boolean. True when the name matches a reserved sheet.
ImportVListSheet #
import-vlist-sheet
Import VList data from a single import sheet to the current sheet
Signature:
Private Sub ImportVListSheet(ByVal currsh As Worksheet, ByVal impsh As Worksheet)
Iterates over the import sheet used range rows, resolving each variable name to a named range on the current sheet. Copies the value when the target cell has no formula. Tracks variables not found as "not imported" report entries.
Parameters:
currsh: Worksheet. The current source VList worksheet.impsh: Worksheet. The import VList worksheet.
ImportHListSheet #
import-hlist-sheet
Import HList data from a single import sheet to the current sheet
Signature:
Private Sub ImportHListSheet(ByVal currsh As Worksheet, ByVal impsh As Worksheet, _
ByVal pasteAtBottom As Boolean)
Creates a CustomTable from the current sheet ListObject and a DataSheet from the import sheet, then delegates to CustomTable.Import. Tracks columns not found in the current table as "not imported" report entries.
Parameters:
currsh: Worksheet. The current source HList worksheet.impsh: Worksheet. The import HList worksheet.pasteAtBottom: Boolean. When True, appends data below existing rows.
SheetTagOf #
Get the sheet type tag from worksheet-level HiddenNames.
Signature:
Private Function SheetTagOf(ByVal sh As Worksheet) As String
Parameters:
sh: Worksheet. The worksheet to query.
Returns: String. The sheet type tag (HList, VList, etc.).
Private - Helpers
SheetExists #
sheet-exists
Check if a worksheet exists in a workbook
Signature:
Private Function SheetExists(ByVal wb As Workbook, ByVal sheetName As String) As Boolean
Parameters:
wb: Workbook. The workbook to search.sheetName: String. The sheet name to look for.
Returns: Boolean. True when the sheet exists.
Private - Error Handling
ThrowError #
throw-error
Raise a class-level exception
Signature:
Private Sub ThrowError(ByVal message As String)
Raises a VBA error using vbObjectError + 516, standardising the source to CLASS_NAME.
Parameters:
message: String. Human-readable description of the failure.
Throws:
- vbObjectError Always raises the error.
Interface Implementation
ILLImporter_HasData #
Signature:
Private Property Get ILLImporter_HasData() As Boolean
Delegated members satisfying the ILLImporter contract. See the corresponding members above for full documentation.