Настройка отчетов в Creatio

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

Раздел [Настройка отчетов] позволяет пользователям создавать отчеты средствами Creatio и выполнять их настройку c помощью дизайнера отчетов FastReport. С обзором раздела и описанием интерфейса (рис. 1) можно ознакомиться в статье "Раздел "Настройка отчетов".

Рис. 1. — Страница настройки отчета

Общий порядок действий при создании отчета:

1. Установите дизайнер отчетов FastReport (выполняется единоразово).
2. Создайте отчет в разделе настройки отчетов.
3. Укажите источники данных для отчета.
4. Создайте провайдер данных отчета, который будет реализовывать логику обработки данных.
5. Скачайте файл с источниками данных и настройте его в дизайнере отчетов FastReport.
6. Загрузите настроенный шаблон отчета в Creatio.

Установка дизайнера отчетов FastReport

Для установки дизайнера отчетов FastReport необходимо скачать zip-архив с установочными файлами по ссылке.

Создание нового отчета

Чтобы создать новый отчет, выполните следующие действия:

1. Перейдите в дизайнер системы по кнопке . В блоке [Настройка системы] перейдите по ссылке [Настройка отчетов] ([Report setup]).
2. Нажмите кнопку [Добавить отчет] ([New report]) (рис. 1, 1).
3. В области настройки параметров отображения (рис. 1, 2) для нового отчета задайте заголовок, раздел, к которому относится отчет, параметры отображения.

Указание источников данных для отчета

В блоке [Укажите источники данных для отчета] ([Specify data sources for the report]) рабочей области страницы (рис. 1, 4) укажите перечень объектов, их колонки и связи, которые будут использоваться для получения данных. При необходимости, укажите локализуемые строки. Для указания источников данных используйте формат json. Пример представления источника данных:

{
    // Название класса провайдера данных.
    "ProviderName": "YourProviderName",
    // Структура таблиц для шаблона отчета.
    "Schemas": {
        // Имя таблиц базы данных или виртуальных таблиц, колонки которых необходимо добавить в отчет.
        "TableName1": {
            // Имя колонки, которую необходимо добавить в отчет.
            "ColumnName1": {
                // Тип данных колонки.
                "DataValueType": DataValueType1
            },
            "ColumnName2": {
                "DataValueType": DataValueType2
            }
        },
        "TableName2": {
            "ColumnName1": {
                "DataValueType": DataValueType1
            },
            "ColumnName2": {
                "DataValueType": DataValueType2
            }
        },
        // Локализуемые строки отчета.
        "LocalizableStrings": {
            // Имя локализуемой строки отчета.
            "LocalizableString1": {
                // Тип данных локализуемой строки.
                "DataValueType": 1
            },
            "LocalizableString2": {
                "DataValueType": 1
            }
        }
    }
}

Чтобы сохранить данные, нажмите кнопку [Применить] ([Apply]) на панели инструментов (рис. 1, 1).

Создание провайдера данных отчета

Провайдер данных отчета — это пользовательский класс на языке C#. Чтобы его создать, выполните следующие действия:

1. В пользовательском пакете разработки создайте схему типа [Исходный код] ([Source Code]).
2. В исходном коде схемы создайте класс сервиса. Задействуйте пространство имен Terrasoft.Configuration или любое вложенное в него. Пометьте класс атрибутом [DefaultBinding] с необходимыми параметрами. Класс сервиса должен быть наследником Terrasoft.Configuration.Reporting.FastReport.IFastReportDataSourceDataProvider.
3. Добавьте в класс реализацию метода GetLocalizableStrings(UserConnection). Метод реализовывает локализацию полей отчета.
4. Добавьте в класс реализацию метода ExtractFilterFromParameters(UserConnection, Guid, IReadOnlyDictionary). Метод реализовывает добавление фильтров интерфейса.
5. Добавьте в класс реализацию метода GetData(UserConnection, IReadOnlyDictionary), который должен возвращать значение типа Task<ReportDataDictionary>. В методе необходимо описать реализацию логики получения данных отчета.
6. Опубликуйте схему исходного кода.

