Параметры

Для большинства сущностей в системе возможно определение настраиваемых параметров. Редактирование перечня параметров осуществляется в оснастке Администрирование⇒Параметры интерфейса администратора. Выбор сущности, для которой определяются параметры, производится в выпадающем списке. Список сущностей может расширяться при установке плагинов.

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

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

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

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

# коды параметров сущности, которые должны быть заполнены перед установкой данного параметра
requireBeforeFillParamIds=<codes>
# коды параметров сущности, которые должны быть пустыми перед установкой данного параметра
requireBeforeEmptyParamIds=<codes>
# теги параметра через запятую - тегированный параметр можно просматривать или править
# только явно разрешив тег в настройке прав на изменение параметра либо просмотр параметров
tags=<tags>
# редактор параметра недоступен (параметр загружается посредством API к БД либо HTTP API)
readonly=1

Где:

<codes> - коды параметров через запятую;
<tags> - теги через запятую.

Группы параметров контрагентов

Группа параметров необходима для ограничения списка параметров контрагента определённого объекта. Например: "Физическое лицо", "Юридическое лицо".

Шаблоны названия контрагентов

Шаблон названия позволяет устанавливать зависимость названия объектов от его параметров. Подстановка параметров осуществляется макросами вида ${param_<code>}, где <code> - уникальный код параметра. Так, например, возможна генерация названия контрагента юридического лица из параметров спискового "Форма собственности" и текстового "Наименование организации", что предотвращает дублирование информации. При изменении параметров в дальнейшем наименование объекта будет правиться автоматически.

Параметр типа "text"

Однострочная строка до 250 символов.

В конфигурации параметра могут быть указаны следующие необязательные параметры:

saveOn=<saveOn>
# параметр содержит URL, в просмотре параметров отображение ссылки перехода по ссылке
showAsLink=1
# вместо значение параметра выводится <ЗНАЧЕНИЕ ЗАШИФРОВАНО>, параметр можно только поправить, нельзя просмотреть
encrypt=encrypted
hint=<hint content>
# отображение подсказки под input элементом

Где:

<saveOn> - режим сохранения, может быть "focusLost", по-умолчанию сохранение производится по нажатию кнопки Ок либо Enter.
<hint content> - настраиваемая текстовая подсказка под input элементом.

В конфигурации параметра могут быть указаны одна или несколько конструкций вида:

regexp.<n>.title=<title>
regexp.<n>.regexp=<regexp>

Где:

<n> - число, порядковый номер регулярного выражения;
<title> - наименование шаблона;
<regexp> - REGEXP, описывающее шаблон.

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

regexp.1.title=<город без г.>,<улица без ул.>,<дом без д.>
regexp.1.regexp=[а-яА-Я\s\-]+,[\dа-яА-Я\s\-]+,\s*[\dа-яА-Я/]+
regexp.2.title=<город без г.>,<улица без ул.>,<дом без д.>,<номер квартиры>
regexp.2.regexp=[а-яА-Я\s\-]+,[\dа-яА-Я\s\-]+,\s*[\dа-яА-Я/]+,*\s*\d+
regexp.3.title=<город без г.>,<улица без ул.>,<дом без д.>,<номер квартиры>, <номер комнаты>
regexp.3.regexp=[а-яА-Я\s\-]+,[\dа-яА-Я\s\-]+,\s*[\dа-яА-Я/]+,*\s*\d+,\s*\d+

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

В таблице параметр выглядит следующим образом.

Параметр типа "blob"

Большая многострочная строка до 65000 символов. В конфигурации параметра могут быть указаны следующие необязательные параметры:

rows=<rows>
saveOn=<saveOn>
hint=<hint content>

Где:

<rows> - количество отображаемых в редакторе строк, по-умолчанию 4;
<saveOn> - режим сохранения, может быть "focusLost" (потеря фокуса полем), по-умолчанию сохранение производится по нажатию кнопки Ок;
<hint content> - настраиваемая текстовая подсказка под input элементом.

