How to manage tasks in the django admin site

This documentation is for users that want to manage tasks within the django admin site.

It is supposed that the users know the basic usage of a django admin interface, so CRUD operations will not be descibed here.

Once you log into the admin site of your app, you’ll find a Task manager section, where you can manage the tasks.

In the django admin site, a Task manager section will appear, containing the app’s views.

Commands

The commands to use in tasks must be collected from the hosting project’s apps, among the defined management tasks, in order to be available as launchable commands.

This can be done through the collectcommands management task 1:

python manage.py collect_commands --excludecore -v2

The complete command’s syntax is visible in the command details page (click on the app name in the row of the command).

Commands can be deleted. This means that in order to create tasks out of them you will need to use the collectcommands task again.

Only commands checked with the active flag will be available to generate tasks. So the best option to remove a command and not allow users to geneate tasks out of it is to set its active status to false.

Note

It is possible to generate a task starting from the collectcommands command, so that the collection of available commands can be launched through the django-uwsgi-taskmanager, too.

Tasks

Tasks is the main admin view, where all the action happens. Tasks can be listed, filtered, searched, created, modified and removed using the standard CRUD processes available in django-admin.

Actions are available to have a task start or stop, both in the list view and in the detail view.

Tasks are sorted, by default, by the latest launch time. This way the most used tasks are shown first, avoiding to clutter the list with unused tasks. Other sort criterion may be chosen by clicking on the column headers, as usual.

Tasks last results are shown both with a color code and with a verbose indication of the number of errors/warnings, if any are there. A task with warnings and errors (yellow and orange color codes), may be perfectly ok, as many times the errors may indicate some problems in the data source. A failed task (red code) requires immediate intervention, as it indicates some missing code or logic in the task itself.

Clicking on the last result status opens a new tab with the log messages for that particular execution.

Hovering over the name of the task shows the descriptive note, if inserted by the task authors. This may describe aspects of that task instance and peculiarities of the arguments to pass.

Task structure

A task has four main sections:

• Definition: name, command, arguments, category and note;

• Scheduling: time of start and repetition period and rate;

• Last execution: spooler id, status, last execution datetime, last result, next execution, n. of errors and warnings;

• Reports: Each task’s execution generates a Report. Only the last 5 reports are kept and shown in the Task’s detail view.

Defining a task

Fields in the definition section:

• name: name a task, use unique names with prefixes, to identify tasks visually

  Note

  It is important to understand that a command can be used multiple times in various tasks, with different arguments. Use different names and specify differences verbosely in the note field to let other users make the right choices on which task to use.

• command: select the command from the collected ones, in the command popup list;

• arguments: the command’s arguments in a special syntax:

  Note

  Single arguments should be separated by a comma (“,”), while multiple values in a single argument should be separated by a blank space,

  eg: -f, --secondarg param1 param2, --thirdarg=pippo, --thirdarg

• category: select from an existing one, or add a new one

• note: a descriptive note on how the command or its arguments are used

Task categories

In order to ease the search of tasks when they start to grow in numbers, a category can be assigned to each one. The tasks list can then be filtered by category.

Note

Use simple, short words as categories and try to have less than 10 categories in all, in order not to confuse other users.

Scheduling a task

Scheduling is performed through the following fields:

• scheduling: date and time, sets the moment in time when the task is going to be launched for the first time.

• repetition period: select one among minute, hour, day, month

• repetition rate: set an integer

To schedule a task to start in the future only once: set the scheduling field to a point in time in the future and press the start button.

To schedule a task to start in the future and run periodically: set both the scheduling field and the repetition fields, then press the start button.

To stop a scheduled start: press the stop button.

Reading the task’s last execution status

The fields in this section are read-only and are meant to show information on the task’s lat execution.

• spooled at: the complete path to the file in the spooler, can be useful when debugging errors, but it’s an internal information and should not be needed by standard users

• status: can be one of:

  • IDLE: the task never started or was stopped,

  • STARTED: the task is currently running,

  • SCHEDULED: the task is going to start for the first time in the future,

  • SPOOLED: the task has been put in the spooler and is going to start again in the future

• last datetime: the last execution date and time

• last result: last execution result

  • OK: correctly executed, with no warnings, nor errors

  • WARNINGS: correctly executed, but contains warnings, see the report

  • ERRORS: correctly executed, but contains errors, see the report

  • FAILED: there was an error while execution, see the report

• errors: the number of errors detected in the last execution

• warnings: the number of warnings detected in the last execution

Note

Consider that before starting for the first time, the task is being put in the spooler, so whenever checking the status of a task, it can happen that its status shows SPOOLED, and after a few moments, refreshing the page, it will show STARTED.

This is perfectly normal.

Reading the task’s reports

Once a task is finished, a report is generated and added to the reports section. Only the last 5 reports are left available to the users, in order to save space.

Each report contains the result and invocation datetime fields, along with the tail of the last 10 lines logged during execution.

Clicking on the show the log messages link, a new page cotaining the log messages is opened.

If the task is still executing, the page will be refreshed, in order for the new messages to be added to the page.

On top of the page there is a toolbar, divided into three sections:

• the levels buttons (ALL, DEBUG, INFO, WARNING, ERROR) act as filters and clicking on one of them only the messages of that type will be listed; the numbers appearing by each button indicate how many messages of that type have been produced; buttons only appear when some message of that type is added to the log file;

• the search field allows to filter messages by a string: only messages containing the string are listed; clicking on the ‘x’ button by the search field will reset all filters and is equivalent to pressing the ALL button;

• as for the commands on the right side of the toolbar:

  • the raw logs button allows to open up a new page with the log files in raw text format

  • the sticky mode button disable or enable the scrolling of the messages display to the bottom; this can be used in order to disable following the logging messages and concentrating on some research;

Note

The complete list of log messages is rendered on a single page. This can be problematic whenever the list is really long, as rendering times may be long too. The only solution that comes to mind is to implement tasks that doesn’t log too many rows.

Footnotes

1

excludecore ensures that core django tasks are not fetched.