calcDeadline

Calculate the earliest date and time that a deadline can be completed. A starting time (start-date-time) and a duration for the task must be given.

If the duration does not specify hours, minutes, or seconds, then it is assumed to be in working days. See Duration Definitions. Days with too little working time do not count as working days; see Minimum Hours in Working Day Calculations.

The calendarLookAhead property in the dac.properties file determines how far ahead in the calendar the calculation algorithm looks to take account of entries that would affect the duration of a task. See "Configuring TIBCO ActiveMatrix BPM Deadline and Calendar Properties" in TIBCO ActiveMatrix BPM Administration for details of this property.

The request may optionally also include a collection of identifiers from which a calendar can be resolved. There can be any number of these, each line being one of:

  • A calendar reference.
  • Information identifying an entity within an organization model which is the participant for the task. An organizational entity may be associated at design time with a particular calendar.

If these identifiers do not define a calendar to be used, then the default Base calendar is used to calculate the deadline.

Once the operation has determined which base and overlay calendars are to be used for the deadline calculation, it determines the available working hours in those calendars. Using that information, the operation calculates and returns the earliest time at which work of the given duration can be completed.

Duration Definitions

Depending on how a duration parameter is expressed, it may be interpreted either as elapsed time, or as a number of working days.

  • If the duration parameter is specified only in years, months, weeks, and/or days, but does not specify hours, minutes, or seconds, then it is assumed to be in working days. For example:
    • the duration P3D is taken to be three working days, not 72 hours.
    • P1M is interpreted as 31 working days (regardless of the number of days in the actual month in which the period occurs).
    • Similarly, P1Y is 365 working days.
  • When a deadline calculation is made in terms of working days, the calculation takes account of the start-date-time to check whether the current day has enough working hours remaining to count as a working day (see Minimum Hours in Working Day Calculations). If it does not, the next available business day is used as the first working day in the calculation. The final result will then be the start of the first available day following the requested number of working days.

    For example, if the working day is defined as being from 08:00 to 17:00, and minimum working hours value is defined as 5, a calculation with a start-date-time before 12:00 noon on the current day will treat the current day as a working day. If the duration is P1D, the calculation would return a deadline of the next business day at 08:00.

    However if the start-date-time is after 12:00 noon on the current day, there are less than five hours remaining in the business day, and so there are no longer enough hours to count the current day as a working day. The calculation then treats the next business day as the first available working day, and the start of the working day after that would be returned as the deadline.

  • If the duration parameter is specified only in hours, minutes, or seconds, then it is assumed to indicate elapsed time. So if the duration were PT72H then it would be taken to be 72 elapsed hours, not three working days.
  • If days (or months, or years) is specified in combination with any of hours, minutes, or seconds, then the duration is taken to be elapsed time and a day is taken as 24 hours. For example, P3D1H would be 73 hours. P1D represents one working day; P1D1H is 25 hours.

Minimum Hours in Working Day Calculations

Each base calendar holds a value that defines the minimum number of hours in a working day (see the Parameter notes to saveCalendar for details of min-hours). This may differ from the normal business hours defined by the day-of-week and time-slot entries in the same base calendar.

When a deadline is being calculated in working days, if the number of available hours in a day being considered is less than the defined minimum hours, that day is not included as a working day, and the calculation moves on to the next available day; where, again, the number of available hours is compared. The final result will be the start of the available day following the requested number of working days.

For example, if the normal working day is defined as eight hours for Mondays to Fridays, and min-hours is defined as four hours:

  • Saturdays and Sundays are ignored for deadline calculation because they have fewer working hours (0) than the min-hours value. The deadline calculation moves on to the Monday, where the number of available hours is compared with the minimum.
  • A day with a six-hour exclusion defined for a training session will be ignored, as this brings the available working hours down below the min-hours value. The deadline calculation moves on to the next available day, where again the number of available hours is compared with the minimum.
Required System Action
readCalendars
API Descriptions