[Woo POS][Local Catalog] Trigger sync periodically in the system background #16244

staskus · 2025-10-14T20:45:09Z

Description

The goal of this PR is to implement the logic of the dispatching system background tasks to make sure:

Existing order and dashboard sync is run
Incremental catalog sync is done once an hour
Full sync is done once an hour

Not in scope:

Additional criteria of running tasks, such as when the POS was last open, POS eligibility, etc...
Foreground task running

Exploration

I began my explorations by looking for a universal way of scheduling foreground and background tasks for POS Catalog (and OrderDashboard sync) with clever prioritization. I've done such a solution locally, but it felt too large and complicated with no clear benefits. Theoretically, we could have one scheduler that:

Defines tasks separately with their priorities, execution logic, and persists the ideal and last run times
Calculates priority based on last run time, failures, etc
Calculates the same next run time when switching between background and foreground
etc..

However, given BGAppRefreshTask already doesn't guarantee when and if it's going to run, the precision is not that important. Therefore, I decided to keep the existing BackgroundTaskRefreshDispatcher and implement a foreground runner to run separately, independent of BackgroundTaskRefreshDispatcher and specifically for POS Catalog. I will share that in another PR.

Solution

Merge posCatalogFullSync and posCatalogIncrementalSync tasks created in [Local Catalog] Refactor background task dispatcher to support POS catalog sync #16205 into a single posCatalogSync task that runs every hour. The motivation is that the system already doesn't guarantee if and when this is going to run. Therefore, posCatalogSync can check if a full sync is available right before running a task, otherwise, run incremental sync.
Created lightweight BackgroundTaskSchedule to implement a couple of simple methods to pick the next task based on the run period and the last schedule date. Asked AI to generate comprehensive test cases based on my scenarios.
Using BackgroundTaskSchedule within BackgroundTaskRefreshDispatcher

Steps to reproduce

Prerequisites:

Before testing, go to BackgroundTaskSchedule and make periods shorter, e.g 30 and 60 seconds
Use a real device

Launch the app with a debugger
Background it
Confirm Scheduled orderDashboardSync with time is logged
Pause the debug (CMD+^+Y)
Type lldb command e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateLaunchForTaskWithIdentifier:@"com.automattic.woocommerce.refresh"]
Continue the debug (CMD+^+Y)
Confirm you see logs of dashboard sync executed
Confirm you see log of the next task scheduled. If the time has passed so the next posCatalogSync is sooner than the next order dashboard sync, you should see Scheduled posCatalogSync
Pause the debug (CMD+^+Y)
Type lldb command e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateLaunchForTaskWithIdentifier:@"com.automattic.woocommerce.refresh.pos.catalog.sync"]
Continue the debug (CMD+^+Y)
Confirm logs show incremental or full sync done
Confirm the next task is scheduled

Testing information

Tested on iPad Air M2 device

Screenshots

Running session

testing.flow.tasks.mov

I have considered if this change warrants user-facing release notes and have added them to RELEASE-NOTES.txt if necessary.

Simplify posCatalogSync tasks by merging into one and then checking within the task whether full or incremental sync needs to be done. Since we have no guarantee when the sync runs, it's more convenient to call a refresh task every hour and then decide whether we do incremental or full.

BackgroundTaskSchedule uses a simple logic to provide the next task to schedule. - When app goes to background, sets the preferred refresh date based on the predefined periods (30 min for order sync and 60 for pos catalog sync) - Provides the next task based on the earliest time - The preferred time is only reset when app goes into background ensuring that when the app is longer in the background, eventually all tasks will get executed

… to select the next task to dispatch

wpmobilebot · 2025-10-14T20:55:19Z

📲 You can test the changes from this Pull Request in WooCommerce iOS Prototype by scanning the QR code below to install the corresponding build.

	App Name	WooCommerce iOS Prototype
	Build Number	`pr16244-571f3cf`
	Version	`23.4`
	Bundle ID	`com.automattic.alpha.woocommerce`
	Commit	`571f3cf`
	Installation URL	6a7rau9s08dbo

