Time management

Automatic reminders are essential to a workflow process. Even though the workflow editor provides a simple and flexible way to configure these, it is important to have a clear view of the different timed events that can occur during a manual activity. These events can be listed in the order in which they can occur as follow:

• Task creation (with or without initial notification)
• Reminder notifications
• Escalation (with or without escalation notification)
• Escalation reminder notifications
• Task expiration

None of these events are mandatory, and they can all be set independently of one another. For example, you can have reminder notifications even if you chose not to have an initial notification at the task creation. You can also set an escalation timer for the task even without reminder or escalation notifications. The important rule here is that all the events that are set will happen precisely in the order above. It is not possible for instance (and, indeed, the configuration guarantees this) for a task to expire if there are remaining notifications to be sent.

Procedure

Automatic notifications are configured in two sub-tabs of the properties tab (see bellow) of your manual task:

• Role/Reminder

• Escalation

To configure reminders and/or escalations it is necessary to have defined beforehand in the configuration tab of the workflow:

• Roles, i.e. the people that shall receive the reminders and the escalation e-mails
• Process emails

Reminders

Reminders are e-mails sent to the role that should perform the manual task. The configuration itself is pretty self-explanatory: you set a role that will set the candidates for the task, and set a mail if you want an initial notification when the task becomes available.

You can define three types of emails:

• The initial notification: The first email sent, describing the processes that should be preformed for example
• The reassignment e-mail: In a workflow it is possible to reassign a task to a new user. The selected e-mail will then be sent
• The reminder e-mail

You then set the number of reminders, the wait period between each notification and either a start date or an end date.

There are indeed two different ways of setting up reminders:

• starting from the task creation, sending notifications at a regular interval after a certain duration
• sending notifications at a regular interval until you reach a certain date

The first one can be sketched like this:

The second one can be represented like this:

The second method is a bit more complex to understand if you send multiple reminders.
The standard case would be to send only one notification before a given due date (note: this is not necessarily related to the due date that you can set in the Activity tab for the task, which is only declarative and more aimed at documenting the process). If you send more than one notification, the duration before the due date will be repeated backward in time to send the other reminders. Only the reminders that can be scheduled before the task creation will be sent (e.g. if you program 100 reminders each day and only have a week to complete the task, only 6 of them will be sent).

Timed events (reminder notifications, task expiration, escalation, ...) can be measured in days or months.
For short span events, however, this can prove cumbersome as precious time can be wasted if they are fired on a day where the people involved cannot complete their work. For instance, if a task has to be completed in a week, and a reminder notification has to be sent 3 days before that, if the notification is sent on a Sunday then the people will have only 2 days, and not 3 to complete their work. The workflow calendar can help address this issue. It can be found in the project configuration, in the 'Workflow' tab.

Here you can select which days of the week are considered working days. Then, in the workflow editor, instead of selecting 'days' as your unit of time, you can select 'business days'. This will automatically ensure that the events are only fired on the working days selected in the calendar. For the previous example, and with working days being monday to friday, this means that we would have to set the task to expire in 5 business days (a standard working week), and the reminder notification to trigger 3 business days before that.

Escalation

There are a lot of similarities with the Role/Reminder tab. Indeed, escalation notifications have the same configuration as standard reminders. The only difference is that we can add an initial delay before the task escalates, then configure reminders as explained above. If we consider the first reminder configuration, this would result in something like this:

Of course, the escalation reminders will be sent to the recipients defined in the escalation role, as long as the mail has been properly configured to include the task role.

Task Expiration

The last event that can be triggered on a manual activity is to have the task expire after a certain duration. This is configured in the Role/Reminder tab, and the duration will expand from the last event:

• Task creation
• Last reminder notification
• Escalation
• Last escalation reminder notification

The expiration will trigger if the task has not been completed before the timer runs off, regardless of the state of the task (claimed, escalated, etc).
It will result in the task being terminated, and the process will proceed forward by following the error links (colored in red) that flow from the expired activity. It will not follow the standard links.
This means that if no outgoing error link has been defined the process execution will terminate prematurely.

A proper design will always ensure that there is at least one error link for every activity that can expire, even if it only connects to the process end activity, otherwise you might miss important execution steps as the ticket updates.

Known limitations

When a timer expires, the execution of the workflow will only follow the outgoing error links. furthermore, this feature is no compatible with an iteration of an activity.

There is a field named 'Due date' in the Activity tab of a manual task or the process start task (see caption). This value is NOT related to the task expiration that is set in the Role / Reminder tab as explained in the following page: Reminders, Escalation and task expiration.

The due date will not be used during the process execution, and is in no way a constraint on the process execution. It only serves documentation purposes, and is available for reporting or displayed in process administration.

The due date of a start task indicates an estimated due date of the process, whereas, the due date of a manual task that of the task itself.

Handling dates and time spans has been made a lot easier by the addition of a few choice javascript functions. The following tips also apply to the date attributes in the discovery and collector editors.

Switching between Date and LDAP String formats

As you may already know from collecting data using the discovery and collector modules, the dates in the iGRC database are stored in LDAP string format, e.g. the 1st of february 1997 will be stored as the string 19970201. This means that, depending on the situation, you may find yourself handling dates that are either defined as a Javascript Date object, or as a raw LDAP String. You can switch seamlessly between the two formats by using the following syntax:

• To get the LDAP String representation of the javascript Date object (or Date attribute) mydate : mydate.toLDAPString()
• To get a Date object from an LDAP string mystring : fromLDAPString(mystring)

Getting the current date

• To get the current date as a Date object : new Date()
• To get the current date as an LDAP String object : (new Date()).toLDAPString()

Beware that this will compute the date at the time of execution of the script or macro, which might not be what you want. For instance, if used in a macro in a workflow timed event such as a reminder notification, this will yield the date when the activity is created (since all timers are resolved at activity creation), whereas if used in the Updates section of the same activity, it will yield the date when the activity is completed (since the macros and scripting functions are executed after task completion). We advise extreme caution when using this, and as a general rule recommend whenever possible to use other means to get event dates in a workflow process, such as retrieving it in a variable from the activity outputs.

Adding/subtracting a time span to a date

This function is only accessible on a proper Date object or attribute (not an LDAP String, or any other type like a long numeral). On such an object, simply use the syntax : mydate.add(unit,value)

unit is a string giving the time unit in which to measure the span. Valid units are:

• "s" for seconds
• "m" for minutes
• "H" for hours
• "d" for days
• "M" for months
• "y" for years

value is the number of time units to be added to the date. Using a negative value allows to subtract time as well.

Examples

Subtracting ten years to a given date : mydate.add("y",-10) Adding 3h30mn to a given date : mydate.add("h",3).add("m",30)

Computing the time span between two dates

You may have to write conditions such as "the time lapse between date1 and date2 cannot be more than 3 days". This is easily done using a function computing the time span between two dates in any of the previously described time units. Once again, this function can only be called on a proper Date object or attribute.

To compute the number of days between date1 and date2, use the syntax : date1.diff(date2, "d")

Please note that this will actually compute date1-date2, not the other way around, and can yield a negative result if date2 is more recent. The previous condition can be written as : date1.diff(date2,"d")<=3