В таблице параметр выглядит следующим образом.

Параметр типа "list"

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

В конфигурации параметра могут быть указаны следующие необязательные параметры:

# мультивыбор
multiple=1
# сохранение сразу после выбора значефния, без нажатия кнопки Ок (только для параметра с одним выбором)
saveOn=select
editAs=<editAs>
#
# сортировка значений по наименованию а не в порядке кодов
sort.mode=byTitle
#
allowCommentValues=<allowCommentValues>
needCommentValues=<needCommentValues>
#
directory=<dirName>
availableValues=<values>
availableValuesInnerJoinFilter=<joinTable>;<joinColumn>;<joinFilter>
availableValuesInnerJoinDependencyFilter=<dependencyFilter>

Где:

<editAs> - может принимать значения combo - по-умолчанию, выпадающий список, radio - выбор значения в виде переключателей, select - выпадающий список с возможностью поиска значения, links - выбор значения из карточки сущности без запуска режима редактирования;
<dirName> - справочник, из которого берутся значения, может быть "address_city" для городов, если справочника нет - значения указываются в самом параметре;
<values> - допустимые коды значений через запятую;
<allowCommentValues> - перечень значений для которых допустимо указание комментария, возможно указание диапазонов, например: 1-3,7,9-14
<needCommentValues> - перечень значений для которых обязателен комментарий, указывается аналогично <allowCommentValues>;
<joinTable> - имя таблицы, с которой осуществляется фильтрующая операция SQL INNER JOIN справочной таблицы;
*<joinColumn> - колонка таблицы, по которой проводится JOIN столбца id справочной таблицы;
<joinFilter> - дополнительное условие INNER JOIN;
<dependencyFilter> - дополнительное условие для возможности фильтрации доступных значений относительно редактируемого объекта (в выражении можно использовать { objectId } которое будет подменено на ID объекта в котором редактируют данный параметр)

Пример конфигурации параметра, в котором доступны контрагенты, входящие в группу с кодом 3.

multiple=1
directory=customer
availableValuesInnerJoinFilter=customer_group;customer_id;group_id IN (3)

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

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

Параметр типа "listcount"

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

В таблице параметров.

Редактор.

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

Имеется возможность:

конфигурирования размера дробной части (от 0 до 5 знаков);
редактирования параметра через UI;
управления значением параметра через интеракторы.

В конфигурации параметра могут быть указаны следующие параметры:

# Количество знаков после запятой
# Принимает значение от 0 до 5
# В случае указания неподдерживаемого значения, используется значение по-умолчанию
# По-умолчанию 2
scale=2

# Ограничение минимального значения параметра, допустимого для использования
# Принимает неотрицательное числовое значение
# Может не быть указан, если не указан, ограничение не производится
# Если указано невалидное значение, значение игнорируется
min=

# Ограничение максимального значения параметра, допустимого для использования
# Принимает числовое значение
# Может не быть указан, если не указан, ограничение не производится
# Если указано невалидное значение, значение игнорируется
max=

Параметр типа "tree"

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

# несколько значений в дереве
multiple=1

Как выглядят конфигурация, таблица параметров и редактирование.

Параметр типа "date"

Дата: год - месяц - день. В конфигурации параметра могут быть указаны следующие необязательные параметры:

# возможность смены месяца
changeMonth=true
# возможность смены года
changeYear=true
yearRange=<yearRange>
# возможность редактирования поля с клавиатуры
editable=1
saveOn=<saveOn>
# при редактировании поля отправка классу-обработчику изменений параметра события ru.bgcrm.event.DateChangingEvent, позволяющего раскрашивать даты различными цветами и сопровождать примечаниями #sendColorMapRequest=1

Где:

<yearRange> - диапазон отображаемых лет в выпадающем списке годов, могут быть значения от текущего года, например: -10:+30 , либо значения от текущей выбранной даты, например: c:-10:c+30, по-умолчанию с10:с+10;
<saveOn> - режим сохранения, может быть "focusLost" (потеря фокуса полем) либо "enter" (нажатие клавиши "Enter"), по-умолчанию режим "enter"; актуально только при editable=1.

