Task Session Ecommerce / WooCommerce: end-to-end setup guide

Task Session connects your workspace to one or more WooCommerce shops. It imports orders, customers, and products, applies your field mapping and custom fields, and can push normalized JSON to your Sender API (CRM or external receiver). This guide is for administrators and implementers: activate the module, connect WooCommerce, configure outbound delivery, schedule cron, and verify the first order. Replace https://yourdomain.com/ with your real installation URL throughout.

Table of Contents

• Prerequisites
• Quick start (end-to-end checklist)
• Activate the Ecommerce module
• Where to find Ecommerce screens
• Permissions and roles
• Add a store and WooCommerce REST API keys
• Ecommerce settings (Woo API, sync rules, queue)
• Webhooks (optional, faster order updates)
• Sender API and auto-push queue
• Field mapping
• Custom fields
• Cron jobs and background processing
• Sync queue (monitor and retry)
• Daily use: orders, customers, products
• Logs, audit, and debug
• Role checklist for managers
• Technical notes
• FAQ

Prerequisites

Before you connect a live shop, ensure that:

• Your main Task Session license is active (Admin > License Activation).
• The WooCommerce addon is activated under Admin > System settings > Addons (see Addons guide).
• Your WooCommerce site is reachable over HTTPS (recommended for production).
• You can create WooCommerce REST API keys in WordPress (Read permission is enough for inbound sync; Write only if you use CRM > Woo outbound push).
• PHP has cURL and OpenSSL enabled on the Task Session server.
• Server cron can call https://yourdomain.com/cron.php on a short interval (Cron jobs).

Quick start (end-to-end checklist)

Use this sequence for a first production store:

1. Activate addon — System settings > Addons > WooCommerce / Ecommerce > Activate.
2. Enable module — System settings > Modules > Ecommerce module ON.
3. Assign permissions — Admin > Roles > grant ecommerce_access and settings keys to the right team  (Permissions).
4. Add store — Ecommerce > Settings > create store, paste Store URL + Consumer key/secret > Test connection.
5. Turn on integration — Enable WooCommerce integration, Queue mode, and the entity toggles you need (orders, customers, products).
6. Configure Sender — Sender API URL, auth, Enable sender profile, Auto push ON, set batch size > save.
7. Map fields — Ecommerce > Field Mapping (+ Custom Fields if you need Woo meta in the JSON).
8. Enable cron — Admin > Cron Management: enable Ecommerce jobs, especially Process sender queue every 1 minute, plus import/poll/queue processors.
9. Optional webhooks — Copy inbound URL from API Webhooks into WooCommerce > Settings > Advanced > Webhooks.
10. Verify — Place a test order in WooCommerce > check Orders list, Sync queue, and Logs; confirm Sender received the payload.

Activate the Ecommerce module

1. Sign in as administrator at https://yourdomain.com/admin/.
2. Open System settings > Addons and activate the WooCommerce / Ecommerce addon (same license key as your main product).
3. In System settings > Modules, turn Ecommerce module ON and save.
4. Confirm Ecommerce appears in the admin sidebar (shopping-cart icon).

If the menu does not appear, log out and back in, clear opcode cache if you use one, and confirm the user’s role has ecommerce_access.

Where to find Ecommerce screens

All paths below are relative to https://yourdomain.com/.

Area	Path	Purpose
Dashboard	ecommerce/dashboard.php	KPI cards, order status donut, queue snapshot
Orders	ecommerce/orders.php	Synced order list and filters
Order detail	ecommerce/order-view.php?id=	Order review + CRM reviews tabs
Customers	ecommerce/customers.php	Customer list
Products	ecommerce/products.php	Product catalog sync
Sync queue	ecommerce/sync-queue.php	Pending/failed jobs, Sender push queue
Settings	ecommerce/settings.php	Stores, Woo API, Sender API, sync rules
Field mapping	ecommerce/field-mapping.php	Woo source > outbound destination rules
Custom fields	ecommerce/custom-fields.php	Extra meta keys in Sender JSON
API / Webhooks	ecommerce/api-webhooks.php	Inbound webhook URL and delivery logs
Cron scheduler	ecommerce/cron-scheduler.php	Ecommerce cron overview (with system cron access)
Logs & audit	ecommerce/logs.php	Module and webhook messages
Debug	ecommerce/debugs.php	Per-store file debug log (troubleshooting only)
Woo connection debug	ecommerce/woo-connection-debug.php	REST connectivity diagnostics
Reports (Ecommerce)	admin/reports.php?ecommerce	Revenue/orders KPIs and dashboard-style charts
Cron management (system)	admin/cron.php	Enable/disable and schedule all cron jobs

