Projekt stworzonej wtyczki jest dostępny w publicznym repozytorium http://192.168.1.61/developers/tutorials. Skompilowana wersja do pobrania tutaj:

pesel-validator-1.0.0.jar

Wstęp

Kurs ten opisuje proces tworzenia wtyczki dla systemu PlusWorkflow w wersji co najmniej 3.1. Wtyczka ta będzie udostępniała walidator formularza, który:

• sprawdzi czy podana w parametrze zmienna spełnia warunki PESELu, gdy warunek wykonania walidatora jest spełniony
• wyświetli wiadomość w przypadku, gdy zmienna nie jest PESELem.

Przygotowanie walidatora

Pierwszym krokiem jest stworzenie definicji walidatora oraz jego metody walidującej. W ten sposób informujemy edytor procesów, że taki walidator jest dostępny i może zostać wykorzystany przy budowie formularza zadania. W tym celu należy stworzyć klasę z odpowiednim zestawem adnotacji oraz metodę walidującą:

@Validator
public class PeselValidator
{
    private final String PESEL_REGEX = "^\\d{11}$";
    
    @Define
    public void definition( ValidatorDefinitionBuilder builder )
    {
        builder
            .id( "pesel-validator" )
            .name( "validator.pesel" )
            .description( "validator.pesel.desc" )
            .category( Categories.TEST )
            .parameter()
                .id( "pesel_param" )
                .name( "validator.pesel.parameter.name" )
                .description( "validator.pesel.parameter.desc" )
                .type( Types.VARIABLE)
                .create();
    }
 
    //Metoda walidująca
    public void validate( @Param( value = "pesel_param" ) Variable pesel, ValidationErrors errors,
                          Translator translator )
    {
        boolean isPesel = Pattern.matches( PESEL_REGEX, (String) pesel.getValue() );
        if ( isPesel == false )
        {
            errors.add( translator.getMessage( "validator.pesel.invalid" ), pesel.getId() );
        }
    }
}

Definicja

Powyżej zdefiniowaliśmy walidator pesel-validator z jednym parametrem tekstowym, czyli w tym miejscu będziemy chcieli otrzymać wartość zmiennej do walidacji. Jako nazwy i opisy walidatora i jego parametru podaliśmy klucze, gdyż będziemy chcieli, aby te właściwości były tłumaczone w zależności od języka użytkownika. Tłumaczenia dodajmy w plikach /resources/locale/messages.properties (domyślne - wersja polska) oraz /resources/locale/messages_en.properties (wersja angielska).

validator.pesel=Walidacja peselu
validator.pesel.desc=Walidator weryfikuje czy podany parametr jest peselem
validator.pesel.parameter.name=Pesel
validator.pesel.parameter.desc=Wartość do walidacji
validator.pesel.invalid=Należy podać prawidłowy PESEL

validator.pesel=Validate pesel
validator.pesel.desc=Validator to validate if parameter is pesel
validator.pesel.parameter.name=Pesel
validator.pesel.parameter.desc=Value to validate
validator.pesel.invalid=Fill with valid PESEL

W definicji akcji podaliśmy również kategorię Categories.TEST. Niezbędne jest stworzenie takiej kategorii lub wykorzystanie kategorii, która już istnieje. Implementacja kategorii wygląda następująco:

public enum Categories
    implements Category
{
    TEST( "Test" );

    private String name;

    private Categories( String name )
    {
        this.name = name;
    }
 
    @Override
    public String getName()
    {
        return name;
    }
}

Metoda walidująca

Oprócz definicji walidatora zaimplementowaliśmy również metodę walidującą.

W metodzie walidującej zdefiniowaliśmy parametry wejściowe.

• @Param( value = "pesel_param" ) String pesel - wartość dla zdefiniowanego parametru walidatora o id pesel_param
• ValidationErrors errors - obiekt, do którego można zapisać błędy walidatora
• Translator translator - obiekt translatora wtyczki

Podczas wywoływania metody do wszystkich parametrów zostaną wstrzyknięte zdefiniowane parametry i obiekty pomocnicze.

Metoda walidująca weryfikuje czy parametr pesel_param jest numerem PESEL. Jeżeli nie jest, to dodaje tłumaczoną informacje o tym do obiektu ValidationErrors oraz oznacza, że chodzi o zmienną podaną w parametrze.

Konfiguracja wtyczki

Walidator został już zdefiniowany. Należy jeszcze "powiedzieć" systemowi, że wtyczka udostępnia walidator i funkcję oraz korzysta z tłumaczeń. Plik suncode-plugin.xml powinien wyglądać następująco:

<?xml version="1.0" encoding="UTF-8"?>
<plugin key="${project.groupId}-${project.artifactId}" name="Pesel Validator Tutorial">
	
	<!-- Translations -->
	<i18n key="i18n" />
	
	<workflow-components key="components" />
</plugin>

Wykorzystanie walidatora w zadaniu

Stworzony walidator będzie mógł być wykorzystany w edytorze procesów po uruchomieniu wtyczki. Aby sprawdzić jego działanie należy stworzyć prosty proces, a następnie dodać nasz walidator do przycisku akceptacji. Aby to zrobić należy wejść w formularz zadania, następnie wejść w edycję przycisku akceptacji i rozwinąć zakładkę Walidatory. Następnie przy pomocy przycisku należy dodać walidator.

Po dodaniu walidatora pojawi się okno z jego definicją. Należy uzupełnić parametr walidatora oraz warunek wywołania.

W tym momencie dodaliśmy walidator do przycisku akceptującego zadanie, który będzie weryfikował czy zmienna Pesel jest numerem PESEL. Walidacja będzie wywoływana tylko jeżeli zmienna Imię i Nazwisko nie będzie pusta.

Poniżej został przedstawiony wynik walidacji błędnego numeru PESEL.