Руководство администратора

Отчеты используются для формирования сводной аналитики по данным, хранящимся в системе — задачам, процессам, документам, пользователям. В "Первой Форме" есть набор типовых отчетов, которые поставляются вместе с приложением. Если у организации возникает потребность разработки дополнительных отчетов, для этого может использоваться дизайнер FastReport. С его помощью можно обращаться напрямую к данным, хранящимся в таблицах БД и получаемым через хранимые процедуры MS SQL Server, и предоставлять их конечным пользователям в наглядном, удобном для восприятия виде.

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

Ссылка на загрузку дизайнера отчетов

Общие принципы разработки отчета в FastReport

Для формирования отчетов FastReport использует данные, с которыми работает приложение "Первая Форма" и которые хранятся на сервере БД.

Для каждого отчета в FasrReport создается шаблон отчета, в котором указываются источники и критерии отбора данных, правила обработки и представления этих данных.

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

•выводиться для просмотра на экран,

•выводиться на печать,

•экспортироваться в документы (текстовые или электронные таблицы),

•отправляться по email.

Эти принципы работы отображены на схеме:

Схема возможностей FastReport

Подробнее о построении отчетов вы можете прочитать в Документации по платформе FastReport от производителя.

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

1. В режиме администратора "Первой Формы" создайте отчет и настройте для него права доступа.

2. Если отчет будет вызываться из определенного контекста (из задачи, категории, раздела, профиля пользователя), то укажите для него контекст. Если для отчета нужны дополнительные условия отбора данных в пользовательском режиме, то создайте или выберите фильтр. После этого отчет можно открывать в дизайнере FastReport. В соответствии с указанными контекстом и фильтром в отчете будут автоматически созданы параметры.

3. В дизайнере создайте или укажите источники данных для отчета. Источниками данных могут быть таблицы базы данных, запросы, построенные на основе этих таблиц, и хранимые процедуры из базы данных. В одном отчете может быть несколько объектов Connection, хотя в большинстве случаев этого не требуется. Между источниками данных могут быть установлены связи "главный-подчиненный".

4. На основе источников данных и параметров отчета создайте страницы отчета — шаблоны, которые будут наполняться данными в момент формирования отчета. В одном отчете могут присутствовать несколько страниц отчета, которые будут использоваться в зависимости от настроенной в отчете логики. Кроме того, страницы могут быть вложены одна в другую по принципу "главный-подчиненный" для детализации выводимых данных.

Пример страницы отчета

5. В процессе настройки вы можете проверить работу отчета с помощью режима предварительного просмотра:

Переход в режим предварительного просмотра отчета из дизайнера

Имейте в виду, что результаты предварительного просмотра отчета в win-дизайнере и реальной работы отчета в web-интерфейсе могут различаться.

Источники данных

Для работы с отчетом надо определить для него источники данных. После создания или подключения они доступны в ветке Источники данных, в объектах Connection.

Источники данных, настроенные в отчете

Создание нового источника данных

В качестве источников данных для отчетов могут использоваться:

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

Выбор таблицы в качестве источника данных

2. Запросы. Для создания запроса можно ввести его текст в поле (1) или использовать конструктор запросов (2):

Создание запроса для получения данных

В окне запроса можно писать не только строго текст SQL-запроса, но и код, соответствующий хранимой процедуре (декларировать и использовать дополнительные переменные и т.п.).

3. Хранимые процедуры. Для вызова хранимой процедуры можно в поле текста запроса ввести строку вида: exec StoredProcName Param1, Param2, ..... ParamN

где StoredProcName — имя процедуры, а Param1... ParamN — значения передаваемых параметров в том порядке, как они описаны в самой процедуре.

Просмотр существующих источников данных

Если вы работаете с отчетом, в котором уже есть источники данных, посмотреть их можно в блоке Connection.

Источники данных, настроенные в отчете

Чтобы посмотреть текст запроса или хранимой процедуры, кликните дважды по названию источника и нажмите кнопку Вперед.

Просмотр запроса или хранимой процедуры

Если источник данных — готовая таблица, то поле с текстом запроса будет пустым.