Пример реализации логики обработки данных отчета:

namespace Terrasoft.Configuration
{
    using System.Collections.Generic;
    using System.Threading.Tasks;
    using Terrasoft.Configuration.Reporting.FastReport;
    using Terrasoft.Core;
    using Terrasoft.Core.Factories;
    
    // Название класса провайдера данных для отчета, логику которого необходимо реализовать.
    [DefaultBinding(typeof(IFastReportDataSourceDataProvider), Name = "YourProviderName")]
    public class YourProviderName : IFastReportDataSourceDataProvider
    {
        // Код реализации логики получения данных для отчета.
        
        // Локализация полей отчета.
        private IEnumerable<IReadOnlyDictionary<string, object>> GetLocalizableStrings(UserConnection userConnection) {
            var localizableStrings = _localizableStringNames.ToDictionary(
                x => x,
                x => (object)(new LocalizableString(userConnection.ResourceStorage, _resourceManagerName, $"LocalizableStrings.{x}.Value")).Value);
            return new[] { localizableStrings };
        }
        
        // Добавление фильтров интерфейса.
        private IEntitySchemaQueryFilterItem ExtractFilterFromParameters(UserConnection userConnection, Guid entitySchemaUId,
                IReadOnlyDictionary<string, object> parameters) {
            var managerItem = userConnection.EntitySchemaManager.GetItemByUId(entitySchemaUId);
            return parameters.ExtractEsqFilterFromReportParameters(userConnection, managerItem.Name) ?? throw new Exception();
        }
        
        // Добавление данных в отчет.
        public Task<ReportDataDictionary> GetData(UserConnection userConnection, IReadOnlyDictionary<string, object> parameters) {            
            
        }

    }
}

Настройка шаблона в дизайнере отчетов FastReport

Скачайте файл с источниками данных. Для этого в блоке [Скачайте файл с источниками данных и сформируйте шаблон отчета] ([Download file with data sources to design a report in the FastReport Designer]) страницы (рис. 1, 4) нажмите кнопку [Скачать файл] ([Download file]). Файл будет иметь расширение *.frx.

Двойным кликом откройте скачанный файл в дизайнере отчетов FastReport и настройте внешний вид шаблона. Выполнение настройки описано в документации FastReport.

Загрузка настроенного шаблона в Creatio

Загрузка подготовленного шаблона отчета в Creatio выполняется нажатием кнопки [Загрузить шаблон] ([Upload template]) в блоке [Загрузите настроенный шаблон отчета в Creatio] ([Import a file with the report template]) (рис. 1, 4). После загрузки шаблона отчет можно сформировать в реестре, на странице записи или в аналитике раздела. Это определяется настройками в области параметров отображения (рис. 1, 2). Готовый отчет будет сохраняться в формате pdf.

Описание примера

Создать базовый отчет "Contact Data", который отображает следующую информацию о контактах:

• [ФИО] ([Full name]);
• [Дата рождения] ([Birthday]);
• [Пол] ([Gender]);
• [Контрагент] ([Account]).

Исходный код

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

Алгоритм реализации примера

1. Выполните настройку параметров отображения отчета

Для создаваемого отчета в области настройки параметров отображения (рис. 1, 2) установите (рис. 2):

• [Название отчета] ([Report title]) — "Contact Data".
• [Раздел] ([Section]) — "Contacts".
• [Отображать в разделе] ([Show in section]) — установить.
• [Отображать на странице записи] ([Show in card]) — установить.
• [Отображать в аналитике раздела] ([Show in the section analytics view]) — установить.
• [Страница фильтрации] ([Filter page]) — SimpleReportFilterPage.

Рис. 2. — Настройка параметров отображения отчета

2. Укажите источники данных

