# events

Events can be used to run code based on data changes or time.

## Data change events

Data change events are prefixed by the database and optionally the document type.
Examples are `raw-data:remove` (triggered every time raw data report removed)
or `integrated-data:patients:add` (triggered every time an indicator
gets created).

<table>
  <thead>
    <tr>
      <th aling=left>Event name</th>
      <th>Description</th>
      <th>Passed arguments to handler</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>
        <strong>add</strong>
      </td>
      <td>a new document added</td>
      <td><code>document</code></td>
    </tr>
    <tr>
      <td>
        <strong>update</strong>
      </td>
      <td>existing document updated</td>
      <td><code>document</code></td>
    </tr>
    <tr>
      <td>
        <strong>remove</strong>
      </td>
      <td>existing document removed</td>
      <td><code>document</code></td>
    </tr>
    <tr>
      <td>
        <strong>change</strong>
      </td>
      <td>any of the events above</td>
      <td><code>eventName</code>, <code>document</code></td>
    </tr>
  </tbody>
</table>

Example

```js
events: [
  on: 'report:add',
  handler: function (server, report) {
    server.methods.sendEmail({
      to: 'john@example.com',
      subject: 'new report submitted',
      text: toText(report),
      html: toHtml(report)
    })
  }
]
```

## Time based events

Time based events can be used for scripts that need to be run on a schedule,
e.g. for doing data backups, or sending a recurring summary notification.
Time based events to not pass any argument to their handler. The schedule is
defined

```js
events: [
  on: {
    // every day at 2am local Lagos time
    hour: 2,
    timezone: 'Africa/Lagos'
  }
  handler: function (server) {
    // sendSummary would be a custom method defined in an app or plugin
    server.methods.sendSummary()

    .catch(function (error) {
      server.log(['events', 'error'], error)
    })
  }
]
```

`on` can be set to an object, or to an array of objects for multiple schedules.
Allowed options are

<table>
  <thead>
    <tr>
      <th aling=left>option</th>
      <th>Description</th>
      <th>Allowed values</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>
        <strong>minute</strong>
      </td>
      <td>Minute of hour</td>
      <td><code>0 - 59</code></td>
    </tr>
    <tr>
      <td>
        <strong>hour</strong>
      </td>
      <td>hour of day</td>
      <td><code>0 - 23</code></td>
    </tr>
    <tr>
      <td>
        <strong>weekDay</strong>
      </td>
      <td>day of week. <code>1</code> is Sunday, <code>7</code> is Saturday</td>
      <td><code>1 - 7</code></td>
    </tr>
    <tr>
      <td>
        <strong>monthDay</strong>
      </td>
      <td>day of month. If set to <code>31</code> but month has only 30 days, the month is skipped</td>
      <td><code>1 - 31</code></td>
    </tr>
    <tr>
      <td>
        <strong>month</strong>
      </td>
      <td>Month of year. 1 is January, 12 is December</td>
      <td><code>1 - 12</code></td>
    </tr>
    <tr>
      <td>
        <strong>timezone</strong>
      </td>
      <td>ISO(?) Name of Timezone</td>
      <td>e.g. <code>Africa/Lagos</code></td>
    </tr>
  </tbody>
</table>