Параметры

После создания или выбора источников данных необходимо указать, по каким условиям отбираются данные из этих источников. Для этого используются параметры. Они доступны в ветке Параметры панели данных.

Параметры отчета

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

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

1. Во все отчеты в качестве параметра передается ID пользователя, который открыл отчет для просмотра (CurrentUserID) — это необходимо для проверки прав пользователя, поскольку ему должна отображаться только та информация, которую он уполномочен просматривать.

2. Параметры контекста. Контекст описывает место в системе, откуда вызывается отчет, и позволяет адаптировать отчет под конкретное окружение. Например, если отчет вызывается из профиля пользователя, то в отчет будут отобраны данные именно по этому пользователю. Параметры контекста формируются автоматически при вызове отчета и передаются в отчет.

Контекст задается в интерфейсе администратора для каждого отчета отдельно:

Контекст вызова отчета, определяемый в интерфейсе администратора

3. Параметры, определяемые фильтром. Фильтры — это пользовательский инструмент для управления отбором данных в отчете. В пользовательском режиме окно фильтров отображается при нажатии на иконку на панели инструментов отчета:

Параметры отчета, отображаемые в интерфейсе пользователя

4. Сами фильтры настраиваются в режиме администратора, а значения этих фильтров меняет пользователь в процессе работы с отчетом. Например, администратор настраивает для отчета фильтр для отбора данных за период, а пользователь при работе с отчетом указывает нужный ему период времени.

Фильтр задается в интерфейсе администратора для каждого отчета отдельно. Каждый фильтр описывает определенный набор параметров отбора (например, период и группу). Один и тот же фильтр может использоваться несколько раз для разных отчетов, если данные в них отбираются по одним и тем же критериям.

Фильтры отчетов в интерфейсе администратора

Настройка фильтров для отчета аналогична настройке фильтров портального блока. Название параметра, определяемого фильтром и передаваемого в отчет, формируется из двух частей — слова Filter и имени параметра, заданного при настройке фильтра. Для фильтров с типом "Период" создаются два параметра, определяющие начало и окончание периода, поэтому их названия дополняются словами From и To:

Контекст вызова отчета

Все параметры отчета используются совместно, не отменяя друг друга и не имея преимуществ.

Передача параметров в источник данных

1. Параметры могут передаваться в SQL-запросы, которые используются в отчете в качестве источника данных. В тексте SQL-запроса параметры обозначаются символом @. На следующем шаге мастера запроса надо определить все эти параметры. Для каждого параметра, упоминаемого в тексте SQL-запроса, нужно выполнить следующие действия:

Создайте параметр, нажав на иконку . Имя параметра (Name) должно соответствовать имени, которое употребляется в тексте SQL-запроса. В большинстве случаев для параметра можно оставить тип VarChar, который будет автоматически преобразован к нужному типу в процессе выполнения отчета.

В поле Expression выберите параметр отчета, который должен подставляться вместо параметра SQL-запроса.

Связывание параметров отчета с параметрами запроса

Как правило, для дат необходимо напрямую указать тип DateTime (если преобразования не выполняются в самом запросе). Если для параметра указан тип не VarChar, то для него необходимо задать значение по умолчанию (DefaultValue), для остальных параметров это поле можно оставить пустым.

2. Если вместо SQL-запроса используется хранимая процедуры, то связь между ее параметрами и параметрами отчета выполняется аналогичным образом.

Связывание параметров отчета с параметрами хранимой процедуры

3. Параметры можно использовать также и другими способами, например, в коде отчета или при отборе в бэнде "Данные":

Использование параметров отчета в настройках фильтра бэнда данных

Особенности работы с различными типами параметров

Дата и Период

Параметр "Дата" передает одну дату, а параметр "Период" определяется двумя датами — датой начала и датой окончания. Поэтому для параметров типа Период в отчет всегда передаются два параметра — например, FilterPeriodFrom и FilterPeriodTo.

Произвольный период

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

Выбор произвольного периода

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

Значение по умолчанию из смарт-выражения

Значение по умолчанию может задаваться не только как один из предопределенных периодов (текущий месяц, предыдущий месяц и т.п.), но и как произвольный период, вычисляемый смарт-выражением.

