2.3Сценарии
Сценарии представляют собой мощный механизм расширения функциональности СУБП, используемый в тех случаях, когда требуемые действия слишком сложно (или невозможно) выполнить при помощи стандартных функций.
Типовые применения сценариев следующие:
преобразование типов и форматов данных;
динамическое изменение данных процесса во время его работы (добавление и удаление переменных процесса, изменение значений переменных);
сложные операции обработки данных, которые невозможно осуществить стандартными средствами (например, работа со справочниками и специфическими карточками DocsVision);
взаимодействие с внешними системами (не предусмотренное функциями или шлюзами этих систем).
Функция сценария (Script) позволяет выполнить в рамках процесса произвольный код на языке платформы .NET (C# или VB.NET).
2.3.1Разработка сценариев
Разработка сценариев включает в себя следующие этапы: написание кода сценария; отладка кода сценария; сохранение готового сценария в процессе или подпроцессе.
Написание кода сценария можно производить как непосредственно в диалоговом окне функции сценария, так и в любом другом редакторе или при помощи Visual Studio.NET - с последующей вставкой полученного кода в функцию процесса. Последний вариант предпочтительнее, так как позволяет избежать грубых ошибок форматирования, синтаксиса и преобразования типов.
Код сценария должен располагаться в классе DVScript, в пространстве имён DVScriptHost:
namespace DVScriptHost
{
class DVScript
{
}
}
Сценарий также может содержать другие классы и пространства имен, но существенным является именно указанный. Класс должен содержать стандартный метод:
public void Execute (ProcessInfo process, PassState passInfo)
В начале исполнения функции управление будет передано данному методу. Входящие параметры метода содержат ссылки на информацию о процессе (process) и данные о текущем проходе (passInfo). Под проходом в данном случае понимается совокупность данных (контекст), специфических для выполнения данного конкретного экземпляра функции. При повторном вызове функции эти данные могут измениться.
Функция сценария должна ссылаться на внутренние пространства имен:
DocsVision.Workflow.Objects – пространство имен, содержащее описания структур данных карточек СУБП (карточка процесса, справочники);
DocsVision.Workflow.Runtime – пространство имен сервиса СУБП, производящего обработку процессов;
DocsVision.Workflow.Gates – пространство имен стандартных шлюзов.
Для работы с клиентскими объектами DocsVision необходимо дополнительно указать ссылку на пространство имен DocsVision.Platform.ObjectManager (описание соответствующих объектов приведено в руководстве разработчика DocsVision).
При необходимости использовать внешние системы (напрямую или через шлюзы) имеется возможность подключить необходимые программные модули на странице свойств функции сценария.
2.3.2Объектная модель сценариев
Основные объекты, которыми оперирует функция сценария, – это внутренние объекты сервиса СУБП, специфические для исполняемого процесса. К ним относятся переменные процесса, шлюзы, журнал процесса и др. Необходимые типы данных расположены в пространстве имен DocsVision.Workflow.Runtime.
Класс ProcessInfo содержит данные о текущем выполняющемся процессе и включает в себя следующие свойства и методы:
 Gates – коллекция шлюзов, входящих в процесс;
Variables – коллекция переменных процесса;
Library – ссылка на справочники (библиотека WorkflowObjects);
ProcessData – ссылка на карточку процесса (библиотека WorkflowObjects);
ProcessLog – журнал процесса (библиотека WorkflowObjects);
 GetGateByName – получение шлюза с указанным именем;
GetVariableByName – получение переменной с указанным именем;
LogMessage – запись информационного сообщения в журнал процесса.
Экземпляр данного класса выступает в качестве входного параметра функции сценария. С его помощью сценарий может оперировать данными процесса.
Для получения конкретных экземпляров переменных или шлюзов рекомендуется использовать методы GetVariableByName и GetGateByName. Корректность выполнения данных методов обеспечивается уникальностью имён шлюзов и переменных в процессе.
2.3.2.1Работа со шлюзами
Коллекция шлюзов процесса (Gates) содержит типизированные экземпляры серверных классов шлюзов, реализующих общий интерфейс IGate. Для получения конкретного шлюза из коллекции, необходимо знать его название или тип. Тип шлюза (уникальный идентификатор) задается в процессе его разработки и в дальнейшем не должен изменяться.
Для организации взаимодействия с объектами внешней системы сценарий может общаться с ней как напрямую (при помощи ее собственного API ), так и с помощью шлюза, который может содержать вспомогательные классы для работы с каждым из объектов внешней системы. Например, при работе со справочником сотрудников DocsVision разработчик сценария может работать как напрямую с данными справочника (см. «Руководство разработчика на платформе DocsVision»), так и воспользоваться соответствующими объектами шлюза DocsVision. Однако чаще всего такие объекты шлюза служат внутренним целям (для организации работы стандартных функций), и могут не иметь всех свойств и методов по сравнению с оригинальным API. Поэтому при наличии такой возможности, рекомендуется работать с внешней системой напрямую.
Пример работы с объектами DocsVision через оригинальный API:
// получение шлюза
DVGate dvGate;
dvGate = (DVGate)process.Gates[DVGate.GateID];
// получение объекта сессии для доступа к API
UserSession session = oDVGate.Session;
// работа через API DocsVision - получение данных карточки
CardData data = session.CardManager.get_CardData("...");
2.3.2.2Работа с переменными
Коллекция переменных бизнес-процесса содержит объекты класса ProcessVariable, включающие в себя следующие свойства и методы:
ID – уникальный идентификатор переменной;
Name – название переменной;
DisplayValue – отображаемое значение объекта, хранящегося в переменной;
Type – тип переменной (VarTypeEnum);
TypeID – идентификатор типа переменной в шлюзе. Для простых типов переменных не заполняется;
GateID – идентификатор шлюза, которому принадлежит переменная. Для простых типов этот идентификатор является пустым GUID;
Value – значение переменной. Для простых типов переменных содержит значение соответствующего типа (string, long, …). Для шлюзовых переменных содержит экземпляр переменной шлюза, реализующий стандартный интерфейс IGateVariable;
VarEnumValues – коллекция строчных значений (для переменных типа Перечисление);
Values – коллекция значений для переменной-коллекции;
IsNull – флаг, показывающий, что значение переменной не задано;
IsMultipleValued – флаг, показывающий, что переменная хранит несколько значений (переменная-коллекция).
Необходимо подчеркнуть, что при работе с переменными простых типов данных, значение переменной можно получить непосредственно из свойства Value. Для прочих типов (переменные шлюзов) в качестве значения переменной будет возвращена ссылка на соответствующий типизированный объект шлюза. Пример:
// получение переменных простого и сложного типа
ProcessVariable varStr = process.GetVariableByName("Строка");
ProcessVariable varDoc = process.GetVariableByName("Карточка договора");
// получение типизированных значений переменных
string strValue = (string)varStr.Value;
DVCard card = (DVCard)varDoc.Value;
Присваивание значений переменным выполняется аналогичным образом. Переменные простых типов получают непосредственное значение, тогда как шлюзовые переменные в качестве нового значения могут получать только объекты шлюза:
// получение переменных простого и сложного типа
ProcessVariable varStr = process.GetVariableByName("Строка");
ProcessVariable varDoc = process.GetVariableByName("Карточка договора");
// получение типизированных значений переменных
varStr.Value = "новое значение строки";
varDoc.Value = dvGate.GetVariable((int)DVVariableType.DOCUMENT, "ID_карточки");
Примеры простейших сценариев можно найти в приложении 3.
2.3.3Отладка сценариев
Отладка сценариев представляет собой процесс тестирования разработанного кода сценария с последующим включением его в разработанный бизнес-процесс. Отладку можно условно разделить на две стадии:
отладка на стадии компиляции;
отладка на стадии исполнения.
При обработке экземпляра СУБП исполнение всех функций сценария проходит две фазы: компиляция и непосредственное исполнение. Компиляция производится при первом обращении к функции сценария и осуществляется при помощи стандартного компилятора, входящего в состав Microsoft .NET Framework. Язык сценария (C# или VB.NET) выбирается соответствующим переключателем в настройках функции.
Если компиляция кода сценария завершилась с одной (или несколькими) ошибками, то дальнейшее выполнение бизнес-процесса считается невозможным и работа бизнес-процесса завершается с ошибкой. Подробное описание возникших ошибок можно найти в журнале соответствующего экземпляра бизнес-процесса (они будут помечены именем функции сценария, компиляция которой не удалась) или в общем журнале работы СУБП - если такой журнал ведется. Подробнее о журнале работы можно узнать в «Руководстве пользователя DocsVision».
Проверить компиляцию сценария можно непосредственно из окна ввода текста сценария, нажатием кнопки “Компилировать”.
В случае, если компиляция завершена успешно, производится исполнение сценария. Исполнение производится последовательно, если структурой кода не предусмотрено иное. После завершения исполнения всего кода сценария сервис СУБП переходит к обработке следующей функции бизнес-процесса.
Для упрощения отладки бизнес-процесса на этапе исполнения можно использовать механизм сообщений. Сценарий может выводить произвольные сообщения в журнал бизнес-процесса при помощи функции LogMessage класса ProcessInfo. Сообщения могут носить декларативный характер (например, сообщать о корректном выполнении тех или иных участков кода) или информировать о состоянии данных (например, значениях переменных). После завершения отладки необязательные для работы сценария сообщения желательно убрать из кода, чтобы избежать замусоривания журнала готового бизнес-процесса.
Сценарии могут использовать для организации корректной работы стандартный механизм исключений. Исключения могут возникать в результате ошибок исполнения сценария, либо сознательно продуцироваться в коде для выполнения необходимых действий. Все возможные исключения сценарий должен обрабатывать самостоятельно и в зависимости от этого реализовывать тот или иной вариант работы (например, записать информацию об исключении в журнал или выполнить другой участок кода).
Если исключение не было обработано сценарием, то оно обрабатывается сервисом СУБП, и сценарий считается завершенным с непредвиденной ошибкой. Обработка процесса в этом случае прерывается на функции сценария, вызвавшей исключение.
Итак, сценарий завершается успешно (исполнение процесса продолжается), если:
компиляция сценария завершена без ошибок;
все возникшие во время исполнения исключения обработаны самим сценарием;
или неуспешно (исполнение бизнес-процесса прерывается), если:
возникла одна или более ошибок при компиляции кода сценария (синтаксические, семантические ошибки или не удалось подключить дополнительные библиотеки);
во время исполнения сценария возникло хотя бы одно необработанное исключение.
2.3.4Сохранение сценариев в сборку и подключение сборок
Начиная с версии DocsVision 4.5 в функции “Сценарий” появилась кнопка “Создать функцию”, которая позволяет сохранить сценарий как библиотеку, т.е. файл *.dll:
При нажатии на эту кнопку отображается стандартный диалог выбора файла для сохранения сборки. При успешной компиляции сборки производится добавление ссылки на сборку в список сборок в справочнике системных настроек, в ветке, относящейся к настройкам Workflow. Это позволяет в дальнейшем использовать данный сценарий в других процессах как готовую функцию, без необходимости копирования его исходного кода.
Внимание! Возможность сохранения сценария в сборку доступна только на сервере DocsVision, т.к. файлы сборок должны располагаться на сервере для возможности работы с ними сервиса Workflow.
После сохранения сценария как .Net-сборки, он отображается в диалоге выбора типа объекта в Универсальной функции в дереве на одном уровне с добавленными в процесс шлюзами:
Чтобы обеспечить возможность повторного использования сценария в виде скомпилированной сборки, в нем обязательно должен быть хоть один публичный (publiс) класс, а в нем должны присутствовать публичные статические (отмеченные в коде как public static) методы. В рамках одного сценария возможно наличие произвольного числа таких методов – каждый из них будет выступать как отдельная функция в Универсальной функции. При этом, методы в качестве параметров и возвращаемого значения должны содержать только параметры типов реализованными шлюзами Workflow (включая шлюз к базовым типам).
Таким образом, если в поле Тип выбрать в качестве типа переменных класс, принадлежащий сборке, в поле Функция отобразятся статические методы выбранного класса, а в поле Параметры функции — параметры метода.
Помимо сборок, созданных на базе сценариев, возможно подключение в таком качестве любых произвольных сборок, отвечающих тем же требованиям:
в них обязательно должны присутствовать публичные статические (отмеченные в коде как public static) методы
методы в качестве параметров и возвращаемого значения должны содержать только параметры типов реализованными шлюзами Workflow (включая шлюз к базовым типам)
Такие сборки необходимо вручную добавить ее в список сборок в справочнике системных настроек, в ветке, относящейся к настройкам Workflow.
Для корректной работы диалога на клиенте сборка должна находиться либо в одном каталоге с клиентским приложением (IE), либо в GAC. На сервере сборка должна находиться либо в одном каталоге с ExecLogic.exe, либо в GAC.
|
