Workiz Push Service

The Workiz Push service is for teams that author records in CleanEstimate Pro but still need selected records to land in Workiz for franchise reporting. It runs on the same server as the app and drives a persistent Workiz browser session from a local queue.

Use Push to Workiz on an estimate detail page when a record is ready to send. CE Pro queues the request on the server, and the local Workiz service processes one queue row at a time.

What It Pushes

The service can queue:

• estimates
• jobs
• invoices

The estimate detail page is the first live UI entry point. Job and invoice queue endpoints are available for later UI wiring.

When a push succeeds, CE Pro stores the returned Workiz id back on the source row and records the push timestamp. Re-pushing the same record uses that saved Workiz id so the service can update the existing Workiz record once the live selectors are configured.

How It Runs

The service is a private local daemon:

• It listens on 127.0.0.1:4567.
• Browser/client-side React never calls that localhost service directly.
• CE Pro server routes enqueue rows from the app server.
• The queue table is workiz_push_queue.
• The older workiz_sync_queue remains separate for legacy Workiz API retry/import behavior.

First Login

Run the first login in a headed browser so the Workiz session can be saved:

WORKIZ_PUSH_HEADLESS=false npm run workiz-push -- --login-only

Sign in to Workiz manually, including any two-factor challenge. The session is saved in .workiz-profile/, which is intentionally not committed.

Normal daemon runs use:

npm run workiz-push

On Linux, install the Playwright browser runtime before running the daemon:

npx playwright install chromium
npx playwright install-deps chromium

Queue Status

Each queue row moves through:

• pending
• in_progress
• done
• failed

Repeated clicks on the same active record reuse the existing pending or in-progress row instead of creating duplicates.

Inspect queue rows directly in Supabase when troubleshooting. A failed row includes last_error, attempts, leased_at, and leased_by.

Failures

Selector or page-state mismatches fail loudly. The service does not guess missing Workiz selectors and does not continue with partial data.

Failure artifacts are stored on the server:

• logs: logs/workiz-push.log
• screenshots: logs/screenshots/
• browser profile: .workiz-profile/

If Workiz redirects to the login page during a push, the queue row fails with session_expired, a screenshot is saved when possible, and the daemon exits. Run the headed login bootstrap again before restarting normal service mode.

Manual Requeue

Failed rows are not retried automatically. To requeue after fixing the cause, update the row back to pending and clear last_error:

update workiz_push_queue
set status = 'pending',
    last_error = null,
    leased_at = null,
    leased_by = null
where id = '<queue-id>';