ИНСТРУКЦИЯ*
Power Curve Collection
APEX
*Инструкция не окончательная и содержит неточности, т.к. приложение находится в
стадии разработки и изменения вносятся даже по ходу написания.
Сокращения:
tf
dp
sl
nf
rg
cbg
hdn
btn
P#
req
ronly
AdO
Item “Text Field”
Item “Date Picker”
Item “Select List”
Item “Number Field”
Item “Radio Group”
Item “Checkbox Group”
Item “Hidden”
Button
Номер страницы в названии элементов, например P#_Job_Info
Поле установлено как обязательное (required)
Поле установлено как ReadOnly
AdminOnly
Оглавление
Сокращения: ..................................................................................................................................................... 2
Структура данных ............................................................................................................................................ 3
Схема БД ...................................................................................................................................................... 3
Пакеты .......................................................................................................................................................... 3
Процедуры ................................................................................................................................................... 3
Описание страниц отчетов .............................................................................................................................. 4
Статические отчеты .................................................................................................................................... 4
Динамические отчеты ................................................................................................................................. 4
Правила нумерации и наименования страниц .............................................................................................. 5
Нумерация страниц ..................................................................................................................................... 5
Наименование таблиц ................................................................................................................................. 5
Общие действия для создания отчета ............................................................................................................ 6
Использование фильтров и параметров в запросе. .................................................................................. 8
Наименования столбцов ............................................................................................................................. 8
Регистрация отчета...................................................................................................................................... 8
Панель администратора................................................................................................................................... 9
Добавление новых пользователей и изменение роли. ............................................................................. 9
Создание и удаления задач отправки (Job) ............................................................................................... 9
Структура данных
Схема БД
На текущий момент в схеме задействовано 4 основных таблицы и 2 представления,
созданных на основе служебных таблиц Apex.
Рис. 1 Схема БД
Пакеты
Управление данными в таблицах практически полностью возложено на написанные
пакеты:
1. PCC_Jobs – Пакет для управлениями задачами автоматической отправки писем с отчетами
по расписанию.
2. PCC_Reports – Пакет для управления отчетами, в том числе добавление/удаление
пользователей из подписок, получения назначенного Job и проверка отчета на статичность
данных.
3. PCC_Users – Пакет для управления пользователями. С помощью подпрограмм данного
пакета можно добавлять пользователей, сбрасывать и отправлять на почту пароль от
клиентской части Apex, управлять доступом.
4. Region_Utils – Пакет для получения информации/управления регионами страниц. На данный
момент содержит одну функцию has_data(page_id) для проверки наличия данных в регионеотчете.
Процедуры
Вне пакетов размещены две процедуры для отправки сообщений пользователям:
send_report_to_user(p_page_id, p_userlogin) для отправки отчета с указанной страницы
конкретному пользователю PCC_Apex.
2. send_report_to_mailing_list(p_page_id) для отправки отчета согласно его списку рассылки
(таблица pcc_apex_subscriptions).
1.
Описание страниц отчетов
Пока не удалось обойти ограничение на передачу данных между страницами без
дублирования самих страниц, отчеты делятся на два типа: статические отчеты (т.е.
отчеты без параметров) и динамические (отчеты, в которых используются фильтры).
Статические отчеты состоят из двух регионов: RegionTitle и ReportData. В
динамических добавляется отдельный регион ReportFilters.
Статические отчеты
Регион
RegionInfo
Элемент
[Static Region] ReportTitle
[tf, ronly]
P#_JOB_INFO
[btn, AdO]
SubscribePanel
[btn]
Subscribe
[btn]
Unsubscribe
ReportData
[btn]
SendEmail
[Interactive Report]
Описание
Название отчета подтягивается автоматически
Описание назначенного задания с временем
следующего срабатывания. Если задание не
назначено, будет указано предложение
запросить назначение у администратора
Кнопка для открытия модального окна
настройки задания и рассылки текущего
отчета. Передает в hdn page_id
Кнопка для самостоятельной подписки
пользователем на текущий отчет при условии,
что задача назначена и пользователь не
подписан
Кнопка для самостоятельной отписки от
отчета при условии, что пользователь
подписан (вне зависимости, есть ли сейчас
назначенное задание или нет)
Кнопка для отправки текущего отчета на
почту
Основной регион отчета.
!!! При необходимости, на страницу статического отчета могут быть добавлены
и другие регионы-отчеты для отображения дополнительных данных. Но регион
ReportData строго с таким названием должен быть обязательно, т.к. это главный
идентификатор для работы процедур и задач отправки отчета. С данным регионом
также связан нерешенный баг, о котором будет сказано в «Создании отчета».
Динамические отчеты
Регион
ReportTitle
ReportFilters
Элемент
--[btn] ShowReport
Поля фильтации
ReportData
[Interactive Report]
Описание
Название отчета подтягивается автоматически
Кнопка для фиксации значений полей фильтра
и загрузки отчета.
Добавляются по необходимости
использования в отчете из Items. Для
значений, которые должны быть
обязательными желательно устанавливать
флаг Value_Require. Также, крайне желательно
задавать валидацию значений.
Основной регион отчета. Ограничений на
название региона нет, тем не менее лучше
придерживаться ReportData для основного
отчета если в дальнейшем будет найден
способ отправки отчета по параметрам.
Правила нумерации и наименования страниц
Нумерация страниц
Как и в MicroStrategy, в PCC Apex отчеты разбиты по папкам. Данные о
страницах и папках хранятся в таблице PCC_Apex_Reports. Выгрузка папок на момент
написания (кликабельно, при необходимости можно посмотреть всю выгрузку):
ROOT_ID
ROOT_NAME
FOLDER_ID
FOLDER_NAME
INCLUDED_REPORTS_ID
1
PCC Reports
2
РПЗ
205, 202, 203, 204, 206, 201
1
PCC Reports
3
Legal
301, 302
1
PCC Reports
4
Отчеты ЦБ
401
1
PCC Reports
5
Rep_Все группы
-
Под ID = 1 (столбец parent_node) находится корневая папка PCC_Reports.
Начиная с номера 2 идут вложенные папки. При необходимости, в одну папку можно
вложить другую, указав в качестве child_node parent_node внешней папки.
Нумерация страниц отчетов (page_id и parent_node должны совпадать)
указывается по формуле: { parent_node папки) * 100 + номер отчета в папке }. Таким
образом в папку с parent_node = 2 (РПЗ) попадают отчеты с номерами страниц 200+, в
Legal – 300+ и т.д.
!!! ID страницы не должно превышать значения в 5999, т.к. начиная от 6000
номера начинаются служебные страницы.
Наименование таблиц
Смысл именования страниц, как и отчетов
заключается в удобстве быстрого нахождения их в общем
списке на главной странице разработки. Ни нумерация ни
наименование не влияют напрямую на работу
приложения. Тем не менее, следует избегать хаотичности.
Текущее состояние списка на изображении справа.
Рекомендуется называть страницу в формате
[наименование папки][два символа «_»][название отчета
на английском].
Если название содержит аббревиатуры (например,
РПЗ) или названия сервисов (Avtokod) – переводить на
английский не требуется, пишется транслитом.
Общие действия для создания отчета
Для создания статического отчета необходимо придерживаться последовательности
действий:
1. Открыть страницу 9500 (Template_Report_Static) для создания статического
отчета или 9501 (Template_Report_Dynamic) для создания динамического отчета.
2. В правом верхней части найти значок
и выбрать пункт Page as Copy
1) CopyPage1: Выбрать пункт Page in this application;
2) CopyPage2: Убедиться, что в поле Copy From Page указана страница 9500 или 9501.
По неизвестной причине, Apex может некорректно определить страницу. В таком
случае необходимо выбрать вручную;
3) CopyPage2: Указать номер новой страницы и название в полях New Page Number и
New Page Name, придерживаясь правил наименования и нумерации страниц отчета;
4) CopyPage2: Поля Copy Public Reports и Breadcrumb должны быть отключены (для
второго – это значение do_not_use…);
5) CopyPage3: Navigation Preference = Do not associate…;
6) CopyPage4: Менять значения не требуется;
7) Нажать кнопку Copy.
3. После создания таблицы, в левом меню необходимо выбрать заголовок
страницы, после чего в панели настроек (справа) найти вкладку Identification. В
ней необходимо изменить поле Title на желаемое название страницы. Оно будет
использоваться по умолчанию пока отчет не будет зарегистрирован (об этом в
разделе «Регистрация отчета»).
4. При необходимости в правой панели можно также изменить схему авторизации,
для которой будет доступен отчет, однако делать это имеет смысл только для
тех страниц, доступ к которым должны иметь только администраторы. Правила
доступа по умолчанию задаются по ролям при регистрации отчета. Другой
случай, когда необходимо задавать схему авторизации – страницы, добавленные
в Navigation Menu, блок, откуда есть возможность попасть на вкладку
администратора.
5. В связи с багом копирования (по всей видимости, Apex оставляет скрытые связи
между регионами, которые невозможно выявить через служебные таблицы
Apex’a) необходимо удалить поле ReportData, а затем заново добавить регион
Interactive Report и назвать его ReportData!
6. Во вкладке Source необходимо выбрать Type = SQL Query, затем в поле SQL
Query вставить запрос. Для статических отчетов нельзя использовать внешние
фильтры, в том числе встроенные (например, :APP_PAGE_ID или :APP_USER).
О встроенных параметрах здесь.
7. В случае, если создавался статический отчет, то дальнейших действий не
требуется. В случае динамического отчета – см. ниже.
Создание динамического отчета и добавление фильтров.
Создание отчета с фильтрами на примере отчета P202_RPZ__Avtokod
На данной странице присутствует 3 поля типа Number Field, определяющих
параметры просрочки. Для удобства был добавлен отдельный регион. Также, добавлен
регион с фильтрами, характерными конкретному отчету: Radio Group и Select List. У
всех фильтров задано значение req, за исключением региона. В случае, если фильтр
является необязательным, обход NULL должен быть обработан в запросе (все
применяемые фильтры в отличие от MicroStrategy возвращают NULL, если значение
не указано вместо пустоты). Подробнее о способах создания фильтров с
параметрами можно ознакомиться в документации Oracle Apex или сделать по
примеру уже созданных отчетов.
Использование фильтров и параметров в запросе.
В Oracle Apex параметры можно использовать в синтаксисе :[НАЗВАНИЕ
ПАРАМЕТРА]. Например, часто ИСПОЛЬЗУЕМЫЕ ВСТРОЕННЫЕ ПАРАМЕТРЫ:
1. :APP_ID – ID приложения, PCC_Apex_Reports = 101;
2. :APP_PAGE_ID – ID текущей страницы для унификации использования
процедур и функций, пакетов;
3. :APP_PAGE_TITLE – Название (title) текущей страницы
4. :APP_USER – получение логина пользователя, под которым выполнен вход.
Аналогичным образом используются в запросах и кастомные параметры из
форм. На примере вышеуказанного отчета блок WHERE:
WHERE ex_case_is_open = :P202_EX_CASE_IS_OPEN
AND debt_age BETWEEN :P202_MIN_DEBT_AGE AND :P202_MAX_DEBT_AGE
AND base_balance >= :P202_MIN_OUTST
AND NVL(:P202_REGION_SELECTOR, region_rus) = region_rus
*пример обработки NULL из фильтра
Наименования столбцов
По умолчанию названия столбцов в отчете будет соответствовать полям,
выбираемых запросом. Существует два способа переименовать столбец.
1. Использовать в запросы Alias столбца, например, reference AS client_id или reference AS “ID
клиента”
2. Другой способ более корректный, но требует больше усилий. После применения запроса в
левой панели необходимо нажать на [название региона-отчета] columns[название
столбца], затем в правой панели заполнить Heading во вкладке Heading.
Регистрация отчета
После создания отчета необходимо перейти в клиентскую часть приложения под
учетной записью администратора по ссылке. На панели Additional Control Panel
расположена кнопка Register Report . В выпадающем списке необходимо выбрать
отчет для регистрации. Если список пуст – все отчеты зарегистрированы в
приложении. После выбора отчета необходимо выбрать папку, в которую отчет будет
помещен, а также указать публичное имя отчета. Указывать описание отчета не
обязательно, на данный момент это поле не применяется и служит лишь для
отображения в таблице. Заполнив, необходимо нажать Enter, затем в окне Next .
Во второй вкладке необходимо выбрать роли, которым будет открыт доступ к
регистрируемому отчету. Выбор нескольких ролей осуществляется с зажатой
клавишей Ctrl. Finish . С этого момента отчет открыт для публичного доступа из
дерева отчетов.
Панель администратора
Добавление новых пользователей и изменение роли.
С помощью панели администратора можно добавить новых пользователей. Для
этого, на панели необходимо нажать кнопку Add new user . В появившемся окне из
выпадающего списка выбирается группа, к которой сейчас принадлежит пользователь
согласно таблицы tallyman_online.users, затем самого пользователя, нажать кнопку
Next . На следующей вкладке необходимо выбрать роль из списка ролей PCC_Apex,
которая будет закреплена за пользователем, а также, при необходимости, отметить
пункт «Отправить пароль пользователю». Изменить роль возможно по нажатию на
кнопку Change user role .
!!! Для предоставления пользователю максимальных прав просмотра необходимо
выбирать UltimateUser. Назначение прав администратора специально сделано
возможным только вручную через процедуру.
Создание и удаления задач отправки (Job)
На панели администратора находится вкладка Job Reporting, на которой можно
отслуживать все существующие в проекте задачи. Здесь же есть возможность создать
новую задачу.
Для этого необходимо в поле Job Name ввести название новой задачи. Название
желательно должно отражать частоту и интервал отправки, например Daily_H9, т.е.
ежедневно в 09:00. Затем выбрать нужные пункты в Job Period Type (либо по периоду
(день, неделя, месяц) либо по интервалу (минуты, часы)). Выбор значения откроет
выбор соответствующих опций и поля для ввода значений. После заполнения всех
данных нажать Create Job . В соседнем окне можно удалить задачу.
Отслеживание ошибок
Apex позволяет отслеживать ошибки, возникающие в приложении. Для этого на
панели администратора необходимо открыть вкладку Application Error Log. В случае
(как и с любым отчетом), если отсутствует нужный столбец, при этом известно, что он
есть – необходимо нажать на вкладки Actions Columns выбрать нужный столбец.