Рабочее расписание

Примечание

Для использования рабочего расписания необходимо наличие лицензии «features.working-schedule»

Без наличия лицензии рабочее расписание при расчетах будет учитывать только обычные выходные дни без учета производственного календаря.

Рабочее расписание и производственный календарь — два взаимосвязанных инструмента для управления рабочим временем в системе.

  • Производственный календарь фиксирует нерабочие, праздничные и сокращённые дни — то, что отклоняется от стандартного графика.

  • Рабочее расписание определяет обычный распорядок рабочих дней: рабочие дни недели, время начала и окончания, часовой пояс и привязанный производственный календарь.

Совместно они позволяют гибко настраивать рабочий график сотрудников и используются в различных модулях системы — например, для расчёта SLA в модуле «Service Desk».

Рабочее расписание используется для четырех видов операций:

  1. Добавить рабочее время к определенной дате и времени.

  2. Добавить рабочие дни к определенной дате.

  3. Рассчитать количество рабочих дней между двумя датами.

  4. Рассчитать рабочее время между двумя датами.

Привязка рабочего расписания к пользователю или группе

Для привязки рабочего расписания к пользователю или группе нужно создать ассоциацию has-working-schedule:schedule

Часовые пояса

При расчетах на основе рабочего расписания используется следующая логика при обработке часовых поясов:

Если мы делаем расчеты с учетом рабочего времени, то есть следующие варианты:

  1. В дате часовой пояс не указан — используется часовой пояс из рабочего расписания, результат не будет содержать часовой пояс.

  2. В дате часовой пояс указан — дата/время, которые получает сервис, он переводит в часовой пояс рабочего расписания. После выполнения всех операций результат переводится в исходный часовой пояс.

Настройка рабочего расписания

В системе предусмотрены 2 сущности для настройки работы рабочего расписания.

Производственный календарь

Сущность нужна для формирования списка дат, которые изменяют обычный распорядок рабочих дней.

Журнал «Производственный календарь» (Рабочее пространство «Раздел администратора» - Модель) доступен по адресу: v2/journals?journalId=working-calendar&viewMode=table&ws=admin$workspace

../../_images/calendar_1.png

../../_images/calendar_2.png

Атрибуты конфигурации календаря приведены с типами данных Kotlin/Java. В модели ECOS даты хранятся как DATE, ссылки — как ASSOC, а список dates — как множественный JSON.

ID

Тип

Описание

id

String

Идентификатор

extensionFor

EntityRef

Ссылка на календарь, который мы расширяем своей конфигурацией

from

LocalDate

Дата начала действия календаря

until

LocalDate

Дата окончания действия календаря

enabled

Boolean

Активен ли календарь

dates

List<WorkingCalendarDateDto>

Список дней календаря

WorkingCalendarDateDto содержит следующие поля:

ID

Тип

Описание

date

LocalDate

Конкретная дата или дата начала диапазона если задано значение until

until

LocalDate

Дата окончания диапазона (включительно)

type

String

Тип даты или всех дат в диапазоне
Допустимые типы:
WORKING — рабочий день. Имеет смысл указывать, когда выходной день становится рабочим
HOLIDAY — праздник
SHORTDAY — сокращенный на 1ч рабочий день
WEEKEND — выходной
NON_WORKING — не рабочий день

description

MLText

Описание дня или диапазона

Рабочее расписание

Определяет обычный распорядок рабочих дней.

Журнал «Рабочее расписание» (Рабочее пространство «Раздел администратора» - Модель) доступен по адресу: v2/journals?journalId=type$working-schedule&viewMode=table&ws=admin$workspace

../../_images/calendar_3.png

../../_images/calendar_4.png

Атрибуты конфигурации расписания приведены с типами данных Kotlin/Java. В модели ECOS поле version имеет тип NUMBER, name — MLTEXT, а config — JSON.

ID

Тип

Описание

id

String

Идентификатор

name

MLText

Имя расписания

type

String

Тип расписания. Для недельного расписания используется weekly

version

Int

Версия расписания

country

String

Страна

config

ObjectData

Конфигурация для типа расписания

Конфигурация расписания для типа weekly:

ID

Тип

Описание

workingDayStart

LocalTime

Начало рабочего дня

workingDayEnd

LocalTime

Завершение рабочего дня

workingDayTimeZone

ZoneId

Часовой пояс рабочего дня

workingDays

List<DayOfWeek>

Список рабочих дней

workingCalendar

EntityRef

Ссылка на производственный календарь

Использование сервиса WorkingScheduleService в java/kotlin коде

  1. Добавляем сервис ru.citeck.ecos.wkgsch.lib.schedule.WorkingScheduleService как spring бин.

  2. Получаем рабочее расписание используя один из методов для поиска:

fun getScheduleById(id: String)
fun getScheduleForGroup(groupId: String)
fun getScheduleForUser(userName: String)
fun querySchedule(query: WorkingScheduleQuery)
  1. Используя методы интерфейса ru.citeck.ecos.wkgsch.lib.schedule.WorkingSchedule производим вычисления даты и/или времени в зависимости от рабочего расписания:

/**
* This interface stands as a contract for defining working schedules.
* It provides a range of functions that manipulate and interpret dates
* with respect to a working calendar/week - which may vary depending on the locale
* or the specific needs of a business.
*/
interface WorkingSchedule {

    /**
    * Adjusts a given date to its nearest following working day.
    * If the specified date is already a working day, no changes will be made.
    * Note: If the date has time and/or timeZone components, these will be preserved in the returned date.
    *
    * @param date any of date or datetime values Instant, LocalDate, LocalDateTime, OffsetDateTime, ZonedDateTime
    */
    fun <T : Temporal> correctDate(date: T): T

