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

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.

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.

Ilustracja 2. 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.

Ilustracja 3. 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.