Background workers

Use Background Workers to understand which hosted worker processes exist in the current Actualog application process, how they start, and where their real controls live.

This page is both a summary and the control surface for process-level startup gates. It does not replace owner pages such as Billing workers, Search Indexes, Feed Management, Sitemap management, AI Services, or Connectors. Use it when you want one place to answer: "Which background processes can run in this environment, and who controls them?"

What a worker is

A worker is a hosted background service that starts with the web application and runs outside a user request.

User actions should usually return quickly. Long-running or recurring work is moved into workers so the UI does not wait for it. For example, Actualog uses workers to collect billing invoices, process queued media operations, rebuild Help Knowledge, refresh Lucene indexes, generate sitemaps, send notifications, and poll external marketplaces.

A worker is not necessarily doing heavy work all the time. Many workers spend most of their time idle, waiting for a timer, a wake signal, or a queued job.

Why workers exist

Workers protect the application from slow or unreliable operations:

• A browser request can queue work and return immediately.
• The worker can process that work with retries and leases.
• Scheduled maintenance can run without a user keeping a page open.
• External systems can be polled on a controlled cadence.
• Expensive startup checks can be delayed, disabled, or moved to an owner panel.

Without workers, operations such as product synchronization, media bulk actions, sitemap generation, invoice collection, and AI processing would either block the UI or be lost when a request ends.

Why Actualog has multiple workers

Actualog uses separate semantic workers because background jobs do not all have the same operational behavior.

Reference Collection import, Product mass update, Document preview, Data export, and AI image generation all look like "queue processing" from the outside. Internally they have different inputs, retries, leases, resource usage, diagnostics, and business consequences. Document preview uses file rendering and storage. Product mass update changes product data. Reference import reads and normalizes uploaded reference data. Data export also performs quota reservation cleanup. AI image generation depends on AI runtime settings and Azure OpenAI image configuration.

A single universal worker would make diagnostics harder and could let one heavy or broken job type block unrelated work. Actualog instead uses a shared worker framework with separate semantic workers. That keeps common lifecycle behavior consistent while preserving clear ownership and troubleshooting.

Runtime models

The Runtime model column explains how the worker lives.

Queue loop does not mean request-time only

This is the most common point of confusion.

When a feature says "generation is queued" or "the job runs on demand", that usually means the work item is created on demand. It does not mean the worker process is created only when the user clicks a button.

In Actualog, most queue workers are hosted loops:

1. The application starts.
2. The worker waits for its coordinated startup slot.
3. The worker enters an idle loop.
4. When a user or service queues work, the worker claims one item and processes it.
5. If there is no work, the worker sleeps and checks later.

Idle queue loops still use a small amount of process memory and wake occasionally. They should not do expensive database work while idle. Actualog uses coordinated startup slots and longer idle delays to keep local development restarts and request testing stable.

Status means effective ability to run

The Status column shows the effective runtime state that controls whether the worker is allowed to execute work.

For owner-managed workers, the status is read from the owner panel. For example, Billing rows read the master billing runtime switch and the individual Billing worker toggles. If Billing workers disables Invoice collector, the summary should show Invoice collector as Disabled.

For startup-gated workers, the status comes from the background worker startup profile and any persisted SettingsStore override.

For application-lifetime queue loops, Runs with app means the loop is registered and available while the app runs. It does not claim that a job is currently executing, and it does not show queue depth.

Start and stop controls

The Control column tells you where execution is controlled.

The owner page link is where an administrator should look for domain-specific context. It may manage credentials, schedules, queue actions, diagnostics, or business settings.

Startup profile and startup gates

A startup gate is a process-level guard. It decides whether an optional worker may take a coordinated startup slot and enter its loop.

Startup gates are useful in Development because local testing often needs the web UI, controllers, and database behavior, not every optional maintenance or integration loop.

When a startup-gated worker is disabled:

• it remains registered as part of the application process;
• it waits before taking a startup slot;
• it does not enter its normal polling or maintenance loop until enabled;
• disabling an already running loop may require an application restart for a clean stop.

The startup profile is environment-scoped. In Development, InteractiveDevelopment is intended to keep local restarts lighter. Full is production-like.