Automatticians: You can use our internal self-serve MC tool to give yourself access to those builds if needed.

…resh-task-dispatching

…sync

dangermattic · 2025-10-15T14:44:47Z

	1 Warning
⚠️	This PR is assigned to the milestone 23.5. This milestone is due in less than 2 days. Please make sure to get it merged by then or assign it to a milestone with a later deadline.

Generated by 🚫 Danger

iamgabrielma

LGTM! 🚀

Sorry it took me a bit longer than usual, a bunch of stuff to unpack here.

Merge posCatalogFullSync and posCatalogIncrementalSync tasks

I don't have the full context of the project for this change, but it sounds like a good idea to me for these tasks, specially when we cannot guarantee precision and is handled by the system.

Minor suggestions for the logs, just from a debugging perspective when we need them:

We should add timezone for easier debugging later on, ie to add an UTC here

🔄 Starting incremental catalog sync for site ID: 215063064, modifiedAfter: 2025-10-16 03:33:35 +0000

This one was a bit confusing regarding what's happening with variations, but unrelated to this PR:

💾 Persisting incremental catalog with 0 products and 0 variations
✅ Incremental catalog persistence complete
Total after incremental update: 86 products, 47 product images, 21 product attributes, 106 variations, 95 variation images, 258 variation attributes

When there is no updates to the local catalog (ie "Persisted 0 products and 0 variations to database for siteID xyz") perhaps we should add the reason.

iamgabrielma · 2025-10-16T03:54:19Z

Modules/Tests/YosemiteTests/Tools/POS/POSCatalogSyncCoordinatorTests.swift

