Wydruk etykiet i raporty

Wstęp

Aplikacja AMAGE posiada bogaty zasób wewnętrznych szablonów raportów oraz mechanizmów automatycznie generujących etykiety. Niemniej szablony etykiet nie zawierają wszystkich wariantów etykiet dostępnych na rynku. Każdy klient posiada własne możliwości wdrażania systemu oraz zastosowania własnych metod oznaczania elementów i urządzeń. W związku z powyższym aplikacja AMAGE udostępnia możliwość tworzenia własnych formatów etykiet, które zostaną wykorzystane przez aplikację do generacji i wydruku etykiet z danymi.

Niniejszy dokument opisuje sposób projektowania etykiet, wymagane/dostępne dane dla klienta oraz sposób integracji w aplikacji AMAGE.

Oprogramowanie

Do projektowania nowych formatów etykiet służy oprogramowania Jaspersoft Studio. Oprogramowanie jest oprogramowaniem darmowym do użytku komercyjnego. Oprogramowanie można pobrać z witryny producenta:

Po pobraniu, instalacji i uruchomieniu aplikacji pojawia się okno projektanta raportów/etykiet.

Konfiguracja wersji raportów projektanta etykiet

Aktualna wersja aplikacji AMAGE wykorzystuje silnik raportów w wersji 6.2.0. Aby dowiedzieć się, jaką wersję posiada się po zainstalowaniu aplikacji Jaspersoft studio należy przejść do informacji o programie. Wersja projektanta etykiet rysunek 1. W zależności od wersji aplikacji projektanta etykiet należy wybrać wersję biblioteki zgodną z aplikacją AMAGE.

label and reports label designer
Rysunek 1. Wersja projektanta etykiet

Aby przygotować raporty zgodne z wersją wymaganą przez aplikację AMAGE należy ustalić ścieżkę dostępu do biblioteki raportów zgodną z wykorzystywaną przez aplikację AMAGE. Aby to zrobić należy wybrać Properties z zakładki "Project". W nowo otwartym oknie przejść do "Configure Workspace Settings" → "Manage Jaspersoft Versions" rys. 2

label and reports propertiesformyreports
Rysunek 2. Ustalanie ścieżki dostępu(path)

W Manage Jaspersoft Versions klikamy na "add from path", a następnie na "Browse" W oknie przeglądarki plików szukamy katalogu z zainstalowaną aplikacją AmageSystems. Przechodzimy do katalogu amageapplication → modules. W tym katalogu zaznaczamy katalog "ext" i naciskamy "Ok".

label and reports sciezkadostepu

Kompilacja raportu/etykiety po ustawieniu wersji biblioteki raportów dostępna jest w menu kontekstowym kompilacji rys. lub w zakładce "Project → build all"

label and reports kompilacja
Rysunek 3. Kompilacja raportu/etykiety
label and reports kompilacja2
Rysunek 4. Kompilacja raportu/etykiety

Tworzenie etykiet

Etykiety do wydruku na elementy wymagające identyfikacji mogą posiadać następujące parametry:

  • CODE – kod etykiety 1D/2D w formie uproszczonej tj. zawierającej tylko numer porządkowy, bez numeru klienta i instancji AMAGE np. „0000001”

  • BARCODE – pełny kod 1D/2D do wydruku jako kod DATAMATRIX. Kod zawiera typ obiektu, numer klienta oraz numer instancji AMAGE wraz z numerem porządkowym.

  • TYPE – typ obiektu. W przypadku elementów jest to typ elementu, w przypadku produktów typ produktu. Dla lokalizacji i grup elementów pole pozostaje puste.

  • NAME – nazwa obiektu. Zgodnie z wyborem jest to nazwa lokalizacji, produktu, grupy elementów i elementu.

  • *SERIAL_NUMBER - numer seryjny obiektu

  • TEXT1 – dodatkowy tekst określany podczas generowania etykiet w aplikacji AMAGE

  • TEXT2 – dodatkowy tekst określany podczas generowania etykiet w aplikacji AMAGE

  • parameter_<nazwa parametru> - dla Produktu, Grupy Elementów i Elementu można pobrać dodatkowo dowolny parametr. Nazwę parametru podaje się razem z przedrostkiem 'parameter_'

Pola w projekcie etykiet oznaczane są poprzez zmienne FIELD i umieszczane w obszarze projektowym za pomocą zmiennych $F{<nazwa_pola>}.

Dla etykiet 3x1 i 4x1 dostępne są następujące parametry, które uwarunkowane są numerem etykiety w rzędzie. Opis parametru jest identyczny z opisem z pojedynczej etykiety.

  • CODE1, CODE2, CODE3, CODE4

  • BARCODE1, BARCODE2, BARCODE3, BARCODE4

  • TYPE1, TYPE2, TYPE3, TYPE4

  • NAME1, NAME2, NAME3, NAME4

  • SERIAL_NUMBER1, SERIAL_NUMBER2, SERIAL_NUMBER3, SERIAL_NUMBER4

  • parameter_<nazwa parametru>1/2/3/4

