For the complete documentation index, see llms.txt. This page is also available as Markdown.

Struktura modelu danych

Struktura drzewa

Model danych ma strukturę drzewa ułatwiającą odwzorowanie hierarchicznej struktury obiektów domeny biznesowej.

Liście drzewa reprezentują najbardziej szczegółowy element struktury. Liście, zwane polami, nie posiadają już żadnych innych elementów podrzędnych (dzieci) i reprezentują pojedyncze pole danych. Przykładami mogą być "imię klienta" czy "numer rachunku bankowego".

Węzły drzewa reprezentują obiekty złożone z innych obiektów i/lub pól. Przykłady: "adres korespondencyjny", "dochód klienta".

Ilustracja 1. Struktura drzewa

Istnieje możliwość zmiany kolejności węzłów i liści na drzewku poprzez ich przytrzymanie i przeciągnięcie. Zmiana kolejności jest możliwa wyłącznie w obrębie tego samego poziomu hierarchii oraz podczas pracy na wersji roboczej. Modyfikacja ta ma charakter wizualny i nie wpływa na logikę działania modelu.

Węzły

Każdy węzeł modelu danych posiada atrybuty:

  • klucz unikalny wśród swojego rodzeństwa (potomków tego samego węzła)

  • liczebność wyrażoną wzorem n..m oznaczającym od n wystąpień minimalnie do m maksymalnie, np:

    • 1..1 - obiekt występuje tylko raz

    • 0..1 - obiekt jest opcjonalny

    • 1..null - obiekt występuje co najmniej raz, bez ograniczenia na maksymalną liczbę wystąpień

  • opis znaczenia obiektu dla aplikacji

Węzły można zatem jednoznacznie wskazać za pomocą klucza powstałego poprzez złączenie kluczy węzłów nadrzędnych, np: client.email.

Liście

Poza atrybutami węzłów, liście posiadają dodatkowo:

  • źródła danych - określają jak i skąd pobierana jest wartość

  • domyślna wartość - co zwróci pole, jeżeli żadne ze źródeł danych nie zwróci wartości

Pole może mieć zdefiniowaną listę źródeł danych. Rozstrzyganie wartości pola polega na wywoływaniu źródeł danych w kolejności ich zdefiniowania aż do uzyskania niepustej wartości. Zatem pierwsze źródło zwracające niepustą wartość wygrywa.

Dane z modelu możemy pobierać tylko dla wybranych przez nas pojedynczych kluczy, tj. nie możemy pobierać wartości kluczy, które mają pod sobą dzieci, tak jak nie możemy pobrać całego modelu w jednym zapytaniu.

Rodzaj wartości pola (typowanie)

Katalog typów jest opcjonalny i konfigurowany osobno dla każdego wdrożenia platformy. Jeśli nie został skonfigurowany, edytor nie wyświetla plakietek rodzaju wartości, a wartości pól nie są walidowane względem rodzaju.

Katalog typów pozwala określić rodzaj wartości pola: tekst, data albo data i godzina. Edytor modelu danych pokazuje go obok nazwy pola, jako plakietkę. Jeśli katalog określa pole jako wielokrotne, zamiast rodzaju wartości wyświetlana jest plakietka Tablica. Gdy wielokrotność węzła w modelu nie zgadza się z katalogiem, plakietka jest przekreślona i oznaczona ikoną ostrzeżenia.

Etykieta "Pole spoza schematu" pojawia się wyłącznie przy kluczu, którego nazwa nie występuje w katalogu typów na danym poziomie. Klucz o znanej nazwie zachowuje plakietkę wynikającą z katalogu, nawet jeśli jego wielokrotność jest niezgodna.

Typ pola
Ilustracja 2. Przykład plakietek

Plakietki mają charakter informacyjny. Niezgodność struktury modelu z katalogiem typów, na przykład inna wielokrotność klucza, nie blokuje publikacji modelu danych.

Walidacja wartości przy zapisie

Wartość zapisywana w polu objętym katalogiem typów musi odpowiadać zadeklarowanemu rodzajowi:

  • Na formularzu - podczas próby przejścia dalej pole zmapowane na typowany klucz zgłasza błąd "Wprowadzona wartość ma nieprawidłowy format", jeśli wpisanej wartości nie można rozpoznać jako zadeklarowanego rodzaju.

  • W ScriptCode - zapis niezgodnej wartości przez API modelu danych jest odrzucany; wartość nie zostaje zapisana.

Przykład: pole zmapowane na klucz typu data i godzina odrzuci wartość wczoraj, ale przyjmie 2026-09-15 lub 2026-09-15T10:00:00Z. Pusta wartość przechodzi walidację niezależnie od rodzaju pola.

Nieprawidłowy format
Ilustracja 3. Błąd zwracany przy wartości niezgodnej z typem pola

Maksymalna długość tekstu z typu

Pole tekstowe zmapowane na klucz z katalogu typów podlega określonemu w nim limitowi długości. Limit ustawiony jawnie w komponencie może być niższy, ale nie może zwiększyć limitu wynikającego z katalogu.

Wyświetlanie na liście spraw

Jeśli wartość zapisana pod typowanym kluczem nie odpowiada zadeklarowanemu rodzajowi, lista spraw wyświetla zamiast niej komunikat "Błąd danych". Może to dotyczyć na przykład wartości zapisanej przed włączeniem walidacji. Sprawa pozostaje widoczna, a pozostałe kolumny są wyświetlane normalnie. Jeśli pole ma zaakceptowaną maskę w procesie depersonalizacji, lista spraw wyświetla ją zamiast komunikatu "Błąd danych".

Wskazywanie pól, które zasilają kolumny listy wszystkich spraw, opisuje strona Kolumny listy wszystkich spraw w konfiguracji aplikacji.

