SPB Git

Repository Public License

workflows.md 7.0 KB

# 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. WorkflowProgress carries the step index, the step count, the kind and the fraction inside the step; overall combines them.
  • Outcomes. Every step produces a StepOutcome with a status (done, nothingToDo with a reason such as noOutlineFound, 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 as skipped. 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. exportText and exportTables call recognize first, as does exportPDF when searchable is on. recognize skips 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. moveToFolder and markFavorite set WorkflowResult.folderName and markFavorite; rename saves the manifest and also reports newTitle. 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 LibraryIndex and calls AppModel.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.

Files main
Menu

Theme