Warnings

The warning system is the system providing the green/yellow/red dots on the front page, and is used to visualize what the user needs to do in the Microbizz system. The colors should be used as follows:

Red	A task which needs immediate attention and/or is overdue, such as a todo with an expired deadline or a phone call planned for yesterday.
Yellow	Pending tasks which needs attention now, but aren't overdue, such as a todo deadlining today, or a phone call planned for today.
Green	A task which have been resolved today.

Implementation

The warning system is implemented in the class StodoWarning. When deciding on a new warning, it should be identified by a module code, which refers to the module generating the warning. A subcode which uniquely identifies the warning type within the module should be decided upon, and at last an id identifying the object from which the warning originated (such as a Todo ID or a Customer ID). A warning should always be personal, and raised in the context of an user, and if applicate, in context of a team.

Raising a warning

A warning is raised with the following function:

raise($wtext, $modcode, $subcode, $objref, $uref, $gref = 0, $lvl = self::LEVEL_RED, $date = '')

$wtext	A text stating what the warning is about. This should be short and objective, such as “The todo XXX is deadlined YYYY”
$modcode	The module code
$subcode	The subcode
$objref	The object reference ID
$uref	The user ID of the user which should receive the warning
$gref	The usergroup ID of the team in which this warning is raised (if any)
$lvl	LEVEL_RED or LEVEL_YELLOW to indicate the severity of the warning
$date	If the warning is related to a specific date, this can be indicated here

Clearing a warning

A warning can be cleared with the following function:

function clear($modcode, $subcode, $objref)

$modcode	The module code
$subcode	The subcode
$objref	The object reference ID

This will clear a raised warning, turning yellow or red dots into green dots. If clear is called on a warning which haven't been raised, nothing happens, so the clear function can be called freely without checking if a warning previously have been raised. This should be called if the condition for which the warning was raised, was resolved.

Terminating a warning

A warning can be terminated with the following function:

function terminate($modcode, $subcode, $objref)

$modcode	The module code
$subcode	The subcode
$objref	The object reference ID

This will terminate a warning, making it disappear without a trace or a green dot. This should be called if the condition for which the warning was raised is no longer relevant. Example: If a deadlined todo is closed, the warning should be cleared. If a deadlined todo is deleted, the warning should be terminated.

Modifying the StodoWarning class

When introducing new warning types, the StodoWarning class needs to be modified in two regards:

First the gvd() function needs to be modified in regards to the wtext field, so it provides a valid link which would lead the user to a page, where the warning could be resolved. I.e. If the warning is about a deadlined todo, the wtext field could link to the todo main page.

The second modification is optional, but often needed. This is the maintain() function. This function is called once each day, and should be used to ensure that warnings changing state when the date changes, is updated. I.e. If a todo is deadlined today, and today becomes tomorrow, this function would have to ensure that the warning is updated from YELLOW to RED. Please be aware to check if the appropriate module is installed to prevent DB errors.