В блоке [Укажите источники данных для отчета] ([Specify data sources for the report]) рабочей области страницы (рис. 1, 4) добавьте следующий код:

{
    // Название класса провайдера данных.
    "ProviderName": "ContactDataProvider",
    "Schemas": {
        "ContactData": {
            "Full name": {"DataValueType": 1},
            "Birthday": {"DataValueType": 1},
            "Gender": {"DataValueType": 1},
            "Account": {"DataValueType": 1}
        },
        // Добавляется для локализации.
        "LocalizableStrings": {
            "ReportTitle": {"DataValueType": 1},
            "FullNameLabel": {"DataValueType": 1},
            "BirthdayLabel": {"DataValueType": 1},
            "GenderLabel": {"DataValueType": 1},
            "AccountLabel": {"DataValueType": 1}
        }
    }
}

Для сохранения внесенных изменений нажмите кнопку [Применить] ([Apply]) на панели инструментов страницы (рис. 1, 1).

3. Создайте провайдер данных отчета

В разделе [Конфигурация] ([Configuration]) пользовательского пакета на вкладке [Схемы] ([Schemas]) выполните действие [Добавить] —> [Исходный код] ([Add] —> [Source Code]). Процесс создания схемы типа [Исходный код] ([Source Code]) описан в статье "Создание схемы [Исходный код]".

Для создаваемой схемы объекта установите (рис. 3):

• [Заголовок] ([Title]) — "Contact Data";
• [Название] ([Name]) — "UsrContactDataSourceCode".

Рис. 3. — Настройка схемы объекта типа [Исходный код] ([Source Code])

Полностью исходный код представлен ниже.

namespace Terrasoft.Configuration
{
    using System;
    using System.Collections.Generic;
    using System.Collections.ObjectModel;
    using System.Linq;
    using System.Threading.Tasks;
    using Terrasoft.Common;
    using Terrasoft.Configuration.Reporting.FastReport;
    using Terrasoft.Core;
    using Terrasoft.Core.Entities;
    using Terrasoft.Core.Factories;
    using Terrasoft.Nui.ServiceModel.Extensions;
    using EntitySchema = Terrasoft.Core.Entities.EntitySchema;
    using EntitySchemaColumn = Terrasoft.Core.Entities.EntitySchemaColumn;

    // Название класса провайдера данных для отчета, логику которого необходимо реализовать.
    [DefaultBinding(typeof(IFastReportDataSourceDataProvider), Name = "ContactDataProvider")]
    public class ContactDataProvider : IFastReportDataSourceDataProvider
    {

        private Guid _entitySchemaUId = new Guid("16BE3651-8FE2-4159-8DD0-A803D4683DD3");
        // Название схемы c исходным кодом.
        private readonly string _resourceManagerName = "UsrContactDataSourceCode";
        private readonly string[] _localizableStringNames = new[] {
            "ReportTitle",
            "FullNameLabel",
            "BirthdayLabel",
            "GenderLabel",
            "AccountLabel"
        };

        // Заполнение колонок в отчете.
        private IEnumerable<IReadOnlyDictionary<string, object>> GetContactData(
            UserConnection userConnection,
            Guid entitySchemaUId,
            IEntitySchemaQueryFilterItem filter) {
                // Получить схему объекта.
                var entitySchema = userConnection.EntitySchemaManager.GetInstanceByUId(entitySchemaUId);
                // Создание объекта класса EntitySchemaQuery.
                EntitySchemaQuery query = new EntitySchemaQuery(entitySchema);
                // Добавление колонок в запрос.
                query.AddColumn("Name");
                query.AddColumn("BirthDate");
                var gender = query.AddColumn("Gender.Name");
                var account = query.AddColumn("Account.Name");
                // Добавление созданного фильтра.
                query.Filters.Add(filter);
                // Получить коллекцию контактов.
                var contacts = query.GetEntityCollection(userConnection);
                var contactsCollection = new Collection<Dictionary<string, object>>();
                // Заполнение колонок в отчете.
                foreach (var entity in contacts)
                {
                    contactsCollection.Add(new Dictionary<string, object> {
                        ["Full name"] = entity.GetTypedColumnValue<string>("Name"),
                        ["Birthday"] = entity.GetTypedColumnValue<string>("BirthDate"),
                        ["Gender"] = entity.GetTypedColumnValue<string>(gender.Name),
                        ["Account"] = entity.GetTypedColumnValue<string>(account.Name)
                    });
                }
                return contactsCollection;
        }
        
