diff --git a/docs/general/guides/guides.md b/docs/general/guides/guides.md index 71acc1a..7ab1c44 100644 --- a/docs/general/guides/guides.md +++ b/docs/general/guides/guides.md @@ -13,3 +13,4 @@ The following guides are available: - [Electoral Board Ceremonies](./electoral-board-ceremonies/) - [Segmented Mixing Guide](./segmented-mixing/) - [Cron Tasks Guide](./cron-tasks/) +- [Scheduled Events Guide](./scheduled-events/) diff --git a/docs/general/guides/scheduled-events/assets/activity-log.png b/docs/general/guides/scheduled-events/assets/activity-log.png new file mode 100644 index 0000000..566d0f4 Binary files /dev/null and b/docs/general/guides/scheduled-events/assets/activity-log.png differ diff --git a/docs/general/guides/scheduled-events/assets/dialog-selector.png b/docs/general/guides/scheduled-events/assets/dialog-selector.png new file mode 100644 index 0000000..17b5651 Binary files /dev/null and b/docs/general/guides/scheduled-events/assets/dialog-selector.png differ diff --git a/docs/general/guides/scheduled-events/assets/dialog.png b/docs/general/guides/scheduled-events/assets/dialog.png new file mode 100644 index 0000000..5145c51 Binary files /dev/null and b/docs/general/guides/scheduled-events/assets/dialog.png differ diff --git a/docs/general/guides/scheduled-events/assets/election-dashboard.png b/docs/general/guides/scheduled-events/assets/election-dashboard.png new file mode 100644 index 0000000..7000f9b Binary files /dev/null and b/docs/general/guides/scheduled-events/assets/election-dashboard.png differ diff --git a/docs/general/guides/scheduled-events/assets/notification.png b/docs/general/guides/scheduled-events/assets/notification.png new file mode 100644 index 0000000..42b9277 Binary files /dev/null and b/docs/general/guides/scheduled-events/assets/notification.png differ diff --git a/docs/general/guides/scheduled-events/scheduled-events.md b/docs/general/guides/scheduled-events/scheduled-events.md new file mode 100644 index 0000000..e6235ea --- /dev/null +++ b/docs/general/guides/scheduled-events/scheduled-events.md @@ -0,0 +1,115 @@ +--- +sidebar_position: 10 +title: Scheduled Events Guide +--- + +# Scheduled Events Guide + +You can automate events such as the start and the stop date time of an election +with scheduled events. These automations are not final, and you can change the +datetimes or even remove the automated datetime at any time. Of course, all +these changes will be reflected in the activity log of the election and these +important dates appear in the election dashboard. + +## Technical Implementation + +Scheduled events are setup with django [celery]. A task is created in celery to +be run at a specific date and time. This task is persisted using [rabbitmq]. + +The scheduled events can be re-scheduled and even cancelled as you will see in +later sections. Since we store the task id for each scheduled event within the +AuthEvent model, we can revoke any previously scheduled task when re-scheduling +or cancelling an event. + +Once the task is called at the scheduled time, it will be executed and the +election start or stop will thus happen **just moments after** the scheduled +time - typically less than a second. But that also depends on the number of +children events, which can take a while more since each child election is +started/stopped separatedly. + +## Election JSON Configuration + +You can configure the scheduled events in the Election Configuration JSON using +the [`scheduled_events`](../../reference/election-creation-json#election-scheduled_events) +field: + +```json +{ + // ... rest of the election configuration... + "scheduled_events": { + "start_voting": { + "event_at": "2023-09-12T09:26:00+00:00" + }, + "end_voting": { + "event_at": "2023-09-13T09:26:00+00:00" + } + }, + // ... rest of the election configuration... +} +``` + +## Scheduled events in the Election Dashboard + +The configuration of scheduled events appears in the election dashboard. On the +one hand, if there's any scheduled start or end of the voting period, it will +appear highlighted. + +On the other hand, at any time you can change and reconfigure the scheduled +events from the Dashboard `Actions` dropdown menu. + +Both are being highlighted by red arrows in the following image: + +![Scheduled events in the Election Dashboard](./assets/election-dashboard.png) + +## Configure Scheduled events: modal dialog + +Once you click in the Election Dashbaord `Actions` > +`Configure scheduled events` dropdown menu item, a modal dialog will appear in +which you can configure the dates in which the election will be automatically +started or stopped of the election. This dialog can be launched at any time, +allowing you to reschedule or even cancel a previously schedule election start +or stop. To cancel an event, just click to uncheck the checkbox. + +![Scheduled events modal dialog](./assets/dialog.png) + +![Scheduled events modal dialog with date selector](./assets/dialog-selector.png) + +Once you click in the `Confirm to change scheduled events` button, the dialog +will close and a notification will appear in the top of the screen saying the +configuration was successful: + +![Scheduled events: change success notification](./assets/notification.png) + +Additionally, the configuration box that shows the Election Status and some +other election information will be automatically updated showing the updated +`Scheduled Start` and/or `Scheduled Stop` dates. This might take a few seconds +to appear since it is updated using polling. + +Please notice that even though the datetime selector uses the browser's local +timezone, the dialog converts it to UTC timezone and thus scheduled events +datetime are thus shown in UTC if configured using the modal dialog. + +## Configure Scheduled events: dashboard and activity log + +When an scheduled event such as the end of the voting period happens, the +election status changes appropriately automatically. For example, the election +status of the election might change from `started` to `stopped`. If you have the +election dashboard open in your browser, it will take a few seconds to refresh +this information automatically. + +Additionally, all and any change of election scheduled events configuration or +change of status by the execution of the task related to an scheduled event will +appear in the election's activity log screen: + +![Scheduled events: activity log](./assets/activity-log.png) + +Note this screnshot shows: +1. That there are different scheduled events configuration changes being logged, +including the revokation of tasks related to previously scheduled events. +2. The successful execution of any scheduled event, in relation to the user +that scheduled such execution. +3. With any scheduled task or revokation of task, the associated task id is +being logged. +-- +[celery]: https://docs.celeryq.dev/en/stable/index.html +[rabbitmq]: https://www.rabbitmq.com/documentation.html \ No newline at end of file diff --git a/docs/general/reference/election-creation-json.md b/docs/general/reference/election-creation-json.md index ed3f091..d385b4c 100644 --- a/docs/general/reference/election-creation-json.md +++ b/docs/general/reference/election-creation-json.md @@ -406,6 +406,36 @@ details. Describes presentation options related to the whole election. See [Election Presentation](#election-presentation-object) for more details. +### Election: `scheduled_events` + +- **Property name**: `scheduled_events` +- **Type:** Object +- **Required:** No +- **Default:** `null` +- **Example:** +```json +{ + "start_voting": { + "event_at": "2023-09-12T09:26:00+00:00" + }, + "end_voting": null +} +``` + +Describes the configuration for automatic scheduled events of an election. It +can be null, or it can be a dictionary that follows the example shown above. + +The only currently configurable schedulable events are the election voting +period begining and end, configurable by the keys `start_voting` and +`end_voting`. + +You can configure any of those two to be either `null` or to be a dictionary +with the key `event_at` containing the date and time of the scheduled event. The +given datetime should follow the string format shown in the example. + +You must use non-naive datetime when providing the event date time, specifying +the timezone (the `+00:00` means UTC). + ### Election: `layout` - **Property name**: `layout`