Период по умолчанию задается смарт-выражением

В общем случае смарт-выражение должно возвращать список из двух дат: { ДатаОт, ДатаДо }.

Если начало периода не ограничено, то вместо первой даты должно стоять значение null: { null, ДатаДо }.

Если конец периода не ограничен, то смарт-выражение может возвращать список из одной даты { ДатаОт } или просто одну дату, без списка.

Если смарт-выражение задано как запрос TSQL, то запрос должен возвращать одну или две строки, и первая колонка должна быть датой. Значение первой колонки в первой строке интерпретируется как начало периода, а во второй строке (если она есть) — как конец периода.

Смарт-выражение для значения параметра "Дата" по умолчанию

Выпадающий список

Значение параметра типа Выпадающий список передается в отчет в виде строки. Это удобно, например, для выбора одного из преднастроенных значений:

Настройка параметра Выпадающий список.

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

if ((String)Report.GetParameterValue("FilterViolation")=="вопрос")
   Column1.Visible = true;

Если в выпадающем списке включен режим мультивыбора, то в отчет передается строка со значениями, перечисленными через запятую без пробелов (например, "план,факт,осталось").

Если выпадающий список формируется как результат смарт-выражения, то в качестве значения в параметр отчета часто передается числовой идентификатор. Но в параметр отчета он также передается в виде строки. Этот параметр затем используется в SQL-запросе. Чтобы обеспечить автоматическое преобразование строки в число, для параметра запроса можно задать тип VarChar:

Настройка параметра Выпадающий список

Пример фильтра, заданного смарт-выражением

Если для создания нужного смарт-фильтра не хватает штатных инструментов, можно использовать дополнительные возможности смартов (см. здесь).

Пользователь, Группа, Оргструктура, Категория

Фильтры для выбора пользователей, групп пользователей, орг. единиц и категорий не имеют значений по умолчанию. Для них по умолчанию включен режим мультивыбора — нельзя настроить их так, чтобы пользователь мог выбрать только одно значение. Для таких фильтров в отчет передается строка с ID выбранных элементов, перечисленными через запятую без пробелов (например, "12345,98765,13579").

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

"Пустые" значения и значения по умолчанию

При настройке фильтра для параметра, как правило, может быть задано значение по умолчанию, которое передается в отчет в момент его открытия.

В пользовательском интерфейсе для параметров типа Выпадающий список невыбранное (пустое) значение обозначается значением "-", а для параметров типа Период — также значением "-" или значением "Другой" с двумя пустыми датами.

Значения по умолчанию и значения, выбранные пользователем в процессе работы с отчетом, передаются в отчет одинаково:

•если значение выбрано, то оно передается в отчет в виде пары дат для Периода, в виде числа для Числа и в виде строки для остальных типов.

•если значение не выбрано, то в отчет в соответствующий параметр типа Пользователь, Группа, Оргстурктура, Категория передается пустая строка "", а для Выпадающего списка, Строки, Числа и Периода — значение null.

 

Пустое значение по умолчанию

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

Способ 1:

1. Откройте отчет в дизайнере, вручную создайте нужный параметр нужного типа  (String, DateTime или Int32). Имя параметра должно соответствовать шаблону Filter<имя> (для Периода — Filter<имя>From и Filter<имя>To), где <имя> — это имя параметра, как оно задано в настройках фильтра.

2. Сохраните отчет.

Способ 2:

1. Выберите в фильтре в качестве значения по умолчанию любое непустое значение и сохраните настройки фильтра;

2. Откройте отчет в дизайнере, убедитесь что нужные параметры автоматически создались и сохраните отчет;

3. Вернитесь в настройки фильтра и укажите пустое значение по умолчанию.

Работа с пустыми значениями в Выражениях (Expression)

Если в параметр передано значение null, то при работе с такими параметрами на странице отчета (например, при форматировании) будет возникать ошибка. Поэтому необходимо выполнять дополнительные проверки, например:

Обработка пустых значений в выражении.

