Документация Avanpost IDM 7 : 6.2.10. Отчёты

Навигатор по разделу:

1. Общие сведения

Раздел "Отчёты" позволяет настраивать, формировать и экспортировать отчеты на основе встроенных или пользовательских шаблонов. Технически отчет состоит из двух компонентов:

1. Источник данных — логика выборки и фильтрации данных из базы. Может быть встроенным или реализованным как пользовательский плагин (библиотека .NET).

2. Шаблон отчета (форма .frx) — определяет визуальное представление данных (макет, дизайн, оформление).

Форма отчёта — это конфигурационная сущность в системе, объединяющая:

• выбранный источник данных;
• привязанный шаблон (.frx);
• предустановленные параметры генерации (опционально).

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

Для работы с отчётами необходимо перейти в режим "Отчёты" операционного интерфейса Системы. Доступ к разделу "Отчеты" осуществляется через меню "Приложение" ⟶ "Отчёты" или через основное меню — раздел "Отчёты". 

Путь к разделу "Отчёты"

Путь к разделу "Отчёты"

2. Настройка и генерация отчетов

Для работы с отчётами в режиме "Отчеты" операционного интерфейса Системы необходимо:

1. Зарегистрировать (загрузить) новый шаблон или изменить шаблон существующего отчёта.

2. Настроить отчет на основе выбранного шаблона.

3. Построить отчета.

2.1 Работа с формами (шаблонами) отчетов

Для работы с шаблонами отчётов необходимо перейти на вкладку "Формы" в раздел "Отчеты". На вкладке отображается список всех доступных шаблонов отчётов, включая:

1. Встроенные шаблоны – предустановленные в Системе формы отчётов, которые нельзя изменить или удалить.

2. Пользовательские шаблоны – формы отчётов, созданные вручную и загруженные в Систему.

Вкладка "Формы"

Для работы с шаблонами отчётов в Системе доступны следующие действия:

1. Загрузка формы (шаблона) отчёта на локальный компьютер.

2. Загрузка формы (шаблона) отчёта в Систему, построенного на основе скачанного.

3. Редактирование формы (шаблона) отчёта, ранее загруженного в Систему.

4. Удаление формы (шаблона) отчёта, ранее загруженного в Систему.

2.2. Регистрация формы (шаблона) отчета

Для регистрации формы (шаблона) отчета в Системе необходимо:

1. Нажать . Откроется окно создания формы (шаблона) отчета.
   Форма создания шаблона отчета
2. В окне создания формы (шаблона) отчета заполнить следующие данные:
   
   • Название — указать название формы (шаблона);
   • Описание — добавить описание формы (шаблона);
   • Источник данных — выбрать источник данных из списка;
   • Файл шаблона — выбрать файл шаблона в формате .frx на локальном компьютере.
   Файл шаблона в формате .frx формируется на основе загруженного файла шаблона из Системы и дальнейшей его модификации

   Заполненная форма создания шаблона отчета

3. Нажать . Созданная форма (шаблон) отчета отобразится в списке форм (шаблонов) отчетов на вкладке "Формы".
   Список форм (шаблонов)

2.3. Редактирование формы (шаблона) отчета в Системе

Чтобы отредактировать файл шаблона, в строке с формой необходимо:

1. Нажать, выбрать пункт "Скачать шаблон". Файл шаблона в формате .frx будет загружен на компьютер.
2. Отредактировать файл шаблона с помощью программы FastReport Designer Community Edition.
3. В строке с нужной формой нажатьи выбрать пункт "Редактировать".
4. В открывшемся окне удалить прикреплённый ранее файл шаблона и загрузить изменённый файл.
5. Нажать, чтобы сохранить изменения.

Окно "Редактирование формы отчёта"

2.4. Удаление формы (шаблона) отчёта из Системы

Для удаления формы (шаблона) отчета из Системы необходимо:

1. В строке записи формы (шаблона) отчета нажать, выбрать пункт "Удалить.
2. В открывшемся окне подтвердить удаление формы (шаблона) отчета из Системы.

Подтверждение удаления

3. Создание отчета

3.1. Создание и настройка отчета

Для создания отчета необходимо:

1. Перейти на вкладку "Настройки".
   Вкладка "Настройки"
2. Нажать кнопку . Откроется форма создания отчета.
   Форма создания отчета. Вкладка "Основное"
