Report


Opis modułu

Moduł zawiera zestaw funkcji wspomagających tworzenie raportów.

Moduł raportowy wspomaga tworzenie dużych raportów poprzez możliwość gromadzenia generowanych danych w pliku tymczasowym na dysku maszyny, na której uruchomiona jest instancja jPalio generująca raport. Generowane raporty mogą mieć dowolny typ, zarówno tekstowy jak i binarny: txt, csv, html, xls itd. Raporty mogą być generowane z opóźnieniem w stosunku do momentu zlecenia (np. w czasie mniejszego obciążenia serwera). Moduł jest przystosowany do współpracy z bazą danych Oracle.

Raport jest wykonywanym na żądanie obiektem jPalio generującym dowolną treść. Generowana treść jest sukcesywnie dołączana do bufora za pomocą funkcji append. Po wykonaniu obiektu bufor przechowujący treść raportu jest zapisywany do obiektu typu BLOB w tabeli r_orders i ew. od razu kompresowany. Treść skompresowana jest zapisywana do osobnego pola BLOB niż treść nieskompresowana. Wewnątrz obiektu generującego może być zapisany dowolny algorytm: zapytanie sql, kilka zapytań, kombinacja zapytań i przetwarzania w jpalio (świetnie się sprawdza przy robieniu raportów zliczeniowych) itd.

Do modułu dołączony jest gotowy interfejs html tworzony poprzez wywołanie funkcji $report.createOrReplaceHtmlInterface(). Służy on do administracji typami raportów oraz zlecania nowych i pobierania treści gotowych raportów. Więcej informacji na ten temat zawiera rozdział Interfejs html.

Każde zlecenie na raport w r_orders posiada pole stanu (z wartością ze słownika w tabeli r_states) i dodatkowe flagi określające status zlecenia. System zarządzający raportami (interfejs html modułu) na podstawie tych flag wyświetla listę dostępnych raportów i umożliwia użytkownikom pobranie wygenerowanych raportów - w celu generacji linków w innych miejscach aplikacji można użyć funkcji reportURL i compressedReportURL.

Wszystkie funkcje operujące na raportach (wykonujące, kompresujące i obcinające) są zabezpieczone przed jednoczesnym operowaniem na tym samym raporcie, można więc uruchomić jednocześnie kilka zadań wykonujących raporty (w ramach tej samej instancji jPalio) bez obawy wykonania tego samego zlecenia kilkukrotnie.

Położenie tabel modułu raportowego jest określone za pomocą konektora o nazwie zdefiniowanej w parametrze connector_name deklaracji modułu w pliku konfiguracyjnym instancji. Jeśli żaden konektor nie jest określony, moduł odwołuje się do tabel przez standardowy konektor data.

Dzięki możliwości umieszczenia danych raportów w miejscu określonych konektorem oraz dzięki możliwości przypisania typów raportów do określonych kategorii typów (tabela r_categories), można stworzyć system raportowy dla wielu usług (instancji jpalio), umieszczony na jednej maszynie, na której każda usługa zapisywałaby własne raporty (własne w sensie przynależności do kategorii przypisanej usłudze), udostępniane nastepnie w jednolity sposób użytkownikom. Wykonanie raportów z różnych instancji może być bezkonfliktowe dzięki wykorzystaniu funkcji executeFirstReport wykonującej pierwszy w kolejce raport należący danej kategorii.

Sposób użycia modułu

Sposób użycia:

  1. Dla jPALIO w wersji niższej niż 7.4 należy utworzyć tabele dla raportów w wybranym schemacie bazy danych za pomocą skryptów zawartych w dalszej części opisu. Dla jPALIO 7.4 i nowszych tabele zostaną utworzone automatycznie.

    Po utworzeniu tabel należy wykonać następujący zestaw insertów:

    insert into r_order_states ( id, name ) values ('O', 'Zamówiony'); 
insert into r_order_states ( id, name ) values ('C', 'Anulowany'); 
insert into r_order_states ( id, name ) values ('G', 'W trakcie generacji'); 
insert into r_order_states ( id, name ) values ('R', 'Wykonany'); 
insert into r_order_states ( id, name ) values ('L', 'Zablokowany'); 