Most settings sub-pages share a store selector in the header. Each store has its own URL, API keys, mapping, and Sender profile.

Permissions and roles

Configure under Admin > Roles in the Ecommerce Permissions group. At minimum:

• ecommerce_access — open the Ecommerce section
• ecommerce_settings_manage — stores, Woo API, Sender API, sync rules
• ecommerce_orders_view / ecommerce_orders_sync — browse and pull/retry orders
• ecommerce_field_mapping_manage / ecommerce_custom_fields_manage — outbound schema
• ecommerce_queue_manage — retry, hold, release queue jobs
• ecommerce_webhooks_manage — webhook logs
• ecommerce_cron_manage — Ecommerce cron scheduler (with system cron access)
• ecommerce_logs_view / ecommerce_debug_manage — audit and troubleshooting

The primary administrator account typically has full access when the module is enabled. Grant narrower keys to operations staff who only need orders or queue management.

Add a store and WooCommerce REST API keys

In Task Session

1. Go to Ecommerce > Settings (ecommerce/settings.php).
2. Under Store accounts, click to add a store and give it a label (for example Main Woo Shop).
3. Store URL — shop base URL with trailing slash, for example https://shop.example.com/ (include subdirectory if WordPress lives in a folder).
4. Consumer key and Consumer secret — from WooCommerce (steps below).
5. REST API version — leave wc/v3 unless your site requires otherwise.
6. Verify SSL — ON in production; OFF only for local XAMPP-style testing with self-signed certificates.
7. Webhook secret — a strong random string (must match WooCommerce webhook secret if you use webhooks).
8. Select the store as Active store in the header dropdown.
9. Click Test connection in the WooCommerce API section.

In WooCommerce (WordPress admin)

1. WooCommerce > Settings > Advanced > REST API (menu path may vary slightly by Woo version).
2. Add key — description e.g. Task Session Integration.
3. User — an administrator who can manage the shop.
4. Permissions — Read for import-only; Read/Write if you enable CRM > Woo outbound push.
5. Generate and copy Consumer key and Consumer secret (secret is shown once).
6. Paste into Task Session store settings and save.

Never commit API keys to source control. Revoke and regenerate keys in WooCommerce if they are exposed.

Ecommerce settings (Woo API, sync rules, queue)

On Ecommerce > Settings, work through these sections for the selected store:

WooCommerce API

• Enable WooCommerce integration — master switch for REST calls and sync.
• Test connection — validates URL, keys, and SSL.
• Manual pull buttons — Pull recent orders, customers, products (batch imports up to 50 rows per click unless you use Pull all).

Feature toggles

• Orders sync, Customers sync, Products sync — enable the entities you need.
• Webhook mode / Polling mode — webhooks for near-real-time orders; polling/cron for periodic catch-up.
• Optional: price, stock, status, notes, custom fields sync when your workflow uses two-way CRM <> Woo updates.

Sync rules

• Default sync date range (days) — how far back order/customer imports look; products use modified date (0 = entire catalog).
• Order statuses to sync — JSON array of Woo statuses (for example ["processing","completed"]).
• Duplicate prevention by Woo order ID — avoids double-importing the same Woo order.
• Queue mode — required for background processing and Sender auto-push. Keep ON for production.
• Two-way sync / Outbound push to WooCommerce — only if CRM edits must write back to Woo (separate from Sender API).

Webhooks (optional, faster order updates)

Without webhooks, orders arrive via cron import and polling. Webhooks notify Task Session when Woo creates or updates an order.

Inbound URL (Task Session)

On Ecommerce > API Webhooks (or the Woo section in Settings), copy:

https://yourdomain.com/ecommerce/ajax/tasksession-woo-webhook.php?store_id=STORE_ID

