[http://support.edokumenty.eu/trac/wiki/NewBusinessAdmin Podręcznik użytkownika] > [http://support.edokumenty.eu/trac/wiki/NewBusinessAdmin/Reports Raporty] > Filtrowanie raportów

= Filtrowanie raportów =

Moduł raportów w systemie eDokumenty umożliwia filtrowanie danego raportu poprzez określenie parametrów na dwa sposoby:
* standardowe parametry
* utworzenie filtrów przez użytkownika

== Standardowe parametry ==

Standardowe parametry to specjalne tokeny, dzięki którym możemy obsłużyć przekazywane dane z listy, kartoteki lub poprzez formularz parametrów do raportu. [[BR]]

Należy zwrócić uwagę na miejsce, z którego jest wywoływany raport, gdyż ma to wpływ na definicję operatora SQL przed takim tokenem.
Warunki stosowania operatorów:
|| Operator || Kiedy stosować || Przykład parametru ||
|| IN || dla listy, gdyż możemy otrzymać kilka zaznaczonych elementów. [[BR]] Token zostanie zamieniony na identyfikatory z danej listy np.: 1,2,3,4 || '''Miejsce:''' Lista klientów [[BR]] '''Parametr:''' contid IN ({CONTID}) ||
|| znak = || dla kartoteki przekazywana jest tylko jedna wartość do parametru || '''Miejsce:''' Kartoteka klienta [[BR]] '''Parametr:''' contid = {CONTID} ||

W przypadku, jeśli w definicji raportu użyjemy np.: {CONTID} a raport zostanie wywołany z modułu (przekazane zostaną zaznaczone elementy), token zostanie zamieniony na pierwszy z zaznaczonych elementów. [[BR]]

W przypadku niewłaściwego podpięcia raportu lub niewłaściwego użycia operatora raport wygeneruje błąd.

== Obsługiwane tokeny ==

Obecnie obsługiwane tokeny to:
|| Nazwa || Opis || Wartość domyślna || Określanie na formularzu ||
|| {DATE_FROM} || Data od  || Początek bieżącego miesiąca || TAK ||
|| {DATE_TO} || Data do  || Koniec bieżącego miesiąca || TAK ||
|| {USR_ID} || Pracownik || Pracownik z listy || TAK ||
|| {LOGGED_USR_ID} || Zalogowany pracownik || Id zalogowanego pracownika (users.usr_id)  || NIE ||
|| {ENT_ID} || Identyfikator podmiotu || Identyfikator podmiotu  || NIE ||
|| {FILTER_STRING} || Ciąg filtrujący  || 'TRUE' || TAK - definicja filtrów to określa ||
|| {ACORID} || Jednostka rozliczeniowa || 0 || TAK ||
|| {TOVCID} || Miejsce powstawania kosztów || 0 || TAK ||
|| {ADANID} || Dodatkowa analityka || 0 || TAK ||
|| {CONTID} || Klient || Pierwszy nie usunięty klient z listy (sortowany po contid) || TAK ||
|| {CONTIDS} || Klient || Pierwszy nie usunięty klient z listy (sortowany po contid) || TAK ||
|| {DOC_ID} || Dokument (z listy lub kartoteka) || 0 || NIE ||
|| {DOC_IDS} || Dokument (z listy lub kartoteka) || 0 || NIE ||
|| {DOCIDS} || Dokument (z listy lub kartoteka)  || 0 || NIE ||
|| {PRC_ID} || Sprawa || 0 || TAK ||
|| {PRC_IDS} || Sprawa || 0 || TAK ||
|| {PRCIDS} || Sprawa || 0 || TAK ||
|| {EVNTID} || Zdarzenie (z listy lub kartoteka) || 0 || NIE ||
|| {EVNTIDS} || Zdarzenie (z listy lub kartoteka) || 0 || NIE ||
|| {CAMPID} || Kampania (z listy lub kartoteka) || 0 || TAK ||
|| {CAMPIDS} || Kampania (z listy lub kartoteka) || 0 || TAK ||
|| {DEVCID} || Urządzenie (z listy lub kartoteka) || 0 || TAK ||
|| {DEVCIDS} || Urządzenie (z listy lub kartoteka) || 0 || TAK ||
|| {DEPOID} || Produkt (z listy lub kartoteka) || 0 || TAK ||
|| {DEPOIDS} || Produkt (z listy lub kartoteka) || 0 || TAK ||
|| {RES_ID} || Zasób (z listy lub kartoteka) || 0 || TAK ||

== Definiowanie filtrów == #definiowanie_filtrow

System eDokumenty umożliwia definiowanie własnych parametrów do raportów określanych jako '''Filtry'''. [[BR]]

Przykładowa definicja raportu (kod SQL):

{{{
SELECT
    contid,
    name_1,
    adddat,
    macrtk,
    is_del   
FROM
    contacts   
WHERE
    ent_id = {ENT_ID}       
    AND {FILTER_STRING}
}}}

== Ważne uwagi == #wazne_uwagi

Aby filtrowanie było możliwe, wymagane jest dodanie specjalnego tokenu '''{FILTER_STRING}''', który w momencie akceptacji filtrów zostanie zamieniony na warunki SQL zgodne z definicją filtrów. Jeśli w definicji raportu zabraknie tego tokenu, to pomimo definicji filtrów nie będą one dostępne na panelu parametrów. [[BR]]

Istotną kwestią jest również miejsce, w którym jest dodany token {FILTER_STRING} oraz operator, jaki go poprzedza (AND/OR - zalecany AND).

__'''Przykład'''__

{{{
SELECT * 
FROM
    (SELECT
        contid,
        name_1,
        adddat,
        macrtk,
        is_del   
    FROM
        contacts   
    WHERE
        ent_id = {ENT_ID} LIMIT 100) AS foo      
    AND {FILTER_STRING}
}}}

Ważne jest, aby przy takiej definicji raportu filtry wskazywały na kolumny umieszczone w głównym zapytaniu.

== Definicja nowego filtra == #definicja_nowego_filtra

Filtrami możemy zarządzać w zakładce '''Filtry''' w kartotece raportu.

[[BR]][[Image(wiki:NewBusinessAdmin/Attachments:raport_filtry.png, 500)]][[BR]]
''Zakładka '''Filtry'''''[[BR]]

Przyciski na widocznym rysunku umożliwiają standardowe zarządzanie filtrami:
|| Nazwa przycisku || Opis ||
|| Nowy || definicja nowego filtra/grupy ||
|| Edycja || edycja istniejącego filtra/grupy możliwa również poprzez dwukrotne kliknięcie elementu drzewka ||
|| Usuń || sunięcie filtra lub grupy (usuwane są też wszystkie podrzędne) ||
|| Odśwież listę || odświeża listę filtrów ||

Nowy filtr lub grupę filtrów definiujemy w formularzu '''Typ raportu'''.

[[BR]][[Image(wiki:NewBusinessAdmin/Attachments:raport_filtry_nowy_filtr.png, 400)]][[BR]]

Wypełniane pola:
* '''Nazwa''' - nazwa filtra lub grupy filtrów, w zależności od wartości polu '''Rodzaj'''
* '''Opis''' - dodatkowa informacja wyświetlania po najechaniu na nazwę filtra w panelu filtrów raportu (dostępny na wygenerowanym raporcie)
* '''Nadrzędny''' - w przypadku, jeśli dany filtr lub grupa ma należeć do grupy, wybieramy ją z listy
* '''Rodzaj'''. Wartość '''Grupa''' grupuje kilka filtrów lub innych grup, wartość '''Filtr''' oznacza konkretny filtr - filtry mogą być definiowane bez elementu nadrzędnego lub mogą należeć do grupy. Filtr nie może należeć do innego filtra.
* '''Typ opcji''' - rodzaj wygenerowanego pola w panelu filtrów w wygenerowanym raporcie. Szczegóły poniżej.
* '''Filtr''' - wyrażenie filtrujące. W zależności od typu opcji może wymagać podania tokena {value} - szczegóły poniżej.
* '''Wartości dla listy''' - tylko dla typu:  '''Lista jednokrotnego wyboru''', '''Lista wielokrotnego wyboru''', '''Pola radiowe - kwerenda SQL''', gdzie pierwsza wartość to klucz, który '''musi być typu INTEGER''', natomiast druga to opis wartości. Można stosować następujące tokeny: '''{LOGGED_USER}''' - identyfikator zalogowanego pracownika (users.usr_id), '''{LOGGED_ORUNID}''' - identyfikator jednostki zalogowanego pracownika (organization_units.orunid), '''{ENT_ID}''' - identyfikator podmiotu (podmioty.id_pod), '''{CURRENT_DATE}''' - bieżąca data w formacie YYYY-MM-DD, '''{CURRENT_TIME}''' - bieżący czas w formacie HH:MM

== Typ opcji == #typ_opcji
Aktualna lista typów opcji oraz przykład definicji:

|| Typ opcji || Opis || Przykład filtru || Wymaga tokenu {value} ||
|| Wartość BOOLEAN || Zastosowanie dla kolumn typu boolean gdzie wartość to TRUE lub FALSE || is_del IS {value} || Tak ||
|| Wartość TEXT || Dowolne pole tekstowe do którego chcemy zastosować wyszukiwanie || name_1 ~* E'{value}' || Tak ||
|| Pole zaznaczane || Jedna opcja zaznaczenia filtruje tylko wtedy gdy jest zaznaczony. Jeśli podamy w filtrze token {value} zostanie zamieniony na TRUE || is_del IS TRUE to samo da nam is_del IS {value} ale is_del IS FALSE nie jest tym samym co is_del IS {value} - {value} jest zawsze zamieniane na TRUE || Nie ale może być patrz przykład ||
|| Lista jednokrotnego wyboru || Pole typu Select gdzie można wybrać tylko jedną wartość. Wymagane jest zadeklarowanie SQL dla listy opcji || adduid = {value} || Tak ||
|| Lista wielokrotnego wyboru || Lista z opcjami do wyboru || adduid || Nie tylko należy zadeklarować kolumnę której filtr dotyczy ||
|| Pola radiowe || Lista z opcjami do wyboru || adduid || Nie tylko należy zadeklarować kolumnę której filtr dotyczy ||
|| Pole daty z godziną || Wizualizacja tego filtru posiada dodatkowe pole do określania godziny jeśli jest wymagana taka do dokładność || adddat >= '{value}' lub można adddat >= '2012-01-01 12:00' || Raczej tak niepodanie tokenu {value} jest niecelowe ||
|| Pole daty bez godziny || Brak pola godzina || adddat >= '{value}' lub można adddat >= '2012-01-01' || Raczej tak niepodanie tokenu {value} jest niecelowe ||
|| Wybór miesiąca oraz roku || Umożliwia wybranie roku oraz miesiąca. Zwracana wartość to rok plus miesiąc oraz 1 dzień czyli np. 2012-02-01. Umożliwia to budowanie zakresów miesięcy jeśli zdefiniujemy drugi filtr tego typu w grupie || adddat >= '{value}' || Tak ||
|| Kontakt z książki adresowej || Zwraca identyfikator (contacts.contid) klienta || contid = {value} || Tak ||
|| Lista spraw || Zwraca identyfikator sprawy (processes.prc_id) || prc_id = {value} || Tak ||
|| Osoba kontaktowa || Zwraca identyfikator osoby kontaktowej (contact_persons.copeid) || copeid = {value} || Tak ||
|| Urządzenie || Zwraca identyfikator urządzenia (devices.devcid) || devcid = {value} || Tak ||
|| Projekt || Zwraca identyfikator projektu (projects.projid) || projid = {value} || Tak ||
|| Lista pracowników || Zwraca identyfikator wybranych pracowników (users.usr_id). '''WAŻNE - wymagane jest aby był operator IN w wyrażeniu filtrującym gdyż wartości są zwracane w postaci 1,2,3,4''' || adduid IN ({value}) || Tak ||
|| Drzewko || Zwraca identyfikator wybranego elementu drzewka. Napełniane kwerendą podaną poniżej w przykładach || category = {value} || Tak ||

__'''Przykład'''__ [[BR]]
Chcę filtrować listę klientów według parametru '''Opiekun'''. Wtedy:
* wybieram '''Typ opcji''': '''Lista pracowników'''
* definiuję '''Filtr''': '''macrtk IN ({value})''' - pole macrtk przechowuje id opiekuna (users.usr_id)

Po zapisaniu filtr zostaje dodany do listy w zakładce '''Filtry''', a po [http://support.edokumenty.eu/trac/wiki/NewBusinessAdmin/Reports/PrintCharts wygenerowaniu raportu] wyświetla się w oknie po kliknięciu odnośnika '''Określ parametry'''.

== Jeden filtr, wiele raportów == #powiazania
Raz zdefiniowane filtry mogą być publikowane (dodawane zostają powiązania) w wielu raportach. Słownik definicji filtrów dostępny jest z menu '''Akcje''' po wybraniu pozycji '''Edycja definicji filtrów''' lub z poziomu zakładki '''Filtry''' kartoteki raportu - po kliknięciu ikony '''Edytuj definicje filtrów raportów''' w '''Pasku narzędzi'''.

Przy dodawaniu filtra bezpośrednio z kartoteki raportu system tworzy definicję filtra i publikuje go w edytowanym raporcie. Zachowanie to możemy zmienić poprzez dodawanie już istniejącej definicji filtra do raportu. Można to zrobić poprzez opcję w menu '''Nowy''' na zakładce Filtry '''Dodaj istniejący (powiązanie)'''. Z otwartego słownika wybieramy filtry lub grupę i klikamy '''Dodaj''' lub '''Dodaj i zamknij'''. Ważne jest, że jeśli publikujemy (dodajemy) element, który ma elementy podrzędne, nastąpi automatyczne dodanie również tych elementów podrzędnych. [[BR]]

Publikować filtry można również poprzez metodę '''drag&drop''' danego elementu drzewka definicji filtrów w oknie '''Definicje filtrów''' na drzewko filtrów w kartotece raportu.

== Dynamiczne grupowanie ==
Aby na panelu filtrów widoczna była opcja dynamicznego grupowania (po kolumnach zdefiniowanych na zakładce '''Kolumny''' w kartotece raportu), w definicji SQL raportu dodajemy token '''{GROUP_BY}'''. Jest to token sterujący, dlatego należy go poprzedzić zapisem '''--'''. Pozycja tokena '''{GROUP_BY}''' nie jest istotna.

__'''Przykład'''__ 
{{{
SELECT * FROM contacts --{GROUP_BY}
}}}


== Przydatne kwerendy SQL do filtrów ==

'''MAGAZYNY'''
{{{
SELECT wahaid, name__ FROM warehouses WHERE is_del IS false ORDER BY prior_
}}}

'''GRUPY PRODUKTÓW'''
{{{
SELECT pgr_id, name__ FROM product_groups 
WHERE is_act IS TRUE AND is_del IS FALSE AND pgr_id NOT IN (SELECT prn_id FROM product_groups) ORDER BY prn_id, name__
}}}

'''KOMÓRKI ORGANIZACYJNE''' 
{{{
-- z ograniczeniem do tych, do których użytkownik ma prawo
SELECT orunid, orunsm AS caption 
FROM organization_units 
WHERE is_del IS FALSE 
AND ndetpe = 'ORGCELL'
AND chkUsrOrgAcc({LOGGED_USR_ID}, orunid) 
ORDER BY orunsm

-- Wybór komórek typu Komórka organizacyjna (same działy)
SELECT orunid, COALESCE(orunsm, '') || ' - ' || ndenam AS stanowisko
FROM orgtree_view 
WHERE orunid > 0 AND ndetpe = 'ORGCELL' 
AND orunsm IS NOT NULL AND is_del IS FALSE
}}}

'''OPIEKUN SPRAWY (lista pracowników)'''
{{{
Filtr = rspuid={value}
Do listy: SELECT usr_id, fullnm FROM orgtree_view WHERE is_del is FALSE
}}}

STATUSY (lista)
{{{
-- SPRAWY
Filtr = state_ in ({value})
SELECT tpstid, dscrpt FROM types_of_processes_states WHERE clsnam LIKE 'PROCESS%' ORDER BY state_

-- DOKUMENTY typu dctpid = 2 (Faktury)
SELECT tpstid, dscrpt FROM types_of_processes_states 
WHERE clsnam = 'DOCUMENT|2' ORDER BY state_
}}}

TERMIN PLANOWANY > OD (data)
{{{
foreda >= '{value}'::date
}}}

WARTOŚĆ SPRAWY (tekstowy)
{{{
forepa > COALESCE(NULLIF('{value}', '')::int,0)
}}}

{{{
-- Osoby, do których użytkownik ma prawo
SELECT ov.usr_id, ov.usrnam FROM orgtree_view ov where
chkUsrOrgAcc({LOGGED_USR_ID}, ov.orunid) IS TRUE


-- Wartości cechy osób, do których użytkownik ma prawo
SELECT ftopid, ftopnm
FROM 
features_options 
INNER JOIN features_options_def USING(fodfid)
LEFT JOIN users u ON u.initls = ftopnm
LEFT JOIN orgtree_view ov ON ov.usr_id = u.usr_id
WHERE featid = 91
AND (CASE WHEN (SELECT count(*) > 0 FROM users_link_group 
WHERE grp_id = 29 AND usr_id = {LOGGED_USR_ID}) THEN 1 = 1 
ELSE chkUsrOrgAcc({LOGGED_USR_ID}, ov.orunid) IS TRUE END)
ORDER BY ftopnm

-- Wartości cechy tekstowej o featid 83
SELECT DISTINCT data__ AS value, data__ AS caption
FROM features_text_view
WHERE featid = 83
ORDER BY data__

-- Wartości do listy wyboru z cechy - lista opcji
SELECT ftopid, ftopnm
FROM 
features_options 
INNER JOIN features_options_def USING(fodfid)
WHERE featid = 66
ORDER BY ftopnm

-- Format zapytania do zwrócenia drzewka
-- Może być wykonane na dowolnej strukturze danych, ważne by zwracało elementy: KLUCZ, RODZIC, NAZWA, TYP. 
SELECT c.strcid AS keyval, c.prn_id, c.strnam AS name__, 
CASE WHEN (SELECT count(*) FROM cregisters.creg_structure_elements c2 
WHERE c2.prn_id = c.strcid) > 0 THEN 'FOLDER' ELSE 'ITEM' END AS icon__ 
FROM cregisters.creg_structure_elements c WHERE c.is_del IS FALSE