ORIX Actions
ORIX Actions is a small workflow engine: an input source followed by an ordered list of steps, each of which calls the same
engine functions the rest of the app uses. The model and the engine are in Packages/ORIXKit/Sources/ORIXKit/Actions/ and
have no dependency on the interface.
Model
Workflow: id, name, symbol (SF Symbol name), input, steps, presetKey (set for built-in presets, which are
read-only; duplicating one makes an editable copy).
WorkflowInput: scan, photos, files, library.
ActionStep: id, kind, and one field per parameter (filter, recognition, preset, searchable, pattern,
folderName). Each kind reads the parameters it needs.
ActionKind |
What it does | Parameters |
|---|---|---|
autoCrop |
DocumentProcessor.autoCrop: detects the page outline on image pages that have no crop |
none |
deskew |
DocumentProcessor.deskew: straightens image pages from their text baseline |
none |
enhance |
Sets the filter of every image page (shadow reduction on, except for Original) | filter |
recognizeText |
DocumentProcessor.recognize with the app's languages |
recognition mode |
rename |
Renames the document from a pattern | pattern with {title}, {date} (yyyy-MM-dd), {time} (HH.mm), {pages} |
moveToFolder |
Files the document in a folder, created if needed | folderName |
markFavorite |
Adds the document to Favourites | none |
exportPDF |
DocumentProcessor.exportPDF |
preset, searchable |
exportText |
Writes the recognized text as a .txt file |
none |
exportTables |
Writes one CSV per detected table | none |
Workflow.validationIssues reports noSteps, missingFolder (a moveToFolder step with an empty name) and
emptyPattern (a rename step with an empty pattern). The builder shows these next to the step and disables Run.
User workflows are stored as WorkflowRecord (JSON payload), so the model can evolve without a SwiftData schema migration.
Presets
Defined in Workflow.presets, with stable identifiers:
| Preset | Input | Steps |
|---|---|---|
| Scan to PDF | Scan | Enhance (Colour) → Create PDF (Balanced, no text layer) |
| Scan to Searchable PDF | Scan | Enhance (Colour) → Recognize Text (Automatic) → Create PDF (Balanced, searchable) |
| Receipt Archive | Scan | Enhance (Greyscale) → Recognize Text → Rename Receipt {date} {time} → Move to Folder "Receipts" |
| Document Cleanup | Photos | Detect Edges → Straighten → Enhance (Black & White) |
| Book Scanner | Scan | Straighten → Enhance (Greyscale) → Recognize Text (Accurate) → Create PDF (Balanced, searchable) |
| Extract Text | Photos | Detect Edges → Recognize Text → Export Text |
| Extract Tables | Photos | Detect Edges → Straighten → Recognize Text (Accurate) → Export Tables |
| Compress PDF | Files | Create PDF (Small File Size, searchable) |
Engine
flowchart TD
Start["WorkflowEngine.run(workflow, on: documentID)"] --> Valid{"validationIssues empty?"}
Valid -- no --> Throw["throw"]
Valid -- yes --> Next{"next step"}
Next --> Cancel{"task cancelled?"}
Cancel -- yes --> Cancelled["throw ORIXError.cancelled"]
Cancel -- no --> Exec["execute step<br/>progress 0…1"]
Exec -- done or nothing to do --> Record["append StepOutcome"]
Exec -- error --> Fail["outcome: failed<br/>remaining steps: skipped"]
Record --> Next
Fail --> Result
Next -- no more steps --> Result["WorkflowResult<br/>outcomes, artifacts, newTitle, folderName, markFavorite"]
- Sequential. Steps run in order on one document.
WorkflowProgresscarries the step index, the step count, the kind and the fraction inside the step;overallcombines them. - Outcomes. Every step produces a
StepOutcomewith a status (done,nothingToDowith a reason such asnoOutlineFound,alreadyStraight,alreadyRecognized,noTextFound,noTablesFound,failed,skipped), a factual detail (pages changed, lines read, file name and size, files written, new title, folder) and its duration. - Failure. A step that throws is recorded as
failed; the run stops and the remaining steps are recorded asskipped. Steps that already ran keep their effect. Because each step saves a complete manifest, the document is valid at every point. - Cancellation. The engine checks before each step and the engine functions check between pages; a cancelled run throws
ORIXError.cancelled. - Text when needed.
exportTextandexportTablescallrecognizefirst, as doesexportPDFwhensearchableis on.recognizeskips pages whose text is already up to date, so an explicit Recognize Text step earlier in the workflow is not repeated. - Library changes are returned, not applied. The engine does not touch the SwiftData index.
moveToFolderandmarkFavoritesetWorkflowResult.folderNameandmarkFavorite;renamesaves the manifest and also reportsnewTitle. The caller applies them. - Artifacts. Export steps append file URLs to
WorkflowResult.artifacts, in step order.
WorkflowEngine.resolve(pattern:title:pageCount:now:timeZone:) expands rename tokens with a fixed POSIX locale so names do
not depend on the device's language.
In the app
WorkflowLauncher.start (App/Sources/Actions/ActionsView.swift) obtains the input: the scanner (or Photos when the
device has no camera), the Photos picker, the file importer, or DocumentChooser for library documents. Capture ends in
AppModel.receive with a .workflow destination, which creates the document and sets AppModel.workflowRun.
WorkflowRunView (App/Sources/Actions/WorkflowRunView.swift) executes the run:
- one document after another for a batch (
WorkflowRun.documentIDs), waiting for any recognition already in progress on that document; - live status per step, a progress bar across the batch, and Cancel;
- after each document it applies the returned library changes through
LibraryIndexand callsAppModel.didChange; - at the end it offers the artifacts to the share sheet and, for a single document, a button to open it.
The run holds a BackgroundWork assertion so it can finish if the app is briefly sent to the background.
WorkflowEditorView is the visual builder: name, icon, input, an ordered list of step cards with their parameters, Add
Step, reordering and deletion in edit mode. Changes are saved to the WorkflowRecord as they are made.
Reuse by other ORIX apps
The engine pattern is independent of documents in three places that another app can copy: a Codable step with a kind
and flat parameters, an executor that returns per-step outcomes plus changes for the caller to apply, and validation that
lives in the model. Today ActionKind and WorkflowEngine.execute are specific to DocumentProcessor; they are not yet
generic over a step protocol. Making the engine generic is the work needed before a second app shares the code rather than
the design.