Editable rows can follow the profile or override it:

• Profile default uses the selected profile. In InteractiveDevelopment, optional maintenance workers and safe Development queue loops default to disabled.
• Force enabled lets that worker run even when the profile would disable it.
• Force disabled keeps that worker parked before its startup slot even when the profile would enable it.

For example, you can keep Document preview worker disabled during ordinary local UI testing, then force it enabled when you specifically test document upload or preview behavior.

Development queue controls

Some queue workers are safe to disable in Development because queued work can wait until the worker is enabled again. These include document preview, media bulk operations, product mass update, product synchronization, reference imports, data export, user avatar generation, and Help Knowledge builds.

When one of these workers is disabled, queued items are not deleted. They remain pending until the worker is enabled and the application is restarted or the running loop observes the new gate. For clean local startup behavior, restart the Development application after changing startup controls.

Other queue loops remain application-lifetime because disabling them changes core application behavior. Mail sender, notifications, messenger, action logs, Lucene indexing, and the worker services orchestrator are visible in the summary, but they are not ordinary Development toggles.

Billing workers

Billing workers are scheduled polling loops. They are not controlled from the Background Workers page.

Use Billing workers for:

• Invoice collector;
• Stripe payout reconciler;
• Revenue recognizer;
• Cancel watcher.

The summary reads the same billing runtime settings. A row is Enabled only when the billing master runtime is enabled and that individual billing worker is enabled.

Marketplace workers

The Marketplace operation processor polls Microsoft Marketplace operations when marketplace credentials are configured.

Its current start/stop control is the Background Workers startup profile, not a toggle on Connectors. The Connectors page owns connector catalog and credential context, but it does not currently expose a runtime switch for the marketplace polling loop.

In Development, use the lighter startup profile to keep this worker disabled unless marketplace polling is part of the test. In production-like environments, keep it enabled only when Microsoft Marketplace integration is configured and operationally owned.

Lucene workers

Lucene has more than one worker because search has more than one background concern:

• Lucene indexer is a queue loop that processes index refresh requests after products, categories, users, companies, or other searchable data changes.
• Lucene index health checker is a startup or manual health check controlled from Search Indexes.
• Lucene optimizer is a maintenance loop that compacts Lucene index segments.

These are related to the same search infrastructure, but they are not the same job. Refreshing stale search data, checking whether an index is healthy, and optimizing index segments have different operational purposes.

Good Development workflow

For ordinary local UI or controller testing:

1. Keep the application in the Development environment.
2. Use the lighter worker startup profile when you do not need optional maintenance or integration loops.
3. Open Background Workers to confirm which loops are enabled.
4. Use owner pages only for the domain you are testing.
5. Re-enable the relevant owner setting or use a production-like profile when a test requires that worker.

For example, if you are testing billing automation, use Billing workers. If you are testing sitemap generation, use Sitemap management. If you are testing marketplace integration, make sure the marketplace startup gate and connector credentials are intentionally configured.

Troubleshooting

The summary shows a worker, but I did not click anything

That is normal. Hosted workers are registered when the application starts. Queue-backed work is on demand, but the loop that waits for queued work may already be running or idle.

Billing says disabled, but the summary says enabled

The summary should read the real Billing worker settings. If the owner page disables billing and the summary still shows an enabled Billing row after refresh, treat that as a defect in the summary state mapping.

A queue worker is enabled while there is no work

Enabled means the worker loop is allowed to claim work. It does not mean a job is currently running.

A worker says Runs with app

The worker is an application-lifetime loop without a Background Workers toggle. It may still be idle most of the time. It starts and stops with the web application process.

I want to stop all optional local workers

Use the InteractiveDevelopment startup profile, then force-enable only the workers needed for the test. Use owner pages for domain-owned workers such as Billing, Feed, AI Services, Search Indexes, and Sitemap.

I need to disable marketplace polling

Use the background worker startup profile or environment configuration for the Marketplace operation processor. The Connectors page currently does not provide a marketplace worker toggle.

Related pages

• Billing workers
• Search Indexes
• Feed Management
• Sitemap management
• Connectors
• Help Knowledge