3. На вкладке "Основное" формы создания отчета заполнить следующие данные:
   1. В поле "Название" указать название отчёта.

   2. В поле "Описание" добавить описание отчёта.

   3. В поле "Форма" выбрать форму (шаблон) из списка, на основе которой будет формироваться отчёт.

   4. В поле "Роли, которым доступен отчёт" выбрать системные роли, у которых будет доступ к конфигурации.

4. Нажать , Откроется вкладка "Настроенные параметры".
5. На вкладке "Настроенные параметры" добавить параметры конфигурации отчета, нажав.
   Форма создания и настройки конфигурации отчета. Вкладка "Настроенные параметры"

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

   Таблица — Предопределенные параметры конфигураций отчетов

   	Ресурсы, в которых будет выполняться поиск	Название права (привилегии)	Идентификатор права (привилегии)	Фильтр сотрудников владельцев УЗ	Фильтр юнитов владельцев УЗ	Период времени от	Период времени до	Юниты	Ограничение количества обрабатываемых записей
   Отчет по аккаунтам с незарегистрированными правами
   Отчет по ресурсам с атрибутами
   Права учетных записей
   Роли с заданным правом
   Роли с правом
   Роли субъектов авторизации
   Субъекты авторизации с заданным правом
   Субъекты авторизации с правом

6. Нажать . Созданный отчет отобразится в списке отчетов на вкладке "Настройки".

3.2. Редактирование отчета в Системе

Для изменения отчёта необходимо:

1. Перейти на вкладку "Настройки".
2. В списке доступных отчётов найти нужный, нажать → "Редактировать". Откроется форма редактирования отчёта.
   Рисунок — Форма редактирования конфигурации отчета. Вкладка "Основное"
   
3. На вкладке "Основное" формы редактирования отчёта внести изменения в соответствующие поля и нажать.
4. На вкладке "Настроенные параметры" формы редактирования отчёта внести изменения в параметры конфигурации и нажать . Отчёт обновится в Системе.
   Форма редактирования конфигурации отчета. Вкладка "Настроенные параметры"

3.3. Удаление конфигурации отчета из Системы

Для удаления отчёта необходимо:

1. Перейти на вкладку "Настройки". В списке доступных отчётов найти тот, который необходимо удалить.
2. Нажать → "Удалить" и подтвердить удаление, нажав .

Удаление отчёта

4. Настройка автоматической генерации отчета и его рассылки по почте

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

1. Перейти на вкладку "Настройки".
2. В списке доступных отчётов найти нужный, нажать → "Рассылка". Откроется форма редактирования отчёта.
   Форма редактирования отчёта. Настройка рассылки отчета
   
3. На вкладке "Основное" заполнить следующие данные:
   • Тип вложения — выбрать, будет ли отчёт прикреплён как файл или отправлен в виде ссылки;

   • Формат файла — выбрать формат файла (доступные варианты: PDF, EXCEL);

   • Срок хранения отчёта — указать количество дней (от 1 до 99), в течение которых будет храниться отчёт;

   • Шаблон уведомления — выбрать шаблон уведомления из списка;

   • Дата начала — указать дату, с которой начнётся рассылка отчёта;

   • Повторять — настроить периодичность. При выборе периода повторения откроется настройка повторений. Доступные варианты:

     • Никогда (запустить один раз);

     • Ежедневно;

     • По будням;

     • Еженедельно;

     • Ежемесячно;

     • Ежегодно.

4. Перейти на вкладку "Получатели" и настроить список сотрудников, которые будут получать отчёт.
5. Перейти на вкладку "Параметры генерации" и настроить параметры для построения отчёта.
   

   Параметры генерации зависят от предопределённых параметров конфигурации

   
   
   

5. Построение отчета

Для построения отчета необходимо:

1. Перейти на вкладку "Настройки". В списке доступных отчётов найти нужный и нажать . Откроется форма построения отчёта.
   
2. На форме построения отчёта заполнить параметры фильтрации данных. Если параметры фильтрации не будут заполнены, то в отчёт попадут все данные. Это может привести к созданию очень объёмного документа.
   

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

   Форма построения отчёта
3. После заполнения формы отчета нажать . В Системе будет создана задача построения отчета.
4. Перейти на вкладку "Сформированные отчеты". 
   Вкладка "Сформированные отчёты"
5. В списке отчетов появится запись о сформированном отчете, содержащая следующую информацию:
   Таблица – Вкладка "Сформированный отчеты"
   

   Столбец	Описание
   Название	Название отчёта
   Настройка	Наименование формы отчёта
   Состояние	Статус задачи формирования отчёта
   Дата построения	Дата и время формирования отчёта

   Для каждого сформированного отчета доступны следующие действия:
   Таблица — Действия для сформированных отчётов

