From 15b8b00191e47fd85bae574d9d4ed073d0cb9b3c Mon Sep 17 00:00:00 2001 From: Davide Caruso Date: Fri, 9 Oct 2026 07:20:07 +0000 Subject: [PATCH 1/3] docs(#10280): document configurable replication intervals --- content/en/building/navigation.md | 2 +- .../building/reference/app-settings/_index.md | 21 +++++++++++++++++++ .../data/performance/replication.md | 9 ++++++++ 3 files changed, 31 insertions(+), 1 deletion(-) diff --git a/content/en/building/navigation.md b/content/en/building/navigation.md index 9ca7aff2c6..43ce36fcd7 100644 --- a/content/en/building/navigation.md +++ b/content/en/building/navigation.md @@ -71,7 +71,7 @@ Triggering a manual sync by clicking the "Sync now" button will provide feedback #### Synchronization Triggers - **On Login**: Synchronization is automatically initiated upon successful user login if the app is connected to the internet. - **Manual**: Clicking the "Sync now" button. -- **Periodic Sync**: The application performs regular checks and attempts to synchronize. The main application database syncs every 5 minutes, while the user metadata database syncs every 30 minutes.. +- **Periodic Sync**: The application performs regular checks and attempts to synchronize. The main application database syncs every five minutes by default. You can configure this interval with [`replication_interval_minutes`](/building/reference/app-settings/#replication-interval). The user metadata database syncs every 30 minutes or at the configured replication interval, whichever is longer. - **On Reload**: Synchronization is automatically initiated when the user reloads the application, refreshes the page, or clicks the reload button in the "Update available" modal. - **On Connect**: The app also detects when an internet connection becomes available and attempts to sync immediately. diff --git a/content/en/building/reference/app-settings/_index.md b/content/en/building/reference/app-settings/_index.md index 17592ac879..ef3afa5c19 100644 --- a/content/en/building/reference/app-settings/_index.md +++ b/content/en/building/reference/app-settings/_index.md @@ -54,6 +54,27 @@ The following settings do not need to be specified. They should only be defined | assetlinks | Array of [Digital Asset Links](/building/reference/app-settings/assetlinks) definitions. This is used to associate your CHT instance's domain to your Android app to verify app links. | | 4.7.0 | |sms.clear_failing_schedules | When `true`, scheduled messages that fail to be generated or sent for various reasons (e.g., empty messages, template issues, or general generation failures) are cleared from the instance's processing queue. This ensures that past messages that were unable to be sent do not perpetually remain scheduled. | false | 5.1.0 | |sms.default_to_sender | When `true`, messages without valid recipients are sent to the sender. When `false`, messages without valid recipients are not sent to the sender if they fail to resolve. They remain in scheduled state. | true | 5.1.0 | +| replication_interval_minutes | Interval in minutes for periodic replication by offline users. Accepts numbers from `5` to `1440`, including fractions. See [Replication interval](#replication-interval). | 5 | | + +### Replication interval + +Set `replication_interval_minutes` to control how often users with offline roles attempt to download data from the server. This is one setting for all offline users, regardless of role. Users with online-only roles do not use periodic replication. + +Use a number from `5` to `1440` minutes (one day), inclusive. Fractional minutes, such as `7.5`, are supported. If you omit the setting or set it to `null`, the interval is five minutes. Other values, including numbers outside the range, strings such as `"30"`, and booleans, use the five-minute default and produce a browser console warning. + +For example, add this setting to `app_settings/base_settings.json` to use a 30-minute interval: + +```json +{ + "replication_interval_minutes": 30 +} +``` + +[Compile and upload the settings](#build), then synchronize and reload each client to apply the configured interval. Until a client downloads the updated settings and reloads, it continues using its previous interval. You can use **Sync now** to download the settings without waiting for the periodic sync. + +The user metadata database syncs every 30 minutes or at the configured replication interval, whichever is longer. For example, a 60-minute interval makes both databases sync every 60 minutes. Startup sync, manual sync, and uploads after local changes still happen as before. Each upload after a local change restarts the periodic timer, so a user who saves changes more often than the interval only gets a periodic download after a full interval without changes. They still get updates on startup, after a reload, and with **Sync now**. + +See [Replication interval](/technical-overview/data/performance/replication/#replication-interval) for the tradeoffs between data freshness and server load. ## SMS Workflows diff --git a/content/en/technical-overview/data/performance/replication.md b/content/en/technical-overview/data/performance/replication.md index 034ad6c4a6..11f7df9d3b 100644 --- a/content/en/technical-overview/data/performance/replication.md +++ b/content/en/technical-overview/data/performance/replication.md @@ -6,6 +6,7 @@ description: > Settings for downloading copies of data onto a user's device keywords: relatedContent: > + building/reference/app-settings/ building/reference/app-settings/replication_depth community/contributing/code/troubleshooting/replicating-production-data-locally aliases: @@ -15,6 +16,14 @@ aliases: Replication is what we call it when users download a copy of the data on to their device. +## Replication interval + +Users with offline roles attempt to download data every five minutes by default. You can increase this interval with the [`replication_interval_minutes` app setting](/building/reference/app-settings/#replication-interval). The setting applies to all offline users and accepts numbers from `5` to `1440` minutes, including fractions. + +A shorter interval within this range gives users fresher data but increases server load. A longer interval reduces the number of periodic replication requests and can ease CPU pressure in deployments with many users. For example, a 30-minute interval schedules periodic syncs less often than the five-minute default, but users may wait longer to receive updates from other users (especially users who keep saving changes, because each local change restarts the periodic timer). Consider how quickly your workflows need those updates before increasing the interval. + +The metadata sync interval also increases when the configured interval exceeds 30 minutes. Manual sync and immediate uploads after local changes remain available. Clients use the configured interval after they download the updated settings and reload. + ## Restricting replication If the user has an online role they can access all the data, otherwise they will get restricted access to the data. From b5248355011ced16b310f1d1714bb26f829e2afa Mon Sep 17 00:00:00 2001 From: da_caruso Date: Mon, 12 Oct 2026 19:41:07 +0200 Subject: [PATCH 2/3] docs(#10280): apply review suggestions Keep the details on the replication page and only a summary row in the app settings table. The links that pointed to the removed app-settings section now point to the replication page and the Optional Settings table. Co-authored-by: Joshua Kuestersteffen <8441903+jkuester@users.noreply.github.com> Co-Authored-By: Claude Opus 5.5 --- content/en/building/navigation.md | 2 +- .../building/reference/app-settings/_index.md | 22 +------------------ .../data/performance/replication.md | 6 ++--- 3 files changed, 5 insertions(+), 25 deletions(-) diff --git a/content/en/building/navigation.md b/content/en/building/navigation.md index 43ce36fcd7..7748c35d48 100644 --- a/content/en/building/navigation.md +++ b/content/en/building/navigation.md @@ -71,7 +71,7 @@ Triggering a manual sync by clicking the "Sync now" button will provide feedback #### Synchronization Triggers - **On Login**: Synchronization is automatically initiated upon successful user login if the app is connected to the internet. - **Manual**: Clicking the "Sync now" button. -- **Periodic Sync**: The application performs regular checks and attempts to synchronize. The main application database syncs every five minutes by default. You can configure this interval with [`replication_interval_minutes`](/building/reference/app-settings/#replication-interval). The user metadata database syncs every 30 minutes or at the configured replication interval, whichever is longer. +- **Periodic Sync**: The application performs regular checks and attempts to synchronize. The main application database syncs every 5 minutes, while the user metadata database syncs every 30 minutes (configurable with [`replication_interval_minutes`](/technical-overview/data/performance/replication/#replication-interval)). - **On Reload**: Synchronization is automatically initiated when the user reloads the application, refreshes the page, or clicks the reload button in the "Update available" modal. - **On Connect**: The app also detects when an internet connection becomes available and attempts to sync immediately. diff --git a/content/en/building/reference/app-settings/_index.md b/content/en/building/reference/app-settings/_index.md index ef3afa5c19..b9dd2e1121 100644 --- a/content/en/building/reference/app-settings/_index.md +++ b/content/en/building/reference/app-settings/_index.md @@ -54,27 +54,7 @@ The following settings do not need to be specified. They should only be defined | assetlinks | Array of [Digital Asset Links](/building/reference/app-settings/assetlinks) definitions. This is used to associate your CHT instance's domain to your Android app to verify app links. | | 4.7.0 | |sms.clear_failing_schedules | When `true`, scheduled messages that fail to be generated or sent for various reasons (e.g., empty messages, template issues, or general generation failures) are cleared from the instance's processing queue. This ensures that past messages that were unable to be sent do not perpetually remain scheduled. | false | 5.1.0 | |sms.default_to_sender | When `true`, messages without valid recipients are sent to the sender. When `false`, messages without valid recipients are not sent to the sender if they fail to resolve. They remain in scheduled state. | true | 5.1.0 | -| replication_interval_minutes | Interval in minutes for periodic replication by offline users. Accepts numbers from `5` to `1440`, including fractions. See [Replication interval](#replication-interval). | 5 | | - -### Replication interval - -Set `replication_interval_minutes` to control how often users with offline roles attempt to download data from the server. This is one setting for all offline users, regardless of role. Users with online-only roles do not use periodic replication. - -Use a number from `5` to `1440` minutes (one day), inclusive. Fractional minutes, such as `7.5`, are supported. If you omit the setting or set it to `null`, the interval is five minutes. Other values, including numbers outside the range, strings such as `"30"`, and booleans, use the five-minute default and produce a browser console warning. - -For example, add this setting to `app_settings/base_settings.json` to use a 30-minute interval: - -```json -{ - "replication_interval_minutes": 30 -} -``` - -[Compile and upload the settings](#build), then synchronize and reload each client to apply the configured interval. Until a client downloads the updated settings and reloads, it continues using its previous interval. You can use **Sync now** to download the settings without waiting for the periodic sync. - -The user metadata database syncs every 30 minutes or at the configured replication interval, whichever is longer. For example, a 60-minute interval makes both databases sync every 60 minutes. Startup sync, manual sync, and uploads after local changes still happen as before. Each upload after a local change restarts the periodic timer, so a user who saves changes more often than the interval only gets a periodic download after a full interval without changes. They still get updates on startup, after a reload, and with **Sync now**. - -See [Replication interval](/technical-overview/data/performance/replication/#replication-interval) for the tradeoffs between data freshness and server load. +| replication_interval_minutes | Interval in minutes for periodic replication by offline users. Accepts numbers from `5` to `1440`. See the [replication documentation](/technical-overview/data/performance/replication/#replication-interval) for more information. | 5 | | ## SMS Workflows diff --git a/content/en/technical-overview/data/performance/replication.md b/content/en/technical-overview/data/performance/replication.md index 11f7df9d3b..73f4ffd2ec 100644 --- a/content/en/technical-overview/data/performance/replication.md +++ b/content/en/technical-overview/data/performance/replication.md @@ -18,11 +18,11 @@ Replication is what we call it when users download a copy of the data on to thei ## Replication interval -Users with offline roles attempt to download data every five minutes by default. You can increase this interval with the [`replication_interval_minutes` app setting](/building/reference/app-settings/#replication-interval). The setting applies to all offline users and accepts numbers from `5` to `1440` minutes, including fractions. +Users with offline roles attempt to download data every five minutes by default. You can increase this interval with the [`replication_interval_minutes` app setting](/building/reference/app-settings/#optional-settings). The setting applies to all offline users and accepts numbers from `5` to `1440` minutes. -A shorter interval within this range gives users fresher data but increases server load. A longer interval reduces the number of periodic replication requests and can ease CPU pressure in deployments with many users. For example, a 30-minute interval schedules periodic syncs less often than the five-minute default, but users may wait longer to receive updates from other users (especially users who keep saving changes, because each local change restarts the periodic timer). Consider how quickly your workflows need those updates before increasing the interval. +A shorter interval within this range gives users fresher data but increases server load. A longer interval reduces the number of periodic replication requests and can ease CPU pressure in deployments with many users. For example, a 30-minute interval schedules periodic syncs less often than the five-minute default, but users may wait longer to receive updates from other users. Consider how quickly your workflows need those updates before increasing the interval. -The metadata sync interval also increases when the configured interval exceeds 30 minutes. Manual sync and immediate uploads after local changes remain available. Clients use the configured interval after they download the updated settings and reload. +The metadata sync interval also increases when the configured interval exceeds 30 minutes. Manual sync and immediate uploads after local changes remain available. ## Restricting replication From e5fd8a56942c4767904877df14f7b6aeceac8dc0 Mon Sep 17 00:00:00 2001 From: Joshua Kuestersteffen Date: Thu, 15 Oct 2026 10:27:05 -0500 Subject: [PATCH 3/3] Flag 5.4.0 as the release for this feature. --- .../en/building/reference/app-settings/_index.md | 2 +- .../data/performance/replication.md | 16 ++++++++-------- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/content/en/building/reference/app-settings/_index.md b/content/en/building/reference/app-settings/_index.md index b9dd2e1121..53af546297 100644 --- a/content/en/building/reference/app-settings/_index.md +++ b/content/en/building/reference/app-settings/_index.md @@ -54,7 +54,7 @@ The following settings do not need to be specified. They should only be defined | assetlinks | Array of [Digital Asset Links](/building/reference/app-settings/assetlinks) definitions. This is used to associate your CHT instance's domain to your Android app to verify app links. | | 4.7.0 | |sms.clear_failing_schedules | When `true`, scheduled messages that fail to be generated or sent for various reasons (e.g., empty messages, template issues, or general generation failures) are cleared from the instance's processing queue. This ensures that past messages that were unable to be sent do not perpetually remain scheduled. | false | 5.1.0 | |sms.default_to_sender | When `true`, messages without valid recipients are sent to the sender. When `false`, messages without valid recipients are not sent to the sender if they fail to resolve. They remain in scheduled state. | true | 5.1.0 | -| replication_interval_minutes | Interval in minutes for periodic replication by offline users. Accepts numbers from `5` to `1440`. See the [replication documentation](/technical-overview/data/performance/replication/#replication-interval) for more information. | 5 | | +| replication_interval_minutes | Interval in minutes for periodic replication by offline users. Accepts numbers from `5` to `1440`. See the [replication documentation](/technical-overview/data/performance/replication/#replication-interval) for more information. | 5 | 5.4.0 | ## SMS Workflows diff --git a/content/en/technical-overview/data/performance/replication.md b/content/en/technical-overview/data/performance/replication.md index 73f4ffd2ec..efd04ec59b 100644 --- a/content/en/technical-overview/data/performance/replication.md +++ b/content/en/technical-overview/data/performance/replication.md @@ -16,14 +16,6 @@ aliases: Replication is what we call it when users download a copy of the data on to their device. -## Replication interval - -Users with offline roles attempt to download data every five minutes by default. You can increase this interval with the [`replication_interval_minutes` app setting](/building/reference/app-settings/#optional-settings). The setting applies to all offline users and accepts numbers from `5` to `1440` minutes. - -A shorter interval within this range gives users fresher data but increases server load. A longer interval reduces the number of periodic replication requests and can ease CPU pressure in deployments with many users. For example, a 30-minute interval schedules periodic syncs less often than the five-minute default, but users may wait longer to receive updates from other users. Consider how quickly your workflows need those updates before increasing the interval. - -The metadata sync interval also increases when the configured interval exceeds 30 minutes. Manual sync and immediate uploads after local changes remain available. - ## Restricting replication If the user has an online role they can access all the data, otherwise they will get restricted access to the data. @@ -212,3 +204,11 @@ Some reports need to be signed off by a supervisor even though that supervisor d ### Sensitive documents We won't replicate reports that are `private` and are about the user when the sender is someone the user can't access. A report is private when it has a property `doc.fields.private` with a value of `true`. For example, if a supervisor submits a private report about one of their CHPs, that CHP won't be able to see it. + +## Replication interval + +_Added in 5.4.0_ + +Users with offline roles attempt to download data every five minutes by default. You can increase this interval with the [`replication_interval_minutes` app setting](/building/reference/app-settings/#optional-settings). The setting applies to all offline users and accepts numbers from `5` to `1440` minutes. + +A shorter interval within this range gives users fresher data but increases server load. A longer interval reduces the number of periodic replication requests and can ease CPU pressure in deployments with many users. For example, a 30-minute interval schedules periodic syncs less often than the five-minute default, but users may wait longer to receive updates from other users. Consider how quickly your workflows need those updates before increasing the interval.