Проверки на основе формул

Проверки на основе формул#

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

Механизм разделяет подготовку данных и условие проверки. Источники данных и аргументы определяют, какие значения необходимо получить и рассчитать, а JEXL-формула задает бизнес-условие, которое применяется к этим значениям.

В обычном JEXL-скрипте получение данных, их отбор, расчеты и дальнейшая обработка задаются кодом скрипта. В формульной проверке подготовка данных настраивается через источники и аргументы, а JEXL используется для описания проверяемого условия.

Например, после определенного этапа закрытия периода можно рассчитать конечное сальдо отдельно по каждому МВЗ и проверить условие Balance == 0. Если хотя бы для одного МВЗ условие не выполнено, итоговый результат проверки становится отрицательным и может использоваться для остановки дальнейшего выполнения сценария.

Принцип работы#

Для проверки настраиваются один или несколько аргументов. Каждый аргумент получает значение одним из способов:

  • Агрегация источника данных — значение рассчитывается по зарегистрированному источнику данных;

  • Запуск программы — значение рассчитывает отдельная программа.

Для аргумента с агрегацией выбираются источник данных, требуемый показатель, условия отбора, функция агрегации и при необходимости группировка. Источник определяет, какие показатели и поля группировки доступны для настройки.

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

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

В упрощенном виде выполнение проверки происходит в следующем порядке:

Источник данных и настройки аргумента
или отдельная программа
→ значение аргумента
→ наборы значений
→ JEXL-формула
→ общий результат проверки
→ системный сценарий или прикладная бизнес-логика

Предварительные требования#

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

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

Для подключения проверки к системному сценарию пользователь должен иметь доступ к настройке этого сценария.

Настройка проверки#

Проверки настраиваются в выборке Bts_FormulaCheck.

Создание проверки#

Чтобы создать проверку:

  1. Создайте запись в выборке Bts_FormulaCheck.

  2. В поле Код укажите уникальное системное имя проверки.

  3. В поле Наименование укажите наименование проверки.

  4. Настройте формулу.

  5. Добавьте аргументы, используемые в формуле.

  6. Сохраните проверку.

Настройка формулы#

В области JEXL-код укажите формулу, которая возвращает значение типа Boolean.

Для обращения к аргументам используются их системные имена.

Например:

abs(Arg) > 100

Здесь Arg — системное имя аргумента проверки.

В области Операторы отображаются доступные операторы JEXL и их назначение.

Настройка аргументов#

Аргументы хранятся в коллекции Bts_FcArgument на закладке Аргумент проверки.

Чтобы открыть аргументы ранее созданной проверки, дважды щелкните запись в списке или выберите запись и нажмите Редактировать.

Поддерживаются два типа аргументов:

Тип аргумента

Когда использовать

Агрегация источника данных

Значение рассчитывается по зарегистрированному источнику данных с помощью функции агрегации

Запуск программы

Значение рассчитывает отдельная программа

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

Условия отбора#

Для каждого аргумента можно настроить собственные условия отбора данных.

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

Условия задаются на селекционном экране аргумента и сохраняются в варианте запуска.

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

Агрегация источника данных#

Для аргумента типа Агрегация источника данных указываются:

Настройка

Назначение

Источник данных

Определяет класс и набор данных, из которого выбираются исходные записи

Функция агрегации

Определяет способ расчета значения

Атрибут результата

Определяет рассчитываемый показатель

Атрибуты группировки

Определяют разрез, в котором формируются отдельные значения

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

Выполняет получение и расчет данных аргумента

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

Для расчета доступны функции:

  • sum — сумма;

  • max — максимальное значение;

  • min — минимальное значение;

  • count — количество строк;

  • avg — среднее значение.

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

Доступные поля источника определяются в Bts_FcAggregationSourceAttr. Для каждого поля задается выражение получения значения и допустимый способ использования.

Системный признак bIsResult разрешает использовать поле в качестве Атрибута результата, а bIsGroupBy — в качестве Атрибута группировки.

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

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

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

Запуск программы#

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

Для аргумента указываются:

  • Процедура оболочки — программа, рассчитывающая значение аргумента;

  • Вариант запуска — сохраненные параметры выполнения программы.

Вариант запуска становится доступным после выбора процедуры оболочки.