6. Разработка плагинов-источников данных

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

6.1. Этапы разработки плагина-источника данных

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

1. На языке C# создать компонент, реализующий обязательный интерфейс IReportDataSource и, при необходимости, вспомогательные интерфейсы (например, IReportParametersValidator для валидации параметров).
2. Собрать проект в библиотеку DLL, содержащую этот компонент.
3. Разместить DLL в специальной папке для плагинов на всех узлах IGA. Путь к папке задаётся параметром connectorsFolder в файле Iga.config. Можно размещать каждый плагин в своей подпапке.
4. Разработать файл шаблона отчёта в формате .frx с помощью FastReport Designer и убедиться, что поля данных в шаблоне соответствуют структуре, которую возвращает плагин.
   

   Разработка и тестирование шаблонов отчётов выполнялись с использованием FastReport Designer Community Edition версии 2024.2.0. В более поздних версиях редактора может присутствовать дополнительный функционал, который на текущий момент не поддерживается системой

5. В интерфейсе IDM перейти в раздел "Отчёты" на вкладку "Формы".
6. Создать новую форму, выбрав в поле "Источник данных" нужный плагин.
7. Загрузить созданный файл шаблона .frx.

6.2. Интерфейс IReportDataSource

Основной интерфейс, который должен реализовать каждый плагин.

public interface IReportDataSource
{
  IAsyncEnumerable<object> GetDataAsync(IDataBaseAccessor dbAccessor,IReadOnlyDictionary<string, object> parameters);

  string GetName();

  string GetDescription();

  IEnumerable<ReportColumn> GetColumns();

  IEnumerable<ReportParameter> GetParameters();

  byte[]? GetFormTemplate();
}

6.2.1. Описание методов:

IAsyncEnumerable<object> GetDataAsync(IDataBaseAccessor dbAccessor,IReadOnlyDictionary<string, object> parameters);

string GetName();

string GetDescription();

IEnumerable<ReportColumn> GetColumns();

IEnumerable<ReportParameter> GetParameters();

byte[]? GetFormTemplate();

6.3. Структура данных отчета

6.3.1 Класс ReportColumn

Описывает одну колонку результата отчёта. Все колонки возвращаются методом GetColumns().

Пример реализации:

public IEnumerable<ReportColumn> GetColumns()
{
    return new List<ReportColumn>
    {
        new("ResourceId", ReportValueType.String, false),
        new("ResourceName", ReportValueType.String, false),
        new("Notes", ReportValueType.String, false),
        new("CatalogId", ReportValueType.String, false),
        new("CatalogName", ReportValueType.String, false),
        new("PropertyName", ReportValueType.String, false),
        new("PropertyValue", ReportValueType.String, false),
    };
}

6.3.2 Класс ReportParameter 

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

Доступные типы параметров:

Пример реализации:

public IEnumerable<ReportParameter> GetParameters()
    {
        return new ReportParameter[]
        {
            new StringReportParameter { Id = "ResourceName", Label = "Название ресурса", IsRequired = false },
            new StringReportParameter { Id = "RightName", Label = "Название права (привилегии)", IsRequired = false },
            new StringReportParameter { Id = "RightId", Label = "Идентификатор права (привилегии)", IsRequired = false },
        };
    }

6.4 Работа с базой данных через IDataBaseAccessor

Для безопасного выполнения SQL-запросов в метод GetDataAsync передается объект, реализующий интерфейс IDataBaseAccessor.

public interface IDataBaseAccessor
{
  DataBaseType Provider { get; }

  string IdmSchemaName { get; }

  string WfSchemaName { get; }

  Task<IList<object[]>> ExecuteRawSqlAsync(
    string sql,
    IReadOnlyDictionary<string, object> parameters);
}

6.5 Опциональный интерфейс IReportParametersValidator

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

public interface IReportParametersValidator
{
    Task<IReadOnlyCollection<ParameterError>> ValidateAsync(IReadOnlyDictionary<string, object> parameters);
}

6.5.1. Описание метода

Task<IReadOnlyCollection<ParameterError>> ValidateAsync(IReadOnlyDictionary<string, object> parameters);

6.5.2 Класс ParameterError

Используется для возврата информации об ошибках валидации:

