HephaestusOban.JobMetadata (hephaestus_oban v0.5.0)

Builds Oban job meta and tags from workflow module attributes.

Every Oban job created by HephaestusOban is enriched with metadata that enables filtering in Oban Web. This module centralizes that logic so all workers produce consistent metadata.

Auto-populated fields

Meta key	Source	Example
`heph_workflow`	Last segment of workflow module, snake_cased	`"onboard_flow"`
`instance_id`	Workflow execution UUID	`"CBD700A6-..."`
`workflow_version`	Workflow module's `__version__/0`	`1`
`step`	Last segment of step module, snake_cased (when applicable)	`"validate_user"`

Custom tags and metadata defined via use Hephaestus.Workflow are merged in. System keys (heph_workflow, instance_id, workflow_version, step) always take precedence over custom metadata to prevent accidental overwrites.

Name conversion

Module names are shortened using Module.split/1 |> List.last/1 |> Macro.underscore/1, matching the context_key_for/1 convention in the core. For example:

MyApp.Workflows.OnboardFlow → "onboard_flow"
MyApp.Steps.ValidateUser → "validate_user"

Summary

Functions

build(workflow_module, instance_id, opts \\ [])

Builds a keyword list of Oban job options (meta and tags) for the given workflow module and instance.

resolve_workflow(workflow_string)

Converts a workflow module string (from job args) back to the module atom.

Functions

build(workflow_module, instance_id, opts \\ [])

@spec build(module(), String.t(), keyword()) :: [meta: map(), tags: [String.t()]]

Builds a keyword list of Oban job options (meta and tags) for the given workflow module and instance.

Options

:step_ref — the step module (atom) or stringified module name. When provided, a "step" key is added to meta with the snake_cased short name.
:runtime_metadata — a map of dynamic metadata accumulated from step executions. Merged after workflow metadata but before system keys.

Examples

iex> HephaestusOban.JobMetadata.build(MyApp.Workflows.OnboardFlow, "abc-123")
[meta: %{"heph_workflow" => "onboard_flow", "instance_id" => "abc-123", "workflow_version" => 1}, tags: ["onboard_flow"]]

iex> HephaestusOban.JobMetadata.build(MyApp.Workflows.OnboardFlow, "abc-123", step_ref: MyApp.Steps.ValidateUser)
[meta: %{"heph_workflow" => "onboard_flow", "instance_id" => "abc-123", "step" => "validate_user", "workflow_version" => 1}, tags: ["onboard_flow"]]

resolve_workflow(workflow_string)

@spec resolve_workflow(String.t()) :: module()

Converts a workflow module string (from job args) back to the module atom.

Uses String.to_existing_atom/1 — safe because workflow modules are always compiled and loaded before any job referencing them can execute.