Calculating Worktime

Some of the Runtime Views for the Stardust Audit Trail Database contain columns for the duration of activity and process instances as well as for the worktime required for their execution. Hereby, it is assumed, that the worktime is only a fraction of the duration according to the availability of human resources or applications.

The calculation of the worktime normally requires additional specific business logic, which can be provided as an extension of the worktimeCalculator extension point of the org.eclipse.stardust.reporting.common plug-in, which is defined as:

 <extension-point id="worktimeCalculator" name="Worktime Calculator" schema="schema/WorktimeCalculator.exsd"/>

with the schema:

...
<element name="worktimeCalculator"> <complexType> <attribute name="class" type="string" use="required"> <annotation> <documentation> Class implementing the interface org.eclipse.stardust.reporting.common.worktime.IWorktimeCalculator. </documentation> <appInfo> <meta.attribute kind="java" basedOn="org.eclipse.stardust.reporting.common.worktime.IWorktimeCalculator"/> </appInfo> </annotation> </attribute> </complexType> </element>
...

Any extension provided this way is listed in the properties dialog for a Stardust Process Database Datasource:

Worktime Calculator

Hence, a worktime calculator is specified for all views of this datasource. However, you may specify different datasource with different worktime calculators.

Using the Default Worktime Calculator

The org.eclipse.stardust.reporting.common.defaultWorktimeCalculator yields the simple duration of a process or activity instance in seconds. Using this worktime calculator, the worktime equals the duration.

Using the Calendar-based Worktime Calculator

The org.eclipse.stardust.reporting.common.calendarBasedWorktimeCalculator reduces the duration to a daily worktime from 8 to 4 on all days excluding the weekends and all fixed (e.g. New Years Day) and all flexible (e.g. Easter) national German holidays.

If you intend to adjust either the daily worktime or intend to add regional holidays, you may subclass the class org.eclipse.stardust.reporting.common.worktime.CalendarBasedWorktimeCalculator and provide workBeginHour, workEndHour and an array of regions in the protected constructor. For the different regions, you are supposed to use the constants defined in org.eclipse.stardust.reporting.common.worktime.States, e.g.:

public class HessenCalendarBasedWorktimeCalculator extends org.eclipse.stardust.reporting.common.worktime.CalendarBasedWorktimeCalculator
{
public HessenCalendarBasedWorktimeCalculator()
{
super(9, 17, org.eclipse.stardust.reporting.common.worktime.States.HESSEN);
}
}

and add an extension specification accordingly (see below).

Providing an Extension for the worktimeCalculator Extension Point

To provide an extension for the worktimeCalculator extension point, you may add the following extension specification to the plugin.xml of your own plug-in or of the org.eclipse.stardust.reporting.common plug-in:

<plugin
  id="org.eclipse.stardust.reporting.common" ... <runtime> ... <library name="lib/your-custom-worktime-calculators.jar"> <export name="*"/> </library> </runtime> ... <extension point="org.eclipse.stardust.reporting.common.worktimeCalculator" id="your-worktime-calculator"> <worktimeCalculator class="your-worktime-calculator-class"/>
</extension>
</plugin>

The JAR containing your class should be copied to the org.eclipse.stardust.reporting.common plug-in's subdirectory lib. It is registered with the plug-in by the addition of a library tag (shown above).

As indicated in the extension point schema, the class your-worktime-calculator class must implement the interface org.eclipse.stardust.reporting.common.worktime.IWorktimeCalculator with:

package org.eclipse.stardust.reporting.common.worktime;

import java.util.Date;

public interface IWorktimeCalculator { /** * * @param startTimestamp * @param endTimestamp * @param performerID * * @return The worktime between startTimestamp and endTimestamp in seconds. */ long calculateWorktime(Date startTimestamp, Date endTimestamp, String performerID); }

Providing an identifier (attribute id) for the extension is mandatory.

Implementing Calendar-based Worktime Calculators

If your extension implementation is supposed to filter a daily worktime and regional or corporate holidays, you may simply extend the class org.eclipse.stardust.reporting.common.worktime.AbstractCalendarBasedWorktimeCalculator by implementing its method:

protected abstract isHoliday(Calendar currentDate)

e.g.:

protected boolean isHoliday(Calendar currentDate)
{
return isWeekend(currentDate) || (currentDate.get(Calendar.MONTH) == 8 && currentDate.get(Calendar.DAY_OF_MONTH) == 15); // Mexican National Holiday
}

The daily worktime can be provided with the constructor:

public AbstractCalendarBasedWorktimeCalculator(int workBeginHour, int workEndHour)
{
...
}

Other Implementations

You may also use your implementation of org.eclipse.stardust.reporting.common.worktime.IWorktimeCalculator to access corporate databases or Business Rules Engines. For this, you have to make sure that these services can be reached at report design time as well as report generation time, e.g. by providing configurations files with the appropriate connection data.