Использование отчётов

Отчёт — механизм, предоставляющий возможность получения прямого доступ к БД Docsvision с целью получения сложных выборок данных, повышения производительности работы Решения, получения данных из внешней БД и т.п.

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

Создание отчётов требует от разработчика понимания внутреннего устройства БД Docsvision.

Создание отчёта

Создание нового отчёта включает два этапа:

Разработка SQL-процедуры, реализующей требуемый механизм взаимодействие с данными в БД.
Настройка отчёта в схеме библиотеки карточек.

Отчёт представляет собой SQL процедуру вида:

BEGIN
 SELECT tblMy.Info1, tblMy.Info2
 FROM [dvtable_{SOME_DV_TABLE_GUID_HERE}] tblMy
 WHERE tblMy.Param1 = @Param1 and tblMy.Param2 = @Param2
 ORDER BY tblMy.Info2
END

В процедуре можно использовать параметры (с символом @), значения которых будут переданы при вызове отчёта. Параметры объявлять не требуется.

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

Процедура должна размещаться в блоке BEGIN .. END.

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

Процедура должна быть сохранена в файл .sql в подпапку (например, "Sql") в одном каталоге со схемой библиотеки карточек.

CardLib
|  MyCardLib.xml
|  MyCard.xml
|--Sql
   |  MyProcedure1.sql
   |  MyProcedure1.sql

Регистрация отчёта в схеме библиотеки карточек выполняется с помощью программы "CardManager". Инструкция по работе с программой приведена в Руководстве пользователя Resource Kit, см в центре загрузок Docsvision.

В качестве примера далее будет выполнена регистрация отчёта GetLogMessages, возвращающего записи из журнала Docsvision за определённый период:

BEGIN
    SELECT appLog.EmployeeID, appLog.Date, appLog.Data
    FROM [dbo].[dvsys_log_application] appLog WITH(NOLOCK)
    INNER JOIN [dbo].dvsys_users users WITH(NOLOCK)
    ON (users.UserID = appLog.UserID)
    WHERE appLog.Date BETWEEN @DateFrom AND @DateTo
END

Чтобы настроить новый отчёт:

Откройте в программе "CardManager" свойства собственной библиотеки карточек и перейдите на вкладку Reports.

Рисунок 1. Вкладка настройки отчётов библиотеки карточек в программе "CardManager"
Добавьте новый отчёт в схему и укажите основные свойства отчёта.
1. Нажмите кнопку Add в блоке Procedures. В список Procedures будет добавлена новая запись.
2. В поле Alias введите псевдоним отчёта.
3. В таблице Названия введите локализованные названия отчёта.
  
  В поле ID будет указан автоматически сгенерированный идентификатор отчёта, по которому отчёт может быть вызван с использованием API.
  
  Рисунок 2. Пример настройки основных свойств отчёта
Добавьте в отчёт файлы с SQL процедурами на вкладке SQL files.
1. Нажмите кнопку Add на данной вкладке. В список Files будет добавлена новая запись.
2. В поле SQL file выберите разработанный ранее SQL-файл с процедурой отчёта. Приведите путь к файлу к относительному виду.
3. В списке Server type выберите тип СУБД, под управлением которой работает БД Docsvision, для которой создаётся отчёт: Microsoft SQL или PostgreSQL.
  
  Рисунок 3. Пример настройки файлов отчёта
Настройте параметры отчёта на вкладке Parameters.
1. Нажмите кнопку Add на данной странице. В список Parameters будет добавлена новая запись.
2. В поле Parameter name введите название параметра, которое ожидается в соответствии с разработанной SQL-процедурой.
3. В поле Parameter type укажите тип параметра, соответствующий типу параметра, используемого в SQL-процедуре.
4. Аналогичным образом добавьте все параметры, ожидаемые разработанной SQL-процедурой.
  
  Рисунок 4. Пример настройки параметров отчёта
Настройте возвращаемые данные отчёта на вкладке Report result.
1. Выберите формат возвращаемого значения:
  - Scalar result — если возвращается единственное значение.
  - TableResult — если возвращается коллекция значений.
2. Если выбран формат Scalar result, укажите:
  - Data type — тип возвращаемых данных.
  - Precision, Scale, Size — точность, масштаб и длина (см. подробнее на сайте Microsoft.).
  - Nullable — если может быть пустым.
3. Если выбран формат TableResult:
  1. Нажмите кнопку Add. В список Columns будет добавлена новая запись.
  2. В поле Name введите название возвращаемого процедурой поля.
  3. Укажите (см. описание выше): Data type, Precision, Scale, Size и Nullable.
  4. Аналогичным образом добавьте все возвращаемые процедурой поля. Данное условие критически важно при работе с PostgreSQL.
    
    Рисунок 5. Пример настройки результатов отчёта
Сохраните настройки библиотеки карточек и загрузите её в Docsvision стандартным образом.
Перезапустите сервер Docsvision.

Вызов отчёта

Для работы с отчётами API Docsvision предоставляет менеджер отчётов типа ReportManager.

Все отчёты содержатся в поле Reports класса ReportManager.

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

var report = userSession.ReportManager.Reports[Guid.Parse("886d96f1-e92f-44aa-b22d-9b324aeb5abc")];

Значения параметров отчёта устанавливаются в поле Parameters:

report.Parameters["DateFrom"].Value = DateTime.Parse("01.01.2012");
report.Parameters["DateTo"].Value = DateTime.Parse("01.01.2019");

Выполнение отчёта запускается методом report.GetData(), который возвращает набор строк с результатами выполнения.

Следующий код демонстрирует пример вызова разработанного отчёта с отображением записей журнала Docsvision в консоли.

var report = userSession.ReportManager.Reports[Guid.Parse("886d96f1-e92f-44aa-b22d-9b324aeb5abc")]; (1)

report.Parameters["DateFrom"].Value = DateTime.Parse("01.01.2012");
report.Parameters["DateTo"].Value = DateTime.Parse("01.01.2019"); (2)

InfoRowCollection results = report.GetData(); (3)

foreach (InfoRow result in results)
{
  Console.WriteLine("{0} | {1} | {2}", result["EmployeeID"].ToString(),result["Date"].ToString(), result["Data"].ToString()); (4)
}

1	Получение отчёта с идентификатором `886d96f1-e92f-44aa-b22d-9b324aeb5abc`.
2	Заполнения параметров отчёта — начальной и конечной даты выборки.
3	Выполнение отчёта.
4	Отображение результатов выполнения отчёта в консоли.

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