Подключение проверки#

Для запуска формульных проверок используется общая сервис-оболочка Выполнение проверки.

Конкретная проверка выбирается в параметрах запуска. Этот выбор можно сохранить в варианте запуска и использовать при подключении проверки к системному сценарию.

Подключение к прикладной бизнес-логике#

Формульную проверку можно запускать из прикладной бизнес-логики через механизм сервис-оболочек.

Метод выполнения проверки не возвращает итоговый Boolean непосредственно вызывающему коду. Результат сохраняется в Bts_FormulaCheckExec.

Выполнение проверки#

Сопоставление аргументов#

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

Формирование ключа#

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

Если настроена группировка, ключ формируется по значениям атрибутов группировки. При использовании нескольких полей группировки ключ составляется из значений этих полей.

Например, два аргумента рассчитываются по МВЗ:

Ключ

Balance

Turnover

МВЗ 01

0

150000

МВЗ 02

200

87000

Для ключа МВЗ 01 значения Balance и Turnover попадают в один набор и доступны одной JEXL-формуле. Аналогично формируется отдельный набор для МВЗ 02.

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

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

Если для существующего ключа один из аргументов не вернул значение, соответствующая переменная отсутствует в контексте JEXL. Формула должна учитывать возможность отсутствия переменной, иначе ее выполнение завершится ошибкой.

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

Результат проверки#

Для каждого сформированного набора значений выполняется JEXL-формула.

Формула возвращает:

  • true — условие выполнено;

  • false — условие не выполнено.

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

Если хотя бы для одного набора формула вернула false, итоговый результат равен false.

Примечание

Если аргументы настроены, но не сформировали ни одного набора значений, проверка считается успешно пройденной. JEXL-формула в этом случае не выполняется, а результат сохраняется как true.

Если в проверке не настроено ни одного аргумента, выполнение завершается ошибкой В проверке отсутствуют аргументы.

Итоговый результат сохраняется в записи выполнения проверки Bts_FormulaCheckExec.

Журнал выполнения#

История запусков отображается на закладке Журнал выполнения в карточке проверки.

В журнале указываются:

  • дата и время запуска;

  • проверка;

  • пользователь;

  • результат выполнения.

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

Для наборов, по которым формула вернула false, создается сообщение об ошибке.

На селекционном экране запуска проверки можно выбрать режим вывода сообщений:

  • Вывести все сообщения (ALL);

  • Вывести ошибки (ERROR).

Подробные результаты отображаются в выборке Bts_FcExecReportAvi.

Если проверка выполняется как шаг сценария закрытия, журнал проверки используется для отображения результата выполнения этого шага.

Сведения о выполнении проверки хранятся в Bts_FormulaCheckExec, сведения о расчете отдельных аргументов — в Bts_FcArgumentExec.

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

Пример использования#

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

Для проверки используется зарегистрированный источник Регистр проводок. В нем определены показатели, доступные для расчета аргументов.

Создайте аргумент со следующими параметрами:

Параметр

Значение

Код

Balance

Тип аргумента

Агрегация источника данных

Источник данных

Регистр проводок

Функция агрегации

sum

Атрибут результата

Сальдо на конец, сумма в НВ

Атрибут группировки

МВЗ

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

В формуле проверки укажите:

Balance == 0

Для подключения проверки к сценарию закрытия периода:

  1. Откройте Контроллинг > Настройка > Сценарии закрытия.

  2. Добавьте задачу типа Запуск программы.

  3. В качестве процедуры оболочки выберите Выполнение проверки.

  4. Укажите вариант запуска, в котором выбрана созданная формульная проверка.

  5. Сохраните сценарий.

При выполнении шага система отбирает записи регистра проводок, рассчитывает конечное сальдо с группировкой по МВЗ и передает полученные значения в JEXL как аргумент Balance. Получение записей, отбор по условиям и группировка выполняются настройками аргумента, а формула работает с уже рассчитанным значением.

Например, получены следующие значения:

МВЗ

Balance

МВЗ 01

0

МВЗ 02

0

МВЗ 03

1250

Для МВЗ 01 и МВЗ 02 формула возвращает true.

Для МВЗ 03 формула возвращает false, поэтому итоговый результат проверки также равен false.

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

Содержание