+    @Test func performSmartSync_performs_full_sync_when_last_full_sync_older_than_threshold() async throws {
+        // Given - last full sync was 25 hours ago (older than 24 hour threshold)
+        let twentyFiveHoursAgo = Date().addingTimeInterval(-25 * 60 * 60)
+        try createSiteInDatabase(siteID: sampleSiteID, lastFullSyncDate: twentyFiveHoursAgo)


TIL about PersistedSite, just for context this seems to be the table that holds each site's ID and associated catalog and sync details, in GRDB?

Yes, Persisted prefix is used for GRDB entities. I'm not sure if that's great naming. We discussed that we may move all the GRDB stuff into a separate module, maybe we could ditch the prefixes.

iamgabrielma · 2025-10-16T04:01:59Z

WooCommerce/Classes/Tools/BackgroundTasks/BackgroundTaskRefreshDispatcher.swift

    ///
    func scheduleAppRefresh() {
-        scheduleTask(type: .ordersAndDashboardSync, earliestBeginDate: Date(timeIntervalSinceNow: 30 * 60))
+        BGTaskScheduler.shared.cancelAllTaskRequests()


Could "cancelling pending tasks" each time we enter in background, introduce any problem with either POS or the dashboard? ie: A long-planned task, let's say a couple of days, is never triggered since we background the app more often than that. My understanding that this is currently handled in setDefaultPreferredTaskDates(), so just raising it 👍

I don't foresee any problems. What I want to ensure is that we only end up scheduling a single thing we're intending to schedule. Right now the mechanism is made naive (setDefaultPreferredTaskDates). Maybe in the future we want to synchronize dates between both foreground and background sync, so that should be a source of truth.

staskus · 2025-10-16T07:02:52Z

Thanks for testing, @iamgabrielma!

Sorry it took me a bit longer than usual, a bunch of stuff to unpack here.

Understandable. It took me time to develop and test as well. One of the reasons I stayed with the current dispatcher class is that I know that it works. So I only integrated within it.

Merge posCatalogFullSync and posCatalogIncrementalSync tasks
I don't have the full context of the project for this change, but it sounds like a good idea to me for these tasks, specially when we cannot guarantee precision and is handled by the system.

I'll try to get feedback from @jaclync on that as well.

Minor suggestions for the logs, just from a debugging perspective when we need them:
We should add timezone for easier debugging later on, ie to add an UTC here

Good suggestion! I'll do it.

This one was a bit confusing regarding what's happening with variations, but unrelated to this PR:
💾 Persisting incremental catalog with 0 products and 0 variations
✅ Incremental catalog persistence complete

It means that there were 0 new products and 0 new variations. If you make a change in between the updates, this should reflect the number of new updates. However, I will update the logs to be clear about that.

…cific site

… only with updated products

…nated and relaunched in the background

staskus added 7 commits October 14, 2025 19:08

Move TimeProvider to WooFoundation

a2d4d6b

Integrate BackgroundTaskSchedule into BackgroundTaskRefreshDispatcher…

dc026a8

… to select the next task to dispatch

Added various BackgroundTaskScheduleTests to verify various scenarios

9a363ce

Cancel previous tasks before scheduling new ones

c3aae83

Only schedule ordersAndDashboardSync if feature flag is disabled

7abfa86

staskus added this to the 23.5 milestone Oct 14, 2025

staskus requested review from iamgabrielma and jaclync October 14, 2025 20:45

staskus added type: task An internally driven task. feature: POS labels Oct 14, 2025

iamgabrielma self-assigned this Oct 15, 2025

staskus added 2 commits October 15, 2025 17:18

Merge branch 'trunk' into woomob-1095-woo-poslocal-catalog-bg-app-ref…

4dd41e5

…resh-task-dispatching

Create a performSmartSync method that decides on incremental or full …

b442512

…sync

Update POSCatalogSyncCoordinator.swift

b603561

staskus mentioned this pull request Oct 15, 2025

[Woo POS][Local Catalog] Add a periodic sync when the app is in the foreground #16246

Merged

1 task

iamgabrielma approved these changes Oct 16, 2025

View reviewed changes

staskus added 7 commits October 16, 2025 11:01

Improve catalog persistence logs to show number of products for a spe…

1ce075c

…cific site

Update catalog logs to be clear that incremental catalog is persisted…

6abb109

… only with updated products

Update POSCatalogIncrementalSyncService logs for clarity

fe57312

Add UTC suffix to smart sync logs for clarity

ee7506d

Fix a typo in a BackgroundTaskSchedule comment

a58294f

Only cancel the tasks that BackgroundTaskRefreshDispatcher handles

14fd3ad

Persist preferredTaskDate to avoid any issues with the app gets termi…

571f3cf

…nated and relaunched in the background

staskus merged commit f5bca54 into trunk Oct 16, 2025
13 checks passed

staskus deleted the woomob-1095-woo-poslocal-catalog-bg-app-refresh-task-dispatching branch October 16, 2025 10:35

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[Woo POS][Local Catalog] Trigger sync periodically in the system background #16244

[Woo POS][Local Catalog] Trigger sync periodically in the system background #16244

Uh oh!

staskus commented Oct 14, 2025

Uh oh!

wpmobilebot commented Oct 14, 2025 •

edited

Loading

Uh oh!

dangermattic commented Oct 15, 2025

Uh oh!

iamgabrielma left a comment

Uh oh!

iamgabrielma Oct 16, 2025

Uh oh!

staskus Oct 16, 2025

Uh oh!

iamgabrielma Oct 16, 2025

Uh oh!

staskus Oct 16, 2025

Uh oh!

staskus commented Oct 16, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

[Woo POS][Local Catalog] Trigger sync periodically in the system background #16244

[Woo POS][Local Catalog] Trigger sync periodically in the system background #16244

Uh oh!

Conversation

staskus commented Oct 14, 2025

Description

Exploration

Solution

Steps to reproduce

Testing information

Screenshots

Uh oh!

wpmobilebot commented Oct 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dangermattic commented Oct 15, 2025

Uh oh!

iamgabrielma left a comment

Choose a reason for hiding this comment

Uh oh!

iamgabrielma Oct 16, 2025

Choose a reason for hiding this comment

Uh oh!

staskus Oct 16, 2025

Choose a reason for hiding this comment

Uh oh!

iamgabrielma Oct 16, 2025

Choose a reason for hiding this comment

Uh oh!

staskus Oct 16, 2025

Choose a reason for hiding this comment

Uh oh!

staskus commented Oct 16, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

wpmobilebot commented Oct 14, 2025 •

edited

Loading