Resume a process from an outside system

Let a process in Picked wait until something happens outside it: a carrier picks up, your ERP approves a credit check, a pallet arrives at the dock. Your system sends a signal, and the waiting work carries on.

When to use this

Use this recipe when a step in your warehouse depends on a system Picked doesn't run. It takes two halves: a wait in the process, and a call from your system.

You need a token with the process-events:write ability (see Authentication).

Build the wait

In the process builder, open the step that should wait:

1. Set its input to Wait.

2. Under What ends the wait, choose A signal from outside.

3. Fill in a Signal name, such as pallet-landed. Your system sends this name. Use up to 255 letters, digits, ., _, : and -, and make it specific: every process waiting on the name hears it.

4. Optional: Only continue when, a condition that picks out the work the signal is about. The signal's fields are available as event_… and the work's own values by name, so event_order_id == order_id only wakes the work for that order. Nested fields are read as event['line']['sku'].

5. Optional: Give up after (minutes). If the signal doesn't come in time, the step continues with the outcome timed_out, and you can branch on it. Without it, the work waits until the signal comes or someone ends the wait.

6. Optional: Outputs that take fields from the signal's payload, so later steps can show and use them as {{ steps.<step>.<name> }}. Each names the Field in the payload (dock, line.sku) and may have a Default. A signal that lacks a field without a default, or has one of another type, doesn't wake the step, the same as one that misses its condition. See Use the answer in later steps.

Once Give up after has passed, the step belongs to the clock: a signal that arrives later wakes nothing, and the work takes timed_out.

Publish the process. Work that reaches the step now goes to sleep there.

Send the signal

POST /api/v1/process-events/{eventKey} with the signal name in the path. The optional payload is any JSON object, up to 100 top-level keys and 64 KB. The condition is checked against it, and the work it wakes can read it.

curl -X POST "https://picked.nl/api/v1/process-events/pallet-landed" \
  -H "Authorization: Bearer $PICKED_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": { "dock": "D3", "sscc": "387123450000012345", "order_id": 48211 }
  }'

HTTP/1.1 200 OK
Content-Type: application/json

{
  "event_key": "pallet-landed",
  "woken_task_batch_ids": [5512],
  "woken_count": 1,
  "deferred_task_batch_ids": [],
  "deferred_count": 0
}

Read the answer

The answer is always 200, whatever the signal woke:

• woken_task_batch_ids: the work that carries on now.
• Nothing woken: no work was waiting on this name, or the condition didn't match. That isn't an error. The work may not have reached the step yet, or a signal before this one already woke it. Don't retry.
• deferred_task_batch_ids: work that matched but can't carry on yet, for want of stock or capacity. Send the same signal again later. Nothing else retries it, so without your retry the signal is lost for that work.

A signal isn't recognised as a repeat: each call is a new delivery. See Idempotency.

Errors to handle

Errors lists every code, and Rate limits what to do on a 429.

Testing

Signals can't be dry-run: a Picked-Dry-Run: true header answers 400 here and nothing is done. Test with a process of your own instead: give its wait a signal name nothing else uses, let a piece of work reach the wait, send the signal and check that woken_count is 1.