Tworzenie własnych szablonów raportów w upmesh

W upmesh możesz tworzyć raporty w kilku miejscach: jako Dzienny raport, raport zgłoszeń lub raport projektowy. Dla Dziennych raportów i raportów zgłoszeń dostępne są już raporty standardowe. Jako administrator firmy możesz dodatkowo w Administracji firmy wgrać własne Szablony raportów.

Aby utworzyć własne raporty, potrzebujesz:

• MS Office lub innego programu, który pozwala na tworzenie plików .doc lub .docx

• Dokumentacji i zmiennych z dialogu informacyjnego pod adresem https://app.upmesh.de/company/reportTemplates

• Wiedzy na temat tego, jak stosować te informacje. Właśnie tego nauczymy Cię w tym poradniku.

Jak działają zmienne?

W kartach „Raport zgłoszeń”, „Dzienny raport” i „Raport projektowy” znajdziesz zmienne dostępne dla danego raportu. Są one posortowane według kategorii i zawierają opis, typ danych oraz sposób zapisu zmiennej.

Typ danych informuje Cię, czy jest to ciąg znaków (tekst), który można bezpośrednio wstawić do dokumentu, czy też wymagany jest specjalny sposób traktowania. Pod hasłem „Zmienna” zobaczysz ścieżkę, za pomocą której możesz użyć danej zmiennej.

Uwaga: Jeśli w tej ścieżce znajduje się symbol [], oznacza to, że mamy do czynienia z tablicą (listą). Aby na przykład wyświetlić tytuł zgłoszenia, musisz albo określić, które konkretnie zgłoszenie ma zostać wyświetlone, albo przejść pętlą przez wszystkie zgłoszenia i wyświetlić ich tytuły po kolei. Więcej informacji znajdziesz w sekcji „Pętle For”.

Typy danych i sposoby ich użycia

Przyjrzyjmy się najpierw typom danych, zakładając, że zmienna nie posiada symbolu [] w swojej ścieżce.

Stringi to teksty, które można wstawić bez dodatkowych przygotowań. Używasz ich, umieszczając w dwóch nawiasach klamrowych. Nazwa projektu mogłaby wyglądać tak: {{project.title}}. Nawiasy wskazują, że jest to fragment kodu, który zostanie zastąpiony podczas generowania raportu.

Zmienne typu Number (liczbowe) możesz wstawiać tak samo jak stringi.

Typ Date (data) również możesz wstawiać jak string. Wynik będzie jednak wyglądał następująco: 2026-07-07T11:41:41.928Z. Lepiej wygląda to, gdy użyjesz przykładów kodu z pierwszej karty dialogu informacyjnego. Znajdziesz tam różne sposoby formatowania:

• Data wraz z godziną: {{ new Date( DATE-FIELD ).toLocaleString('pl-PL') }}

• Tylko godzina: {{ new Date( DATE-FIELD ).toLocaleTimeString('pl-PL') }}

• Tylko data: {{ new Date( DATE-FIELD ).toLocaleDateString('pl-PL') }}

• Dzisiejsza data: {{ new Date(new Date()).toLocaleDateString('pl-PL') }}

Uwaga: MS Word w zależności od ustawień językowych może zastąpić wpisane cudzysłowy w ostatnim nawiasie innymi. Te zamienione znaki nie będą działać. Rozpoznasz je po innym kształcie (pierwszy cudzysłów jest na dole zamiast na górze). Zaleca się zatem kopiowanie i wklejanie cudzysłowów zamiast ich ręcznego wpisywania.

„Null” oznacza, że typ może być pusty. Typ „Date | null” oznacza albo datę, albo wartość pustą. Ważne: W takim przypadku użyj zapytania IF, aby upewnić się, że zmienna istnieje, zanim jej użyjesz.