Для параметра yearRange нулевое значение указывать как +0, например: -10:+0

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

Параметр типа "datetime"

Дата + время различной точности.

В конфигурации параметра могут быть указаны следующие необязательные параметры:

type=<type>
stepHour=<stepHour>
stepMinute=<stepMinute>
#
# при редактировании поля отправка классу-обработчику изменений параметра события ru.bgcrm.event.DateChangingEvent, позволяющего раскрашивать даты различными цветами и сопровождать примечаниями #sendColorMapRequest=1

Где:

<type> - может принимать значения ymdh, ymdhm, ymdhms в зависимости от требуемой точности поля;
<stepHour> - шаг в выборе часов;
<stepMinute> - шаг в выборе минут.

Пример параметра. Конфигурация, как выглядит в таблице и редактирование.

Параметр типа "address"

Адресный, ссылающийся на дом в справочнике адресов.

В конфигурации параметра могут быть указаны следующие необязательные параметры:

# несколько адресов в параметре
multiple=1

Как выглядит в таблице и редактирование.

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

Формат строки отображаемой в таблице задаётся в конфигурации.

Параметр типа "phone"

Один или несколько телефонов с комментариями.

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

Как выглядит в таблице и редактирование.

Формат строки отображаемой в таблице задаётся в конфигурации.

Параметр типа "email"

Один или несколько EMail адресов либо только адресов доменов с комментариями.

В конфигурации параметра могут быть указаны следующие необязательные параметры:

# несколько EMail в параметре
multiple=1
# regexp-паттерн, которому должен соответствовать EMail-адрес
validation.regexp="^testMail@.*"
# флагу, которым должен соответствовать EMail-адрес
validation.flags=1,2

Валидация параметра типа "email"