В данном случае используется тернарный оператор языка С#, который является аналогом условной функции IIf()  и состоит из трех частей:

<булево условие> ? <выражение, которое вычисляется если условие = true> : <выражение, которое вычисляется если условие = false>

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

Работа с пустыми значениями в SQL запросах

Если в качестве источников данных используются SQL-запросы, то для проверки периода можно использовать, например, такую конструкцию:

WHERE (@from is null OR t.Date>= @from) AND (@to is null OR t.Date <= @to)

В таком условии проверяются и ограниченные, и открытые периоды.

При обработке SQL-запроса если значение параметра не может быть вычислено (например, оно равно null), то вместо такого параметра подставляется значение, заданное по умолчанию:

Значения по умолчанию для параметров запроса

Чтобы в случае открытого периода в отчет попадали все записи, значения по умолчанию нужно подбирать так, чтобы они заведомо были меньше самой ранней даты в вашей базе данных (например, "01.01.1900") или больше самой поздней возможной даты (например, "01.01.2900"). Обратите внимание, что значение самого параметра отчета при этом не изменяется и остается равным null, а значение по умолчанию подставляется только при обработке SQL-запроса.

Страницы отчета

Для включения интерфейса "Лента" (Ribbon) перейдите во вкладку "Вид" (View) и выберите пункт "Опции..." (Options...) — в открывшемся окне отметьте опцию "Использовать интерфейс Лента" (Use the new Ribbon interface):

Шаги для включения интерфейса "Лента" (Ribbon)

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

Добавление страницы в отчет

Страница отчета представляет собой шаблон, который наполняется реальными данными в момент формирования отчета. Страница отчета состоит из горизонтальных областей — бэндов. Каждый бэнд формирует определенную область страницы итогового отчета  — заголовок отчета, "шапку" страницы, детальные строки отчета, "подвал" страницы, "подвал" отчета и др.

Структура страниц и бэндов в отчете

FastReport содержит инструменты для автоматической группировки данных и подведения промежуточных итогов. Например, можно сгруппировать данные по пользователю, группе пользователей, контрагенту, дате и т.п. и по каждой группе получить промежуточные итоги.

Структура отчета при просмотре в интерфейсе пользователя

На бэнде "Данные" обычно размещаются элементы, которые соответствуют данным одной строки результирующего набора данных. Чтобы бэнд был повторен в отчете столько раз, сколько строк в результирующем наборе, для бэнда необходимо указать источник данных в свойстве DataSource.

Источник данных для элемента указывается в свойстве Text. Значения свойств могут задаваться как в редакторе свойств , так и непосредственно в коде — в процедурах, назначенных обработчиками событий. Обработчики событий указываются на вкладке "События" и программируются в коде.

Настройки страницы

На вкладке "Бумага" нужно установить правильную ориентацию страницы.

На вкладке "Прочее" важны следующие настройки:

•при включенном флажке "Широкая страница в дизайнере" вы сможете размещать элементы отчета так, чтобы они выходили за пределы размеров страницы. При выгрузке на печать эти элементы будут попадать на отдельную (следующую) страницу;

•при включенном флажке "Unlimited height" отчет будет отображаться в веб-интерфейсе без разрыва страниц по вертикали. Это удобно, например, при работе с длинными таблицами;

•при включенном флажке "Unlimited width" отчет будет отображаться в веб-интерфейсе без разрыва страниц по горизонтали. Это удобно при работе с широкими таблицами, особенно с матрицами, которые "растут" не только в длину, но и в ширину.

Параметры страницы отчета

Примеры

Вывод матрицы — с включенным флажком Unlimited width не будет разрывов страницы по горизонтали

Особенности использования FastReport

Использование тернарного оператора вместо IIf

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

  <булево условие> ? <выражение, которое вычисляется если условие = true> : <выражение, которое вычисляется если условие = false>

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

Проверка пустого значения при форматировании

Например, для формирования строки с периодом можно использовать такое выражение:

за период с [IsNull("FilterPeriodFrom")?"-":FormatDateTime([FilterPeriodFrom])] по [IsNull("FilterPeriodTo")?"-":FormatDateTime([FilterPeriodTo])]