Booleany (wartości logiczne) mogą przyjmować tylko jedną z dwóch wartości: true lub false (prawda lub fałsz). Jeśli użyjesz ich jak stringa, zostanie wyświetlona dokładnie ta wartość. Za pomocą instrukcji IF możesz zmienić sposób wyświetlania, na przykład {{IF $ticket.archived}}zarchiwizowane{{END-IF}} wyświetli słowo „zarchiwizowane”, jeśli ticket.archived jest równe true.

Obiekty są określane jako „object” lub są reprezentowane przez nawiasy klamrowe z nazwami innych zmiennych wewnątrz. Tagi w raporcie zgłoszeń są na przykład tablicą obiektów: {tagName: string; groupName: string; color: string }[].

Obiekt zawsze zawiera dodatkowe informacje. Jeśli wypiszesz go jako string, zostanie on wyświetlony w takim samym formacie jak typ danych, ale z wypełnionymi danymi. Tag może wyglądać tak: {tagName: Tag, groupName: Grupa, color: #ffffff }. Taki widok może pomóc Ci podczas testowania i szukania błędów. Uwaga: Nie wszystkie właściwości obiektu są zawsze wyświetlane, jeśli nie zostały wypełnione.

Aby w tym przykładzie wyświetlić nazwę tagu, możesz wpisać {{ $t.tagName}}, jeśli wcześniej zdefiniowałeś t jako pojedynczy tag (patrz sekcje „Pętle For” i „Zmienne & Obliczenia”).

IF & END-IF

Zapytania IF mówią upmesh: „Jeśli X, to zrób Y”. Zawsze zaczynają się od IF i kończą na END-IF. W pierwszym nawiasie klamrowym po IF znajduje się warunek (jeśli X), a między nawiasami od IF do END-IF znajduje się to, co ma się stać (to zrób Y).

Jeśli zapomnisz o END-IF, generowanie raportu zakończy się błędem. Najlepiej jest dopisać END-IF od razu po IF, zanim zrobisz cokolwiek innego. Dzięki temu o nim nie zapomnisz.

Przykład:

{{IF project.title === 'upmesh'}}
{{project.title}}
{{END-IF}}

Oznacza to: „Jeśli nazwa projektu to 'upmesh', to wypisz nazwę projektu w tym miejscu raportu”.

Możliwe jest również odwrotne:

{{IF project.title !== 'upmesh'}}
{{project.title}}
{{END-IF}}

Oznacza to: „Jeśli nazwa projektu nie jest 'upmesh', to wypisz nazwę projektu w tym miejscu raportu”.

W listach może to wyglądać następująco:

{{IF Array(custom.Projekte).toString().includes('upmesh')}}Tak{{END-IF}}
{{IF Array(custom.Projekte).toString().includes('upmesh')== false}}Nie{{END-IF}}

Jeśli niestandardowe pole listy „Projekty” zawiera wartość „upmesh”, upmesh wypisze „Tak” w tym miejscu raportu. Jeśli pole nie zawiera wartości „upmesh”, upmesh wypisze „Nie”.

Zapytania IF są niezbędne w przypadku zmiennych, które mogą być null lub nie istnieć, w przeciwnym razie generowanie raportu zakończy się niepowodzeniem:

{{IF tickets[0]}}
{{tickets[0]}}
{{END-IF}}

Oznacza to: „Jeśli istnieje co najmniej jedno zgłoszenie, wypisz je”.

{{IF tickets[0] && tickets[0].assignee}}
{{tickets[0].assignee}}
{{END-IF}}

Oznacza to: „Jeśli istnieje co najmniej jedno zgłoszenie i ma ono przypisaną osobę, wypisz tę osobę”.

Ponieważ przy każdym zapisie nowy raport jest sprawdzany w tle na małym teście projektowym, brak instrukcji IF może spowodować błędy już podczas zapisywania. Nie musi to być jednak problemem, szczególnie w przypadku mocno zagnieżdżonych instrukcji IF, które często są zauważane dopiero później. W razie wątpliwości lepiej dodać o jedno zapytanie IF za dużo niż za mało.

Pętle For

Pętle For służą do przechodzenia przez listy. Mówią one upmesh: „Dla każdego elementu tej listy zrób X”.

{{FOR ticket IN tickets}}
#{{$ticket.ticketNumber}} {{$ticket.title}}
{{END-FOR ticket}}

Ta pętla przechodzi przez zgłoszenia, tworząc przy tym nową zmienną o nazwie ticket, która zawiera aktualny element listy. Ponieważ jest to własna zmienna, musisz postawić $ przed jej nazwą, gdy jej używasz. W przykładzie wypisywany jest numer i tytuł zgłoszenia.

Pętla kończy się instrukcją END-FOR. Podanie ticket w END-FOR jest opcjonalne, ale sprawia, że całość jest bardziej czytelna, gdy mamy kilka zagnieżdżonych pętli FOR, na przykład gdy wewnątrz pętli zgłoszeń tworzysz kolejną pętlę, aby przejść przez tagi pojedynczego zgłoszenia.

Brak instrukcji END-FOR spowoduje błąd raportu. Najlepiej jest od razu po FOR x IN y napisać END-FOR, a dopiero potem określić, co ma się stać z elementami.

Zmienne & Obliczenia

Możesz również tworzyć własne skrypty JavaScript i uruchamiać je w raporcie. Nie są one wypisywane, lecz służą do definiowania funkcji lub stałych, z których możesz korzystać w innym miejscu raportu.

Działa to w następujący sposób:

{{EXEC
MOJA_STAŁA = 3;
}}

Wszystko, co znajduje się między {{EXEC a }}, staje się częścią skryptu kodu. Możesz tego obszaru użyć również do wykonywania obliczeń, czego dobrym przykładem jest skalowanie obrazów w następnej sekcji.

Wstawianie obrazów

Obrazy to obiekty w formacie { width: number; height: number; data: string | ArrayBuffer; extension: string}. width i height określają szerokość i wysokość obrazu. Jeśli zmienisz te wartości, obraz zostanie wyświetlony w innym formacie. data zawiera dane obrazu, a extension rozszerzenie pliku.

Obrazy wstawiasz, wpisując IMAGE w nawiasy klamrowe przed nazwą zmiennej, na przykład {{ IMAGE $ticket.plan.large}} (zakładając, że wcześniej zdefiniowałeś ticket jako konkretne zgłoszenie, patrz sekcja „Pętle For”). To wyświetli plan w pełnym rozmiarze.

Jeśli obraz ma być mniejszy, możesz najpierw skopiować obiekt do zmiennej, a następnie dostosować height i width. Przykład takiego obliczenia:

{{FOR ticket IN tickets}}
{{IF $ticket.plan.large}} 
{{EXEC 
targetHeight = 7;
scaled = targetHeight / $ticket.plan.large.height;
targetWidth = $ticket.plan.large.width * scaled;
newImage = { width:targetWidth,height:targetHeight,data:$ticket.plan.large.data, extension:$ticket.plan.large.extension }; 
}}
{{IMAGE newImage}} 
{{END-IF}} 
{{END-FOR ticket}}

Łączenie elementów

Możesz teraz połączyć wszystkie te elementy, aby stworzyć raport. Możesz zagnieżdżać wiele zapytań IF, wiele pętli For lub łączyć IF i FOR ze sobą.

Zaleca się budowanie raportu krok po kroku i regularne testowanie w trakcie pracy. Ułatwia to szukanie błędów, ponieważ gdy wiesz, co zmieniło się od ostatniego testu, możesz lepiej określić, gdzie może leżeć błąd.

Formatowanie zmiennych, czyli kolor tekstu, rozmiar tekstu i czcionka, zostaje przeniesione do wygenerowanego raportu. Teraz Twoim zadaniem jest stworzenie własnego raportu i sformatowanie go tak, jak tego potrzebujesz.