Валидация происходит в первую очередь по тому паттерну, который указан в конфигурации параметра. Если в конфигурации отсутствует validation.regexp - валидация проводится по тому паттерну и тем флагам, которые указаны в глобальной конфигурации (email.regexp и email.flags соответственно). Если же и в глобальной конфигурации отсутствует паттерн, то по умолчанию берётся паттерн, вшиты в код ERP-а (ru.bgcrm.util.Utils#rfc6531).

Приоритет выбора регулярного выражения для валидации: Конфигурация параметра → Глобальная конфигурация → Значение по умолчанию

Как выглядит в таблице и редактирование.

Параметр типа "file"

Один или несколько файлов.

В конфигурации параметра могут быть указаны следующие необязательные параметры:

# несколько файлов в параметре
multiple=1

В таблице параметр выглядит следующим образом.

Параметр типа "boolean"

Графической интерпретацией параметра является чекбокс, галочку в котором может нажать и отжать. Наличие галочки соответствует значению true, отсутствие - false.

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

checked.text=<checkedText>
unchecked.text=<uncheckedText>

Где:

<checkedText> - текстовое описания значения true, соответствующего нажатой галочке;

<uncheckedText> - текстовое описания значения false, соответствующего отжатой галочке.

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

Параметр типа "number"

Параметр данного типа содержит в себе значение в виде числа с плавающей запятой. Имеется возможность:

конфигурирования размера дробной части (от 0 до 5 знаков);
редактирования параметра через UI;
управления значением параметра через интеракторы.

В конфигурации параметра могут быть указаны следующие параметры:

# Количество знаков после запятой
# Принимает значение от 0 до 5
# В случае указания неподдерживаемого значения, используется значение по-умолчанию
# По-умолчанию 0
scale=0

# Ограничение минимального значения параметра, допустимого для использования
# Принимает числовое значение
# Может быть не указан; Если не указан, ограничение не производится
# Если указано невалидное значение, значение игнорируется
min=

# Ограничение максимального значения параметра, допустимого для использования
# Принимает числовое значение
# Может быть не указан; Если не указан, ограничение не производится
# Если указано невалидное значение, значение игнорируется
max=

В БД введённое значение хранится в формате decimal(20,5).

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

Параметр типа "objectList"

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

Возможности:

Настройка отображения параметра через конфигурацию
Редактирование параметра через пользовательский интерфейс (UI), включая порядок и обязательность
Управление значением параметра с помощью интеракторов.

scheme=Пример значения параметра {{123}}, и второго {{321}}
required=1

Где:

scheme - то как будет выглядеть предпросмотр параметра (в фигурных скобках {{}}, указывается id параметра, для получения его значения). Если схема отсутствует, а значение параметра есть, то будет отображаться сообщение Шаблон отсутствует.

required - обязательность параметра (если установлено значение true или 1, то параметр нельзя обнулить и его необходимо заполнить)

Для создания параметра objectList необходимо следующее:

Создать параметр в редакторе

После сохранения нажать на редактирование данного параметра

Добавить необходимые параметры.

Заполнение параметра:

Нажать на значение параметра (если его нет, будет написано не указан)

Для добавления новой записи необходимо нажать на кнопку Добавить элемент (при создании нового элемента, создается значение с отрицательным id)

На данном этапе имеется возможность сохранить параметр, либо удалить его. При сохранении будут проверены значения: если обязательные параметры не заполнены, появится сообщение об этом. При удалении, запись будет удалена вместе с её значениями.

objectList save with null reuired params

Редактор для значений параметров в ObjectList используется на Vue, а не jsp, поэтому он имеет существенные отличия, и может работать отлично от jsp (отсутствие некоторых функций)

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

Все изменения с данным параметров сохраняются сразу, новые значения под отрицательным id, сохраненные под положительным

Интерактор:

Для процесса добавлена новая аннотация BindObjectList и обработчик к ней ObjectListParamInteractionHandler. Данная аннотация должна размещаться на функции, которая возвращает след тип данных List<Interface extend ObjectListInteractor>

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

Имеется возможность создавать новые записи в данном параметре через префикс new в названии метода, возвращает интерактор для новой записи

Необходимо использовать аннотацию DropCache, что бы не перезаписывать старый элемент, а создать новый. Особенность get интерактора

Имеется возможность удалить все значения параметра, префикс clear в названии метода и void в качестве возвращаемого типа

Например:

public interface BillingPaymentProcess extends ProcessInteractor {
    @BindObjectList(123)
    @DropCache()
    List<Test> getObjectList();

    @BindObjectList(123)
    @DropCache()
    Test newObjectList();

    @BindObjectList(123)
    void clearObjectList();
}

interface Test extends ObjectListInteractor {
    @BindTextParam(321)
    String getReason();

    @BindTextParam(322)
    String getSubReason();

    @BindTextParam(321)
    setReason(String reason);

    @BindTextParam(322)
    getSubReason(String subReason);
}

Интерактор ObjectListInteractor имеет фабрику ObjectListInteractorDispatcherFactory, в которой описаны все параметры для взаимодействия (должны поддерживаться аннотации всех параметров).

Так же в ProcessInteractor имеется обработчик для аннотации BindObjectList

Обрабатывать изменения параметров в процессе можно с помощью аннотации OnParamChanged

@OnParamChanged([123])
fun must_only_one_listener(event: ParamChangedEvent) {}

@OnParamChanged([123])
fun must_only_one_listener(event: ObjectListParamChangedEvent) {}

ObjectListParamChangedEvent содержит в objectId:

строку параметра objectList
параметр
новое и старое значение
rootParameter — сам параметр objectList
rootObjectId — родительский объект (например, процесс)

Событие ParamChangingEvent не поддерживается

История изменений параметра:

Для каждого элемента имеется история изменений в соответствующей элементу таблице (text, number, boolean и тп) по id
Логируются записи о добавлении и удалении элементов в параметре ObjectList