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

Система BGERP является в первую очередь платформой, поэтому значительный эффект от её применения достигается путём реализации различного рода расширений под специфику пользователя.

Выбор технологии

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

Конфигурирование

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

JEXL и JSP

Использование JEXL скриптов для изменения логики и JSP страниц для отображения. Хорошая обратная совместимость, в случае использования стандартного Java DAO API. Нет валидации ошибок, среды разработки.

Динамический код

Замена JEXL скриптов динамическим кодом. Более громоздко в написании, но можно пользоваться Java в полнофункциональной IDE. Код проверяется компилятором, есть автодополнение кода, подсветка синтаксиса.

Собственный плагин либо изменение исходного кода

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

JEXL

JEXL - язык коротких выражений.

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

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

Пример использования выражения:

processCreateLink.1.title=Проект (Уфа)
processCreateLink.1.processTypeId=9260
processCreateLink.1.linkType=processDepend
processCreateLink.1.checkExpression=1 =~ processParam.addressCityIds( 90 ) and process.getStatusId() == 39
processCreateLink.1.copyParams=90,89,238
processCreateLink.1.copyLinks=1

В данном случае создание связанного процесса будет доступно только для процессов в статусе с кодом 39 и с наличием адреса в параметре с кодом 90 с городом 1.

В JEXL процессор всегда передаются объекты:

  • u - статический контекст объекта ru.bgcrm.util.Utils - возможность вызова статических функций;

  • tu - статический контекст объекта ru.bgcrm.util.TimeUtils - возможность вызова статических функций;

  • su - статический контекст объекта org.apache.commons.lang.StringUtils - возможность вызова статических функций;

  • сu - статический контекст объекта org.apache.commons.collections.CollectionUtils - возможность вызова статических функций;

  • log - объект класса org.apache.log4j.Logger, позволяет вести отладку с помощью log.debug и других вызовов;

  • NEW_LINE - перенос строки;

  • NEW_LINE2 - два переноса строки.

Дополнительные объекты передаются в зависимости от места использования.

Типовой дополнительный набор объектов для обработчика процесса:

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

onProcessEvent.2.doExpression=<<END
  dao = new("ru.bgcrm.dao.ParamValueDAO", conSet.getConnection());
  dao.updateParamText(process.getId(), 63, "тест");
END

Часто необходимая информация (детальное описание - по ссылкам далее):

  • оператор [] - создание массива, {} - HashSet, подойдёт на место Collection;

  • функция new (см. пример выше) - создание объекта класса, конструктор может быть с параметрами;

  • операторы проверки наличия объектов в коллекциях: =~ , !~

Методы вызываются у объектов классов с помощью точки, для вызова статического метода используется объект типа java.lang.Class нужного класса, который может быть создан просто записью полного имени класса. Небольшой пример, как вызывать статические методы ru.bgcrm.util.Utils.

u = ru.bgcrm.util.Utils;
v = u.parseInt(3);

Подробная спецификация по языку:

Обратите внимание на вызов функции u.escapeXml - она преобразует все символы HTML разметки в спецпоследовательности. Если не использовать эту функцию для генерации HTML, возможны проблемы, в случае появления в описании процесса символов <,> либо кавычек. Пример ниже.
processReference.1.stringExpression=u.escapeXml( u.maskNull( u.getFirst( processParam.addressValues( 345, 'fromStreet' ) ) ) ) + " (" + size( processParam.addressValues( 345 ) ) + ")"

Java REGEXP

Регулярные выражения позволяют гибко описывать шаблоны строк.

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

