From 16474c885fe551596be826d540150fc5df408662 Mon Sep 17 00:00:00 2001
From: Bryan Ashby <bryan@l33t.codes>
Date: Mon, 19 Nov 2018 20:00:29 -0700
Subject: [PATCH] Initial Event Scheduler docs

---
 docs/configuration/event-scheduler.md | 79 +++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)
 create mode 100644 docs/configuration/event-scheduler.md

diff --git a/docs/configuration/event-scheduler.md b/docs/configuration/event-scheduler.md
new file mode 100644
index 00000000..77b56f15
--- /dev/null
+++ b/docs/configuration/event-scheduler.md
@@ -0,0 +1,79 @@
+---
+layout: page
+title: Event Scheduler
+---
+## Event Scheduler
+The ENiGMA½ scheduler allows system operators to configure arbitrary events that can can fire based on date and/or time, or by watching for changes in a file. Events can kick off internal handlers, custom modules, or binaries & scripts.
+
+## Scheduling Events
+To create a scheduled event, create a new configuration block in `config.hjson` under `eventScheduler.events`. 
+
+Events can have the following members:
+
+| Item | Required | Description |
+|------|----------|-------------|
+| `schedule` | :+1: | A [Later style](https://bunkat.github.io/later/parsers.html#text) parsable schedule string such as `at 4:00 am`, or `every 24 hours`. Can also be (or contain) an `@watch` clause. See **Schedules** below for details. |
+| `action` | :+1: | Action to perform when the schedule is triggered. May be an `@method` or `@execute` spec. See **Actions** below. |
+| `args` | :-1: | An array of arguments to pass along to the method or binary specified in `action`. |
+
+### Schedules
+As mentioned above, `schedule` may contain a [Later style](https://bunkat.github.io/later/parsers.html#text) parsable schedule string and/or an `@watch` clause. 
+
+`schedule` examples:
+* `every 2 hours`
+* `on the last day of the week`
+* `after 12th hour`
+
+An `@watch` clause monitors a specified file for changes and takes the following form: `@watch:<path>` where `<path>` is a fully qualified path.
+
+:information_source: If you would like to have a schedule **and** watch a file for changes, place the `@watch` clause second and seperated with the word `or`. For example: `every 24 hours or @watch:/path/to/somefile.txt`.
+
+### Actions
+Events can kick off actions by calling a method (function) provided by the system or custom module in addition to executing arbritary binaries or scripts.
+
+#### Methods
+An action with a `@method` can take the following forms:
+
+* `@method:/full/path/to/module.js:methodName`: Executes `methodName` at `/full/path/to/module.js`.
+* `@method:rel/path/to/module.js:methodName`: Executes `methodName` using the *relative* path `rel/path/to/module.js`. Paths for `@method` are relative to the ENiGMA½ installation directory.
+
+Methods are passed any supplied `args` in the order they are provided.
+
+##### Method Signature
+To create your own method, simply `export` a method with the following signature: `(args, callback)`. Methods are executed asynchronously.
+
+Example:
+```javascript
+// my_custom_mod.js
+exports.myCustomMethod = (args, cb) => {
+    console.log(`Hello, ${args[0]}!`);
+    return cb(null);
+}
+```
+
+#### Executables
+When using the `@execute` action, a binary or script can be executed. A full path or just the binary name is acceptable. If using the form without a path, the binary much be in ENiGMA½'s `PATH`.
+
+Examples:
+* `@execute:/usr/bin/foo`
+* `@execute:foo`
+
+Just like with methods, any supplied `args` will be passed along.
+
+## Example Entries
+
+Post a message to supplied networks every Monday night using the message post mod (see modding):
+```hjson
+eventScheduler: {
+    events: {
+        enigmaAdToNetworks: {
+            schedule: at 10:35 pm on Mon
+            action: @method:mods/message_post_evt/message_post_evt.js:messagePostEvent
+            args: [
+                "fsx_bot"
+                "/home/enigma-bbs/ad.asc"
+            ]
+        }
+    }
+}
+```
\ No newline at end of file