TaskNotes Workflows

by callumalpass
5
4
3
2
1
Score: 41/100

Description

Markdown-defined workflow automation for TaskNotes

Reviews

No reviews yet.

Stats

22
stars
5,867
downloads
3
forks
103
days
2
days
9
days
10
total PRs
0
open PRs
2
closed PRs
8
merged PRs
16
total issues
9
open issues
7
closed issues
31
commits

Latest Version

9 days ago

Changelog

Changed

  • Updated the expression engine to obsidian-bases-expression 0.3.0-rc.5 and the expression editor to obsidian-bases-expression-builder 0.2.0-rc.3. Expressions no longer overflow the stack if they read a value that refers back to itself (obsidian-bases-expression #7). Thanks to @konstantinopolka for reporting this.

README file from

Github

TaskNotes Workflows

TaskNotes Workflows is an optional companion plugin for TaskNotes. It lets you automate TaskNotes workflows with editable Markdown files in your vault.

Use it for things like:

  • starting or stopping time tracking when task status changes
  • clearing scheduled dates when work starts
  • rolling overdue scheduled tasks forward
  • raising priority as due dates approach
  • copying parent task metadata into subtasks
  • getting a reminder when blocked tasks need review

Requirements

  • Obsidian 1.8.7 or newer
  • TaskNotes installed and enabled
  • mdbase-sync is optional for local TaskNotes-only workflows and required for cross-application contract events and contract actions

Install

Download main.js, manifest.json, and styles.css from the latest release, place them in .obsidian/plugins/tasknotes-workflows/, then enable TaskNotes Workflows in Obsidian's Community plugins settings.

Getting Started

Workflow notes live in TaskNotes/Workflows/. Each workflow is a normal Markdown file: the frontmatter defines the automation, and the body explains what it does.

The plugin creates starter workflows disabled by default, so they are safe to inspect before use. Open TaskNotes/Views/workflows.base to review, edit, dry-run, and enable them.

Useful commands:

  • Open workflows
  • New workflow
  • Reload workflows
  • Maintain default workflow files
  • Migrate workflow files to the mdbase runtime format
  • Run: <workflow name> for enabled workflows that include a manual trigger

Automatic execution is controlled by Run workflows on this device, a device-local setting that defaults on for desktop and off for mobile. Manual runs remain available when it is off. Keep automatic execution enabled on one device for a synced vault.

Run idempotency reservations persist for seven days; cron/interval downtime coalesces into one firing. Concurrency supports skip, queue, replace, and allow. This client does not provide distributed leases, a transactional event journal, or interrupted-run replay; see the schema and execution limits.

In an mdbase 0.3 collection, new/migrated notes use its configured explicit type key (including TaskNotes v5's mdbase_type). If the runtime type is missing or older than pack 0.2.1, whose type first accepts keys other than type, the plugin suggests installing the mdbase runtime standard pack.

Included Workflows

The default set includes disabled examples for time tracking, status-triggered date cleanup, started timestamps, overdue review, scheduled-date rollover, due-date priority escalation, blocked-task review, folder movement, subtask inheritance, dependency inheritance, and parent-to-subtask mirroring.

Enable only the workflows that match your vault. Most templates are meant to be adjusted first, especially if you use custom status or priority names.

Example

---
type: runtime_workflow
id: auto-start-time-tracking
version: 1.0.0
name: Auto-start time tracking
enabled: true

triggers:
  - id: status-active
    event:
      id: task.status.changed
      version: 1.0.0
    x-tasknotes:
      type: tasknotes.event
    if:
      $expr: 'event.data.after.status == "active"'

steps:
  - id: start-time
    action:
      id: time.start
      version: 1.0.0
    input:
      task:
        $expr: event.data.after.path

run:
  concurrency:
    group:
      $expr: workflow.id
    policy: skip
  limits:
    max_items: 25
  on_error: stop
x-tasknotes:
  format_version: 2
  source: tasknotes-workflows
---

Cross-application triggers always name an event contract and a compatible version. The optional source narrows which application may publish it:

triggers:
  - id: canvas-drop
    event:
      id: canvas.drop
      version: ^1.0.0
    x-tasknotes:
      type: contract.event
      source: canvas-bases

New files and editor saves validate against the canonical mdbase runtime runtime_workflow schema from Runtime profile 0.2. Files created by TaskNotes Workflows 0.1.x continue to run through the compatibility reader. The migration command shows a per-file diff, checks for changes after analysis, and creates a backup before rewriting legacy frontmatter; it never runs automatically during plugin startup. It also converts format v1 expressions to CEL. Unsupported conversions disable the workflow and explain the required manual work.

Contract Events And Actions

The mdbase interoperability profile lets workflows connect applications without giving one application ownership of another's types. A trigger selects an event contract and compatible version range; a step selects an action contract and may pin a provider application:

triggers:
  - id: task-completed
    event:
      id: tasknotes.task.completed
      version: ^1.0.0
    x-tasknotes:
      type: contract.event

steps:
  - id: add-card
    action:
      id: canvas.card.create
      version: ^1.0.0
    provider:
      application: canvas-bases
    input:
      canvas_path: TaskNotes/Canvases/Completed tasks.canvas
      card:
        kind: file
        file:
          $expr: event.data.task_path

The included Add completed tasks to a canvas workflow demonstrates this flow and is disabled by default. Enable Allow plugin integrations in mdbase settings before enabling it.

Contract events use CloudEvents and are multicast. Action execution requires exactly one compatible provider. Run details preserve contract, provider, request, attempt, and outcome evidence. Compatibility never acts as authorization; the mdbase host grant remains default-deny.

Editing Workflows

Use the workflow Base as the primary UI. Workflow cards open a modal editor for definition fields, triggers, steps, and run policy. The modal renders typed fields from the step catalog, including TaskNotes catalog-backed status and priority options, a visual builder for canonical TaskNotes runtime task queries, and selected Obsidian file, workspace, and frontmatter actions.

The Markdown note remains the source of truth. Use the card's note action when direct YAML editing is useful.

Workflows execute in this client using Runtime 0.2 records and CEL expressions. CEL workflows open their YAML note for editing; v1 workflows keep the original visual editor and Bases evaluator until migrated. Plain strings are literals in CEL workflows. Run history keeps its existing interface and stores runtime run/action-attempt evidence.

See Workflow Schema and AI Agent Authoring Script for the full format.

Development

npm install
npm run build:test
npm run test:testbed
obsidian vault=test plugin:reload id=tasknotes-workflows

npm run build:test copies main.js, manifest.json, and styles.css to the local test vault by default. npm run test:testbed runs the real workflow action provider through the spec-owned black-box provider lifecycle scenario, including valid invocation, invalid-input rejection, and unload.