How to get started with OmniOutliner Automation?

The thing I am missing about automation is ‘how to get started’.

There needs to be some basic tutorials in an obvious place.

(And, no Is good - but it doesn’t cut it… the first line ‘familiarity with javascript’… what it needs is an ‘okay, so you know no JavaScript… let’s talk you through how this can work and we’ll show you the minimum as we need it… but understand that to get good, a broader knowledge of JavaScript will be needed’


@SGIII, I got intrigued about your request and solved this problem. Your comments were listened :-)

Out of my house, now. When I get back, will post the solution.

@unlocked2412 Thank you so much! Look forward very much to seeing your solution! I once again have a glimmer of hope.

@murkee I feel your pain in getting started with Omni Automation! I’ve been able to make some modest progress by studying posts here by @draft8 and @unlocked2412 as well as @Sal (both here and in the Slack channel, and of course on his automation website to which you link). @draft8 has listed somewhere (I can’t find it immediately) helpful sources for learning JavaScript. If I recall correctly, one was the first part of a book called Eloquent JavaScript.

It’s one thing, though, to gain a basic understanding of JavaScript and quite another to relate that to what I understand is called “functional” programming style, with “currying” and all that, often with generic functions, and to interfacing with a specific API. In some cases I’ve ended up just installing useful plug-ins posted here, hoping someday I will understand exactly how they do what they do.

Examples by @sal on the automation website can sometimes be easier to parse and follow, but some seem to use dated JavaScript syntax, worrisome for an unsure beginner trying to avoid pitfalls by following current best practices.

The cross-platform automation can be immediately useful, quickly adding features not baked into the apps, offering flexibility that competitors can’t offer. But it’s hard, and needs a healthy forum to support it. For learning this kind of thing, old school telephone and email support only––no matter how diligent––just doesn’t cut it, at least not for me. Perhaps I already said that before:)

Thanks for those links, they’ll be handy for when time is on my side.

I’ve got a bit of a hacker toolkit, a bit of python, a bit of scripting etc - just no JS.