Do identyfikacji w systemie AMAGE stosuje się tylko kody DATAMATRIX. Tylko taki kod będzie poprawnie zidentyfikowany z elementem przez terminale mobilne wyposażone w aplikacje serii AMAGE Mobile/CE.

Definiowanie parametrów

Parametry mogą być dowolnie edytowalne w programie Jaspersoft studio. Najpierw należy utworzyć nowe pole (fields → create field) i nadać mu nazwę parametru "parameter_nazwaparametru". Następnie trzeba wybrać z palety "text field" i umieścić go na obszarze "detail". Teraz wystarczy już tylko nadać mu wartość wyrażenia (Expressions): $F+{parameter_nazwaparametru}+ i skompilować. Program przekształci plik jrxml do pliku jasper, który jest plikiem wejściowym dla aplikacji.

Szablon etykiety

Przykładowy szablon etykiety znajduje się na rysunku 7. Rysunek ten zawiera wszystkie niezbędne informacje potrzebne do wydrukowania etykiety z wszystkimi w/w polami.

label and reports label
Rysunek 5. Szablon etykiety

Szablon etykiety dostarczany jest razem z niniejszą dokumentacją w formie pliku „label_50x25.jrxml”. Jest to format etykiety 50mm x 25 mm z podanymi danymi.

W projektancie etykiet można otworzyć dostarczony projekt etykiety i dostosować do swoich wymagań m.in.:

  • Zmieniając rozmiar etykiety

  • Dodając informacje własnościowe np. logo

  • Zmieniając ułożenie elementów

  • Usuwając niepotrzebne wizualnie elementy

Szczegółowa instrukcja obsługi oprogramowania Jaspersoft Studio wykracza poza tą instrukcję. Należy odnieść się do dokumentacji producenta.
label and reports label design
Rysunek 6. Projektant etykiet/raportów

W momencie zakończenia projektowania etykiety plik oryginalny należy zachować do ponownego użycia a następnie wybrać z opcji raportu jego kompilację (menu kontekstowe na raporcie w eksploratorze projektu). Po kompilacji – jeśli cały projekt jest poprawnie wykonany – tworzy się plik wynikowy raportu w formacie *.jasper. Taki plik jest parametrem wejściowym dla aplikacji AMAGE.

Zastosowanie etykiet

Aby wykorzystać własny projekt etykiet, należy w momencie wyboru formatu etykiety do wydruku (Kreator drukowania identyfikatorów) wybrać Szablon etykiet: „Własna etykieta” oraz we włączonym polu wyboru wybrać zaprojektowany plik *.jasper.

image 2025 08 13 22 50 11 359
Rysunek 7. Wybór własnej etykiety - wybierz przycisk "Projektuj"
image 2025 08 13 22 51 02 155
Rysunek 8. Kreator etykiet z wyborem dowolnego formatu etykiet
Następnie można przejść do generacji etykiet i ich wydruku. Po zapisaniu projektu jako szablon ("Zapisz jako szablon"), będzie on dostępny w aplikacji AMAGE do wykorzystania w przyszłości. Jeśli zaznaczymy opcję Prywatne, to szablon będzie dostępny tylko dla nas, a jeśli nie zaznaczymy tej opcji, to szablon będzie dostępny dla wszystkich użytkowników aplikacji AMAGE.

Tworzenie własnych wyglądów raportów

Aplikacja posiada wbudowane własne domyślne szablony wszystkich raportów. Użytkownik z odpowiednią wiedzą może dowolnie modyfikować wygląd raportów zgodnie ze swoimi wymaganiami. Pozwala na to możliwość zmiany wyglądu domyślnego raportu oraz zmiany wyglądu poszczególnych zakładek (konfiguracji) raportów. Pozwala to na posiadanie kilku wyglądów (własne, wewnętrzne, dla klienta itp.) każdego z raportów.

Po rozpakowaniu wybranego raportu np. ''ReportProduct.jrxml''. Należy go otworzyć w projektancie raportów. Następnie wystarczy dowolnie go zmodyfikować zgodnie z oczekiwaniami (kolory, wygląd, tabele, obrazy itp.). Po poprawnej modyfikacji raportu należy go skompilować do formatu ''jasper''. Następnie wszystkie raporty tj. główny oraz ewentualnie pomocnicze podraporty w oryginalnych nazwach (WAŻNE!), należy skompresować do pliku ZIP. Ten plik wgrywamy w głównej aplikacji AMAGE do konfiguracji raportu lub konfiguracji zakładki.