        // Локализация заголовков отчета.
        private IEnumerable<IReadOnlyDictionary<string, object>> GetLocalizableStrings(UserConnection userConnection) {
            var localizableStrings = _localizableStringNames.ToDictionary(
                x => x,
                x => (object)(new LocalizableString(userConnection.ResourceStorage, _resourceManagerName, $"LocalizableStrings.{x}.Value")).Value);
            return new[] { localizableStrings };
        }
        
        // Добавление фильтров интерфейса.
        private IEntitySchemaQueryFilterItem ExtractFilterFromParameters(UserConnection userConnection, Guid entitySchemaUId,
                IReadOnlyDictionary<string, object> parameters) {
            var managerItem = userConnection.EntitySchemaManager.GetItemByUId(entitySchemaUId);
            return parameters.ExtractEsqFilterFromReportParameters(userConnection, managerItem.Name) ?? throw new Exception();
        } 

        // Получить данные.
        public Task<ReportDataDictionary> GetData(UserConnection userConnection, IReadOnlyDictionary<string, object> parameters) {
            var filter = ExtractFilterFromParameters(userConnection, _entitySchemaUId, parameters);
            var result = new ReportDataDictionary {
                // Заполнить колонки в отчете.
                ["ContactData"] = GetContactData(userConnection, _entitySchemaUId, filter),
                ["LocalizableStrings"] = GetLocalizableStrings(userConnection)
            };
            return Task.FromResult(result);
        }
    }
}

Присвойте локализуемым строкам шаблона отчета следующие значения (табл. 1):

Табл. 1. — Настройка локализованных строк

Больше о работе с локализуемыми строками в статье "Дизайнер исходного кода".

Опубликуйте схему.

4. Скачайте шаблон из Creatio и настройте его внешний вид в FastReport

Скачайте файл ContactData.frx. Для этого в блоке [Скачайте файл с источниками данных и сформируйте шаблон отчета] ([Download file with data sources to design a report in the FastReport Designer]) рабочей области страницы (рис. 1, 4) нажмите кнопку [Скачать файл] ([Download file]).

Чтобы открыть шаблон в дизайнере отчетов, выполните следующие действия:

1. Откройте дизайнер отчетов FastReport, запустив файл Terrasoft.Reporting.FastReport.Designer.exe из zip-архива (рис. 4).

   Рис. 4. — Файл с дизайнером отчетов FastReport

   

2. Нажмите кнопку [Open...] в появившимся окне (рис. 5).

   Рис. 5. — Кнопка [Open...]

   
   Также перейти к выбору шаблона отчета можно в меню [File] по нажатию кнопки [Open...] (рис. 6) или по нажатию клавиш [Ctrl+O].

   Рис. 6. — Кнопка [Open...] в меню [File]

   

3. Перейдите в папку со скачанным отчетом (обычно Downloads), выберите файл с шаблоном и нажмите кнопку [Open] (рис. 7).

   Рис. 7. — Открытие шаблона отчета в FastReport

   

Настройте внешний вид шаблона (рис. 8).

Рис. 8. — Настройка шаблона в дизайнере отчетов FastReport

5. Загрузите настроенный шаблон в Creatio

Чтобы загрузить файл ContactData.frx, нажмите кнопку [Загрузить шаблон] ([Upload template]) в блоке [Загрузите настроенный шаблон отчета в Creatio] ([Import a file with the report template]) рабочей области страницы (рис. 1, 4). Подтвердите успешность загрузки шаблона.

