enigma-bbs/configuration/event-scheduler.html

2413 lines
24 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html lang="en-US">
<head>
<meta charset='utf-8'>
<meta http-equiv="X-UA-Compatible" content="chrome=1">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="icon" type="image/png" sizes="16x16" href="/enigma-bbs/assets/images/favicon-16x16.png">
<link rel="icon" type="image/png" sizes="32x32" href="/enigma-bbs/assets/images/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="32x32" href="/enigma-bbs/assets/images/favicon-32x32.png">
<link rel="stylesheet" href="/enigma-bbs/assets/css/style.css?v=">
<!-- Begin Jekyll SEO tag v2.7.1 -->
<title>Event Scheduler | ENiGMA½ BBS Software</title>
<meta name="generator" content="Jekyll v4.2.1" />
<meta property="og:title" content="Event Scheduler" />
<meta property="og:locale" content="en_US" />
<meta name="description" content="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 &amp; scripts." />
<meta property="og:description" content="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 &amp; scripts." />
<meta property="og:site_name" content="ENiGMA½ BBS Software" />
<meta property="og:type" content="article" />
<meta property="article:published_time" content="2023-03-31T18:15:35+00:00" />
<meta name="twitter:card" content="summary" />
<meta property="twitter:title" content="Event Scheduler" />
<script type="application/ld+json">
{"publisher":{"@type":"Organization","logo":{"@type":"ImageObject","url":"/enigma-bbs/assets/images/enigma-logo.png"}},"description":"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 &amp; scripts.","url":"/enigma-bbs/configuration/event-scheduler.html","@type":"BlogPosting","headline":"Event Scheduler","dateModified":"2023-03-31T18:15:35+00:00","datePublished":"2023-03-31T18:15:35+00:00","mainEntityOfPage":{"@type":"WebPage","@id":"/enigma-bbs/configuration/event-scheduler.html"},"@context":"https://schema.org"}</script>
<!-- End Jekyll SEO tag -->
</head>
<body>
<div id="container">
<div class="sidebar" id="sidebar">
<hr class="mobile-divide">
<div class="container">
<a href="/enigma-bbs/"><img src="/enigma-bbs/assets/images/enigma-logo.png" class="logo" alt="Enigma logo"></a>
</div>
<ul>
<li>Installation</li>
<ul>
<li><a href="/enigma-bbs/installation/installation-methods.html">Installation Methods</a></li>
<li><a href="/enigma-bbs/installation/install-script.html">Install Script</a></li>
<li><a href="/enigma-bbs/installation/docker.html">Docker</a></li>
<li><a href="/enigma-bbs/installation/manual.html">Manual Installation</a></li>
<li>OS / Hardware Specific</li>
<ul>
<li><a href="/enigma-bbs/installation/hardware/rpi.html">Raspberry Pi</a></li>
<li><a href="/enigma-bbs/installation/hardware/windows.html">Installation Under Windows</a></li>
</ul>
<li><a href="/enigma-bbs/installation/network.html">Network Setup</a></li>
<li><a href="/enigma-bbs/installation/testing.html">Testing Your Installation</a></li>
<li><a href="/enigma-bbs/installation/production.html">Production Installation</a></li>
</ul>
<li>Configuration</li>
<ul>
<li><a href="/enigma-bbs/configuration/creating-config.html">Creating Initial Config Files</a></li>
<li><a href="/enigma-bbs/configuration/sysop-setup.html">SysOp Setup</a></li>
<li><a href="/enigma-bbs/configuration/config-files.html">Configuration Files</a></li>
<li><a href="/enigma-bbs/configuration/config-hjson.html">System Configuration</a></li>
<li><a href="/enigma-bbs/configuration/hjson.html">HJSON Config Files</a></li>
<li><a href="/enigma-bbs/configuration/menu-hjson.html">Menu HSJON</a></li>
<li><a href="/enigma-bbs/configuration/directory-structure.html">Directory Structure</a></li>
<li><a href="/enigma-bbs/configuration/external-binaries.html">External Support Binaries</a></li>
<li><a href="/enigma-bbs/configuration/archivers.html">Archivers</a></li>
<li><a href="/enigma-bbs/configuration/file-transfer-protocols.html">File Transfer Protocols</a></li>
<li><a href="/enigma-bbs/configuration/email.html">Email</a></li>
<li><a href="/enigma-bbs/configuration/colour-codes.html">Colour Codes</a></li>
<li class="active-nav">Event Scheduler</li>
<li><a href="/enigma-bbs/configuration/acs.html">Access Condition System (ACS)</a></li>
<li><a href="/enigma-bbs/configuration/security.html">Security</a></li>
</ul>
<li>Miscellaneous</li>
<ul>
<li><a href="/enigma-bbs/misc/user-interrupt.html">User Interruptions</a></li>
</ul>
<li>File Base</li>
<ul>
<li><a href="/enigma-bbs/filebase/index.html">About File Areas</a></li>
<li><a href="/enigma-bbs/filebase/first-file-area.html">Configuring a File Base</a></li>
<li><a href="/enigma-bbs/filebase/acs.html">ACS</a></li>
<li><a href="/enigma-bbs/filebase/uploads.html">Uploads</a></li>
<li><a href="/enigma-bbs/filebase/web-access.html">Web Access</a></li>
<li><a href="/enigma-bbs/filebase/tic-support.html">TIC Support</a></li>
<li><a href="/enigma-bbs/filebase/network-mounts-and-symlinks.html">Network Mounts &amp; Symlinks</a></li>
</ul>
<li>Message Areas</li>
<ul>
<li><a href="/enigma-bbs/messageareas/configuring-a-message-area.html">Message Base</a></li>
<li><a href="/enigma-bbs/messageareas/message-networks.html">Message Networks</a></li>
<li><a href="/enigma-bbs/messageareas/bso-import-export.html">BSO Import / Export</a></li>
<li><a href="/enigma-bbs/messageareas/netmail.html">Netmail</a></li>
<li><a href="/enigma-bbs/messageareas/qwk.html">QWK Support</a></li>
<li><a href="/enigma-bbs/messageareas/ftn.html">FidoNet-Style Networks (FTN)</a></li>
</ul>
<li>Art</li>
<ul>
<li><a href="/enigma-bbs/art/general.html">General Art Information</a></li>
<li><a href="/enigma-bbs/art/themes.html">Themes</a></li>
<li><a href="/enigma-bbs/art/mci.html">MCI Codes</a></li>
<li>Views</li>
<ul>
<li><a href="/enigma-bbs/art/views/button_view.html">Button View</a></li>
<li><a href="/enigma-bbs/art/views/edit_text_view.html">Edit Text View</a></li>
<li><a href="/enigma-bbs/art/views/full_menu_view.html">Full Menu View</a></li>
<li><a href="/enigma-bbs/art/views/horizontal_menu_view.html">Horizontal Menu View</a></li>
<li><a href="/enigma-bbs/art/views/mask_edit_text_view.html">Mask Edit Text View</a></li>
<li><a href="/enigma-bbs/art/views/multi_line_edit_text_view.html">Multi Line Edit Text View</a></li>
<li><a href="/enigma-bbs/art/views/spinner_menu_view.html">Spinner Menu View</a></li>
<li><a href="/enigma-bbs/art/views/text_view.html">Text View</a></li>
<li><a href="/enigma-bbs/art/views/toggle_menu_view.html">Toggle Menu View</a></li>
<li><a href="/enigma-bbs/art/views/vertical_menu_view.html">Vertical Menu View</a></li>
</ul>
</ul>
<li>Servers</li>
<ul>
<li>Login Servers</li>
<ul>
<li><a href="/enigma-bbs/servers/loginservers/telnet.html">Telnet Server</a></li>
<li><a href="/enigma-bbs/servers/loginservers/ssh.html">SSH Server</a></li>
<li><a href="/enigma-bbs/servers/loginservers/websocket.html">Web Socket / Web Interface Server</a></li>
</ul>
<li>Content Servers</li>
<ul>
<li><a href="/enigma-bbs/servers/contentservers/web-server.html">Web Server</a></li>
<li><a href="/enigma-bbs/servers/contentservers/gopher.html">Gopher Server</a></li>
<li><a href="/enigma-bbs/servers/contentservers/nntp.html">NNTP Server</a></li>
</ul>
</ul>
<li>Modding</li>
<ul>
<li><a href="/enigma-bbs/modding/local-doors.html">Local Doors</a></li>
<li><a href="/enigma-bbs/modding/door-servers.html">Door Servers</a></li>
<li><a href="/enigma-bbs/modding/telnet-bridge.html">Telnet Bridge</a></li>
<li><a href="/enigma-bbs/modding/existing-mods.html">Existing Mods</a></li>
<li><a href="/enigma-bbs/modding/file-area-list.html">File Area List</a></li>
<li><a href="/enigma-bbs/modding/last-callers.html">Last Callers</a></li>
<li><a href="/enigma-bbs/modding/whos-online.html">Who's Online</a></li>
<li><a href="/enigma-bbs/modding/user-list.html">User List</a></li>
<li><a href="/enigma-bbs/modding/msg-conf-list.html">Message Conference List</a></li>
<li><a href="/enigma-bbs/modding/msg-area-list.html">Message Area List</a></li>
<li><a href="/enigma-bbs/modding/bbs-list.html">BBS List</a></li>
<li><a href="/enigma-bbs/modding/rumorz.html">Rumorz</a></li>
<li><a href="/enigma-bbs/modding/file-transfer-protocol-select.html">File Transfer Protocol Select</a></li>
<li><a href="/enigma-bbs/modding/onelinerz.html">Onelinerz</a></li>
<li><a href="/enigma-bbs/modding/show-art.html">The Show Art Module</a></li>
<li><a href="/enigma-bbs/modding/file-base-download-manager.html">File Base Download Manager</a></li>
<li><a href="/enigma-bbs/modding/file-base-web-download-manager.html">File Base Web Download Manager</a></li>
<li><a href="/enigma-bbs/modding/set-newscan-date.html">Set Newscan Date Module</a></li>
<li><a href="/enigma-bbs/modding/node-msg.html">Node to Node Messaging</a></li>
<li><a href="/enigma-bbs/modding/top-x.html">TopX</a></li>
<li><a href="/enigma-bbs/modding/user-2fa-otp-config.html">2FA/OTP Config</a></li>
<li><a href="/enigma-bbs/modding/autosig-edit.html">Auto Signature Editor</a></li>
<li><a href="/enigma-bbs/modding/menu-modules.html">Menu Modules</a></li>
</ul>
<li>Administration</li>
<ul>
<li><a href="/enigma-bbs/admin/administration.html">Administration</a></li>
</ul>
<li>Modding</li>
<ul>
<li><a href="/enigma-bbs/modding/wfc.html">Waiting For Caller (WFC)</a></li>
</ul>
<li>Administration</li>
<ul>
<li><a href="/enigma-bbs/admin/oputil.html">oputil</a></li>
<li><a href="/enigma-bbs/admin/updating.html">Updating</a></li>
</ul>
<li>Troubleshooting</li>
<ul>
<li><a href="/enigma-bbs/troubleshooting/monitoring-logs.html">Monitoring Logs</a></li>
</ul>
</ul>
</div>
<div class="main_area">
<div class="container">
<section id="main_content">
<div class="PageNavigation">
<a class="btn" style="float:left;margin-right: 20px;" href="/enigma-bbs/configuration/colour-codes.html">« Colour Codes</a>
<a href="#sidebar" class="btn menu_button">MENU</a>
<a class="btn" style="float: right;margin-left: 20px" href="/enigma-bbs/configuration/acs.html">Access Condition System (ACS) »</a>
<br clear="both">
</div>
<div class="page">
<h1 class="page-title">Event Scheduler</h1>
<h2 id="event-scheduler">Event Scheduler</h2>
<p>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 &amp; scripts.</p>
<h2 id="scheduling-events">Scheduling Events</h2>
<p>To create a scheduled event, create a new configuration block in <code class="language-plaintext highlighter-rouge">config.hjson</code> under <code class="language-plaintext highlighter-rouge">eventScheduler.events</code>.</p>
<p>Events can have the following members:</p>
<table>
<thead>
<tr>
<th>Item</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code class="language-plaintext highlighter-rouge">schedule</code></td>
<td><img class="emoji" title=":+1:" alt=":+1:" src="https://github.githubassets.com/images/icons/emoji/unicode/1f44d.png" height="20" width="20"></td>
<td>A <a href="https://bunkat.github.io/later/parsers.html#text">Later style</a> parsable schedule string such as <code class="language-plaintext highlighter-rouge">at 4:00 am</code>, or <code class="language-plaintext highlighter-rouge">every 24 hours</code>. Can also be (or contain) an <code class="language-plaintext highlighter-rouge">@watch</code> clause. See <strong>Schedules</strong> below for details.</td>
</tr>
<tr>
<td><code class="language-plaintext highlighter-rouge">action</code></td>
<td><img class="emoji" title=":+1:" alt=":+1:" src="https://github.githubassets.com/images/icons/emoji/unicode/1f44d.png" height="20" width="20"></td>
<td>Action to perform when the schedule is triggered. May be an <code class="language-plaintext highlighter-rouge">@method</code> or <code class="language-plaintext highlighter-rouge">@execute</code> spec. See <strong>Actions</strong> below.</td>
</tr>
<tr>
<td><code class="language-plaintext highlighter-rouge">args</code></td>
<td><img class="emoji" title=":-1:" alt=":-1:" src="https://github.githubassets.com/images/icons/emoji/unicode/1f44e.png" height="20" width="20"></td>
<td>An array of arguments to pass along to the method or binary specified in <code class="language-plaintext highlighter-rouge">action</code>.</td>
</tr>
</tbody>
</table>
<h3 id="schedules">Schedules</h3>
<p>As mentioned above, <code class="language-plaintext highlighter-rouge">schedule</code> may contain a <a href="https://bunkat.github.io/later/parsers.html#text">Later style</a> parsable schedule string and/or an <code class="language-plaintext highlighter-rouge">@watch</code> clause.</p>
<p><code class="language-plaintext highlighter-rouge">schedule</code> examples:</p>
<ul>
<li><code class="language-plaintext highlighter-rouge">every 2 hours</code></li>
<li><code class="language-plaintext highlighter-rouge">on the last day of the week</code></li>
<li><code class="language-plaintext highlighter-rouge">after 12th hour</code></li>
</ul>
<p>An <code class="language-plaintext highlighter-rouge">@watch</code> clause monitors a specified file for changes and takes the following form: <code class="language-plaintext highlighter-rouge">@watch:&lt;path&gt;</code> where <code class="language-plaintext highlighter-rouge">&lt;path&gt;</code> is a fully qualified path.</p>
<blockquote>
<p><img class="emoji" title=":bulb:" alt=":bulb:" src="https://github.githubassets.com/images/icons/emoji/unicode/1f4a1.png" height="20" width="20"> If you would like to have a schedule <strong>and</strong> watch a file for changes, place the <code class="language-plaintext highlighter-rouge">@watch</code> clause second and separated with the word <code class="language-plaintext highlighter-rouge">or</code>. For example: <code class="language-plaintext highlighter-rouge">every 24 hours or @watch:/path/to/somefile.txt</code>.</p>
</blockquote>
<h3 id="actions">Actions</h3>
<p>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.</p>
<h4 id="methods">Methods</h4>
<p>An action with a <code class="language-plaintext highlighter-rouge">@method</code> can take the following forms:</p>
<ul>
<li>
<code class="language-plaintext highlighter-rouge">@method:/full/path/to/module.js:methodName</code>: Executes <code class="language-plaintext highlighter-rouge">methodName</code> at <code class="language-plaintext highlighter-rouge">/full/path/to/module.js</code>.</li>
<li>
<code class="language-plaintext highlighter-rouge">@method:rel/path/to/module.js:methodName</code>: Executes <code class="language-plaintext highlighter-rouge">methodName</code> using the <em>relative</em> path <code class="language-plaintext highlighter-rouge">rel/path/to/module.js</code>. Paths for <code class="language-plaintext highlighter-rouge">@method</code> are relative to the ENiGMA½ installation directory.</li>
</ul>
<p>Methods are passed any supplied <code class="language-plaintext highlighter-rouge">args</code> in the order they are provided.</p>
<h5 id="method-signature">Method Signature</h5>
<p>To create your own method, simply <code class="language-plaintext highlighter-rouge">export</code> a method with the following signature: <code class="language-plaintext highlighter-rouge">(args, callback)</code>. Methods are executed asynchronously.</p>
<p>Example:</p>
<div class="language-javascript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// my_custom_mod.js</span>
<span class="nx">exports</span><span class="p">.</span><span class="nx">myCustomMethod</span> <span class="o">=</span> <span class="p">(</span><span class="nx">args</span><span class="p">,</span> <span class="nx">cb</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">{</span>
<span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="s2">`Hello, </span><span class="p">${</span><span class="nx">args</span><span class="p">[</span><span class="mi">0</span><span class="p">]}</span><span class="s2">!`</span><span class="p">);</span>
<span class="k">return</span> <span class="nx">cb</span><span class="p">(</span><span class="kc">null</span><span class="p">);</span>
<span class="p">}</span>
</code></pre></div></div>
<h4 id="executables">Executables</h4>
<p>When using the <code class="language-plaintext highlighter-rouge">@execute</code> 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 <code class="language-plaintext highlighter-rouge">PATH</code>.</p>
<p>Examples:</p>
<ul>
<li><code class="language-plaintext highlighter-rouge">@execute:/usr/bin/foo</code></li>
<li><code class="language-plaintext highlighter-rouge">@execute:foo</code></li>
</ul>
<p>Just like with methods, any supplied <code class="language-plaintext highlighter-rouge">args</code> will be passed along.</p>
<h2 id="example-entries">Example Entries</h2>
<p>Post a message to supplied networks every Monday night using the message post mod (see modding):</p>
<pre><code class="language-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"
]
}
}
}
</code></pre>
</div>
<div class="PageNavigation">
<a class="btn" style="float:left;margin-right: 20px;" href="/enigma-bbs/configuration/colour-codes.html">« Colour Codes</a>
<a class="btn" style="float: right;margin-left: 20px" href="/enigma-bbs/configuration/acs.html">Access Condition System (ACS) »</a>
<br clear="both">
</div>
</section>
</div>
</div>
</div>
</body>
</html>