STORE_ID is the numeric store ID from Settings > Store accounts.

In WooCommerce

1. WooCommerce > Settings > Advanced > Webhooks > Add webhook.
2. Status: Active.
3. Topic: Order created (add Order updated if you need status changes).
4. Delivery URL: paste the Task Session URL including ?store_id=.
5. Secret: same value as Webhook secret on the store in Task Session.
6. API version: WP REST API Integration v3.
7. Save, place a test order, then check API Webhooks > Webhook logs (signature should show OK).

Production webhook URLs must use HTTPS. Local tunnels or HTTP-only sites often fail signature or delivery checks.

Sender API and auto-push queue

The Sender API is your outbound integration: ERP, custom CRM endpoint, middleware, or any HTTP receiver that accepts order JSON.

Configure Sender profile

On Ecommerce > Settings > Sender API:

• Enable sender profile — ON.
• Sender endpoint URL — HTTPS POST target.
• HTTP method, Authentication, API token or key, optional Custom headers.
• Timeout and Retry policy — match your receiver’s limits.

Auto-push and queue (recommended)

• Queue mode (Sync rules) must be ON.
• Auto push orders to Sender on import — enqueues a Push order to Sender API job when an order is imported from Woo.
• Send queued orders right after import — drains up to Orders per sender cron run immediately after each import batch (useful for backlogs).
• Orders per sender cron run — batch size per cron tick (use 1 if the receiver accepts one order at a time).

Enable the cron job Ecommerce: Process sender queue (cron/woo_process_sender_queue.php) at 1 minute in Admin > Cron Management. With batch size 1, roughly one order per minute is sent from the queue.

Manual actions on an order: open Order detail > CRM reviews tab > Send to Sender API or inspect the built payload with Test payload.

Field mapping

Ecommerce > Field Mapping defines how Woo data becomes your outbound JSON. Each row has:

• Entity type — order, customer, or product.
• Source field — Woo path (for example billing.email, line_items.0.sku).
• Destination field — key in the Sender payload.
• Transform rule — optional formatting (trim, date, concat, etc., per your build).
• Default value — used when source is empty.
• Required / Active — validation and enablement.

Mappings can be store-specific or global (store_id NULL). After changing mapping, re-import or wait for the next sync and verify JSON on the order’s CRM reviews tab or in Debug logs.

Custom fields

Ecommerce > Custom Fields registers extra Woo order meta or line-item meta keys to include in the Sender JSON even when they are not standard Woo columns.

• Field key — Woo meta key name.
• Destination JSON key — top-level key in Sender output (for example sales_type).
• Default value — sent when Woo meta is empty.

Custom fields work together with field mapping: mapping shapes core structure; custom fields pull additional meta into the payload.

Cron jobs and background processing

Task Session runs Ecommerce work through the central scheduler. Your server must hit:

https://yourdomain.com/cron.php

on a regular interval (for example every 1–5 minutes). Use Admin > Cron Management (admin/cron.php) to enable jobs. Ecommerce jobs are hidden when the module is off.

Job name	Script	Suggested interval	Role
Process sender queue	cron/woo_process_sender_queue.php	1 minute	POST order JSON to Sender API (auto-push)
Import new orders	cron/woo_import_orders.php	10 minutes	Pull recent Woo orders into CRM
Poll Woo updates	cron/woo_poll_updates.php	15 minutes	Detect order changes when not using webhooks
Process inbound queue	cron/woo_process_inbound_queue.php	5 minutes	Process queued Woo > CRM jobs
Process outbound queue	cron/woo_process_outbound_queue.php	5 minutes	CRM > Woo push jobs
Retry failed queue	cron/woo_retry_failed_queue.php	30 minutes	Re-queue failed sync jobs
Sync customers	cron/woo_sync_customers.php	1 hour	Customer catalog sync
Sync products	cron/woo_sync_products.php	1 hour	Product catalog sync
Health check	cron/woo_health_check.php	1 hour	Connection and module health
Clean logs	cron/woo_clean_logs.php	1 day	Trim old log rows per retention setting

Minimum production set for order > Sender flow: central cron.php running, Queue mode ON, Process sender queue enabled every 1 minute, plus at least Import new orders or webhooks for inbound data.

