Sprawdzanie unikalności pól

W programie bs4 core można zdefiniować reguły, które zapobiegają zapisywaniu powtarzających się wartości w obrębie jednej klasy.

Unikalność może dotyczyć:

• jednego pola,
• kombinacji kilku pól.

Mechanizm ten pozwala kontrolować jakość danych i ograniczać powstawanie zduplikowanych obiektów.

1. Zastosowanie reguł unikalności #

Regułę unikalności można zastosować na przykład wtedy, gdy:

• login użytkownika nie może się powtarzać,
• numer NIP kontrahenta powinien być unikalny,
• kod produktu nie może występować w więcej niż jednym obiekcie,
• kombinacja numeru NIP i nazwy kontrahenta nie może się powtarzać,
• zestaw wartości w kilku polach powinien jednoznacznie identyfikować obiekt.

Przykład unikalności jednego pola #

W klasie osoby kontrahenta przechowywany jest login do zewnętrznego systemu.

Każda osoba musi mieć inny login, dlatego pole Login powinno być objęte regułą unikalności.

Program nie powinien pozwolić na utworzenie dwóch osób z takim samym loginem.

Przykład unikalności kilku pól #

W klasie kontrahenta można zdefiniować regułę obejmującą jednocześnie pola:

• NIP,
• Nazwa.

W takim przypadku pojedyncza wartość może się powtarzać. Może więc istnieć kilku kontrahentów o tej samej nazwie albo kilka obiektów z takim samym numerem NIP, jeżeli konfiguracja na to pozwala.

Nie może się jednak powtórzyć identyczna kombinacja wartości w obu polach.

2. Dodawanie reguły unikalności #

Aby zdefiniować regułę unikalności:

1. Przejdź do kartoteki edycji wybranej klasy.
2. Otwórz menu Zaawansowane.
3. Wybierz zakładkę Unikalne pola.
4. Kliknij Dodaj nowe.
5. Skonfiguruj nową regułę.
6. Zapisz zmiany.

Reguła zawsze obowiązuje w obrębie klasy, w której została utworzona.

3. Wybór pól objętych regułą #

W elemencie formularza Pole wskaż jedno albo kilka pól należących do edytowanej klasy.

Reguła obejmująca jedno pole #

Jeżeli zostanie wskazane jedno pole, jego niepuste wartości będą musiały być unikalne w obrębie klasy.

Przykładowo po wskazaniu pola Login program będzie sprawdzał, czy inny obiekt nie ma już takiej samej wartości.

Reguła obejmująca kilka pól #

Jeżeli zostanie wskazanych kilka pól, unikalna musi być ich kombinacja.

Przykładowo dla pól:

• NIP,
• Nazwa,

dopuszczalne mogą być następujące wartości:

• 1234567890 i Firma Alfa,
• 1234567890 i Firma Alfa Poznań,
• 9876543210 i Firma Alfa.

Niedopuszczalne będzie natomiast ponowne zapisanie dokładnie takiej samej pary:

• 1234567890 i Firma Alfa.

4. Blokowanie zapisu lub wyświetlanie ostrzeżenia #

Podczas konfigurowania reguły należy określić wartość pola Czy blokada.

Ustawienie to decyduje, co program zrobi po wykryciu powtarzających się wartości.

Czy blokada: Tak #

Jeżeli pole Czy blokada ma wartość Tak, program:

• wyświetli komunikat o braku unikalności,
• odrzuci operację zapisu,
• nie zapisze żadnych zmian wprowadzonych podczas tej operacji.

Dotyczy to całego zapisywanego obiektu.

Jeżeli użytkownik zmienił jednocześnie kilka pól, a problem dotyczy tylko jednego z nich, program nie zapisze również zmian w pozostałych, poprawnie wypełnionych polach.

Użytkownik musi poprawić dane naruszające regułę i ponownie wykonać zapis.

Czy blokada: Nie #

Jeżeli pole Czy blokada ma wartość Nie, program:

• wyświetli komunikat ostrzegawczy,
• poinformuje o powtórzeniu wartości,
• pozwoli zapisać obiekt.

Takie ustawienie można wykorzystać, gdy powtarzające się dane są niepożądane, ale nie powinny całkowicie blokować pracy użytkownika ani procesów automatycznych.

5. Kiedy sprawdzana jest unikalność #

Reguły unikalności są sprawdzane podczas:

• dodawania nowego obiektu,
• edycji istniejącego obiektu.

Podczas zapisu program ustala, czy którekolwiek ze zmienionych lub dodawanych pól jest objęte regułą unikalności.

Jeżeli tak, odpowiednia reguła zostaje sprawdzona przed zakończeniem zapisu.

6. Reguły obowiązują we wszystkich sposobach zapisu danych #

Unikalność nie jest sprawdzana wyłącznie podczas ręcznej pracy użytkownika w formularzu.

Reguły obowiązują również wtedy, gdy dane są dodawane albo zmieniane za pomocą:

• API,
• importów danych,
• triggerów,
• operacji automatycznych,
• hurtowej edycji obiektów w zestawieniu,
• innych mechanizmów zapisujących dane do klasy.

Oznacza to, że rygorystyczna reguła z włączoną blokadą może zatrzymać nie tylko zapis z formularza, lecz także import lub integrację działającą przez API.

Przed włączeniem blokady należy więc przeanalizować wszystkie procesy, które tworzą lub aktualizują obiekty danej klasy.

7. Konfiguracja komunikatu #

W polu Wyświetlany komunikat można określić treść informacji prezentowanej użytkownikowi po wykryciu braku unikalności.

Domyślny komunikat zawiera tekst informujący o istniejącej konfiguracji unikalnych pól oraz znacznik:

{details}

Znacznik {details} jest automatycznie zastępowany przez program szczegółami dotyczącymi pól, które naruszają regułę.

Komunikat można dostosować do konkretnego zastosowania, na przykład:

• „Wprowadzony numer NIP istnieje już w bazie.”
• „Login musi być unikalny i nie może się powtarzać.”
• „Istnieje już kontrahent o takiej nazwie i numerze NIP.”
• „Kod produktu został już przypisany do innego produktu.”

Przyjazny i precyzyjny komunikat ułatwia użytkownikowi zrozumienie problemu i poprawienie danych.

8. Puste wartości a sprawdzanie unikalności #

Ważnym wyjątkiem jest sytuacja, w której wszystkie pola objęte regułą mają wartości uznawane przez program za puste.

W takim przypadku reguła unikalności nie jest sprawdzana.

Jedno pole #

Jeżeli reguła dotyczy pola NIP, a pole pozostanie puste, program pozwoli zapisać obiekt.

Puste pole nie jest traktowane jako powtarzająca się wartość.

Kilka pól #

Jeżeli reguła obejmuje pola NIP i Nazwa, nie zostanie ona sprawdzona wtedy, gdy oba pola będą puste.

Jeżeli jednak przynajmniej jedno z pól będzie miało wartość, program może sprawdzić regułę dla aktualnej kombinacji wartości.

9. Wartości uznawane za puste #

Zgodnie z mechanizmem unikalności za brak wartości mogą być uznawane między innymi:

• pusty tekst,
• brak wskazanego obiektu w polu typu powiązanie,
• wartość 0 w polu liczbowym.

Jeżeli wszystkie pola wchodzące w skład reguły mają takie wartości, reguła nie jest wykonywana.

Należy to uwzględnić przy projektowaniu kontroli danych. Jeżeli pole musi zostać obowiązkowo uzupełnione, należy niezależnie ustawić je jako wymagane.

Reguła unikalności nie zastępuje kontroli wymaganych pól.

10. Wiele reguł w jednej klasie #

W jednej klasie można zdefiniować wiele niezależnych reguł unikalności.

Przykładowo w klasie kontrahenta można utworzyć:

• regułę unikalności pola NIP,
• regułę unikalności pola Nazwa,
• regułę unikalności kombinacji pól NIP i Nazwa (przy istnieniu dwóch poprzednich merytorycznie nie miałaby sensu)
• regułę unikalności pola Kod kontrahenta.

Każda reguła jest sprawdzana osobno.

Jeżeli zostaną utworzone dwie osobne reguły:

1. jedna dla pola Nazwa,
2. druga dla pola NIP,

oznacza to, że:

• każda nazwa musi być unikalna,
• każdy NIP musi być unikalny.

Nie jest to równoznaczne z jedną regułą obejmującą jednocześnie pola Nazwa i NIP.

11. Osobne reguły a reguła wielopolowa #

Sposób zdefiniowania reguł ma istotne znaczenie.

Dwie osobne reguły #

Reguła 1:

• pole NIP.

Reguła 2:

• pole Nazwa.

W takim wariancie ani NIP, ani nazwa nie mogą się powtarzać.

Jedna reguła wielopolowa #

Reguła:

• pole NIP,
• pole Nazwa.

W takim wariancie NIP i nazwa mogą występować ponownie osobno, ale nie może się powtórzyć ich identyczna kombinacja.

12. Zalecenia konfiguracyjne #

Przed utworzeniem reguły warto ustalić:

• czy unikalne ma być jedno pole, czy zestaw pól,
• czy powtórzenie ma blokować zapis, czy tylko wyświetlać ostrzeżenie,
• czy reguła nie zakłóci importów i integracji przez API,
• jaki komunikat będzie zrozumiały dla użytkownika,
• czy pola powinny być również oznaczone jako wymagane,
• jak program ma zachować się w przypadku pustych wartości.

Reguły unikalności należy konfigurować możliwie precyzyjnie. Zbyt szeroka lub zbyt rygorystyczna reguła może niepotrzebnie blokować użytkowników oraz automatyczne procesy zapisujące dane.