> For the complete documentation index, see [llms.txt](https://docs.eximee.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.eximee.com/budowanie-aplikacji/logika-biznesowa/scriptcode/script-code-bazy-projekcji.md).

# Obsługa baz projekcji (Registry)

### Eximee Registry API w ScriptCode

API `api.registry.v1` służy do zapisywania, aktualizowania i odczytywania danych w podręcznej bazie projekcji.

Dzięki pełnej integracji z silnikiem platformy, z Registry API korzystasz bezpośrednio w kodzie JavaScript:

* **W kontekście interfejsu użytkownika (formularza):** W skryptach walidacji, serwisach stron (PageService) oraz skryptach wejścia/wyjścia (EntryService, ExitService).
* **W kontekście automatyzacaji procesów:** W zadaniach skryptowych [SciptCode Taks](/budowanie-aplikacji/logika-biznesowa/scriptcode/zadanie-skryptowe-scripttask.md) oraz [konsumentach zdarzeń z Kafka/MQ](/eksploatacja-aplikacji/obsluga-zdarzen/konsumenci-kafka.md).

Wartości do zapisu można wyliczyć w serwisach formularza (EntryService, PageService...) lub pobierać bezpośrednio z modelu danych aplikacji (`api.model.v1.get()`). Wyniki wyszukiwania można dynamicznie prezentować użytkownikowi na ekranie lub wykorzystywać w algorytmach, np. do weryfikacji warunków widoczności.

### API

Poniższa tabela zawiera opis metod i parametrów interfejsu `api.registry.v1`

| Metoda      | Argumenty                                                    | Typ zwracany         | Opis                                                                                                       |
| ----------- | ------------------------------------------------------------ | -------------------- | ---------------------------------------------------------------------------------------------------------- |
| save        | namespace: String, id: String, data: String                  | void                 | Zapisuje lub aktualizuje (upsert) dane tekstowe pod wskazanym identyfikatorem w wybranej przestrzeni nazw. |
| saveVersion | namespace: String, id: String, data: String, version: String | void                 | Zapisuje dane wraz z jawnym określeniem ich wersji schematu.                                               |
| get         | namespace: String, id: String                                | String               | Pobiera i zwraca zapisany ciąg znaków dla danej przestrzeni nazw oraz identyfikatora.                      |
| getVersion  | namespace: String, id: String                                | TempStoreVersionItem | Pobiera obiekt zawierający zarówno model danych, jak i wersję schematu.                                    |
| delete      | namespace: String, id: String                                | void                 | Trwale usuwa wpis o wskazanym identyfikatorze z wybranej przestrzeni nazw.                                 |

#### Obsługa formatu JSON (data)

Ponieważ metody zapisu przyjmują oraz zwracają dane jako ciąg znaków (String), w skryptach JavaScript należy stosować serializację i deserializację obiektów:

* **Przy zapisie (save / saveVersion):** Przekazywany obiekt JavaScript należy zamienić na tekst za pomocą JSON.stringify(object).
* **Przy odczycie (get):** Pobrany tekst należy sparsować do obiektu za pomocą JSON.parse(string).

#### TempStoreVersionItem

Obiekt zwracany przez metodę getVersion posiada właściwości (gettery) dostępne bezpośrednio w JavaScript:

* data (String) – Surowy ciąg znaków z zapisanym modelem danych.
* version (String) – Przypisana wersja schematu.

### Znaczenie przestrzeni nazw (*namespace*)

Parametr namespace nie jest sztywnym słownikiem narzuconym przez platformę Eximee. Daje on low-coderowi pełną swobodę w definiowaniu logicznych domen zapisu i wyszukiwania (tzw. context-bounded domains).

Możesz go traktować jako autonomiczną przestrzeń adresową – dowolny, zdefiniowany przez Ciebie ciąg znaków, który logicznie grupuje powiązane ze sobą wpisy. Dzięki temu osiągamy:

* **Separacja danych:** Ta sama aplikacja low-code może zapisywać różne aspekty tej samej sprawy do osobnych domen (np. "KredytHipoteczny\_Wniosek", "KredytHipoteczny\_Zabezpieczenia", "KredytHipoteczny\_Scoring"), co ułatwia zarządzanie uprawnieniami i czytelność danych.
* **Brak kolizji:** Różne aplikacje mogą korzystać z dokładnie tych samych identyfikatorów (np. tego samego numeru PESEL), ponieważ ich dane są odizolowane wewnątrz swoich przestrzeni nazw.
* **Elastyczne wyszukiwanie:** Wyszukując informacje metodą get, odpytujesz wyłącznie wybraną, precyzyjnie określoną domenę, co gwarantuje błyskawiczne czasy odpowiedzi bazy projekcji.

### Strategia wyboru klucza biznesowego

Przed zapisaniem danych należy określić klucz główny (`id`), który jednoznacznie zidentyfikuje rekord w bazie projekcji. Rejestr nie narzuca sztywnego formatu – kluczem może być dowolny unikalny ciąg znaków.

Częste scenariusze to:

* **PESEL lub CIF klienta:** Gdy chcesz agregować i sprawdzać wnioski powiązane z daną osobą (np. blokada wielokrotnego wnioskowania).
* **NIP lub REGON firmy:** Gdy chcesz powiązać sprawy dotyczące danej firmy.
* **Numer rachunku bankowego:** W przpadku potrzeby powiązania różnych procesów modyfikujących parametry konta
* **Identyfikator koszyka zakupowego / transakcji (basketId):** Gdy sprawa dotyczy grupy produktów procesowanych wspólnie.
* **Klucz kompozytowy:** Dynamiczne połączenie kilku parametrów (np. PESEL\_KODPRODUKTU) utworzone w skrypcie.

### Przykład: Ograniczenie liczby równoczesnych procesów kredytowych do 1

Chcemy kontrolować liczbę wniosków kredytowych klienta i ograniczyć ją do jednego. Jeżeli klient spróbuje rozpocząć drugi wniosek otrzyma informację o konieczności zakończenia poprzedniego wniosku lub zostania automatycznie przekierowany do wniosku rozpoczętego wcześniej.

#### Zapis faktu wnioskowania o kredyt (Inicjalizacja)

Skrypt podpinany najczęściej pod akcję przejścia do kolejnej strony lub kliknięcia przycisku "Wyślij":

```javascript
// Zapisanie faktu wnioskowania o kredyt gotówkowy
api.registry.v1.save(
    "KredytGotowkowy",                // przestrzeń nazw
    api.model.v1.get("klient.pesel"), // PESEL z modelu danych jako identyfikator
    JSON.stringify({                  // W danych możesz przekazać cokolwiek potrzebujesz
        businessKey: api.model.v1.get("businessKey"), 
        kwota: api.model.v1.get("kredyt.kwota"),  
        status: "new"
    })
);
```

#### Weryfikacja i blokada wielokrotnego wnioskowania.

Skrypt uruchamiany na wejściu do formularza (EntryService), sprawdzający czy klient nie posiada już aktywnego wniosku w toku:

```javascript
// Wyszukiwanie aktywnych wniosków dla PESEL-u z modelu danych
const istniejacyProces = api.registry.v1.get("KredytGotowkowy", api.model.v1.get("klient.pesel");

// Jeśli znaleziono aktywny proces, ustawiamy komunikat blokady na formularzu
if (!istniejacyProces) {
    // Blokujemy klientowi możliwość dalszego wnioskowania
} else {
    // Sprzedajemy klientowi kredyt
}
```

#### Usuwanie informacji o aktywnym procesie

Skrypt uruchamiany na zakończenie proceswania wniosku, np. jako ServiceTask

```javascript
api.registry.v1.delete("WniosekKredytowy", api.model.v1.get("klient.pesel"));
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.eximee.com/budowanie-aplikacji/logika-biznesowa/scriptcode/script-code-bazy-projekcji.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.