Aby to zrobić, włączamy główną aplikację. Wyświetlamy w eksploratorze listę raportów. Domyślnie wyświetlane są wszystkie raporty, które mają możliwość wyświetlania ich bezpośrednio z eksploratora. Część raportów jest domyślnie niewidoczna, gdyż nie mają możliwości wyświetlania samodzielnego np. raporty wyglądu dokumentu zamówienia - generowany jest tylko w kontekście danego zamówienia.

image 2025 08 13 23 03 09 790
Rysunek 9. Lista podstawowa raportów

Wygląd raportu można zmienić na dwa sposoby. Zmiana globalna szablonu raportu - dostępny będzie zawsze w nowym wyglądzie lub dodanie zakładki raportu ze zmianą wyglądu.

Globalną zmianę wyglądu raportu wykonujemy, przez edycję konfiguracji raportu i wyświetlenie jego właściwości. W tym oknie możemy zaznaczyć nadpisywanie wyglądu raportu oraz wybrać opracowany przez nas zestaw wyglądu w postaci pliku ZIP (patrz wyżej jego opracowanie). Od tego momentu wszystkie raporty generowane z tego typu raportu będą miały zaprojektowany przez nas wygląd.

image 2025 08 13 23 04 01 927
Rysunek 10. Menu kontekstowe dostępu do konfiguracji raportów
image 2025 08 13 23 04 39 858
Rysunek 11. Właściwości globalne wybranego raportu

Jeśli chcemy posiadać kilka wyglądów raportu i/lub dodatkowo określać parametry raportu z panelu filtrów możemy utworzyć zakładkę raportu. Okno dodawania/edycji takiej zakładki ma możliwość definicji wyglądu dodatkowego tak jak dla globalnego raportu. Jedyną zmianą jest możliwość określenia czy plik ZIP z nowym wyglądem szablonu będzie zapisywany w bazie danych (dostępny dla wszystkich użytkowników), czy będzie odniesieniem do pliku lokalnego na systemie plików.

image 2025 08 13 23 06 52 053
Rysunek 12. Lista zakładek raportu - dostęp do konfiguracji
image 2025 08 13 23 07 13 179
Rysunek 13. Konfiguracja zakładki raportu
Pliki w archiwum ZIP muszą mieć dokładnie taką samą nazwę jak oryginalny plik. Aplikacja rozpoznaje pliki raportu do podmiany właśnie po nazwie. Plik ZIP może mieć już dowolną nazwę.

Szablon wyglądu raportu możemy też zmodyfikować w podglądzie raportu. W podglądzie raportu przechodzimy do zakładki Projekt i tam wgrywamy plik ZIP z wyglądem raportu. Po wgraniu pliku ZIP możemy zobaczyć podgląd raportu z nowym wyglądem. W przypadku, gdy raport posiada wiele zakładek, należy każdą z nich zmodyfikować osobno.

image 2025 08 13 23 09 00 103
Rysunek 14. Projektant/podgląd raportu
W przypadku projektanta, gdy dołączymy zamiast pliku ZIP pojedynczy plik *.jasper lub *.jrxml, to aplikacja przyjmie ten plik, jako główny wygląd raportu. Nie ma w tym przypadku możliwości dołączenia podraportów, ale upraszcza to proces wgrywania raportu.

Generowanie raportów na serwerze

Aplikacja AMAGE posiada możliwość generowania raportów na serwerze. W tym przypadku raporty są generowane w tle i nie wymagają interakcji użytkownika. Raporty mogą być generowane na podstawie danych z bazy danych lub z innych źródeł danych. Zobacz definicję zdarzeń automatycznych Automatyzacja - generator raportów, aby dowiedzieć się więcej o generowaniu raportów na serwerze.

Kompatybilność/tworzenie raportów

Ze względu na zmiany w API systemu lub dostępnych bibliotek należy w przypadku błędów generacji raportów wygenerowanych/przygotowanych dla starszych wersji systemu sprawdzić/zmienić następujące funkcje w raportach:

  • Brak funkcji dekodowania obrazów Base64 Było: new java.io.StringBufferInputStream( new org.w3c.tools.codec.Base64Decoder($V{logo}).processString()

    • Należy zmienić na: new ByteArrayInputStream(java.util.Base64.getDecoder().decode($V{logo})))

  • obrazy (np. podpisy) w raporcie pola/zmienne powinny być typu java.io.InputStream zamiast java.awt.Image (lub java.awt.BufferedImage)

Howto powstało na bazie wersji systemu 1.29.0.0 (08.2025) oraz przedstawia funkcje, które mogą nie być dostępne w Twoim systemie. Zapytaj AMAGE o udostępnienie tej funkcjonalności.
Ze względu na ciągły rozwój systemu niektóre ekrany lub pliki konfiguracji mogą wyglądać nieznacznie inaczej, ale zachowają nadal pełną funkcjonalność tutaj opisaną. Nie wpływa to na zasadnicze funkcje opisywane w tym dokumencie.