Configuration Reference

Overview

This document provides a comprehensive reference for all configuration options related to Formbird's offline functionality.

Client Configuration

Client configuration is stored in the clientConfiguration section of the configuration document and sent to the browser.

Complete Configuration Example

{
  "clientConfiguration": {
    "maxUploadSize": "12MB",
    "unsyncedRecordCheckTime": 5000,
    "offline": {
      "syncher": "rust",
      "dexieAddons": [
        {
          "fileName": "https://cdn.formbird.com/components/dexie-addon/v1-0-3/dexie-elasticsearch-addon.js",
          "exportName": "ElasticIndexedDBAddon"
        }
      ],
      "searchTimeout": 90000,
      "syncPageSize": 10000,
      "android": {
        "enableSharedWorkers": false
      }
    },
    "offlineSearchOptions": {
      "geohashPrecision": {
        "boundingBox": 8
      },
      "indexedDBIndexesPriority": [
        "*parentRel____documentId",
        "*localeRel____documentId",
        "*localeRel____name",
        "status",
        "startDate",
        "*shiftRel____documentId",
        "siteType",
        "*actionRel____documentId",
        "*siteRel____name",
        "*siteRel____documentId",
        "*accountTypeRel____documentId",
        "*customerRel____documentId"
        "systemHeader.systemType",
        "systemHeader.summaryName",
        "systemHeader.summaryDescription",
        "name",
        "systemHeader.versionId",
        "documentId",
        "systemHeader.templateId",
        "*appTags",
        "status"
      ]
    },
    "cachingEnableTemplate": [
      {
        "documentId": "9ed4c3fb-1a59-49dc-be26-7e40e95ab194",
        "name": "Enabling Caching"
      }
    ],
    "cachingNotAllowed": false
  }
}

Offline Object

Offline Search Options

Note: Both indexedDBIndexesPriority and offlineIndex.indexedDBIndexes are case-sensitive. Ensure the field names match exactly.

Note: If indexedDBIndexesPriority is not set, the default priority is the order of indexes in the offlineIndex.indexedDBIndexes array.

Note: The following common system fields should always be placed at the end of indexedDBIndexesPriority as they are present on every template and do not help optimize offline querying: - systemHeader.templateId - *appTags - systemHeader.systemType - systemHeader.currentVersion

Important: The offlineIndex.indexedDBIndexes array and clientConfiguration.offlineSearchOptions.indexedDBIndexesPriority should contain the same keys. Both configurations define which fields are indexed for offline queries, and they must be kept in sync to ensure consistent behavior.

Top-Level Configuration

OpenLayers Configuration (Optional)

The openLayers object configures map functionality including tile servers and offline map caching.

{
  "clientConfiguration": {
    "openLayers": {
      "googleMapsKey": "your-google-maps-api-key",
      "tile": {
        "road": {
          "minResolution": 0.5
        }
      },
      "tileServer": {
        "crossOrigin": null,
        "url": "https://osm.formbird.com/tiles/{z}/{x}/{y}.png"
      },
      "useCurrentLocation": false,
      "mapViewsToCache": [
        {
          "name": "Vicmaps Colour",
          "styleLocationUrls": [
            "https://vicmap.land.vic.gov.au/hosting/rest/services/Hosted/Vicmap_Vector_Tile_Basemap_Colour_WM_Hosted/VectorTileServer/resources/styles/root.json"
          ],
          "minZoom": 1,
          "maxZoom": 15,
          "dataBounds": [
            {
              "topLeftCoord": [144.173, -37.209],
              "bottomRightCoord": [144.965, -37.959]
            }
          ],
          "url": "https://vicmap.land.vic.gov.au/hosting/rest/services/Hosted/Vicmap_Vector_Tile_Basemap_Colour_WM_Hosted/VectorTileServer/tile/{z}/{y}/{x}.pbf"
        }
      ]
    }
  }
}

OpenLayers Properties

Map Views to Cache Properties

The mapViewsToCache array defines which map views should be cached for offline use.

Account Group Configuration (Deprecated)

Deprecated: The accountGroupConfig document (identified by systemHeader.systemType: accountGroupConfig) has been deprecated and is no longer required for offline functionality. The settings previously configured here have been moved to other locations:

Old Location	New Location
accountGroupConfig.indexedDBIndexes	offlineIndex document (see offlineIndex Document)
accountGroupConfig.tileServerGLCacheBounds	clientConfiguration.openLayers.mapViewsToCache (see OpenLayers Configuration)

The properties below are documented for reference but should be migrated to the new locations.

Map Tile Caching (Deprecated)

Deprecated: Use clientConfiguration.openLayers.mapViewsToCache instead.

{
    "tileServerGLCacheBounds": [147.24710, -42.90330, 147.32692, -42.80992],
    "tileServerGLCacheZoomLevels": [10, 11, 12, 13, 14, 15, 16]
}

OpenLayers Configuration (Deprecated)

Deprecated: Use clientConfiguration.openLayers instead.

{
    "openLayers": {
        "tileServerGL": true,
        "tileServerURL": "https://vmap.formbird.com"
    }
}

Document Configuration

Offline Keys

Documents are marked for offline access using keyIds in the systemHeader:

{
    "systemHeader": {
        "keyIds": ["your-offline-uuid-key"]
    }
}

Template Attach Keys

Templates can automatically attach offline keys to new documents:

{
    "attachKeys": ["your-offline-uuid-key"]
}

offlineIndex Document (Required)

The offlineIndex document is required for offline functionality. It must exist in order to store documents in IndexedDB. It defines the indexes used for offline queries in IndexedDB.

Note: If indexedDBIndexesPriority is not set in clientConfiguration, the order of indexes in this indexedDBIndexes array becomes the default priority order.