В прикреплённом ZIP-архиве Avanpost.Plugin.Report.zip содержится пример плагина. Архив включает:

1. Файл проекта Avanpost.Plugin.Report.csproj


   <Project Sdk="Microsoft.NET.Sdk">
   
     <PropertyGroup>
       <TargetFramework>net8.0</TargetFramework>
       <LangVersion>default</LangVersion>
       <Nullable>enable</Nullable>
     </PropertyGroup>
   
     <ItemGroup>
       <ProjectReference Include="..\Avanpost.Iga.Plugins\Avanpost.Iga.Plugins.csproj" />
     </ItemGroup>
   
   </Project>

2. Файл реализации компонента ResourcesWithPropReport.cs


   using System;
   using System.Collections.Generic;
   using System.Text;
   using System.Threading.Tasks;
   using Avanpost.Iga.Plugins.Data;
   using Avanpost.Iga.Plugins.Reporting;
   
   namespace Avanpost.Plugin.Report;
   
   /// <summary>
   /// Отчёт по ресурсам с атрибутами.
   /// </summary>
   public class ResourcesWithPropReport : IReportDataSource, IReportParametersValidator
   {
       /// <inheritdoc/>
       public string GetName() => "Plugin-ResourcesWithProp";
   
       /// <inheritdoc/>
       public string GetDescription() => "Отчёт по ресурсам с атрибутами (плагин)";
   
       /// <inheritdoc/>
       public IEnumerable<ReportColumn> GetColumns()
       {
           return new List<ReportColumn>
           {
               new("ResourceId", ReportValueType.String, false),
               new("ResourceName", ReportValueType.String, false),
               new("Notes", ReportValueType.String, false),
               new("CatalogId", ReportValueType.String, false),
               new("CatalogName", ReportValueType.String, false),
               new("PropertyName", ReportValueType.String, false),
               new("PropertyValue", ReportValueType.String, false),
           };
       }
   
       /// <inheritdoc/>
       public IEnumerable<ReportParameter> GetParameters()
       {
           return new ReportParameter[]
           {
               new StringReportParameter { Id = "ResourceName", Label = "Название ресурса", IsRequired = false },
               new StringReportParameter { Id = "RightName", Label = "Название права (привилегии)", IsRequired = false },
               new StringReportParameter { Id = "RightId", Label = "Идентификатор права (привилегии)", IsRequired = false },
           };
       }
   
       /// <inheritdoc/>
       public async IAsyncEnumerable<object> GetDataAsync(IDataBaseAccessor dbAccessor, IReadOnlyDictionary<string, object> parameters)
       {
           const int paramCount = 3;
           if (parameters.Count != paramCount)
               throw new ArgumentOutOfRangeException(nameof(parameters), $"Для построения данных отчёта требуется {paramCount} параметра");
   
           if (dbAccessor.Provider != DataBaseType.Postgres)
               throw new NotSupportedException("Построение данных отчёта возможно только с провайдером Postgres");
   
           var paramResourceName = parameters["ResourceName"] as string;
           var paramRightName = parameters["RightName"] as string;
           var paramRightId = parameters["RightId"] as string;
   
           // мы знаем что это postgres, поэтому экранируем кавычками
           // если бы не знали, можно было бы экранировать с помощью dbAccessor.EscapeName
           var sql = new StringBuilder();
   
           sql.Append($@"
   SELECT r.""Id"", r.""Name"" , r.""Notes"",  rc.""Id"", rc.""Name"", t.""PropName"", t.""PropValue""    
   FROM {dbAccessor.EscapeName(dbAccessor.IdmSchemaName)}.{dbAccessor.EscapeName("Resource")} AS r
   LEFT JOIN ""{dbAccessor.IdmSchemaName}"".""ResourceCatalog"" AS rc ON r.""CatalogId"" = rc.""Id""
   INNER JOIN (
       SELECT r2.""Value"" AS ""PropValue"", e.""Name"" AS ""PropName"", r2.""ResourceId""
       FROM ""{dbAccessor.IdmSchemaName}"".""ResourceProperty"" AS r2
       INNER JOIN ""{dbAccessor.IdmSchemaName}"".""ExtendedPropertyType"" AS e ON r2.""TypeId"" = e.""Id""
   ) AS t ON r.""Id"" = t.""ResourceId""
   WHERE NOT (r.""Deleted"") ");
   
           if (!string.IsNullOrEmpty(paramResourceName))
           {
               sql.Append(" AND (strpos(r.\"Name\", @ResourceName) > 0)");
           }
   
           if (!string.IsNullOrEmpty(paramRightName) || !string.IsNullOrEmpty(paramRightId))
           {
               sql.AppendLine($@" AND EXISTS (SELECT 1 FROM ""{dbAccessor.IdmSchemaName}"".""RightSpec"" AS r0 WHERE (r.""Id"" = r0.""ResourceId"") ");
   
               if (!string.IsNullOrEmpty(paramRightName))
               {
                   sql.Append(@" AND (strpos(r0.""Name"", @RightName) > 0)");
               }
   
               if (!string.IsNullOrEmpty(paramRightId))
               {
                   sql.Append(@" AND (strpos(r0.""RightId"", @RightId) > 0)");
               }
   
               sql.Append(')');
           }
   
           sql.AppendLine(" ORDER BY r.\"Id\", rc.\"Id\"");
   
           var items = await dbAccessor.ExecuteRawSqlAsync(sql.ToString(), parameters);
           foreach (var item in items)
           {
               yield return new ResourcesWithPropRowModel(item);
           }
       }
   
       /// <inheritdoc/>
       // делегируем системе генерацию формы
       public byte[]? GetFormTemplate() => null;
   
       public Task<IReadOnlyCollection<ParameterError>> ValidateAsync(IReadOnlyDictionary<string, object> parameters)
       {
           ArgumentNullException.ThrowIfNull(parameters);
   
           if (parameters.TryGetValue("ResourceName", out var value) && value is string stringValue)
           {
               if (stringValue.Length % 2 != 0)
               {
                   var result = new[] { new ParameterError("ResourceName", "Длина названия ресурса должна быть чётная") };
   
                   return Task.FromResult<IReadOnlyCollection<ParameterError>>(result);
               }
           }
   
           return Task.FromResult<IReadOnlyCollection<ParameterError>>(Array.Empty<ParameterError>());
       }
   }

3. Файл модели данных ResourcesWithPropRowModel.cs


   namespace Avanpost.Plugin.Report;
   
   public class ResourcesWithPropRowModel
   {
       public string ResourceId { get; set; }
       public string ResourceName { get; set; }
       public string Notes { get; set; }
       public string CatalogId { get; set; }
       public string CatalogName { get; set; }
       public string PropertyName { get; set; }
       public string PropertyValue { get; set; }
   
       public ResourcesWithPropRowModel(object[] rowValues)
       {
           ResourceId = rowValues[0]?.ToString();
           ResourceName = rowValues[1] as string;
           Notes = rowValues[2] as string;
           CatalogId = rowValues[3]?.ToString();
           CatalogName = rowValues[4] as string;
           PropertyName = rowValues[5] as string;
           PropertyValue = rowValues[6] as string;
       }
   }

6.6. Редактирование формы отчета в FastReport Designer

Форма отчёта представляет собой текстовый XML-документ с расширением .frx, созданный в среде FastReport. Файл содержит описание визуального оформления: расположение элементов, стили шрифтов, цвета, а также привязки к полям данных. Сам файл не редактируется в интерфейсе IDM — для его модификации используется внешняя программа FastReport Designer Community Edition. Скачать её можно по ссылке. Подробное руководство по работе с интерфейсом редактора приведено в документации Fast Report.

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

Типичный отчет в системе IDM содержит следующие обязательные элементы:

1. Заголовок отчета (Report Title) — отображается один раз в начале документа. Включает название отчета, логотип организации и общую информацию.
2. Заголовки колонок (Page Header) — выводятся на каждой странице и содержат названия столбцов таблицы данных.
3. Область данных (Data Band) — основная часть отчета, которая повторяется для каждой строки данных. Здесь размещаются ссылки на конкретные поля, возвращаемые плагином.
4. Нижний колонтитул (Page Footer) — отображается внизу каждой страницы. Обычно содержит номер текущей страницы, общее количество страниц и дату формирования отчета.
   Редактирование формы отчёта
   

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

1. Колонки, определенные в плагине — метод GetColumns() возвращает список полей отчета.

2. Поля данных в шаблоне — теги <Column> внутри .frx файла должны иметь те же имена.

3. Привязки в макете — ссылки вида [DataSource.ИмяПоля] в области данных шаблона.

После завершения редактирования необходимо сохранить файл в формате .frx и загрузить его в систему. 

Avanpost.Plugin.Report.zipОтчёт по ресурсам с атрибутами.frx