Tablice w modelu danych

Węzły modelu oznaczone jako wielokrotne (liczebność maksymalna >1) tworzą tablicę prostych wartości (dla pól) oraz złożonych obiektów (dla węzłów nie będących liśćmi). Możliwe jest również zdefiniowanie kolekcji zagnieżdżonych.

Klucze i identyfikatory

Odwołując się do węzłów modelu danych zdefiniowanych jako tablica (lub będącymi potomkami tablicy) należy zawsze używać notacji tablicowej:

  • tablica[].pole - pobiera wszystkie wystąpienia pola; zależnie od używanego API zwróci kolekcję lub pojedynczy string z separatorem ","

  • tablica[0].pole - pobierze pojedynczą wartość rozwiązaną wierszem kolekcji wskazanym w kluczu (w przykładzie 0 oznacza pierwszy element tablicy),

  • tablica.pole - spowoduje błąd, nie ma możliwości odniesienia się do tablicowego węzła bez notacji tablicy,

Definiowanie tablicy

W celu zdefiniowania tablicowego pola konieczne jest:

  • wielokrotny węzeł modelu danych musi posiadać krotność większą niż multiplicityMax=1, np. 1..null,

  • wielokrotny węzeł modelu danych musi mieć zdefiniowane źródła wskazujące na tablicę, indeksy tej kolekcji zostaną użyte do indeksacji powtórzeń wartości modelu,

  • węzły poniżej wielokrotnego węzła modelu danych mogą w mapowaniu stosować indeks iterowanego węzła modelu do wskazania konkretnych elementów wyjścia usługi,

    • nadrzędny węzeł zawsze udostępni w kontekście wykonania swój bieżący indeks (w trakcie rozwiązywania wartości dla kolekcji) pod identyfikatorem nazwaWezłaIdx,

    • pola iterowane rodzicem powinny wskazywać na obiekty wewnątrz kolekcji, po której iteruje rodzic,

    • nie jest to jednak stricte konieczne, możliwe jest wykorzystanie tego indeksu do iterowania po zupełnie innym polu lub do wyciągania pól w ogóle nie będących tablicami.

Przykładowo, mając wynik usługi, który składa się ze stałego pola i dwóch tablic - o których wiadomo, że mają tę samą długość (tablicaA, tablicaB, poleC) - możliwe jest stworzenie mapowania, w którym model iteruje po tablicyA, ale jego podpola wyciągają kolejne pola tablicyB i stałą wartość z polaC.

Powiązanie providera z modelem danych

Provider to lokalne źródło danych napisane w ScriptCode, które definiuje sposób pozyskiwania wartości dla pól modelu. Może być wykorzystywane przez pola do zasilania ich watości. Źródłem danych może być funkcja:

  • skryptowa,

  • wywołująca zewnętrzną usługę REST,

  • odwołująca się do innego elementu modelu,

  • pobierająca wartość z konfiguracji aplikacji.

Opisany poniżej provider stanowi źródło danych dla liścia modelu danych. Służy ono do pobrania aktualnego kursu waluty z zewnętrznego API (NBP):

  • exchangeRate jest liściem (polem) w drzewie,

  • pole to nie posiada dzieci i reprezentuje pojedynczą wartość (kurs waluty),

  • może być zagnieżdżone w węźle, np.: exchangeRates.exchangeRateEUR.

przykład z kodem providera
Ilustracja 4. Przykład providera pobierającego aktualny kurs waluty z API (NBP)

Przebieg działania:

  • z parametrów wejściowych providera pobierany jest klucz, czyli kod waluty (currencyCode), np. „EUR” lub „USD”,

  • wartość ta jest przekazywana do providera z modelu danych,

  • provider wykonuje zapytanie GET do skonfigurowanego endpointu nbpExchangeRate przy użyciu api.rest.v1.get,

  • parametry ścieżki (pathParams) budują adres zapytania w postaci: /rates/A/{currencyCode} (litera „A” oznacza tabelę średnich kursów walut publikowanych przez NBP),

  • odpowiedź z API zawiera obiekt body, w którym znajduje się tablica rates, a z tablicy pobierany jest pierwszy element (rates[0]), następnie jego pole mid, które reprezentuje średni kurs waluty,

  • provider zwraca obiekt zawierający pole exchangeRate, wartość tego pola odpowiada pobranemu kursowi waluty i może być dalej wykorzystana w modelu danych lub formularzu.

Konfiguracja źródeł danych dla pola

Każde pole w modelu danych posiada możliwość zdefiniowania źródeł danych. Konfiguracja dostępna jest po kliknięciu ikony ołówka przy wybranym polu, co otwiera szufladę ustawień źródeł danych powiązanych z tym polem. Jeżeli dla danego klucza zostały już zdefiniowane źródła danych, ich nazwy są widoczne w panelu - w przedstawionym przykładzie jest to exchangeRateFromNBPProvider. Po wybraniu źródła możliwa jest konfiguracja parametrów wejściowych oraz mapowania wyjścia.

przykład z kodem providera
Ilustracja 5. Przykład wykorzystania providera jako źródła danych w modelu

W zakładce Parametry definiowane są wartości przekazywane do providera. W opisywanym przypadku:

  • klucz: currencyCode

  • wartość: EUR

Parametr ten jest wykorzystywany przez provider do wywołania zewnętrznego API.

W sekcji Mapowanie określane jest, które dane z odpowiedzi providera zostaną przypisane do pola w modelu. W tym przykładzie mapowana jest wartość exchangeRate.

Uzyskana wartość może być następnie wykorzystana w modelu danych lub bezpośrednio w formularzu. Więcej o wykorzystaniu modelu danych na wniosku w zakładce Model danych na interfejsie.

Ostatnia aktualizacja

Czy to było pomocne?