---------------------------------------------------------------------------------------------------------------

insert into r_type_categories ( id, name ) values ('default', 'Grupa domyślna'); 

---------------------------------------------------------------------------------------------------------------

insert into r_types ( id, active, default_file_name_timestamp, 
  can_immediate_execute, defult_generation_priority, param_form_init_object,
  param_form_display_object, param_form_check_object, param_form_save_object,
  generation_object, category_id, name,
  default_file_name, default_mime_type, description, 
  default_compressed, default_generation_method ) 
values ( 
  1, 'T', 'F',
  'T', 0, 91030,
  91031, 91032, 91033,
  91034, 'default', 'Raport testowy obiektów referencyjnych',
  'test_rep', 'text/html', NULL,
  'F', 'MEMORY');

  2. W konfiguracji instancji należy dodać wpis deklarujący moduł a w nim wskazać nazwę konektora do schematu zawierającego utworzone tabele (przykład poniżej zakłada, że tabele raportowe są w tym samym schemacie co tabele jPalio). Jeżeli tabele modułu report są w bazie, na którą wskazuje konektor data, ten punkt można pominąć.

      <module name="report">
    <connector_name>palio</connector_name>
  </module>

  3. W dowolnym obiekcie wykonać funkcję $report.createOrReplaceHtmlInterface(), co spowoduje utworzenie interfejsu do zarządzania, zlecania i pobierania raportów (zostanie utworzony zestaw obiektów i stron jPalio).

  4. W portalu dodać linki do zarządzania raportami. Przykładowy zestaw linków poniżej i w obiekcie report_module.examples.links (91036) interfejsu do zarządzania.

    <a class="mainpage_menu_link" href="#" onclick="window.open('$url(report_module.types,null, $util.urlEncode("&interfaceMode=admin&reportModuleStyleSheet=&allowedCategories=&allowedTypes=&mainTitle=raporty dla portalu
xyz"))')">Zarządzanie typami raportów</a><br>
<a class="mainpage_menu_link" href="#" onclick="window.open('$url(report_module.orders,null, $util.urlEncode("&interfaceMode=order&reportModuleStyleSheet=&allowedCategories=&allowedTypes=&mainTitle=raporty dla portalu
xyz"))')">Zlecanie raportów</a><br>
<a class="mainpage_menu_link" href="#" onclick="window.open('$url(report_module.by_types,null, $util.urlEncode("&interfaceMode=get&reportModuleStyleSheet=&allowedCategories=&allowedTypes=&mainTitle=raporty dla portalu
xyz"))')">Pobieranie raportów</a><br>

    W linku można przekazać dodatkowe parametry:

    • interfaceMode - parametr obowiązkowy, oznaczający tryb interfejsu: "admin" - zarządzanie kategoriami i typami, zlecanie i pobieranie raportów, "order" - zlecanie i pobieranie raportów, "get" - pobieranie raportów
    • reportModuleStyleSheet - id lub kod obiektu, który zastąpi standardowy arkusz styli CSS interfejsu
    • allowedCategories - lista id kategorii, rozdzielonych przecinkami, które będą widoczne w sekcjach do zlecania i pobierania raportów, np: " 'default','katA','katB' "
    • allowedTypes - lista id typów, rozdzielonych przecinkami, które będą widoczne w sekcjach do zlecania i pobierania raportów, np: "1,2,7"
    • mainTitle - tytuł wyświetlany na górze każdej strony interfejsu

  5. Napisać obiekty generujące raport(y) oraz umożliwiające jego zlecanie, wzorując się na obiektach z katalogu "02 Obiekty referencyjne" interfejsu do zarządzania. Jeśli parametrem raportu jest jedynie zakres czasowy, można ograniczyć się do użycia przykładowych obiektów i napisać tylko obiekt generujący raport.

    Po utworzeniu odpowiednich obiektów należy dodać nowy typ raportu przypisując do niego te obiekty. Aby utworzone obiekty były widoczne w interfejsie do zarządzania raportami ich nazwy muszą zaczynać się ciągiem "Rep obj ".

    Obiekty inicjalizacji i sprawdzania nie są wymagane, interfejs zakłada wtedy, że dane w formularzu zamówienia są poprawne i zawsze po submicie formularza zlecenia wywołuje obiekt zapisu zlecenia.

  6. Utworzyć zadanie (lub kilka), które będzie wykonywało zlecone raporty. Przykładowy obiekt zadania realizujący taką funkcjonalność jest zawarty w report_module.examples.scheduler_execution (91035).
    Osoby z uprawnieniami "order" mogą wykonać ręcznie te raporty, dla których przy określaniu typu zaznaczono flagę wykonania ręcznego. Uprawnienia "admin" pozwalają wykonać dowolny raport. Ręczne wykonanie raportów jest możliwe na stronie "raporty oczekujące".

