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

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

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

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

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

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

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

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

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

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

Рисунок — Путь к разделу "Отчёты"

Таже доступ к разделу "Отчёты" осуществляется через основное меню — раздел "Отчёты". 

Рисунок — Путь к разделу "Отчёты"

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

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

1. Регистрация (загрузка) или изменение формы (шаблона) отчёта

2. Конфигурирование отчета на основе выбранной формы (шаблона).

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

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

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

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

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

Рисунок — Вкладка "Формы"

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

• Скачивание шаблона отчёта на локальный компьютер;

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

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

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

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

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

Рисунок — Форма создания формы (шаблона) отчета

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

• Название — указать название формы (шаблона);

• Описание — добавить описание формы (шаблона);

• Источник данных — выбрать источник данных из выпадающего списка;

• Файл шаблона — выбрать файл шаблона в формате .frx на локальном компьютере.

Рисунок — Заполненная форма создания формы (шаблона) отчета

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

Рисунок — Список форм (шаблонов)

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

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

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

Чтобы отредактировать файл шаблона, в строке с нужной формой нажать кнопку , выбрать пункт "Скачать шаблон". Файл шаблона в формате .frx будет скачан на ваш компьютер. Отредактировать файл шаблона с помощью программы FastReport Designer Community Edition.

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

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

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

Рисунок — Подтверждение удаления

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

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

Для создания отчета перейти на вкладку "Настройки".

Рисунок — Вкладка "Настройки"

Нажать кнопку . Откроется форма создания отчета.

Рисунок — Форма создания отчета. Вкладка "Основное"

На вкладке "Основное" формы создания отчета заполнить следующие данные:

• В поле "Название" указать название отчёта;

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

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

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

Рисунок — Форма создания отчета. Вкладка "Основное"

Нажать кнопку , чтобы перейти на вкладку "Настроенные параметры".

На вкладке "Настроенные параметры" добавить параметры конфигурации отчета, нажав кнопку .

Рисунок — Форма создания и настройки конфигурации отчета. Вкладка "Настроенные параметры"

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

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

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

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

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

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

Рисунок — Форма редактирования конфигурации отчета. Вкладка "Основное"

На вкладке "Основное" формы редактирования отчёта внести необходимые изменения в соответствующие поля и нажать кнопку .

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

Рисунок — Форма редактирования конфигурации отчета. Вкладка "Настроенные параметры"

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

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

Рисунок — Удаление отчёта

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

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

В списке доступных отчётов найти нужный отчёт, нажать и выбрать "Удалить". Откроется форма редактирования отчёта.

Рисунок — Форма редактирования отчёта. Настройка рассылки отчета

На вкладке "Основное" заполните следующие данные:

• Тип вложения — выбрать, будет ли отчёт прикреплён как файл или отправлен в виде ссылки;

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

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

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

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

• Повторять — настроить периодичность (доступные варианты: Никогда (запустить один раз), Ежедневно, По будням, Еженедельно, Ежемесячно, Ежегодно). При выборе периода повторения откроется настройка повторений.

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

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

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

Для построения отчета необходимо перейти на вкладку "Настройки". В списке доступных отчётов найти нужный и нажать . Откроется форма построения отчёта.

Рисунок — Форма построения отчёта

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

Рисунок — Форма построения отчёта

После заполнения формы отчета нажать . В Системе будет создана задача построения отчета.

Перейти на вкладку "Сформированные отчеты".

Рисунок — Вкладка "Сформированные отчёты"

В списке отчетов появится запись о сформированном отчете, содержащая следующую информацию:

Таблица — Вкладка "Сформированные отчёты"

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

Таблица — Действия для сформированных отчётов

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

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

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

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

2. На языке C# создайте компонент, реализующий обязательный интерфейс IReportDataSource и, при необходимости, вспомогательные интерфейсы (например, IReportParametersValidator для валидации параметров).

3. Соберите проект в библиотеку DLL, содержащую ваш компонент.

4. Разместите DLL в специальной папке для плагинов на всех узлах IGA. Путь к папке задаётся параметром connectorsFolder в файле Iga.config. Можно размещать каждый плагин в своей подпапке.

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

6. В интерфейсе IDM перейдите в раздел Отчёты на вкладку Формы.

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 содержит следующие обязательные элементы:

Заголовок отчета (Report Title) — отображается один раз в начале документа. Включает название отчета, логотип организации и общую информацию.

Заголовки колонок (Page Header) — выводятся на каждой странице и содержат названия столбцов таблицы данных.

Область данных (Data Band) — основная часть отчета, которая повторяется для каждой строки данных. Здесь размещаются ссылки на конкретные поля, возвращаемые плагином.

Нижний колонтитул (Page Footer) — отображается внизу каждой страницы. Обычно содержит номер текущей страницы, общее количество страниц и дату формирования отчета.

Рисунок — Редактирование формы отчёта

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

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

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

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

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

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