diff --git a/modules/microsite/docs/doc/notifydueitems.md b/modules/microsite/docs/doc/notifydueitems.md new file mode 100644 index 00000000..a816c8fb --- /dev/null +++ b/modules/microsite/docs/doc/notifydueitems.md @@ -0,0 +1,76 @@ +--- +layout: docs +title: Notify about due items +permalink: doc/notifydueitems +--- + +# {{page.title}} + +Each user that provides valid email (smtp) settings, can be notified +by docspell about due items. You will then receive an e-mail +containing a list of items, sorted by their due date. + +You need first define smtp settings, please see [this +page](mailitem#e-mail-settings). + +Notifying works simply by searching for due items periodically. It +will be submitted to the job queue and is picked up by an available +[job executor](joex) eventually. This can be setup in the user +settings page. + +
+ +
+ +At first, the task can be disabled/enabled any time. + +Then two settings are required for sending an e-mail. You need to +specify the connection to use and the recipients. + +It follows some settings to customize the query for searching items. +You can choose to only include items that have one or more tags (these +are `and`-ed, so all tags must exist on the item). You can also +provide tags that must *not* appear on an item (these tags are +`or`-ed, so only one such tag is enough ot exclude an item). A common +use-case would be to manually tag an item with *Done* once there is +nothing more to do. Then these items can be excluded from the search. +The somewhat inverse use-case is to always tag items with a *Todo* tag +and remove it once completed. + +The *Remind Days* field species the number of days the due date may be +in the future. Each time the task executes, it searches for items with +a due date lower than `today + remindDays`. + +If you don't restrict the search using tags, then all items with a due +date lower than this value are selected. Since items are (usually) not +deleted, this only makes sense, if you remove the due date once you +are done with an item. + +The last option is to check *cap overdue items*, which uses the value +in *Remind Days* to further restrict the due date of an item: only +those with a due date *greater than* `today - remindDays` are +selected. In other words, only items with an overdue time of *at most* +*Remind Days* are included. + +The *Schedule* field specifies the periodicity. The syntax is similiar +to a date-time string, like `2019-09-15 12:32`, where each part is a +pattern to also match multple values. The ui tries to help a little by +displaying the next two date-times this task would execute. A more in +depth help is available +[here](https://github.com/eikek/calev#what-are-calendar-events). For +example, to execute the task every monday at noon, you would write: +`Mon *-*-* 12:00`. A date-time part can match all values (`*`), a list +of values (e.g. `1,5,12,19`) or a range (e.g. `1..9`). Long lists may +be written in a shorter way using a repetition value. It is written +like this: `1/7` which is the same as a list with `1` and all +multiples of `7` added to it. In other words, it matches `1`, `1+7`, +`1+7+7`, `1+7+7+7` and so on. + +You can click on *Start Once* to run this task right now, without +saving the form to the database ("right now" means it is picked up by +a free job executor). + +If you click *Submit* these settings are saved and the task runs +periodically. + +You can see the task executing at the [processing page](processing). diff --git a/modules/microsite/src/main/resources/microsite/data/menu.yml b/modules/microsite/src/main/resources/microsite/data/menu.yml index 7c625869..e94eca55 100644 --- a/modules/microsite/src/main/resources/microsite/data/menu.yml +++ b/modules/microsite/src/main/resources/microsite/data/menu.yml @@ -42,6 +42,9 @@ options: - title: Send via E-Mail url: doc/mailitem + - title: Notify on due Items + url: doc/notifydueitems + - title: Joex url: doc/joex diff --git a/modules/microsite/src/main/resources/microsite/img/notify-due-items.jpg b/modules/microsite/src/main/resources/microsite/img/notify-due-items.jpg new file mode 100644 index 00000000..85ab4e05 Binary files /dev/null and b/modules/microsite/src/main/resources/microsite/img/notify-due-items.jpg differ