org-notify.js

Archived Node.js
On branch current
Latest: ???/cur
Running: c7c7ba0 (v1.1.2)
??? commits behind

Notifies you about Org tasks.

Supported notification method

Currently the only supported notification method is to chat you via Hubot, but the design is such that it is trivial to plug in alternate methods.

:Notify:

Add a property of Notify (case insensitive) to get notifications for a task.

Scheduling notifications

The notify property should have a comma-separated list of when to send the notification. For example 1d,30m will send a notification one day (24 hours) before the task is due and then again 30 minutes before it is due. If you have a negative number it will send an overdue notification. For example, -1d will send a notification after the task has been overdue for one day. You can use d, h, m, and s.

You can also use a string like 08:00 or 08:00 (use 24 hour time). The notification for the task will go out at that time on the day it is due or scheduled.

You can add day offsets to the time strings: 08:00+1d will send a notification at eight in the morning the day before the task is due. The same applies for overdue tasks: 08:00-1d will send an overdue notification the day after at eight in the morning. You can chain these together: 08:00-1d-2d+1d+4d.

You can append an r to make the notifications repeat. For example, 1dr or 08:00-1dr. The first will send a notification every day before the task is due at the same time of the task's due date and the second will send an overdue notification at eight in the morning every day after the due date. 08:00r means 08:00+1dr,08:00,08:00-1dr (send a notification at eight every morning).

You use a > or < in conjunction with r. For example, 1dr<10 will send a notification every day once the task is due in ten days. 1dr>10 will send a notification every day until the task is due in ten days. You don't have to use it with r, but it's pointless otherwise. (This functionality is still in the works.)

Task formatting

Leading asterisks and task state will be stripped before sending the notification.

Change which timestamps are used

You can add a ; and one or more of the letters below to change which timestamps are used to generate the notification. This is only useful if you have multiple timestamps on your task.

Not including any is the same as including them all.

  • [p]lain
  • [s]cheduled
  • [d]eadline

For example: :Notify: 1d;d.

"All-day" tasks

If a task is scheduled for a day but not a specific time, 00:00 (midnight) is assumed as the time.

No date

If a task has no date you will not be notified.

Task States

If you use more than just "TODO" and "DONE", you'll need to add #+SEQ_TODO: to each file. Read this for more information.

Eventually you will also be able to set a global list of keywords in config.json.

:Notify_Title:

If you include a :Notify_Title: property (case insensitive), then that content will be used in place of the task title.

Humanizing (Not implemented yet)

Before sending the notification, it will be "humanized" by prepending text like "Good morning. You have an appointment today." You can edit the humanizing phrases in phrases.config.

You can set time periods for what phrases should be used. Within those objects, you can set phrases for each task state. If there is no matching property for the state (case insensitive), "default" is used. They should be in order because the first matching one will be used. Within a set of phrases, a random one will be chosen.

If you use d (days) and above (week, month, year), it will ignore the time portion of the due date. In other words, <24h and <1d are not the same thing. For example, if it is currently eight in the morning and you get a notification for a task due tomorrow at ten in the morning (26 hours away), <24h will not trigger but <1d will. Essentially this lets you use words like "today" and "tomorrow" in the phrases without ever being wrong.

Examples

See examples/tasks.org for some examples.

Install

org-notify.js is meant to be used on an always-on Linux server. Dependencies are nodejs and sqlite3 (mongodb support is planned).

For Arch Linux, see my arch-org-notify.js package. I haven't bothered with the AUR because I don't expect this to gain any kind of popularity.

Otherwise, you just need to run bin/cli.js in whatever way is appropriate for your operating system, put config.json and phrases.json somewhere, and pass in the config path with --config. See org-notify.js.service in the examples folder for an example.

Whichever way you do it, you'll also want to edit config.json and copy notify.coffee to your Hubot scripts folder (assuming you'll be using Hubot).