{
    "documentId": "9425d82f-b25f-4dba-a370-d2b7c7fc289f",
    "indexedDBIndexes": [
        "systemHeader.versionId",
        "documentId",
        "systemHeader.summaryName",
        "systemHeader.summaryDescription",
        "name",
        "*parentRel____documentId",
        "*localeRel____documentId",
        "*localeRel____name",
        "status",
        "startDate",
        "*shiftRel____documentId",
        "siteType",
        "*actionRel____documentId",
        "*orderRel____documentId",
        "*truckRel____documentId",
        "*primaryVehicleRel____documentId",
        "*primaryVehicleRel____name",
        "*secondaryVehicleRel____documentId",
        "*secondaryVehicleRel____name",
        "*siteRel____name",
        "*siteRel____documentId",
        "*accountTypeRel____documentId",
        "*customerRel____documentId",
        "systemHeader.templateId",
        "*appTags",
        "systemHeader.systemType",
        "systemHeader.currentVersion"
    ],
    "appTags": [
        "offline",
        "system"
    ],
    "systemHeader": {
        "systemType": "offlineIndex",
        "summaryName": "Offline Index",
        "keyIds": ["your-offline-key-here", "read-key-for-user"]
    }
}

Note: The last four indexes (systemHeader.templateId, *appTags, systemHeader.systemType, systemHeader.currentVersion) are present on every template and should always be placed at the end of the array as they do not help optimize offline querying.

Important: The indexedDBIndexes array in this document and clientConfiguration.offlineSearchOptions.indexedDBIndexesPriority should contain the same keys. Both configurations must be kept in sync to ensure consistent offline query behavior.

Index Naming Conventions:

How Array Subfield Indexing Works:

For a document with a relationship array like:

{
  "siteRel": [
    { "documentId": "abc-123", "name": "Site A" },
    { "documentId": "def-456", "name": "Site B" }
  ]
}

The index "*siteRel____documentId" works in two steps:

1. ____ (four underscores) - During indexing, extracts the documentId property from each object in siteRel and creates a new property on the stored document: json "siteRel____documentId": ["abc-123", "def-456"]

2. * (asterisk prefix) - Tells IndexedDB to flatten the array and store an index entry for each value, enabling queries to match any individual value in the array

Example of stored document after indexing:

siteRel: [{documentId: "abc-123", name: "Site A"}, {documentId: "def-456", name: "Site B"}]
siteRel____documentId: ["abc-123", "def-456"]
siteRel____name: ["Site A", "Site B"]

This enables efficient querying like "find all documents where siteRel contains documentId abc-123".

Note on Arrays Without * Prefix:

You can index an array field without the * prefix (e.g., "appTags" instead of "*appTags"), but this stores the entire array as a single index key rather than indexing each value individually. This is less useful for most cases, but could be handy if you need to match the exact array. However, if you want to query for individual items within an array, you must use the * prefix to ensure each array value is indexed separately.

Best Practices: 1. Place documentId as a high priority value (returns small result sizes) 2. Order by the power of each term to minimize query result size, not by query frequency. Even a less frequently queried term that returns only one document should be a higher priority than a frequently queried term that returns hundreds of documents. 3. Include fields used in search queries, filters, or sorting 4. Place common system fields last (systemHeader.templateId, *appTags, systemHeader.systemType, systemHeader.currentVersion) as they return large result sets 5. Keep offlineIndex.indexedDBIndexes and indexedDBIndexesPriority in sync

User Account Configuration

Access Keys with Offline Rights

Configure offline access in user account documents:

{
    "accessKeys": [
        {
            "keyId": "your-offline-uuid-key",
            "rights": ["Create", "Update", "Read", "Offline"]
        }
    ]
}

Component Configuration

sc-datatables Offline Query

Configure datatables to use offline queries:

{
    "componentName": "sc-datatables",
    "searchOptions": {
        "searchOfflineOnly": true
    }
}

sc-street-address Offline Maps

Enable cached maps in address components:

{
    "componentName": "sc-street-address",
    "tileServerGL": true
}

Vendor Libraries

Configure vendor libraries for offline caching:

{
    "documentId": "e2bdbe4f-4acb-43d6-9511-f002496a6160",
    "name": "d3",
    "fileName": "https://cdn.jsdelivr.net/npm/d3@3.5.6/d3.min.js",
    "systemHeader": {
        "systemType": "vendorLibrary",
        "keyIds": ["your-offline-uuid-key"]
    }
}

Checking Configuration Status

From Rulesets

// Check if caching is enabled
const cachingEnabled = ntf.context.isCachingEnabled();

// Check if device is online (note: may change mid-operation)
const isOnline = ntf.context.isOnline();

From Browser Console

// Check caching status
localStorage.getItem('userConfig');

// Check IndexedDB version
indexedDB.open('formbird').onsuccess = (e) => console.log(e.target.result.version);

Configuration Checklist

Before enabling offline for users, ensure:

1. Offline keys created - UUIDs for marking documents
2. Documents have keys - Templates and documents have keyIds
3. User accounts configured - accessKeys include "Offline" right
4. offlineIndex document created (required) - Custom indexes defined for offline queries
5. Map caching configured (optional) - clientConfiguration.openLayers.mapViewsToCache configured with appropriate bounds and zoom levels
6. Vendor libraries configured (if needed) - Libraries have offline keys

Related Documentation

• 100-Formbird-Offline-Mode.md - Setup guide
• 101-Offline-Architecture.md - System architecture
• 102-IndexedDB-and-Dexie.md - Index configuration details
• JayRules: Setting Rules for Offline Processing - Extra ruleset fields to control when rules run offline