В результате отчет "Contact Data" будет доступен на странице контакта по кнопке [Печать] ([Print]) (рис. 9).

Рис. 9. — Отображение отчета "Contact Data" на странице записи раздела [Контакты] ([Contacts])

Также отчет доступен в аналитике раздела [Контакты] ([Contacts]) по кнопке [Отчеты] ([Reports]) (рис. 10).

Рис. 10. — Отображение отчета "Contact Data" в аналитике раздела [Контакты] ([Contacts])

Формирование отчета выполняется в соответствии с выбранной опцией [По отфильтрованным в разделе записям] ([Filtered records in list]) на странице фильтрации (рис. 11). Для загрузки отчета нажмите кнопку [Создать отчет] ([Create report]), для закрытия страницы фильтрации и отмены формирования отчета нажмите [Отмена] ([Cancel]).

Рис. 11. — Страница фильтрации отчета "Contact Data"

Отчет имеет следующий вид (рис. 12).

Рис. 12. — Пример отчета "Contact Data"

Отчет по нескольким записям раздела

Чтобы включить в отчет информацию из нескольких записей раздела, выполните следующие действия (рис. 13):

1. Перейдите в раздел.
2. При необходимости установите фильтр.
3. Выполните [Действия] —> [Выбрать несколько записей] ([Actions] —> [Select multiple records]).
4. Выберите необходимый отчет в выпадающем списке кнопки [Печать] ([Print]).

Рис. 13. — Получение отчета "Contact Data" из нескольких записей раздела [Контакты] ([Contacts])

Отчет имеет следующий вид (рис. 14).

Рис. 14. — Пример отчета "Contact Data" по нескольким записям раздела

Мультиязычные элементы интерфейса в отчетах

Раздел [Переводы] ([Translations]) дизайнера системы позволяет установить значение элементов интерфейса для отчета на разных языках. Выполнить поиск локализуемых ранее строк отчета можно по ключу Configuration:НазваниеCхемы (например, Configuration:UsrContactDataSourceCode). Поиск поля отчета можно выполнить по ключу Configuration:НазваниеСхемы:НазваниеПоля.Value (например, Configuration:UsrContactDataSourceCode:LocalizableStrings.ReportTitle.Value).

При установленных признаках [Отображать в разделе] ([Show on the section list review]) и [Отображать на странице записи] ([Show on the section record page]) необходимо выполнить перевод отображаемого названия отчета. Его поиск можно выполнить по ключу Configuration:НазваниеСхемы:Caption (например, Configuration:UsrContactDataSourceCode:Caption). При установленном признаке [Отображать в аналитике раздела] ([Show in the section analytics view]) (рис. 1, 2) необходимо выполнить перевод отображаемого названия отчета. Его поиск можно выполнить по ключу Data:SysModuleAnalyticsReport.Caption:ИдентификаторПоля (например, Data:SysModuleAnalyticsReport.Caption:d52e8b78-772b-77ee-3394-bdb3616d859a).

Работа с разделом [Переводы] ([Translations]) описана в статье "Как выполняется перевод интерфейса и элементов системы".

Перенос пакета с отчетом на другую среду разработки

Чтобы перенести пакет с отчетом на другую среду, в разделе [Конфигурация] ([Configuration]) перейдите на вкладку [Данные] ([Data]) и выполните привязку данных следующих элементов:

• FastReportDataSource_ReportName — источник данных отчета. Подключается по Id источника из таблицы [dbo.FastReportDataSource] базы данных.
• FastReportTemplate_ReportName — шаблон отчета. Подключается по Id шаблона из таблицы [dbo.FastReportTemplate] базы данных.
• SysModuleReport_ReportName — отчет. Подключается по Id отчета из таблицы [dbo.SysModuleReport] базы данных.