Skip to content

Initial Caching Process

Overview

When a user enables offline caching, the system performs an initial caching process to download all required data for offline use. During this process, the application operates in online mode until caching completes. This ensures data consistency and allows users to continue working while caching progresses.

Caching Phases

The initial caching process consists of several sequential phases:

┌─────────────────────────────────────────────────────────────────────┐
│                    Initial Caching Process                          │
│                                                                      │
│  1. Static App Caching                                              │
│     └─ Service worker precaches JS, CSS, fonts, images              │
│                                                                      │
│  2. Map Tile Caching                                                │
│     └─ Vector tiles for configured region                           │
│                                                                      │
│  3. Document Caching                                                │
│     └─ Documents with offline access keys                           │
│                                                                      │
│  4. File/Attachment Caching                                         │
│     └─ Files referenced by cached documents                         │
│                                                                      │
│  5. Custom Function Caching                                         │
│     └─ Address database, custom data sources                        │
│                                                                      │
│  ═══════════════════════════════════════════════════════════════    │
│  Initial Caching Complete                                           │
│  └─ Device can now operate offline                                  │
└─────────────────────────────────────────────────────────────────────┘

Enabling Caching

User Interface

Users enable caching through the user menu:

  1. Click user icon in header
  2. Select "Enable Offline"
  3. Navigate to caching progress page

Caching Enable Template

Configure a template to show during caching:

{
    "clientConfiguration": {
        "offline": {
            "cachingEnableTemplate": [
                {
                    "documentId": "9ed4c3fb-1a59-49dc-be26-7e40e95ab194",
                    "name": "Enabling Caching"
                }
            ]
        }
    }
}

This template typically contains the sc-offline-status component to show progress.

Online Mode During Caching

Behavior

While initial caching is in progress:

  • All data reads come from the network (RestDataService)
  • All data saves go directly to the server
  • Documents are not written to IndexedDB
  • The device cannot operate offline

Implementation

The DataService checks caching status before using offline storage:

const offlineMode = this.offlineStatusService.isCachingEnabled()
    && this.offlineStatusService.isInitialCachingComplete();

if (offlineMode) {
    // Use IndexedDB
    return this.indexedDBService.getDocument(documentId);
} else {
    // Use network
    return this.restDataService.getDocument(documentId);
}

Initial Caching Completion

Definition

Initial caching is complete when all documents with offline access keys that existed at the time caching was enabled have been cached.

Cut-off Time

The system records the timestamp when caching was enabled:

// Documents are cached until serverUpdatedDate < cachingEnabledTime
const cachingEnabledTime = offlineStatusService.getCachingEnabledTime();

// Initial caching complete when no more documents
// with serverUpdatedDate < cachingEnabledTime remain

Continuous Document Streams

If documents are being saved continuously on the server:

  • Initial caching only includes documents before the cut-off time
  • Documents saved after caching was enabled are synced separately
  • This prevents initial caching from never completing

Completion Message

The "Initial Caching Complete" message displays when:

  1. All documents before cut-off time are cached
  2. All map tiles are cached
  3. All static files are cached
  4. No errors occurred during caching

Connection Loss Handling

Automatic Resume

If network connection is lost during caching:

  1. Blue notification appears: "Loaded offline data"
  2. Caching pauses automatically
  3. When connection is regained, caching resumes
  4. Progress continues from where it stopped

Configuration

Configure retry interval for network loss:

{
    "clientConfiguration": {
        "offline": {
            "cacheRetryInterval": 20000
        }
    }
}

Default retry interval is 10 seconds (10000ms).

Recovery Behavior

Phase Recovery Action
Static App Service worker handles
Map Tiles Resumes from current tile
Documents Resumes from last sync time
Files Retries failed files

Progress Tracking

Progress Indicators

The sc-offline-status component displays:

Metric Description
Documents cached Count of documents in IndexedDB
Documents to cache Total documents matching offline keys
Files cached Count of attachment files cached
Tiles cached Count of map tiles cached

Internal State

// OfflineStatusService
class OfflineStatusService {
    initialCachingComplete: boolean = false;
    cachingEnabled: boolean = false;
    cachingEnabledTime: Date;

    pageDownloadProgress: {
        pageNumber: number;
        loaded: number;
        total: number;
    };
}

Checking Caching Status

// Check if device can operate offline
if (offlineStatusService.isInitialCachingComplete()) {
    // Safe to use offline features
}

// Check caching is enabled but not complete
if (offlineStatusService.isCachingEnabled() &&
    !offlineStatusService.isInitialCachingComplete()) {
    // Still caching, use online mode
}

Refreshing During Caching

Behavior

If the user refreshes the page during caching:

  1. Caching progress is preserved
  2. Page reloads in online mode
  3. Caching resumes automatically
  4. Progress display updates

Page Navigation

Users can navigate away from the caching page:

  • Caching continues in the background
  • App operates in online mode
  • Progress is tracked in OfflineStatusService
  • User can return to see progress

Error Handling

Error Types

Error Behavior
Network timeout Retry after interval
Server error (5xx) Retry after interval
Auth failure (401) Stop caching, require re-login
Storage full Stop caching, show error

Error Recovery

try {
    await this.loadDataCache();
} catch (err) {
    // Don't mark as complete on error
    this.offlineStatusService.initialCachingComplete = false;

    // Schedule retry
    setTimeout(() => this.retryCache(), this.retryInterval);
}

Storage Space

If browser storage is insufficient:

  1. Error message displayed
  2. Caching stops
  3. User prompted to clear space
  4. Can retry after clearing

Configuration Options

Caching Page Size

Control how many documents are fetched per request:

{
    "clientConfiguration": {
        "offline": {
            "syncPageSize": 10000
        }
    }
}

Retry Interval

Time to wait before retrying after connection loss:

{
    "clientConfiguration": {
        "offline": {
            "cacheRetryInterval": 20000
        }
    }
}

Best Practices

Preparation

  1. Ensure stable network - Initial caching requires significant data transfer
  2. Allow sufficient time - Large datasets may take extended time
  3. Check storage space - Verify browser has adequate storage
  4. Stay connected - Avoid switching networks during caching

For Administrators

  1. Configure offline keys - Only mark necessary documents for offline
  2. Limit document count - Fewer documents = faster caching
  3. Use appropriate page size - Balance between speed and memory
  4. Test caching flow - Verify with representative users

Monitoring

  1. Watch progress - Ensure count increases steadily
  2. Check for errors - Monitor console for issues
  3. Verify completion - Confirm "Initial Caching Complete" appears
  4. Test offline - Verify app works when disconnected

Troubleshooting

Caching Never Completes

Causes: - Continuous document saves on server - Network interruptions - Storage space issues

Solutions: 1. Check for automated document saves 2. Verify network stability 3. Clear browser storage 4. Check cacheRetryInterval setting

"Initial Caching Complete" Shows Prematurely

Causes: - Error during caching process - Incorrect completion logic

Solutions: 1. Check console for errors 2. Verify document count matches expected 3. Clear cache and retry

Progress Resets on Refresh

Causes: - State not persisted correctly - Service worker issue

Solutions: 1. Don't refresh during caching 2. Check service worker is active 3. Verify keyValueStorage has correct state

Memory Issues During Caching

Causes: - Large document batches - Browser memory limits

Solutions: 1. Reduce syncPageSize 2. Close other tabs 3. Use supported browser version