api.timing Работа с временными характеристиками и счетчиками времени

Временные характеристики

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

  • api.timing.serviceStartTime(serviceTime, timeZone)

    Получение ближайшей даты начала обслуживания (1).

    Параметры метода:

    • serviceTime — код элемента справочника "Классы обслуживания"
    • timeZone — код элемента справочника "Часовые пояса"

    Возвращает ближайшее время начала обслуживания (на основе текущей даты).

  • api.timing.serviceStartTime(startDateTime, serviceTime, timeZone)

    Получение ближайшей даты начала обслуживания (2).

    Параметры метода:

    • startDateTime — дата, к которой необходимо найти ближайшее время начала периода обслуживания
    • serviceTime — код элемента справочника "Классы обслуживания"
    • timeZone — код элемента справочника "Часовые пояса"

    Возвращает ближайшее время начала обслуживания, на основе указанной даты (startDateTime).

    Пример. Скрипт, определяющий попадает ли текущая дата в рабочее время.

    Copy 
    def serviceCall = ... //берем запрос
    def startDateTime = new Date() //берем текущую дату
    def serviceStartTime = api.timing.serviceStartTime(startDateTime, serviceCall.serviceTime, serviceCall.timeZone) //вычисляем от нее ближайшую дату начала обслуживания
    if(startDateTime == serviceStartTime)
    {
    //дата попадает в рабочее время
    }
    else
    {
    //дата попадает в НЕ рабочее время
    }

  • api.timing.serviceEndTime(serviceTime, timeZone, startTime, interval)

    Получение вычислимой даты сервисного времени окончания периода обслуживания.

    Параметры метода:

    • serviceTime — элемент или код элемента справочника "Классы обслуживания"
    • timeZone — элемент или код элемента справочника "Часовые пояса"
    • startTime — время, от которого необходимо начать отсчитывать период обслуживания
    • interval — период обслуживания (количество миллисекунд, целое число)

    "serviceTime" и "timeZone" либо оба являются кодом элемента справочника, либо оба — элементы справочника

    Возвращает время окончания обслуживания.

  • api.timing.serviceTime(serviceTime, timeZone, startTime, endTime)

    Получение регламентного периода обслуживания. Вычисляется разница между датами начала и окончания с учетом класса обслуживания, т.е. учитываются только рабочие часы по классу обслуживания.

    Параметры метода:

    • serviceTime — элемент или код элемента справочника "Классы обслуживания"
    • timeZone — элемент или код элемента справочника "Часовые пояса"
    • startTime — время, от которого необходимо начать отсчитывать период обслуживания
    • endTime — время окончания периода обслуживания

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

Счетчики времени

  • api.timing.timerDefinition(fqn, attrCode)

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

    Параметры метода:

    • fqn — fqn класса, содержащего атрибут-счетчик
    • attrCode — код атрибута типа "Счетчик времени" (прямой или обратный), для которого нужно получить описание.

  • Параметры счетчика времени, полученного при помощи метода api.timing.timerDefinition:

    • timerDef.getCode() — Код счетчика
    • timerDef.getTitle() — Название счетчика
    • timerDef.getDescription() — Описание счетчика
    • timerDef.getResolutionTimeAttribute() — Код атрибута, выбранного в поле "Промежуток времени" счетчика
    • timerDef.getServiceTimeAttribute() — Код атрибута, выбранного в поле "Класс обслуживания" счетчика
    • timerDef.getTimeMetric() — Код атрибута, выбранного в поле "Метрика времени" счетчика
    • timerDef.getTimeZoneAttribute() — Код атрибута, выбранного в поле "Часовой пояс" счетчика
    • timerDef.isRemoved() — Признак архивности счетчика
    • timerDef.isSystem() — Является ли счетчик системным.

  • api.timing.parseDate(text)

    Формирование даты по текстовому представлению.

    Возвращает дату по тексту в формате "dd.MM.yyyy HH:mm:ss"

Работа с календарными датами, с учетом класса обслуживания

  • api.timing.addWorkingDays(date, amountOfDays, serviceTime, timeZone)

    Добавление рабочих дней к текущей дате (отнимание рабочих дней от текущей даты).

    Параметры метода:

    • date — дата/дата-время, к которой применяется перерасчет. Возможно указание значения null. Если дата не указана (передан null), то пересчет применяется к текущей дате.

      Для корректной работы метода в формате "дата" должен быть указан часовой пояс, который будет передан в параметре timeZone.

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

      Пример формата с указанием часового пояса:

      String strDate = "28/10/2023 22:00:00 +0500"
