ACTION_ID: delay_step
NAME: Delay
CATEGORY: Data Operations
CREDITS: 0

Pause a row for a fixed duration before continuing to the next action.
Use it when a downstream action depends on time-sensitive state from
an upstream action (e.g. waiting for a CRM search index to catch up
after a record is created).

INDEX:
  1. Inputs
  2. Outputs
  3. How to configure
  4. Key notes
  5. Where it fits in a workflow
  6. When to use
  7. When not to use

================================================================================
1. INPUTS
================================================================================

time (string, required) — Timer
  How long the row waits before continuing to the next action.
  String-encoded whole number of seconds. The PATCH endpoint
  rejects raw numbers ("received an unsupported value type") — pass
  the value quoted.
    "60"      1 minute
    "300"     5 minutes
    "3600"    1 hour
    "86400"   1 day

  Note on the field name: this field is `time` on the API, not
  `timer`. The UI labels it "Timer" but the underlying PATCH input
  is `time`. Sending `{"timer": "60"}` returns an `unknown_field`
  warning and the value is silently dropped — the action stores no
  timer and the row passes through immediately.

================================================================================
2. OUTPUTS
================================================================================

(no output fields — the row passes through unchanged once the delay
elapses.)

================================================================================
3. HOW TO CONFIGURE
================================================================================

Configure Action body:

{
  "inputs": {
    "time": "60"
  }
}

Field-by-field:
  - time    Wait duration in seconds before the row advances.
            String-encoded — pass `"60"`, not `60`. See Section 1
            on the field-name vs UI-label discrepancy.

================================================================================
4. KEY NOTES
================================================================================

- The row pauses at this step; other rows are independent and continue
  through the chain in parallel.
- Use delays only where downstream genuinely depends on time-sensitive
  external state (indexing, engagement, rate limits). Adding a delay
  "just in case" only slows the workflow.
- Cell state during the wait is opaque. While the delay is running,
  polling the row returns `{"status": "queued"}` on the delay cell
  with no time-remaining, scheduled-completion-at, or progress
  fields. The `row_status` stays `"running"`. The cell flips
  directly to `{"status": "complete"}` once the timer elapses.
  Don't build downstream logic that expects to read a remaining-time
  signal from the cell — there isn't one.

================================================================================
5. WHERE IT FITS IN A WORKFLOW
================================================================================

UPSTREAM — events that need a settle window before the next action
  CRM event triggers (most common):
    a HubSpot webhook firing on contact / company / deal create
    triggers a Floqer workflow. The event arrives before the source
    system's search index has fully caught up, so an immediate
    lookup against the new record can return stale or empty data.

THIS ACTION
  Pauses the current row for `time` seconds, then advances it to the
  next action. Each row pauses independently when it reaches this
  step — one slow row does not block others.

DOWNSTREAM — actions that need the upstream event to have settled
  hubspot_lookup_object, salesforce_lookup_record, list filters that
  depend on the new record, conditional branches on values that take
  time to populate.

================================================================================
6. WHEN TO USE
================================================================================

Use delay_step when a downstream action depends on time-sensitive
state from a CRM event — most often, when a CRM webhook triggers a
Floqer workflow but the new record isn't fully indexed yet on the
CRM side.

  HubSpot trigger -> downstream lookup
    The most common case. HubSpot fires a webhook (e.g. "contact
    created") that triggers the Floqer workflow. By the time the
    workflow runs, the contact exists in HubSpot, but HubSpot's
    Search API has an indexing lag — new records typically appear
    in search results within 5-10 seconds (HubSpot targets <5s), and
    bulk operations or peak load can push that to several minutes.
    If the next step calls hubspot_lookup_object, an associated
    lookup, or a list filter that depends on the new record, insert
    delay_step between the trigger and the lookup. Recommended
    values:
      - 60    (1 min)   — typical, single-record trigger
      - 300   (5 min)   — safer when reliability matters
      - 1800  (30 min)  — bulk operations or peak load

  Salesforce / other CRMs with search-index lag
    Same pattern. A CRM-side create or update fires the workflow,
    and the workflow's first lookup needs the index to catch up.

  Floqer-initiated HubSpot create -> lookup
    Same indexing lag, but the create happens inside the workflow
    via hubspot_create_object / hubspot_upsert_object. Insert
    delay_step between the create and any downstream search-based
    lookup.

================================================================================
7. WHEN NOT TO USE
================================================================================

Skip delay_step when:

  Downstream is purely computational
    LLM calls, formatters, in-workflow data transformations, and
    other actions that don't reach back to an external system don't
    need anything to "settle." A delay only slows the row.

  The data needed downstream is already in the upstream response
    If the previous action's response synchronously returns the
    fields the next step uses, no delay is required. Delay is only
    needed when the next action goes back to the source via a
    search / lookup / list filter that depends on indexing.

================================================================================

This file is maintained manually. Last updated: 2026-05-14.
Full interactive reference: https://floqer.com/docs/reference
Action catalog: https://floqer.com/docs/action-catalog.txt