Interfejs html

Do modułu dołączony jest interfejs html. Interfejs można utworzyć poprzez wywołanie funkcji $report.createOrReplaceHtmlInterface() - zostanie utworzony zestaw obiektów i stron jPalio. Za jego pomocą można zlecić raport, który zostanie wykonany w tle przez zadanie o godzinie określonej we właściwościach raportu. Zadanie trzeba napisać samodzielnie na podstawie przykładu zawartego w interfejsie.

Dodanie raportu polega na dodaniu kilku obiektów wspópracujących z interfejsem html, których szablony są zawarte w interfejsie w katalogu "02 Obiekty referencyjne". Jeden z tych obiektów służy do generowania właściwego raportu.

Obiekt generujący raport jest przypisany do typu raportu określonego w tabeli r_types. Obiekt taki powinien być sparametryzowany. W tabeli r_types istnieją pola param_form_init_object, param_form_display_object, param_form_check_object, param_form_save_object w których system przyjmowania zleceń na raporty przechowuje id obiektów inicjalizujących, wyświetlających, sprawdzających i zapisujących formularz, pozwalający określić parametry raportu. Obiekt zapisujący powinien wywołać funkcję addReport i przekazać do niej tabelę nazw parametrów, zapamiętywanych jako parametry raportu. Parametry te są zapisywane przez addReport w nowym zleceniu na raport danego typu w tabeli r_orders. Przed wykonaniem obiektu raportu parametry są odtwarzane przez funkcję executeReport w kontekście, w którym raport jest wykonywany (ustawiane jako zwykłe parametry jPaliowe). Tabela r_types zawiera także parametry zaczynające się prefiksem default_ określające domyślne warunki wykonywania raportu danego typu. Warunki te są przepisywane do tabeli r_orders wraz z tworzeniem nowego zlecenia na raport. Funkcja wykonująca raport bierze pod uwagę warunki wykonania z r_orders. Nie jest zalecane modyfikowanie warunków wykonania w tabeli r_orders poza interfejsem html. Czas wykonania może być inny niż czas dodania zlecenia na raport, np. można umożliwić ciągłe przyjmowanie zleceń na raporty, ale wykonywać je lub kompresować za pomocą zadania w czasie mniejszego obciążenia.

Po utworzeniu odpowiednich obiektów dla raportu należy w interfejsie html dodać nowy typ raportu, przypisując do niego te obiekty. Aby utworzone obiekty były widoczne w interfejsie do zarządzania raportami ich nazwy muszą zaczynać się ciągiem "Rep obj ". Po poprawnym skonfigurowaniu typu raportu można dodawać zlecenia wykonania raportów tego typu.

Obiekty inicjalizacji i sprawdzania nie są wymagane, interfejs zakłada wtedy, że dane w formularzu zamówienia są poprawne i zawsze po submicie formularza zlecenia wywołuje obiekt zapisu zlecenia.

Przepływ sterowania pomiędzy obiektami służącymi do zlecania raportów prezentuje poniższy diagram.

Baza danych

Moduł wykorzystuje tabele o następującej strukturze:

Skrypt tworzący tabele dla Oracle można pobrać tutaj. Schemat tabel dla Spirali v0.9.1 można pobrać tutaj.

Znaczenie pól tabel:

Tabela r_type_categories (kategorie typów raportów):

Tabela r_types (typy raportów):

Tabela r_order_states (słownik stanów zleceń na raport):

Tabela r_orders: