# `JoobQ.Workflows`
[🔗](https://github.com/azutoolkit/joobqui/tree/master/sdks/elixir/blob/main/lib/joobq/workflows.ex#L2)

Workflow runs from a producer (JoobQ Pro): the joobq-pro engine conducts every run of a registered blueprint; these
calls start a run and talk to it. Each answers `{:ok, answer}` or `{:error, %JoobQ.Error{}}` (`:pro_required`
without a licence, a 404 `:gateway` error for an unknown run) and takes `:name`, the instance, in `opts`.
Calls are sent once: a `:transport` error MAY mean the gateway acted (give `start/3` an `:id` to make a start
safe to send again).

  * `start/3` (`JoobQ.start_workflow/3`): starts a run of the newest blueprint of `name` with `input`; options
    `:id` (the run's id; a start with a known id answers that run, `"created" => false`), `:context` (a map the
    run's steps read), `:search_attributes` (a map), `:build` (the worker build to pin the run to).
  * `signal/4` (`JoobQ.signal_workflow/4`): sends the signal `name` with `payload` to the run `id`.
  * `update/4` (`JoobQ.update_workflow/4`): sends the update `name` with `input`; options `:update_id` (1 to 64
    letters, digits, `_` and `-`; a reused id answers the first outcome) and `:wait_ms` (100 to 30 000: how long
    to wait for the outcome; it is `"accepted"` past it). An update name is 1 to 200 of the same characters.
  * `query/3` (`JoobQ.query_workflow/3`): answers the blueprint's query `name`, resolved by the server.
  * `describe/2`, `result/2` (option `:wait_ms`, 0 to 25 000: wait for the run, followed through
    continue-as-new, to close; `"closed" => false` when the wait ended first) and `history/2` (options
    `:after_seq`, 0 to 10 000 000, and `:limit`, 1 to 200, the gateway's most; answers the list of events): reads of
    the run, payloads masked by the gateway. A call that waits may take its wait and 5 s more, beyond
    `:request_timeout`.
  * `upsert_attributes/2` (`JoobQ.upsert_workflow_attributes/2`): options `:set` (a map) and `:remove` (a list
    of names) of the run's search attributes, at most 64 of each, names of 1 to 200 characters.

# `describe`

```elixir
@spec describe(String.t(), keyword()) :: {:ok, map()} | {:error, JoobQ.Error.t()}
```

The run `id` (`GET /sdk/workflows/:id`).

# `history`

```elixir
@spec history(String.t(), keyword()) :: {:ok, [map()]} | {:error, JoobQ.Error.t()}
```

The events of the run `id`, oldest first (`GET /sdk/workflows/:id/history`): `{:ok, [event]}`.

# `path`

```elixir
@spec path(String.t(), String.t()) :: String.t()
```

The path of the run `id`, with `suffix`. A run id is 1 to 200 letters, digits, `_` and `-` (the engine's id
pattern): it can never be a dot segment or leave its path segment.

# `query`

```elixir
@spec query(String.t(), String.t(), keyword()) ::
  {:ok, term()} | {:error, JoobQ.Error.t()}
```

The answer of the query `query` of the run `id` (`POST /sdk/workflows/:id/query`): `{:ok, result}`.

# `result`

```elixir
@spec result(String.t(), keyword()) :: {:ok, map()} | {:error, JoobQ.Error.t()}
```

The run `id` once closed, or after `:wait_ms` (`GET /sdk/workflows/:id/result`).

# `signal`

```elixir
@spec signal(String.t(), String.t(), term(), keyword()) ::
  {:ok, map()} | {:error, JoobQ.Error.t()}
```

Sends the signal `signal` with `payload` to the run `id` (`POST /sdk/workflows/:id/signal`).

# `start`

```elixir
@spec start(String.t(), term(), keyword()) :: {:ok, map()} | {:error, JoobQ.Error.t()}
```

Starts a run of the workflow `name` (`POST /sdk/workflows`): `{:ok, %{"id", "created", "status"}}`.

# `update`

```elixir
@spec update(String.t(), String.t(), term(), keyword()) ::
  {:ok, map()} | {:error, JoobQ.Error.t()}
```

Sends the update `update` with `input` to the run `id` (`POST /sdk/workflows/:id/updates`).

# `upsert_attributes`

```elixir
@spec upsert_attributes(String.t(), keyword()) ::
  {:ok, map()} | {:error, JoobQ.Error.t()}
```

Sets and removes search attributes of the run `id` (`POST /sdk/workflows/:id/search-attributes`).

---

*Consult [api-reference.md](api-reference.md) for complete listing*