Sync queue (monitor and retry)

Ecommerce > Sync Queue lists background jobs. Filter by Sender push jobs to see orders waiting for the Sender endpoint.

• Waiting — cron has not picked up the job yet (check Process sender queue cron).
• Sending now — HTTP POST in progress.
• Done — Sender returned success.
• Failed — exhausted retries; fix endpoint/mapping and use Retry.

Users with ecommerce_queue_manage can retry, hold, or release jobs. Legacy demo jobs can be purged from the queue page when shown.

Daily use: orders, customers, products

Orders

ecommerce/orders.php — filter by status, date, sync state. Open a row to view detail:

• Order review — line items, totals, Woo JSON, timeline.
• CRM reviews — sync status, mapping preview, Sender payload, queue position, logs.

Customers and products

• ecommerce/customers.php and customer-view.php?id=
• ecommerce/products.php and product-view.php?id=

Store switch

Use the store dropdown in the Ecommerce header on any page. Lists, settings, mapping, and queue are scoped to the active store.

Dashboard and reports

• ecommerce/dashboard.php — KPIs and order status breakdown.
• admin/reports.php?ecommerce — revenue, orders, AOV, customers, products, queue status for reporting.

Logs, audit, and debug

• Logs & Audit (ecommerce/logs.php) — module messages, webhook deliveries, Sender results.
• Debug (ecommerce/debugs.php) — per-store file log under logs/ (not web-accessible). Enable only while investigating; disable in production.
• Woo connection debug — REST probe and environment checks.

Debug channels include Woo REST, Sender HTTP, and module database log lines.

Role checklist for managers

Goal	Permission keys
Full Ecommerce implementation	Administrator account + module/addon enabled
Connect stores and Sender API	ecommerce_access, ecommerce_settings_manage, ecommerce_api_manage
Operations: view and sync orders	ecommerce_orders_view, ecommerce_orders_sync
Manage outbound schema	ecommerce_field_mapping_manage, ecommerce_custom_fields_manage
Queue operator	ecommerce_queue_manage, ecommerce_logs_view
Webhook monitoring only	ecommerce_webhooks_manage, ecommerce_logs_view

Technical notes

• Inbound webhook handler: ecommerce/ajax/tasksession-woo-webhook.php (requires store_id query parameter).
• Business logic and queue helpers: includes/ecommerce/page-helpers.php.
• Per-store settings: vendor/woocommerce/includes/class-tasksession-woo-settings.php.
• Sender push status on orders: migration includes/migrations/4.9.sql (sender_push_status, sender_sent_at, sender_last_error).
• Ecommerce cron jobs are registered in includes/migrations/4.5.sql and filtered when the module is disabled in cron.php.
• After upgrades, run migrations, verify cron.php, and test on staging before changing production mapping.

FAQ

Why is the Ecommerce menu missing?

Activate the WooCommerce addon, enable the Ecommerce module in System settings, and grant ecommerce_access to the user’s role.

Test connection fails

Check store URL (trailing slash), consumer key/secret, REST API enabled in Woo, permalinks flushed, SSL verify setting, and firewall allowing outbound HTTPS from Task Session.

Orders list is empty

Enable orders sync and WooCommerce integration; run Import new orders cron or manual pull; confirm active store and date range; clear order filters.

Webhook signature fails

Webhook secret must match exactly on both sides; URL must include ?store_id=; use HTTPS on production.

Orders import but Sender never receives them

Enable sender profile, endpoint URL, Queue mode, Auto push, and Process sender queue cron (1 minute). Check Sync queue for failed jobs and Logs for HTTP errors.

When should I use field mapping vs custom fields?

Field mapping maps standard Woo fields and structure. Custom fields add specific Woo meta keys (account IDs, delivery notes, etc.) into the JSON by key name.

Is debug safe in production?

Keep debug OFF unless actively troubleshooting. It writes detailed API data to disk under logs/.

---

With the addon activated, store and API keys validated, Sender and mapping configured, cron enabled (especially the sender queue), and a test order verified end to end, Task Session Ecommerce provides a controlled WooCommerce > CRM > external API pipeline alongside day-to-day order operations.