Managing Tasks in Django Admin Site

This guide is intended for users who want to manage tasks using Django’s built-in administrative interface.

It is assumed that these users are familiar with the basic functionality of a Django admin interface, therefore CRUD (Create, Read, Update, Delete) operations won’t be covered here.

Upon successful login to the admin site of your application, a Task Manager section will be visible, providing you the ability to manage your tasks.

Within the Django admin site, the Task Manager section will include the application’s views.

Gathering commands

Commands for tasks should be gleaned from the host project’s applications, specifically among those tasks that have been defined for management. This will enable them to be available as launchable commands.

This process can be achieved using the collectcommands management task [1].

python manage.py collect_commands --excludecore -v2

Complete syntax of a command can be found on the command details page, which is accessible by clicking on the application name in the command’s row.

Commands are removable. To recreate tasks from these deleted commands, re-running the collectcommands task will be necessary.

Only those commands flagged as active can be utilised to generate tasks. Hence, to prevent a command from being used to create tasks, simply turn its active status to false.

You can also generate a task using the collectcommands command. This allows you to launch the collection of available commands directly through django-eztaskmanager.

Tasks Overview

The Tasks section serves as the central administration view where every operation takes place. Tasks can be listed, filtered, searched, created, modified, and removed using Django-admin’s standard CRUD processes.

You have the capabilities to start or stop a task both in the list view and the detail view.

By default, tasks are sorted according to their latest launch time. This ensures that the most frequently used tasks are displayed upfront, avoiding clutter by infrequently used tasks. Additional sorting criteria can be applied by clicking the column headers.

The outcomes of the tasks are indicated both color-coded and with detailed notes of errors/warnings, if any. Tasks with warnings or errors (yellow and orange color codes) might still be functioning as expected as sometimes the errors can be attributed to issues with the data source. Tasks that fail (red code) require immediate attention as it suggests there are issues within the task’s code or logic itself.

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

Hovering over the task name reveals a descriptive note, given that the task authors have added one. This note can provide insight into different aspects of the task instance and highlight any peculiarities of the arguments needed.

Task Structure

A task is comprised of four main sections:

• Definition: Contains the task name, command, arguments, category, and notes.

• Scheduling: Specifies the start time and recurrence rate.

• Last Execution: Shows the queued job id, status, last execution datetime, last result, next execution, and the count of warnings or errors.

• Reports: Every execution of a task generates a Report. Only the last five reports are stored and shown in each task’s detail view.

Task Definition

The Definition section contains the following fields:

• Name: This is where you provide a unique name for the task. Using unique names with prefixes can facilitate easy visual identification of tasks.

  Note

  Remember that one command can be applied to multiple tasks with different arguments. Ensure that you give distinct names and describe the differences in detail in the note field. This will help other users make informed decisions about which task to use.

• Command: Select the appropriate command from the list available in the command popup.

• Arguments: Here, you enter the arguments the command requires using a specific syntax:

  Note

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

  For example: -f, --secondarg param1 param2, --thirdarg=pippo, --thirdarg

• Category: Choose an existing category or create a new one for the task.

• Note: This field is for a descriptive note explaining how the command or its arguments are used.

Task Categories

Task categories are an efficient way of managing tasks when their quantity starts to increase. You can assign a category to each task and then filter the tasks list by category.

Note

Keep your category names simple and short. Try to limit the total number of categories to less than ten to avoid any confusion for other users.

Task Scheduling

The Scheduling process involves the following fields:

• Scheduling: Specify a date and time for the task’s initial launch.

• Repetition Period: Select a frequency for the task to repeat: minute, hour, day, or month.

• Repetition Rate: Set a numerical value for the task’s repetition rate.

• To schedule a one-time future task: Set the scheduling field to a future time and press the start button.

• To schedule a recurring future task: Set both scheduling and repetition fields, then press the start button.

• To cancel a scheduled start: Press the stop button.

Understanding the Task’s Last Execution Status

The fields in this section are read-only and display information about the task’s last execution.

• Status: This can show one of the following: - IDLE: The task has either never started or it was stopped. - STARTED: The task is currently running. - SCHEDULED: The task is set to start at some point in the future.

• Last Datetime: This shows the date and time of the last execution.

• Last Result: This shows the result of the last execution:

  • OK: The task ran without any errors or warnings.

  • WARNINGS: The task ran correctly, but with warnings. Refer to the report for details.

  • ERRORS: The task ran correctly, but with errors. Refer to the report for details.

  • FAILED: There was a runtime error. Refer to the report for details.

• Errors: This shows the number of detected errors from the last execution.

• Warnings: This shows the number of detected warnings from the last execution.

Note

Before a task starts for the first time, it is put in the spooler. Therefore, the task’s status may show as SPOOLED. A few moments later, after refreshing the page, the status will change to STARTED. This is to be expected.

Reading the Task’s Reports

After a task is complete, a report is generated and added to the reports section. To conserve space, only the last 5 reports remain accessible for users.

Each report includes the result and invocation datetime fields, plus the last 10 log lines from the execution.

Clicking on the show the log messages link opens a new page containing the log messages.

If the task is still running, the page will refresh to display new messages as they’re added.

At the top of the page is a toolbar divided into three sections:

• Levels Buttons (ALL, DEBUG, INFO, WARNING, ERROR): These function as filters. Clicking one only shows messages of that type. The numbers next to each button indicate the amount of messages per type. A button only appears after a message of its type has been added to the log file.

• Search Field: This helps in filtering messages by a specific string. Only messages containing this string are listed. Clicking on the ‘x’ button next to the search field will reset all filters (equivalent to pressing the ALL button).

• Commands on the right side of the toolbar: - The raw logs button opens a new page displaying the log files in raw text format. - The sticky mode button toggles the auto-scrolling of message displays. This can be used to focus on a specific part of the log messages.

Note

The entire list of log messages is rendered on a single page. This can cause long rendering times for lengthy lists. The recommended solution is to implement tasks that do not log excess messages… rubric:: Footnotes

[1]

The excludecore parameter is used to prevent the fetching of core Django tasks.