AdminConsole
Tutorials/Advanced
Advanced2 hrREST + Android

Automate a complete Workmate task lifecycle

Provision workers, dispatch jobs, consume transitions, enforce proof, and reconcile closure.

By the endAn idempotent field-service integration.
Real-world scenario

Build against an explicit contract

A utility operator must create, assign, execute, prove, review, and close work without losing responsibility during retries or offline periods.

A Mappls developer projectA restricted REST applicationFixture data with no production credentialsA request, aggregate, or correlation ID strategy
Step 1

Define the user and system contract

A utility operator must create, assign, execute, prove, review, and close work without losing responsibility during retries or offline periods. Record the region, data freshness, latency budget, privacy purpose, credential owner, and fallback before choosing an SDK or endpoint.

Step 2

Model task and provider identities

Give the internal task, provider task, assignee, policy, and idempotency command independent durable IDs.

Workmate · SDK or product slice
{
  "externalId": "JOB-2026-004219",
  "type": "equipment_inspection",
  "assigneeId": "worker_1288",
  "location": { "mapplsPin": "MMI000" },
  "window": { "startsAt": "2026-08-17T04:30:00Z", "endsAt": "2026-08-17T06:30:00Z" },
  "requiredProof": ["arrival_location", "checklist", "photo", "customer_signature"]
}
Step 3

Enforce explicit transitions

Validate actor, current version, prerequisites, and evidence for assign, accept, travel, arrive, submit proof, approve, rework, and close.

Step 4

Reconcile asynchronous outcomes

Persist an outbox command before provider calls, ingest provider callbacks idempotently, and keep ambiguous results pending until queried or replayed.

Step 5

Prove the production behavior

Automate the happy path and every named failure. The release is ready only when every transition names actor and evidence; offline replay cannot duplicate work; terminal closure retains proof and provider acknowledgement. Capture provider request identity without logging credentials or unnecessary precise location.

Recovery design

Failure modes you must exercise

assignee rejects or becomes unavailable

Fail fast with a typed, user-safe outcome and preserve the original request identity.

proof is incomplete or rejected

Keep the last verified state, mark freshness honestly, and retry only within the documented idempotency boundary.

provider timeout after accepting a command

Reconcile durable local and provider evidence before declaring success or issuing a compensating command.

Never turn uncertainty into success

Timeout after a stateful command is an unknown outcome. Query by provider/idempotency identity or wait for authoritative events; do not blindly retry a new command.

Acceptance criteria

Definition of done

every transition names actor and evidenceoffline replay cannot duplicate workterminal closure retains proof and provider acknowledgement

REST production checks

Credentials never reach a browser or mobile bundleTimeout, retry, and idempotency policies are explicitCoordinates, addresses, and identifiers have data-retention rulesEvery operation is attributable in logs and usage reporting
Grounded implementation

Continue from source, contracts, and a full app

These links resolve to repository-derived evidence; unsupported package names and endpoints are not filled in from guesswork.

Study the complete Field-service task lifecycle state machine
Tutorial complete

Run it, break it, then observe it

Start with fixture credentials, execute the failure plan, and use request logs, usage, webhook evidence, and operational metrics before promoting traffic.