What’d work for me, I think, is a series of examples explained step by step and built up… including things like

  1. How to automate a new task of a specific type (e.g. add an item to a shopping list with a due date of +2d
  2. Automating a list given some parameters (i.e. ask user for due date, use that, have items in the list with relative dates calculated from user input, modify some text in the titles of task with user input) - e.g. a packing list
  3. Modifying existing tasks, e.g. push a project back a week, or, if a project is due on wednesday, push back 5 days, and if due on Monday push back 2 days (e.g. for a project that could come due on Mondays or Wednesdays to coincide with a meeting)
  4. Only modifying items in a list that are incomplete
  5. Triggering a script

Really well written tutorials that do the above could guide someone from scratch, and show what they needed - and link to places for more info.

Saying ‘learn JavaScript here’ and then you can do it, is just such a huge barrier to entry… saying ‘let’s build up some common scripts, explain it, link to more info and here’s some tweaks you could make’ is a much nicer starter (even if there is still a world to explore).

1 Like

I responded to @ohoh on the issue of timestamped entries, although not with an Omni Automation solution. Not sure why that one didn’t appear in my forum updates email, or maybe I missed it.

The Problem

Philosophically, the problem I have with Omni Automation is that if people had the time / skills / inclination to write their own solutions, they wouldn’t need to buy apps. And Omni Automation does, necessarily, require one to get into programming in a large way. It’s a solution that is cost-effective to the vendor because it relies on existing constructs and supporting libraries, but not so much for the customer, creating high friction leading to low adoption and a bajillion questions. To repeat a funny analogy I read in another forum, “It’s like trying to buy a fur coat and being handed a bow and arrow.”

A Counter-example

The positively brilliant thing about tinderbox is that it exposes object-oriented concepts of the infrastructure, through the application. And by providing a simple scripting language (programming in a “small” way) things can be done with this tool (that on the surface looks like an outliner) to do amazing things. Some things I’ve done with it:

  • A regular expression teaching tool that renders the expression as a live graph representing the Deterministic Finite Automaton, and visually showing activity as a string is pumped through it. The automaton can be updated live, while it is working.
  • A graph reachability analysis that allows one to interactively represent a graph, with the nodes automatically updating to depict which nodes they can still reach (meaning it found a route to those nodes) which is very useful in the building of a semantic network and asking questions such as “How is X related to Y?”

I could go on. The graph reachability analysis was only about 5-10 lines of code. How does Tinderbox accomplish this? By the use of a simplistic scripting language that relies on the capabilities baked into the system, including the easy-to-understand notion that every note is an object. Therefore if I tell a note, “Keep a list of your outbound links, and the outbound links of those notes too,” the reachability data self-assembles.

Tinderbox was never designed to do these things. The creator would call it a “Spatial Hypertext tool.” But it is a testament to the design that things as far afield as the above examples can be done with ease, and the user is only limited by a failure of imagination.

Why am I explaining this?

Tinderbox strikes a balance. In essence it says, “If you want to do something fancy, you have to be able to express it,” and then does all the heavy lifting. In the end, something like Javascript is more capable and broadly capable, but it’s a bow and arrow. You have to do the heavy lifting.



The website is in the process of incremental updating to a new more accessible format. During that process, many examples are being re-written, using more recent JavaScript constructs and techniques, and the many new Omni Automation features (like Fetch.API, Credentials, and Preferences) are being documented for the first time.

Currently, the OmniFocus, OmniPlan, Shared Classes, and Script-URL sections have been renovated, and the Plug-Ins section is in process. OmniOutliner and Omnigraffle are scheduled after that.

In addition, it is a goal to have corresponding tutorial material for each app. Feedback regarding the OmniFocus Scripting Tutorial would be very helpful in determining the design for the other topics.

Thank you for your interest in Omni Automation and for being a contributing member of the automation community. Cheers – SAL


I agree. I find many aspects of the Omni forums really impossible to follow. I couldn’t figure out which version I needed to see the Automation menu. The OmniJS_Automation webpages (or documentation) are bizarrely styled and not scalable unless I hack the CSS with Chrome, which is ridiculous. More fundamentally, I don’t see why import-export is still such an impossible task. There are ways to do it, and make some decisions about trees and structure. But exporting to Excel yields blank documents. RTF breaks multi-columns badly so it’s unusable. Formatting on exported Word docs are awful/unusable. Trying Pandocs on the OPML exports yields bizarre Markdown. I can’t get anything out of OO without writing it myself. I regret all the time I put into putting my research notes into OO, but I am stuck with having to write my own exports in some Frankenstein version of AppleScript and their own OmniJS.

@nutellacrepe Curious which parts of the forums you found hard to follow (other than, of course, the OO threads that just end without being answered).

It used to be clearer, I think, that Pro was needed for scripting/automation. I see that isn’t stated on the Mac App Store. You can find it somewhat deep in The Omni Group site here.

The site by @Sal is distinctively styled. But on my machines I find it really easy to increase/decrease the font size by command +/- and pinch out/in on the iPad. The problem I have is not the formatting but the gotcha assumptions. For example, I understand much of the automation is via “plug-ins” and many plug-ins are “bundles.” I know generally what a bundle is (a specialized folder) and have looked inside them at times. But, not being a developer, I don’t know how to create one. Or why one might use a bundle rather than a “solitary action” file. Or how to convert a bundle plug-in to a single file plug-in. It’s just assumed the user will know how to do all this.

I’ve found many decent ways to get content out of OO. No blank documents here when exporting to Excel, etc. The data comes over just fine. Some or all formatting is lost in many cases, but that’s common with many apps. If you’re having trouble with specific documents I would think that is a situation where contacting support by email is the way to go.

I complained several times to get the year added to posts. Some threads are old and “14” could have been the year or the month-day. It’s still not easy to parse at a glance.

I search the forums for “OmniOutliner” in quotes and get other apps’ threads, although OO is mentioned in the sidebar or footer, etc.

Here is how the styling looks for me – I make my browser window as large as feasible and try zoom in/out the text. It’s pretty bad either way.

The instructions relying on the Automation Menu apply to a 5.3.x version of Pro, not my 5.1.x version. It took me a while to figure that out. I just had to guess as I couldn’t find a straight answer in the docs.

It seems there is not a base way to get started. I understand that people post snippets, but it’s not clear when it’s pasted in the console, or in a text file -> plug-ins.

After I updated I got the Automation Menu, but when I followed instructions for the Plug-Ins folder, it launched the one test plug-in every time I simply clicked on the Automation Menu, adding rows and columns to the test document.

Reading the docs, I’m also supposed to see some navigation to specify which plug-ins I want, but for me, clicking Plug-Ins just opens the folder in the Finder. I tried to figure this out for an hour and couldn’t find anything in the docs or a search of the Internet.

Re: Export: toy examples of 1 row export okay, but I don’t want to iteratively increase my docs to see which row/column is annoying the exporter. I think -it should tell me-.

“Paste with original style” for me only gives the typeface, not the color or justification or many other aspects I consider to be part of “text styling”.

The examples I see of OmniJS are often for single-column to-do lists. My documents are much bigger and have more columns, but not so much so that they ought to export so poorly.

There are a lot of things I like about OO, but I am looking forward to writing something to export all my hundreds of docs into another format that is more versatile. I am trying the Zettelkaesten approach so I write more documents rather than keep collecting research notes, and am finding all the OO docs I’ve written are totally incompatible and not exportable without a whole lot of custom work by me. Shouldn’t be left up to individual users, but it seems it is.

Greetings! I’m in the process fo updating the Omni Automation website to consolidate all the materials about plug-ins into one section. Here is the link to the section (in progress):

Generally, single-file plug-ins (also called simple plug-ins) are the best way to add functionality. Bundle plug-in are used for those situation where a plug-in might carry assisting resources like images, files, etc. Single-file plug-ins are easy to create and implement.

Also, there are single-file plug-in generators for each of the Omni apps that can instantly create the plug-in shells with just a click:

Hope this helps!

P.S. Hope to have the updated plug-in section done this week!

1 Like

Greetings! Thank you for your feedback. Sorry you’re having difficulty viewing some of the webpages. The section you’re viewing is one of the first sections created, but as I stated earlier in this thread, the entire website is being updated to a more accessible-friendly design. OmniOutliner is one of my favorite apps and I‘m looking forward to updating it as well.


Thanks! The single-file plug-ins (sometimes called “solitary action” plug-ins… I think) perhaps deserve the top billing. I think the site originally started with a description of bundle plug-ins, which I found immediately somewhat intimidating as I’m reasonably comfortable with simple scripting, but have no “real” coding or development experience. (I assume people like me can be an important part of the target user base for automation.)

Starting the section with single-file plug-ins will help. Once I saw how much simpler that was I was able to do a little “monkey-see-monkey-do” and get one of my own to work, learning a lot in the process. But it would also help to know (generally) how to convert bundle plug-ins to single-file plug-ins. People like @unlocked2412 who really know what they are doing are comfortable with bundle plug-ins, as in this thread. I’ve made it a project for myself to convert that to a single-file plug-in, but just don’t know enough without being pointed in the right direction. The site could help with that.

You’re doing great! Single-file plug-ins are so much easier to create, especially for those new to the whole scripting thing. Using some of the examples and templates helps to understand the basic concepts. Like you mentioned, single-file pug-ins should be covered first! In the updated plug-on section, single-file plug-ins are covered first and all of the related plug-in topics are close at hand as well.

I look forward to seeing the tools and plug-ins you create!

One-Click Templates:
New Plug-In section (in progress):

UPDATE: The Plug-Ins section has been updated and posted:

1 Like

@regexp :)

1 Like

This post was flagged by the community and is temporarily hidden.