Разработка собственных отчетов для BILLmanager

Материал из ISPWiki
Версия от 10:45, 28 июня 2016; Igor (обсуждение | вклад) (Добавление диаграмм и графиков)
Перейти к: навигация, поиск

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

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


Простейший отчет

Разработка простейшего отчета состоит из следующих пунктов

  • Подключение отчета в основное меню или в список отчетов
  • Описание формы для ввода параметров (если требуется)
  • Описание внешнего вида отчета
  • Построение SQL запроса для получения данных

Описание отчета, как и любого другого плагина делается с помощью xml файла /usr/local/mgr5/etc/xml/<mgr>_mod_<name>.xml, где <mgr> имя продукта, а <name> имя плагина. Допустим мы пишем плагин для BILLmanager и называем его myreport, тогда файл должен иметь имя

 /usr/local/mgr5/etc/xml/billmgr_mod_myreport.xml

Создадим очень простое XML- описание

<?xml version="1.0" encoding="UTF-8"?>
<mgrdata>
        <mainmenu level="29">
                <node name="stat">
                        <node name="myreport"/>
                </node>
        </mainmenu>
 
        <metadata name="myreport" type="report">
                <band name="company">
                        <query>select id, name from profile where account=1</query>
                        <col name="name" type="data"/>
                </band>
        </metadata>
 
        <lang name="ru">
                <messages name="desktop">
                        <msg name="menu_myreport">Мой первый отчет</msg>
                </messages>
                <messages name="myreport">
                        <msg name="title">Заголовок моего первого отчета</msg>
                </messages>
        </lang>
</mgrdata>

В данном примере мы добавили ссылку на отчет в основное меню, в раздел "Статистика". В самом отчете мы вывели список компаний провайдера.

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

Rep1.png

Вложенные данные

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

<metadata name="myreport" type="report">
        <band name="company">
                <query>select id, name from profile where account=1</query>
                <col name="name" type="data"/>
                <band name="paymethod">
                        <query>select p.name_ru as paymethod from paymethod2company pc left join paymethod p on pc.paymethod=p.id where pc.company=[[company.id]]</query>
                        <col name="paymethod" type="data"/>
                </band>
        </band>
</metadata>

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

Rep2.png

Ввод параметров для построения отчета

Далее давайте рассмотрим пример использования форм. Допустим нам необходимо вывести только методы оплаты оплаты минимальная сумма платежу у которых более определенного значения, для этого добавим форму и параметр в SQL-запрос. Кроме всего прочего, для того чтоб отчет не выполнялся автоматически с неопределенными параметрами, мы предотвратим его построение до заполнения формы, добавив атрибут firstrun="no".

<metadata name="myreport" type="report" firstrun="no">
        <form>
                <field name="minamount">
                        <input type="text" name="minamount" save="yes" required="yes" check="int"/>
                </field>
        </form>
        <band name="company">
                <query>select id, name from profile where account=1</query>
                <col name="name" type="data"/>
                <band name="paymethod">
                        <query>select p.name_ru as paymethod, minamount from paymethod2company pc left join paymethod p on pc.paymethod=p.id where pc.company=[[company.id]] and p.minamount>=[[minamount]]</query>
                        <col name="paymethod" type="data"/>
                        <col name="minamount" type="data" sort="digit"/>
                </band>
        </band>
 </metadata>

Переход из отчетов в другие модули

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

<metadata name="myreport" type="report" firstrun="no">
                <form>
                        <field name="repminamount">
                                <input type="text" name="repminamount" save="yes" required="yes" check="int"/>
                        </field>
                </form>
                <band name="company">
                        <query>select id, name from profile where account=1</query>
                        <col name="name" type="data"/>
                        <band name="paymethod">
                                <query>select p.id, p.name_ru as paymethod, minamount from paymethod2company pc left join paymethod p on pc.paymethod=p.id where pc.company=[[company.id]] and p.minamount>=[[repminamount]]</query>
                                <col name="id" type="data" nestedreport="paymethod.edit"/>
                                <col name="paymethod" type="data"/>
                                <col name="minamount" type="data" sort="digit"/>
                        </band>
                </band>
</metadata>