    /**
    * Adjusts a given date to its nearest following working day and then adds specified working days to it.
    * Note: If the date has time and/or timeZone components, these will be preserved in the returned date.
    *
    * @param date any of date or datetime values Instant, LocalDate, LocalDateTime, OffsetDateTime, ZonedDateTime
    */
    fun <T : Temporal> addWorkingDays(date: T, days: Int): T

    /**
    * Computes the number of working days between two dates.
    *
    * @param from the start date from which working days are counted. Accepted values: Instant, LocalDate, LocalDateTime, OffsetDateTime, ZonedDateTime
    * @param to the end date up to which working days are counted. Accepted values: Instant, LocalDate, LocalDateTime, OffsetDateTime, ZonedDateTime
    */
    fun getWorkingDays(from: Temporal, to: Temporal): Int

    /**
    * Adds a specified working time to a certain date.
    *
    * @param date any of date or datetime values Instant, LocalDate, LocalDateTime, OffsetDateTime, ZonedDateTime
    */
    fun <T : Temporal> addWorkingTime(date: T, time: Duration): T

    /**
    * Get working time between two dates.
    *
    * @param from the start time from which working time are counted. Accepted values: Instant, LocalDateTime, OffsetDateTime, ZonedDateTime
    * @param to the end time up to which working time are counted. Accepted values: Instant, LocalDateTime, OffsetDateTime, ZonedDateTime
    */
    fun getWorkingTime(from: Temporal, to: Temporal): Duration
}

Records API в браузере и при использовании в BPMN процессе

Во всех примерах явно выбрано расписание DEFAULT. В поставляемой конфигурации оно задаёт рабочие дни с понедельника по пятницу, время 09:00–17:00, часовой пояс +03:00 и ссылку на производственный календарь emodel/working-calendar@RU.

Примечание

Результаты зависят от настроек расписания и активных расширений производственного календаря с учётом лицензионных условий, описанных выше. Базовая конфигурация календаря RU содержит идентификатор и описание. Праздники 2023 года приведены в файле примера RU-2023.yml.sample. Для их учёта необходимо загрузить соответствующую конфигурацию календаря и включить её. Наличие файла примера в исходниках само по себе не означает, что календарь настроен в системе.

Добавить рабочее время

await Records.queryOne({
    sourceId: 'emodel/working-schedule-action',
    query: {
        type: 'add-working-time',
        config: {date: '2023-03-05T14:00:00', time: '10h'},
        query: {scheduleId: 'DEFAULT'}
    }
}, "data")
Records.query({
    sourceId: 'emodel/working-schedule-action',
    query: {
        type: 'add-working-time',
        config: {date: '2023-03-05T14:00:00', time: '10h'},
        query: {scheduleId: 'DEFAULT'}
    }
}, 'data').records[0].data

Запрос возвращает дату и время после добавления 10 рабочих часов. В обеих вкладках используются одинаковые входные данные без указания часового пояса.

Добавить рабочие дни

await Records.queryOne({
    sourceId: 'emodel/working-schedule-action',
    query: {
        type: 'add-working-days',
        config: {date: '2023-03-05', days: 10},
        query: {scheduleId: 'DEFAULT'}
    }
}, "data")
Records.query({
    sourceId: 'emodel/working-schedule-action',
    query: {
        type: 'add-working-days',
        config: {date: '2023-03-05', days: 10},
        query: {scheduleId: 'DEFAULT'}
    }
}, 'data').records[0].data

Запрос возвращает дату после добавления 10 рабочих дней с учётом выбранного расписания и производственного календаря.

Рассчитать количество рабочих дней между двумя датами

await Records.queryOne({
    sourceId: 'emodel/working-schedule-action',
    query: {
        type: 'get-working-days',
        config: {from: '2023-03-05', to: '2023-03-21'},
        query: {scheduleId: 'DEFAULT'}
    }
}, "data")
Records.query({
    sourceId: 'emodel/working-schedule-action',
    query: {
        type: 'get-working-days',
        config: {from: '2023-03-05', to: '2023-03-21'},
        query: {scheduleId: 'DEFAULT'}
    }
}, 'data').records[0].data

Запрос возвращает количество рабочих дней за указанный период с учётом выбранного расписания и производственного календаря.

Рассчитать рабочее время между двумя датами

await Records.queryOne({
    sourceId: 'emodel/working-schedule-action',
    query: {
        type: 'get-working-time',
        config: {from: '2023-03-05T00:00:00', to: '2023-03-21T00:00:00'},
        query: {scheduleId: 'DEFAULT'}
    }
}, "data")
Records.query({
    sourceId: 'emodel/working-schedule-action',
    query: {
        type: 'get-working-time',
        config: {from: '2023-03-05T00:00:00', to: '2023-03-21T00:00:00'},
        query: {scheduleId: 'DEFAULT'}
    }
}, 'data').records[0].data

Запрос возвращает длительность рабочего времени за указанный период. Длительность представляется в формате ISO 8601: например, PT80H означает 80 часов. Конкретное значение зависит от выбранного расписания и производственного календаря.

Во всех запросах есть поле query, которое может иметь следующие поля:

ID

Тип

Описание

user

String

Пользователь, для которого нам нужно найти рабочее расписание.
Если расписание для пользователя не найдено, то берется DEFAULT.

group

String

Группа, для которой нам нужно найти рабочее расписание.
Если расписание для группы не найдено, то берется DEFAULT.

scheduleId

String

Идентификатор конкретного рабочего расписания.
Если задан, то user и group игнорируются.
Примеры идентификатора: „DEFAULT“, «some-id»