def myDate = new Date().parse("d/M/yyyy H:m:s Z", strDate)
    • amountOfDays — количество добавляемых рабочих дней (целое положительное число), количество отнимаемых рабочих дней (целое отрицательное число).
    • serviceTime — элемент справочника "Классы обслуживания". Необходимо передавать информацию об элементе справочника в качестве объекта, но не UUID
    • timeZone — элемент справочника "Часовые пояса". Необходимо передавать информацию об элементе справочника в качестве объекта, но не UUID. Возможно указание значения null. Если значение параметра null, то берется часовой пояс сервера.

    Возвращает пересчитанное значение даты-времени.

    Особенности работы метода:

    • Если время в полученном дне недоступно, то функция вернет значение в зависимости от параметра amountOfDays:

      • amountOfDays > 0, функция вернет первую секунду следующего рабочего периода;
      • amountOfDays < 0, функция вернет последнюю секунду предшествующего рабочего периода.

      Например, в системе задан класс обслуживания с периодами обслуживания пн-пт с 9:00 до 14:00 и с 15:00 до 18:00.

      На вход в метод передана пятница 14:30, к ней прибавлен 1 рабочий день. Будет получен понедельник 14:30. Но это время не попадает в период обслуживания, поэтому метод вернет первую секунду следующего рабочего периода, т.е. понедельник 15:00.

    • Если в метод переданы дата-время начала/конца рабочего дня, то результат работы метода сдвигается на 1 рабочий день от искомого.

      Например, для вторника, 23 апреля 09:00:00, результатом вычитания одного дня будет не понедельник, 22 апреля 09:00:00, а пятница, 19 апреля 17:00:00:

      Copy 
      def serviceTime = utils.findFirst('serviceCall', [:]).serviceTime
      def timeZone = utils.findFirst('serviceCall', [:]).timeZone

      String theDate = "23/04/2024"
      def date = new Date().parse("d/M/yyyy", theDate)

      use(groovy.time.TimeCategory){
      def startToday =  api.timing.getStartOfWorkingDay(date, serviceTime, timeZone) //Tue Apr 023 09:00:00 MSK 2024
      def startPrevWorkDay = api.timing.addWorkingDays(startToday, -1, serviceTime, timeZone) //Fri Apr 19 17:00:00 MSK 2024
      }

      Чтобы получить искомый рабочий день (понедельник), необходимо к дате-времени, к которой применяется перерасчет, добавить 1 секунду:

      Copy 
      use(groovy.time.TimeCategory){
      def startToday =  api.timing.getStartOfWorkingDay(date, serviceTime, timeZone)+ 1.second //Tue Apr 023 09:00:00 MSK 2024
      def startPrevWorkDay = api.timing.addWorkingDays(startToday, -1, serviceTime, timeZone) //Mon Apr 022 09:00:01 MSK 2024
      }

  • api.timing.addWorkingHours(date, amountOfHours, serviceTime, timeZone)

    Добавление рабочих часов к текущей дате (отнимание рабочих часов от текущей даты).

    Параметры метода:

    • date — дата /дата-время, к которой применяется перерасчет. Возможно указание значения null. Если дата не указана (передан null), то пересчет применяется к текущей дате.
    • amountOfHours — количество добавляемых рабочих часов (целое положительное число), количество отнимаемых рабочих часов (целое отрицательное число).
    • serviceTime — элемент справочника "Классы обслуживания". Необходимо передавать информацию об элементе справочника в качестве объекта, но не UUID
    • timeZone — элемент справочника "Часовые пояса". Необходимо передавать информацию об элементе справочника в качестве объекта, но не UUID. Возможно указание значения null. Если значение параметра null, то берется часовой пояс сервера.

    Возвращает пересчитанное значение даты-времени.

  • api.timing.getStartOfWorkingDay(date, serviceTime, timeZone)

    Получение начала рабочего дня.

    Параметры метода:

    • date — дата, для которой необходимо найти начало рабочего дня. Возможно указание значения null. Если дата не указана (передан null), то пересчет применяется к текущей дате
    • serviceTime — элемент справочника "Классы обслуживания". Необходимо передавать информацию об элементе справочника в качестве объекта, но не UUID
    • timeZone — элемент справочника "Часовые пояса". Необходимо передавать информацию об элементе справочника в качестве объекта, но не UUID. Возможно указание значения null. Если значение параметра null, то берется часовой пояс сервера.

    Возвращаемое значение: первая рабочая секунда указанного дня. null — если день нерабочий.

  • api.timing.getStartOfWorkingMonth(date, serviceTime, timeZone)

    Получение начала рабочего месяца.

    Параметры метода:

    • date — дата, для которой необходимо найти начало рабочего месяца. Возможно указание значения null. Если дата не указана (передан null), то пересчет применяется к текущей дате
    • serviceTime — элемент справочника "Классы обслуживания". Необходимо передавать информацию об элементе справочника в качестве объекта, но не UUID
    • timeZone — элемент справочника "Часовые пояса". Необходимо передавать информацию об элементе справочника в качестве объекта, но не UUID. Возможно указание значения null. Если значение параметра null, то берется часовой пояс сервера.

    Возвращаемое значение: первая рабочая секунда указанного месяца. null — если месяц не содержит рабочих дней.

  • api.timing.getStartOfWorkingYear(date, serviceTime, timeZone)

    Получение начала рабочего года.

    Параметры метода:

    • date — дата, для которой необходимо найти начало рабочего года. Возможно указание значения null. Если дата не указана (передан null), то пересчет применяется к текущей дате
    • serviceTime — элемент справочника "Классы обслуживания". Необходимо передавать информацию об элементе справочника в качестве объекта, но не UUID
    • timeZone — элемент справочника "Часовые пояса". Необходимо передавать информацию об элементе справочника в качестве объекта, но не UUID. Возможно указание значения null. Если значение параметра null, то берется часовой пояс сервера.

    Возвращаемое значение: первая рабочая секунда указанного года. null — если год не содержит рабочих дней.

  • api.timing.getEndOfWorkingDay(date, serviceTime, timeZone)

    Получение конца рабочего дня.

    Параметры метода:

    • date — дата, для которой необходимо найти конец рабочего дня. Возможно указание значения null. Если дата не указана (передан null), то пересчет применяется к текущей дате
    • serviceTime — элемент справочника "Классы обслуживания". Необходимо передавать информацию об элементе справочника в качестве объекта, но не UUID
    • timeZone — элемент справочника "Часовые пояса". Необходимо передавать информацию об элементе справочника в качестве объекта, но не UUID. Возможно указание значения null. Если значение параметра null, то берется часовой пояс сервера.

    Возвращаемое значение: первая рабочая секунда указанного дня. null — если день нерабочий.

  • api.timing.getEndOfWorkingMonth(date, serviceTime, timeZone)

    Получение конца рабочего месяца.

    Параметры метода:

    • date — дата, для которой необходимо найти конец рабочего месяца. Возможно указание значения null. Если дата не указана (передан null), то пересчет применяется к текущей дате
    • serviceTime — элемент справочника "Классы обслуживания". Необходимо передавать информацию об элементе справочника в качестве объекта, но не UUID
    • timeZone — элемент справочника "Часовые пояса". Необходимо передавать информацию об элементе справочника в качестве объекта, но не UUID. Возможно указание значения null. Если значение параметра null, то берется часовой пояс сервера.

    Возвращаемое значение: первая рабочая секунда указанного месяца. null — если месяц не содержит рабочих дней.

  • api.timing.getEndOfWorkingYear(date, serviceTime, timeZone)

    Получение конца рабочего года.

    Параметры метода:

    • date — дата, для которой необходимо найти конец рабочего года. Возможно указание значения null. Если дата не указана (передан null), то пересчет применяется к текущей дате
    • serviceTime — элемент справочника "Классы обслуживания". Необходимо передавать информацию об элементе справочника в качестве объекта, но не UUID
    • timeZone — элемент справочника "Часовые пояса". Необходимо передавать информацию об элементе справочника в качестве объекта, но не UUID. Возможно указание значения null. Если значение параметра null, то берется часовой пояс сервера.

    Возвращаемое значение: первая рабочая секунда указанного года. null — если год не содержит рабочих дней.