Например:

  • (342) - это символы 342 следующие один за другим;

  • 3\d2 - это 3 затем любая цифра и 2;

  • 342)|(559 - последовательность симоволов 342 либо 559;

  • 44[2-8] - строки 442, 443, 444, 445, 446, 447, 448.

Расшифровка некоторых макросов:

  • а-b - на этом месте может располагаться симовол от a до b (в таблице символов);

  • [abc] - на этом месте может располагаться любой из символов a, b либо c;

  • abc - последовательное расположение символов a, b, c;

  • abc)|(def - на этом месте последовательно располагаются abc либо def, () - группа символов.

Ссылки:

Логирование

Log4j - библиотека логирования для Java. Настройка логирования производится в файле log4j.properties, изменение файла можно производить при работающем приложении. Вид файла при установке системы:

log4j.rootLogger=INFO, file

log4j.logger.ru.bgcrm=ALL, session
log4j.additivity.ru.bgcrm=true

log4j.appender.file=org.apache.log4j.RollingFileAppender
log4j.appender.file.layout=org.apache.log4j.PatternLayout
log4j.appender.file.layout.ConversionPattern=%d{MM-dd/HH:mm:ss} %5p [%t] %c{1} - %m%n
log4j.appender.file.File=./log/bgcrm.log
log4j.appender.file.Append=true
log4j.appender.file.BufferedIO=false
log4j.appender.file.BufferSize=1024
log4j.appender.file.MaxBackupIndex=5
log4j.appender.file.MaxFileSize=10MB
log4j.appender.file.Threshold=INFO

log4j.appender.session=ru.bgcrm.util.SessionLogAppender
log4j.appender.session.layout=org.apache.log4j.PatternLayout
log4j.appender.session.layout.ConversionPattern=%d{MM-dd/HH:mm:ss} %5p [%t] %c{1} - %m%n

Сообщения в логе разделяются на уровни (в порядке возрастания): DEBUG, INFO, WARN, ERROR, FATAL. По-умолчанию настроен уровень INFO, т.е. выводятся информационные и ошибочные сообщения (INFO, FATAL, ERROR), отладка не выводится. Вывод осуществляется в файл log/bgcrm.log, который обрезается на размере 10МБ с созданием отдельных файлов.

Для включения вывода отладочной информации необходимо установить:

log4j.appender.file.Threshold=DEBUG

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

Ссылки:

Динамическое логирование

Для более удобной отладки JEXL скриптов, конфигураций либо динамического кода возможно получение логов только текущей сессии с помощью оснастки Пуск ⇒ Логирование.

ext dyn log

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

Динамический код

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

Динамические классы необходимо создавать в пакете ru.bgcrm.dyn.<дальнейшая иерархия пакетов> и в соответствующем каталоге.

Параметры динамического кода могут быть настроены в конфигурации.

Для написания динамического кода возможно использование как простого текстового редактора, так и полноценные IDE для Java разработки. Методология при этом аналогична применяемой для разработки в BGBilling.

Компиляция динамического кода осуществляется в оснастке Администрирование ⇒ Динамический код интерфейса администратора. Можно скомпилировать только все классы сразу. При успешной компиляции динамический код применяется также целиком.

ext dyn

Как видно из снимка экрана, помимо компиляции в оснастке возможно создание и запуск объекта класса реализующего интерфейс java.lang.Runnable. Кроме данного способа возможны перечисленные в последующих разделах способы создания и применения объектов динамических классов. Синхронный запуск происходит в потоке запроса и позволяет легко изучить логи.

Примеры

В составе поставки доступны примеры динамических классов в dyn/ru/bgcrm/dyn поименованные как Example.. с описанием в комментариях. Помимо этого вы можете найти примеры динамического кода здесь.

Java библиотеки

Пользовательские Java библиотеки, используемые в динамическом коде, JEXL выражениях либо JSP страницах должны быть размещены в каталоге lib/custom JAR файлы из lib/ext перетираются при получении обновления библиотек.

Запуск кода

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

Обработчики событий процессов

Имя класса-обработчика может быть указано в свойствах типа процесса. Создаваемые динамические классы - обработчики событий должны расширять абстрактный класс ru.bgcrm.event.listener.DynamicEventListener. Информацию по типам событий можно получить из API документации к системе в формате JavaDoc.

При старте сервера

Параметры runOnStart и createOnStart в конфигурации сервера. Указанные в них объекты классов создаются и запускаются для runOnStart при старте сервера.

HTTP запросом

<crmUrl>/admin/dynamic.do?action=runDynamicClass&iface=<iface>&class=<className>&j_username=<user>&j_password=<pswd>&param1=value&param2=..

Где:

  • <crmUrl> - URL и порт BGERP;

  • <className> - имя динамического класса;

  • <user> и <pswd> - логин и пароль пользователя BGERP, подробнее о запросах внешних систем;

  • <iface> - тип класса-обработчика, подробнее ниже.

При параметре <iface> равным event класс должен расширять абстрактный класс ru.bgcrm.event.listener.DynamicEventListener в который передаётся событие ru.bgcrm.event.RunClassRequestEvent. В противном случае класс может реализовать интерфейс java.lang.Runnable, который просто будет запущен.

Из командной строки

Для запуска любого класса, статического или динамического в контексте сервера BGERP вызовите:

./crm.sh "runclass <class_name>"

Где <class_name> - полное имя класса с пакетом. Класс должен реализовывать интерфейс java.lang.Runnable.

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

Планировщик

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

JSP

JSP шаблоны используются в BGERP для генерации всего HTML интерфейса, а также как шаблоны печатных форм в плагине Document. В сочетании с библиотекой тегов и возможностью лёгкого вызова Java кода, JSP предоставляет обширные возможности по адаптации интерфейса.

Пользовательские JSP файлы располагайте в каталогах WEB-INF/jspf/custom/.., это гарантирует вас от перетирания названия каталога штатными шаблонами и позволит легко контролировать все кастомизации в одном месте. Например: /WEB-INF/custom/process_jur_zayavka.jsp.

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

Вкратце схема работы JSP шаблона представлена на схеме ниже.

На вход шаблона передаётся объект Request. Изначально это чаще всего HTTP запрос с параметрами, но в общем и целом это просто некий Map c Java объектами. По мере обработки запроса в этот Map помещаются:

ext jsp schema

Любой объект в Request доступен в JSP шаблоне как ${object}. Для вызова метода ${object.method()}. На выходе шаблона образуется по сути текст, который указан в шаблоне, за исключением специальных инструкций. Это может быть HTML, передаваемый на клиента, либо простой текст. Специальные инструкции, оперируя с объектами из Request, добавляют в этот текст дополнительные данные.

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

Обзор использования тегов с элементами управления пользователя вы можете посмотреть в файле webapps/test.jsp, для выполнения шаблона наберите в браузере http://<host>:<port>/test.jsp Полный обзор библиотеки BGERP вы можете получить в файлах объявлениях webapps/WEB-INF/tld/...

Изменение файлов системы

При корректировке штатных файлов системы: JSP страниц, конфигурационных файлов, библиотек и т.п. предварительно необходимо создать файл с аналогичным именем но дополненным .orig в конце. Например: process_color.jspprocess_color.jsp.orig. В противном случае изменённый файл будет перетёрт при следующем обновлении. При наличии .orig файла программа сверит файл из обновления с ним и перетрёт файл в дистрибутиве только в случае несовпадения, сохранив резервную копию перетираемого файла. .orig файл обозначает версию оригинального файла, относительно которого был создан изменённый.

Интеграция с внешними системами

Все запросы на изменение данных в возвращают результат в JSON формате. Запросы выборки данных возвращают результат в HTML формате, однако возможно получение данных и в JSON формате, путём добавления в запрос параметра responseType=json.

Для прозрачной авторизации запроса сторонней системы логин и пароль пользователя могут быть переданы в запросе в HTTP параметрах запроса j_username и j_password соответственно. Параметр authToSession=0 в запросе указывает на хранение отсутствие необходимости в HTTP сессии. Настоятельно рекомендуется использовать его при запросах внешних систем, т.к. предотвращение создания HTTP сессий экономит память BGERP.

Пример запроса на получение данных во внешнюю систему в JSON формате (выборка по очереди процессов):

http://server.bgcrm.ru/user/process.do?action=queueShow&id=4&dateStatusStatus=10&status=10&status=9&status=13&currentUserMode=&group=7&sort=0&j_username=shamil&j_password=*****&responseType=json&authToSession=0

При изучении формата запросов и ответов возможно использование инструмента разработчика в браузере с отслеживанием запросов отправляемых браузером при работе пользователя в BGERP.