Преимущество тернарного оператора

При использовании функции IIf() сначала вычисляются все три выражения (булево условие, выражение для true и выражение для false), а затем выбирается нужное выражение в зависимости от условия. Таким образом, если вы хотите отформатировать дату, как в примере выше, то для значения null форматирование вызовет ошибку. При использовании тернарного оператора сначала вычисляется условие, а потом, в зависимости от него, вычисляется только одно из двух выражений. Поэтому для значения null форматирование не будет выполнено, и ошибка не возникнет.

Преобразование параметров к нужному типу

Данные не всегда могут быть автоматически преобразованы к нужному типу (например, тип Int32 к типу Double). В частности, если вы используете в выражениях цифровые константы, то они должны быть нужного типа. Например, на скриншоте ниже для работы с типом Double используется константа 60.0 (константа 60 вызвала бы ошибку).

Работа с типом Double

При обработке выражений и SQL-запросов параметры, изначально имеющие тип String, могут автоматически преобразовываться к нужному типу. Однако в рамках одного отчета тип параметра должен быть одинаковым. Например, если параметр используется для передачи идентификатора, т.е. преобразуется к типу Int32, то для сравнения можно использовать такое выражение:

(@UserID = 0 OR Users.UserID = @UserID)

Если же параметр используется для передачи текстового значения, т.е. как тип String, то для сравнения можно использовать такое выражение:

(@UserName= '' OR Users.FullName = @UserName)

Итоги для группы

Если итоги по группе выводятся не в подвале группы, а в заголовке, то для итогового поля необходимо поставить свойство ProcessAt равное GroupFinished, а для всего отчета (объекта Report в дереве отчета) свойство DoublePass надо установить равным True. В этом случае отчет будет формироваться в два прохода: на первом проходе итоги будут подсчитываться, а на втором — выводиться на печать. Подробнее об этом написано в документации по FastReport.

Однако название группы должно формироваться на первом проходе (ProcessAt равное Default). Поэтому название и итог в этом случае должны обязательно выводиться в разных полях:

Разделение названия группы и итогов по группе

Вызов детальной страницы с параметром — списком значений

Если при вызове страницы детализации в качестве значения параметра требуется передать в строке список значений (например, список из нескольких ID задач), то в качестве разделителя списка нельзя использовать запятую. Следует использовать какой-либо другой, "нейтральный" символ — например, подчеркивание.

Запятая воспринимается FastReport-ом как разделитель между значениями нескольких параметров.

Пример

Вызов отчета по нажатию на кнопку на карточке задачи

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

Вызов отчета по нажатию на настраиваемую кнопку в карточке задачи

В поле "JavaScript выражение" записывается строка вида:

window.open('/MVC/ReportView/123/contextId/' + TaskID,'_newtab');

где 123 — ID отчета, TaskID - параметр для передачи контекста задачи.

Восстановление отчета из архивной копии

Структура отчета хранится в базе данных "Первой Формы". Однако вы можете сохранить и локальную копию отчета. Это бывает особенно полезно перед внесением серьезных изменений в отчет, чтобы иметь возможность вернуться к первоначальному варианту. Сохранить локальную копию можно при закрытии отчета, если в отчет были внесены изменения. Отчет сохраняется в файле с расширением FRX.

Сохранение архивной копии отчета

Если позднее вы захотите вернуться к сохраненному варианту, это можно сделать следующим образом:

1. Включите в отчете режим отображения начального экрана. Сохраните отчет (Ctrl+S) и закройте его.

Настройки для вызова начального экрана

2. Снова откройте отчет, на начальном экране выберите пункт "Открыть", затем в открывшемся диалоге выберите сохраненный ранее файл с отчетом и снова нажмите "Открыть".

Выбор архивной копии для восстановления отчета

3. Отчет из сохраненного ранее файла будет загружен в данный отчет, полностью заменив его текущее содержимое. Сохраните внесенные изменения (Ctrl+S). После этого режим отображения начального экрана можно снова отключить.

Полезные заметки

Документация по FastReport от производителя

Видео с уроками по FastReport от производителя

Печатные формы документов