Apps
Database Connection Settings
Sample Code Revit Batch Processor 1.1.16 documentation
The Database Connection section in the Settings view manages all aspects of the SQLite database used by the application. This includes database creation, connection management, data import/export, and custom field definitions. The database stores all document and revision information used by the application for matching, tracking, and metadata management.
The application uses SQLite as its database engine with the sqlite-net-pcl library as the Object-Relational Mapping (ORM) layer. This provides a lightweight, file-based database solution that requires no separate database server installation.
Description: The file path where the SQLite database is located or will be created.
Type: Text input
Format: Full file path with .db or .sqlite extension
Example: C:\ProjectData\DocumentDatabase.db
Validation:
When Connected: Path must be valid and database must be connected
When Disconnected: No validation (allows entering path before connection)
For Creation: Directory must exist or be creatable, filename must be valid
Features:
All import and export operations require an active database connection. These operations work with CSV format files for easy data exchange with external systems and spreadsheet applications.
Description: Checkbox that controls how revision history is handled during import/export operations.
Options:
Behavior:
Exports ALL documents in ALL revisions
Documents not in a particular revision appear with blank revision indicators
Creates a complete matrix of documents × revisions
Results in larger CSV files with many blank cells
Use Case:
When you need to see which documents are present in each revision
For comprehensive revision tracking across all documents
When importing/exporting to systems that expect a full matrix
Example: If you have 100 documents and 10 revisions, the export will have up to 1000 rows (100 × 10), with blanks where a document wasn’t part of that revision.
Behavior:
Exports only documents that have revision indicators in each revision
Skips documents that weren’t part of a revision
Creates more compact CSV files
Only includes meaningful revision history entries
Use Case:
When you only care about documents that have explicit revision markers
For smaller, more focused exports
When most documents don’t participate in every revision
Example: If you have 100 documents but only 30 have revision indicators, the export will only include those 30 documents’ revision entries.
Function: Imports document data from a CSV file into the database
Button: Import Documents
Enabled When:
Database is connected
Not busy with other operations
Process:
Opens file dialog to select CSV file
Parses CSV and validates format
Creates or updates documents in database
Creates custom property records for new documents
Reloads data into Manager
Displays success/error statistics
CSV Format Expected:
Required Columns:
Number - Document number (unique identifier)
Name - Document name/title
Revision - Current revision code
Optional Columns:
[CustomFieldName] - Any active custom field property name
Custom fields must match those defined in the database
Revision History Columns (if using Full Revision History Mode):
Columns named after revision codes (e.g., A, B, C, P01)
Values are revision indicators (e.g., S0, S1, AS, -)
Blank cells indicate document was not in that revision
Import Behavior:
New Documents:
Created with specified properties
Custom property records created for all active custom fields
Blank custom fields set to empty string
Existing Documents:
Updated with new values
Document number used as primary key for matching
Custom properties updated or created as needed
Validation:
CSV must have required columns
Document numbers must be valid (not null/empty)
Warns about documents with issues but continues with others
Success Message: Shows count of documents created and updated
Error Handling:
Displays first error encountered if import fails
Partial imports possible (some documents may succeed)
Check message banner for detailed error information
Function: Exports document data from the database to a CSV file
Button: Export Documents
Enabled When:
Database is connected
Data is loaded into Manager
Not busy with other operations
Process:
Validates data is loaded
Opens Save File Dialog for output location
Retrieves all documents from Manager
Retrieves all active custom field definitions
Retrieves all revisions (if applicable)
Generates CSV with appropriate columns
Writes file to specified location
Displays success message with count
CSV Format Generated:
Standard Columns:
Number - Document number
Name - Document name
Revision - Current revision code
Custom Field Columns:
One column per active custom field
Column header matches custom field property name
Values from custom property records
Revision History Columns (if Full Revision History Mode enabled):
One column per revision code
Contains revision indicators for that document in that revision
Blank for documents not in that revision
File Naming: Default filename is Documents.csv but can be changed in Save dialog
Success Message: Shows count of documents exported and output filename
Use Cases:
Backup document data
Share document list with external systems
Bulk editing in spreadsheet applications
Data migration between databases
Function: Imports revision definitions from a CSV file into the database
Button: Import Revisions
Enabled When:
Database is connected
Data is loaded into Manager
Not busy with other operations
Process:
Opens file dialog to select CSV file
Parses CSV and validates format
Creates or updates revisions in database
Reloads data into Manager
Displays success/error statistics
CSV Format Expected:
Required Columns:
RevisionCode - Unique revision identifier (e.g., “A”, “B”, “P01”)
RevisionDate - Date of revision in ISO format (YYYY-MM-DD)
Description - Description of the revision
Example:
RevisionCode,RevisionDate,Description
A,2024-01-15,Issued for Construction
B,2024-02-20,Client Comments Incorporated
P01,2024-03-10,Planning Submission
Import Behavior:
New Revisions:
Created with specified properties
Added to the revisions collection
Existing Revisions:
Updated with new date and description
RevisionCode used as primary key for matching
Validation:
CSV must have required columns
Revision codes must be unique within file
Dates must be valid format
Success Message: Shows count of revisions created and updated
Error Handling:
Displays errors if CSV format invalid
Shows first error if revisions fail to import
Function: Exports revision definitions from the database to a CSV file
Button: Export Revisions
Enabled When:
Database is connected
Data is loaded into Manager
Not busy with other operations
Process:
Validates data is loaded
Opens Save File Dialog for output location
Retrieves all revisions from Manager
Generates CSV with revision columns
Writes file to specified location
Displays success message with count
CSV Format Generated:
RevisionCode - The revision identifier
RevisionDate - Date in ISO format (YYYY-MM-DD)
Description - Revision description
File Naming: Default filename is Revisions.csv but can be changed in Save dialog
Success Message: Shows count of revisions exported and output filename
Use Cases:
Backup revision list
Share revision schedule with project team
Synchronize revisions between databases
Documentation of project timeline
Custom Fields allow you to extend the document data model with additional properties specific to your project needs. Custom fields are stored in the database and can be used throughout the application for filtering, metadata export, and reporting.
Visibility: Only visible when database is connected
Behavior:
Automatically expands when database connected
Collapses when database disconnected
Contains ListView and management buttons
Each custom field has the following properties:
Description: The name of the custom property field
Constraints:
Must be unique within the database
Case-sensitive
Should follow naming conventions (e.g., PascalCase, no spaces)
Becomes a property on the Document model
Examples:
Discipline
BuildingName
ContractorCompany
DrawingType
ProjectPhase
Best Practice: Use descriptive, meaningful names that clearly indicate the field’s purpose
Description: Whether the custom field is currently active and usable
Values:
Active: Field can be used in metadata mappings, exports, and throughout the application
Inactive: Field is hidden from most operations but data is preserved in database
Displayed As:
“Active” in green (in ListView)
“Inactive” in gray (in ListView)
Purpose: Allows temporarily disabling fields without deleting data
Description: Database identifier for the custom field
Values:
0 - New field not yet saved to database
> 0 - Existing field persisted in database
Visibility: Not displayed in UI, used internally for operations
Button: Add
Enabled When: Database is connected
Process:
Click Add button
Dialog opens prompting for field name
Enter desired custom field name
Click OK in dialog
Field added to list with Status “Active” (not saved yet)
Status shows as unsaved (Id = 0)
Validation in Dialog:
Field name cannot be empty
Field name must be unique (checked against existing fields)
Field name should follow property naming conventions
Important: New fields are NOT saved to the database immediately. You must click “Update Database” to persist changes.
Success Message: Displays confirmation that field was added with instruction to update database
Use Case: Add project-specific properties needed for document categorization or reporting
Button: Remove
Enabled When:
Database is connected
A custom field is selected
Selected field has Id = 0 (not yet saved to database)
Restriction: Can only remove fields that haven’t been saved yet
Process:
Select an unsaved custom field (Status shows Id = 0)
Click Remove button
Field removed from list immediately
Pending changes flag updated
Rationale: Once a custom field is saved to the database and has data, it should be deactivated rather than deleted to preserve data integrity.
For Saved Fields: Use “Toggle Active” instead to deactivate the field
Button: Toggle Active
Enabled When:
Database is connected
A custom field is selected
Process:
Select a custom field from the list
Click Toggle Active button
Field’s IsActive status toggles (Active ↔ Inactive)
Status display updates in ListView
Pending changes flag set
Important: Status change is NOT saved immediately. Click “Update Database” to persist the change.
Behavior by Status:
Activating a Field:
Field becomes available for use in metadata mappings
Field appears in document property lists
Field available for import/export
Deactivating a Field:
Field removed from available properties in mappings
Existing metadata mappings using this field are removed automatically
Data preserved in database (custom property records remain)
Field hidden from import/export by default
Can be reactivated later without data loss
Warning: Deactivating a custom field will remove any cloud metadata mappings that reference it. This cleanup happens automatically when “Update Database” is clicked.
Button: Update Database
Enabled When:
Database is connected
There are pending custom field changes
Pending Changes Include:
New fields added (Id = 0)
Active status toggled on existing fields
Process:
Click Update Database button
Confirmation dialog appears showing summary of changes:
New fields to be added
Fields to be activated
Fields to be deactivated
Review changes and click Yes to proceed
Application applies changes to database:
New fields: Schema updated, custom property records created for ALL documents
Activations: IsActive flag updated in database
Deactivations: IsActive flag updated, metadata mappings cleaned up
Data reloaded into Manager
Custom Fields list refreshed
Success message displayed
Change Summary Dialog Contents:
The confirmation dialog shows:
Count of new fields with their names
Count of activated fields with their names
Count of deactivated fields with their names
Warning if new fields will create records for all documents
Example:
Apply Custom Field Changes?
New Fields: 2
- ProjectPhase
- ContractorName
Deactivated Fields: 1
- OldFieldName
Note: New fields will create records for all documents.
Database Operations Performed:
For New Fields:
Adds CustomFieldDefinition record to database
Creates CustomProperty record for EVERY existing document
Initial values set to empty string
May take time if many documents exist
For Status Changes:
Updates IsActive flag on CustomFieldDefinition
For deactivations: Removes metadata mappings referencing the field
CustomProperty data preserved in database
Automatic Cleanup:
When fields are deactivated:
Scans all cloud metadata mappings
Removes any mappings referencing deactivated fields
Shows notification of removed mappings
Triggers refresh in Cloud Document Manager view
Success Message: Displays count of changes applied and any mappings removed
Error Handling:
If any change fails, entire operation rolls back (transaction)
Error message shows which field caused the failure
Changes are not persisted if errors occur
Use Cases:
Adding custom fields for new project requirements
Deactivating fields no longer needed
Batch applying multiple custom field changes
Columns:
Displays the property name of the custom field
Sorted alphabetically by default
Primary identifier for the field
Shows “Active” or “Inactive”
Indicates current usability of the field
Determines availability in metadata mappings
Visual Indicators:
New fields (Id = 0): May be shown in different style (implementation-specific)
Active fields: Standard display
Inactive fields: Grayed out or dimmed
Selection:
Single selection mode
Selected field determines which buttons are enabled
Click to select, click away to deselect
The SQLite database contains the following core tables:
Purpose: Stores document master records
Key Fields:
Id (Primary Key)
Number (Unique)
Name
Revision
Indexes: Number (for fast lookups)
Purpose: Stores revision definitions and schedule
Key Fields:
Id (Primary Key)
RevisionCode (Unique)
RevisionDate
Description
Purpose: Stores custom field values for documents
Key Fields:
Id (Primary Key)
DocumentId (Foreign Key to Document)
PropertyName
PropertyValue
Relationship: Many-to-one with Document (one document can have many custom properties)
Purpose: Stores custom field definitions (metadata about custom fields)
Key Fields:
Id (Primary Key)
PropertyName (Unique)
IsActive
Usage: Defines which custom fields exist and their status
Relationship: One document has many custom properties
Cascade: When document deleted, custom properties deleted
Purpose: Allows flexible extension of document data model
Relationship: Many-to-many through DocumentRevision join table
Purpose: Tracks which documents are in which revisions
Indicators: Each relationship has an indicator string (e.g., “S0”, “S1”)
Rules:
Must have valid path format
Directory must exist or be creatable
Filename must be valid (no invalid characters)
Extension typically .db or .sqlite
Validated When:
Path is entered or changed
Connect or Create button is clicked
Rules:
Must be connected before saving settings
Must be connected to enable import/export
Must be connected to manage custom fields
Error Message: “Database must be connected”
Rules:
Field name cannot be empty
Field name must be unique in database
Should follow naming conventions (no spaces, special characters)
Validated When:
Adding new custom field in dialog
Updating database schema
Location: Store database in a stable location with regular backups
Naming: Use descriptive names indicating project and purpose
Backups: Regularly export documents and revisions as CSV backups
Version Control: Keep database backups when making major changes
Network Drives: Avoid network drives for database location (performance issues)
Before Import:
Backup current database
Validate CSV format in spreadsheet first
Check for duplicate document numbers
Ensure custom field names match exactly
Export Workflow:
Export regularly for backup purposes
Use descriptive filenames with dates
Keep exported CSVs for audit trail
Test import/export cycle periodically
CSV Editing:
Edit exported CSVs in Excel or similar
Don’t modify document numbers (primary keys)
Keep required columns
Maintain date formats (ISO 8601)
Planning:
Plan custom fields before creation
Use consistent naming conventions
Document field purposes and usage
Consider export requirements
Naming Conventions:
Use PascalCase (e.g., ProjectPhase)
Avoid spaces and special characters
Be descriptive but concise
Follow property naming standards
Lifecycle:
Add fields as needed for new requirements
Deactivate rather than delete obsolete fields
Test with sample documents before production use
Update documentation when fields change
Performance:
Limit to necessary fields (each adds database operations)
Create fields with data population plan
Consider indexing needs for large databases
Symptoms: Error when clicking Connect button
Solutions:
Verify file exists at specified path
Check file is not locked by another application
Ensure you have read/write permissions
Check database file is not corrupted
Verify it’s a valid SQLite database
Symptoms: Error message about CSV format during import
Solutions:
Open CSV in spreadsheet and verify columns
Check required columns are present
Ensure column names match exactly
Look for extra commas or quotes in data
Verify file is saved as CSV (not Excel format)
Check for BOM or encoding issues
Symptoms: New custom field doesn’t show in Cloud Document Manager
Solutions:
Verify custom field is Active status
Check “Update Database” was clicked after adding field
Confirm database was reloaded
Refresh the Cloud Document Manager template
Symptoms: Error when clicking Update Database button
Solutions:
Check database is not read-only
Verify you have write permissions
Ensure database is not locked
Check disk space available
Try smaller batch of changes
Review error message for specific field causing issue
Symptoms: Document count shows 0 after import operation
Solutions:
Check if import file was empty or had errors
Restore from backup database or CSV export
Verify import file had correct format
Review import error messages
Cause: Attempting operation without database connection
Solution: Click Browse to select database, then Connect
Cause: Database connected but data not loaded into Manager
Solution: Reconnect to database, or restart application
Cause: Attempting to add duplicate custom field name
Solution: Choose a different, unique field name
Cause: Selected import file doesn’t exist or was moved
Solution: Browse to correct file location
In Database:
All document records with properties
All revision definitions
All custom field definitions (schema)
All custom property values (data)
In Settings File:
Database path
Last connection state
UI preferences (expander states, etc.)
Automatic:
When database operations complete (Connect, Create)
When import/export succeeds
When Update Database applies changes
Manual:
Click Save button in Settings view to save path
Custom field changes require explicit Update Database click
Recommended:
Regular Database Backups: Copy .db file to backup location
CSV Exports: Export documents and revisions monthly
Version Control: Keep dated backups before major changes
Test Restores: Periodically verify backups are valid
SQLite handles databases up to 140 TB (theoretical)
Practical limit depends on disk space and performance needs
Thousands of documents: No issues
Tens of thousands: Some operations may take seconds
Hundreds of thousands: Consider indexing and optimization
Each custom field adds:
One column in conceptual data model
One record per document in CustomProperty table
Overhead in import/export operations
Limit to 20-30 custom fields for best performance
More fields = larger database and slower operations
CSV operations are relatively fast
Large files (>10,000 rows) may take 10-30 seconds
Progress not shown during operation (appears busy)
Database operations are transactional (all or nothing)
Database provides:
Document numbers for filename matching
Revision codes for revision extraction
Custom fields for metadata enrichment
Database provides:
Document properties for metadata mappings
Revision information for document context
Custom field values for dynamic metadata
Database provides:
Document master records for matching incoming files
Revision history for superseded tracking
Custom properties for enriched document data
SQLite is file-based with no user authentication
File system permissions control access
Anyone with file access can read/modify database
No encryption by default (consider encrypted containers)
Database may contain sensitive project information
Store in secure locations with appropriate permissions
Consider access control at file system level
Include in data governance policies
Exported CSVs contain all project data
Secure backup locations with access controls
Encrypt backups if required by policy
Control access to historical exports
Number,Name,Revision,[CustomField1],[CustomField2],...,[Rev1],[Rev2],...
ABC-001,Floor Plan,A,Value1,Value2,...,S0,S1,...
ABC-002,Elevation,B,Value1,Value2,...,-,S0,...
Notes:
Custom field columns match active custom field property names
Revision columns (if Full History Mode) are revision codes
Revision indicators: S0, S1, S2, AS, etc. or blank/dash
RevisionCode,RevisionDate,Description
A,2024-01-15,Issued for Construction
B,2024-02-20,Client Comments
P01,2024-03-10,Planning Submission
Notes:
Date must be ISO format (YYYY-MM-DD)
Description can contain spaces and special characters
RevisionCode should be concise (typically 1-4 characters)