Я добавил колонку id метода оплаты с атрибутом nestedreport="paymethod.edit", который говорит о том, что нужно сделать ссылку, при нажатии на которую открывать новую вкладку с функцией paymethod.edit которой в качестве ключа будет передано значение колонки. Кроме того в вызываемую функцию будут переданы все поля формы, и поскольку функция paymethod.edit имеет свой параметр minamount, для того чтоб предотвратить его подмену параметром из нашей формы, я переименовал параметр на форме в repminamount.

Переход в другой, связанный отчет

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

для этого я изменю в имеющемся отчете описание колонки со ссылкой

<col name="id" type="data" nestedreport="myreport.detail"/>

и добавлю описание нового отчета

<metadata name="myreport.detail" type="report">
                <band name="payments">
                        <query>select status, sum(paymethodamount) as amount, count(*) as cnt from payment where paymethod=[[elid]] group by status</query>
                        <col name="status" type="msg"/>
                        <col name="amount" type="data" convert="money" sort="digit" total="sum"/>
                        <col name="cnt" type="data" sort="digit" total="sum"/>
                </band>
</metadata>

Так же добавим секцию сообщений для нового отчета

<messages name="myreport.detail">
                        <msg name="title">Статистика метода оплаты</msg>
                        <msg name="status_1">Новый</msg>
                        <msg name="status_4">Зачислен</msg>
                        <msg name="status">Состояние</msg>
                        <msg name="cnt">Количество</msg>
</messages>

Обратите внимание, как я превратил коды статусов в их название.

Добавление диаграмм и графиков

Теперь сделаем наш отчет красивее, добавив в него диаграмму. для этого в band необходимо добавить всего одну строчку

    <diagram name="statuspie" label="status" data="amount" type="pie"/>

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

Rep3.png

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

<?xml version="1.0" encoding="UTF-8"?>
<mgrdata>
        <mainmenu level="29">
                <node name="stat">
                        <node name="myreport"/>
                </node>
        </mainmenu>
 
        <metadata name="myreport" type="report" firstrun="no">
                <form>
                        <field name="repminamount">
                                <input type="text" name="repminamount" save="yes" required="yes" check="int"/>
                        </field>
                </form>
                <band name="company">
                        <query>select id, name from profile where account=1</query>
                        <col name="name" type="data"/>
                        <band name="paymethod">
                                <query>select p.id, p.name_ru as paymethod, minamount from paymethod2company pc left join paymethod p on pc.paymethod=p.id where pc.company=[[company.id]] and p.minamount>=[[repminamount]]</query>
                                <col name="id" type="data" nestedreport="myreport.detail"/>
                                <col name="paymethod" type="data"/>
                                <col name="minamount" type="data" sort="digit"/>
                        </band>
                </band>
        </metadata>
        <metadata name="myreport.detail" type="report">
                <band name="payments">
                        <diagram name="statuspie" label="status" data="amount" type="pie"/>
                        <query>select status, sum(paymethodamount) as amount, count(*) as cnt from payment where paymethod=[[elid]] group by status</query>
                        <col name="status" type="msg"/>
                        <col name="amount" type="data" convert="money" sort="digit" total="sum"/>
                        <col name="cnt" type="data" sort="digit" total="sum"/>
                </band>
        </metadata>
 
        <lang name="ru">
                <messages name="desktop">
                        <msg name="menu_myreport">Мой первый отчет</msg>
                </messages>
                <messages name="myreport">
                        <msg name="title">Заголовок моего первого отчета</msg>
                        <msg name="paymethod">Метод оплаты</msg>
                        <msg name="repminamount">Минимаьный платеж</msg>
                        <msg name="hint_repminamount">Показывать только те способы оплаты где минимаьный платеж больше указанного значения</msg>
                </messages>
                <messages name="myreport.detail">
                        <msg name="title">Статистика метода оплаты</msg>
                        <msg name="status_1">Новый</msg>
                        <msg name="status_4">Зачислен</msg>
                        <msg name="status">Состояние</msg>
                        <msg name="cnt">Количество</msg>
                </messages>
        </lang>
</mgrdata>

За более широкой, дополнительной информацией обращайтесь [Описание отчетов|к соответсвующий документации]

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

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