structtasks Plugin

External requirements: This plugin requires the following additional components that must be installed separately:

• struct
• sqlite

Download and install the plugin using the Extension Manager. Refer to Plugins on how to install plugins manually.

This plugin provides a task-tracking system for your wiki by leveraging the Struct plugin. A user configures this plugin to look at a particular schema, which must contain some specific fields. Each page assigend to that schema then represents a tasks. Whenever a task page is saved, the plugin will check for changes to the struct data and email users accordingly. The plugin also provides a CLI script which, if set up as a cronjob, can send reminders of tasks which are coming due.

This plugin can work with a schema of your choice, set using the configuration manager. However, the plugin will report an error if the schema does not have the following fields:

• assignees: A field of type User or Mail. It may be multi-valued.
• duedate: A field of type Date or DateTime. It must not be multi-valued.
• status: A field of type Dropdown or Text. It must not be multi-valued.

You are free to set any other properties of these fields (e.g., label text, hint, etc.) as you see fit. You may also define any other fields in this schema that you like; they will have no effect on the operation of this plugin.

If you would like to have reminders sent for open tasks which are coming due soon or are overdue, you need to run this plugin's CLI script. This is best done by setting a cronjob to run it once per day. You should configure it to run something like the following command: /usr/bin/php $DOKUWIKI_ROOT/bin/plugin.php structtasks -v &> $DOKUWIKI_ROOT/structtasks-cron.log. Here, $DOKUWIKI_ROOT refers to the directory in which DokuWiki was installed. The -v option produces verbose output, which can be useful for debugging purposes. You will likely want to schedule this to run in the early morning.

Cronjobs are configured using your crontab file. If you are using shared-hosting for your DokuWiki instance, your hosting provider should provide some means to set up cronjobs, using a tool such as cPanel.

As this script is not run as part of a HTTP request, DokuWiki can not autodetect the baseurl or basedir. In order to generate valid page links in the reminder email, you must set these explicitly in your wiki configurations.

Cronjobs run using the time-zone configured for your server, not that of the DokuWiki instance. If you are on a shared host, it may not be obvious what this is. You can find it using these instructions. Simply adjust the time set for your cronjob accordingly, so it runs at the desired time in your time-zone. As different jurisdictions enter Daylight Savings Time on different dates (if at all), it is recommended to run the cronjob more than an hour after midnight. This should ensure that it will always be run on the expected day.

• schema: The name of a struct schema containing information on tasks. See the previous section for an explanation of the schema requirements. If blank, the plugin is effectively deactivated.
• reminder: On which days before a task is due to send reminder emails to assignees. 0 indicates the due-date itself. Only sends emails for tasks which are not “closed”. Requires the CLI script to be run (e.g., via a cronjob).
• overdue_reminder: Whether to send emails to assignees for tasks which are not closed after their due-date. Requires the CLI script to be run (e.g., via a cronjob).
• completed: A regular expression which will be applied to the “status” field of a task. Tasks with statuses matching the regular expression will be considered completed or closed and reminder emails will not be sent. All other tasks are considered “open”.

When struct data is changed for a page assigned the appropriate schema, the plugin will send emails to those assigned to the task, that are not the editor, in the following circumstances:

• The user is newly-assigned to a task
• The user is removed from the task
• Someone else removed themselves from the task
• The due-date of the task is changed
• The page associated with the task is deleted
• The task's status is changed from “open” to “closed” (e.g., completed, cancelled, etc.)
• The task's status is changed from “closed” to “open”

Running the CLI script for this plugin (e.g., with a command like /usr/bin/php $DOKUWIKI_ROOT/bin/plugin.php structtasks -v) will send users assigned to a task the following types of notifications, depending on the plugin configurations:

• Reminders of tasks coming due in a certain number of days (set by the reminder configuration) which are not marked as closed
• Reminders of tasks due today (if reminder is set to send notifications for tasks due in 0 days), if the task is not already closed
• Reminders of open tasks for which the due-date has already passed (if the overdue_reminder setting is set to true)

• Bumbed release date (2023-06-05 15:14)
• Update lang.php (2023-06-05 15:12)
• Fixed issue with no assignment notifications on page creation (2023-04-07 00:41)
• fixed indentation (2023-04-07 00:36)
• Fixed broken lang data for deletion notifier (2023-04-07 00:30)
• Upped release (2023-04-07 00:27)
• Fix #2, assignee-removal notifications sent on page deletion (2023-04-07 00:26)
• Fix #4, date-change notifications sent for every edit. (2023-04-07 00:26)

Please report bugs and issues at http://github.com/cmacmackin/dokuwiki-plugin-structtasks/issues

• Add a syntax plugin to display kanban boards for issues
• Provide Ajax handlers so moving tasks on kanban boards can update their status

There exist a number of other plugins for handling tasks. However, the approach I took with this plugin provided two unique features I particularly wanted:

1. There is a whole page associated with each task, on which to keep notes about progress.
2. You can make use of Struct aggregations to create highly flexible tables of tasks.

The latter point is very important. The plugin places no upper limit on the number and type of fields contained in your struct schema, so you can associate arbitrary additional metadata with your tasks, indicating things like category, priority, etc. You can then filter and sort your tasks in an aggregation however you like.