importers

Adds importers for file formats, so macros from other tools can be brought in.

Details #

An importer reads a file in some other tool's format and turns it into Switchboard macros. Your code does the parsing and returns the macros plus notes about anything it could not bring over, so the person can review the result before it is saved.

Declare it in switchboard.json under adds.importers. Every entry has an id (lowercase, digits and . _ -, up to 64 characters, starting with a letter), a title (1 to 80 characters) and an optional description. Ids must be unique within the list.

{
  "adds": {
    "importers": [
      { "id": "alfred", "title": "Alfred workflows", "formats": ["alfredworkflow"] }
    ]
  }
}

Gotchas #

A call that takes more than 60 seconds without answering fails.
The extension only sees the text. A file that is not UTF-8 text arrives as text: null.
The manifest checks the entry's shape; the handler does the work. Without a matching handler the extension doesn't load.
Unknown keys in an entry are refused.

The sample below can be downloaded from the Full example section and edited into your own.

Where it runs #

The engine runs an importer with POST /extensions/<extension id>/import/<importer id> and the body {"path": "<file>"}. A leading ~ in the path is expanded. The answer is whatever your handler returned. Importers that ship with Switchboard (Keyboard Maestro, BetterTouchTool, Alfred and others) use their own readers; this point is for formats they do not cover.

The handler #

The handler gets { path, text }. text is the file's contents as UTF-8, or null when the file is not text (a folder, a binary file). Read nothing else: the importer has no file access of its own, and does not need it.

It returns { macros, groups?, notes? }:

macros: an array of macros in Switchboard's macro format: id, name, group, enabled, when, onlyIf and do (the steps).
groups: optional groups the macros belong to.
notes: optional strings, one per thing that was skipped or approximated. Write one for every line you drop, so nothing disappears silently.