Walidator

Walidatory to komponenty użytkownika, umożliwiające sprawdzenie formularza podczas akceptacji zadania oraz zablokowanie akceptacji, gdy jakieś dane nie są prawidłowe. Przykładowe walidatory mogą np.

• weryfikować, czy kwota została odpowiednio ustawiona
• weryfikować, czy w zadaniu został dodany komentarz lub dokument.

Stworzone walidatory dostępne są w edytorze procesów i mogą być łatwo wykorzystane w procesie biznesowym umożliwiając tym samym realizacje logiki biznesowej. Ich zachowanie może być dodatkowo konfigurowane za pomocą parametrów. 

Definiowanie walidatora

Walidatory tworzone są w oparciu o ich definicję stworzoną przez użytkownika. Definicja taka musi zawierać następujące elementy:

1. Adnotację 

   Javadoc
   displayValue @Validator property javadoc.plusworkflow className com.suncode.pwfl.workflow.form.validator.annotation.Validator

    (jeżeli walidator nie jest definiowany we wtyczce, musi on pochodzić z pakietu com.suncode)
2. Publiczną metodę oznaczoną adnotacją 

   Javadoc
   displayValue @Define property javadoc.plusworkflow className com.suncode.pwfl.component.annotation.Define

    z jednym parametrem

   Javadoc
   property javadoc.plusworkflow className com.suncode.pwfl.workflow.form.validator.ValidatorDefinitionBuilder

3. Publiczną metodę o nazwie validate, która odpowiada za przeprowadzenie walidacji formularza.

Przykładowa definicja przedstawiona jest poniżej:

@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() );
        }
    }
}

Implementacja funkcji walidującej

Walidator musi posiadać metodę walidującą o nazwie validate. Metoda może posiadać następujące typy parametrów:

• pojedynczy parametr walidatora - typ parametru musi być zgodny ze zdefiniowanym typem oraz musi być poprzedzony adnotacją 

  Javadoc
  displayValue @Param property javadoc.plusworkflow className com.suncode.pwfl.component.annotation.Param

  ,

• Javadoc
  property javadoc.plusworkflow className com.suncode.pwfl.component.Parameters

   - zawiera wszystkie zdefiniowane parametry walidatora wraz z ich wartościami, jest to alternatywa dla pobierania parametru za pomocą wyżej wspomnianej adnotacji

  Javadoc
  displayValue @Param property javadoc.plusworkflow className com.suncode.pwfl.component.annotation.Param

  ,

• Javadoc
  property javadoc.plusworkflow className com.suncode.pwfl.workflow.form.validator.error.ValidationErrors

   - obiekt, w którym ustawiane są wszystkie błędy,

• Javadoc
  property javadoc.plusworkflow className com.suncode.pwfl.workflow.form.validator.ValidationContext

   - kontekst walidacji, można z niego odczytać identyfikator procesu i zadania, których dotyczy ta walidacja,

• Javadoc
  property javadoc.plusworkflow className com.suncode.pwfl.workflow.activity.ActivityContextMap

   - obiekt przechowujący zmienne formularza wraz z aktualnymi wartościami oraz identyfikator procesu i zadania; jest on w całości tylko do odczytu, nie ma możliwości zmiany wartości zmiennych,

• Javadoc
  property javadoc.plusworkflow className com.suncode.pwfl.workflow.component.ContextVariables

   - zmienne kontekstowe dostępne w tym walidatorze. Więcej informacji tutaj,

• Javadoc
  property javadoc.plusworkflow className com.suncode.pwfl.translation.Translator

   - translator dla tego komponentu, dzięki któremu wiadomości zwracane przez walidator mogą być tłumaczone. Więcej informacji tutaj,

• Javadoc
  property javadoc.plusworkflow className com.suncode.pwfl.administration.user.UserInfo

   - obiekt zawierający informacje na temat użytkownika akceptującego zadanie.

W celu przerwania akceptacji zadania i wyświetlenia stosownego komunikatu należy dodać wiadomość do obiektu 

Rejestracja walidatora we wtyczce

Jeżeli walidator jest definiowany we wtyczce to należy dodatkowo zaznaczyć, że wtyczka ta udostępnia komponenty. W tym celu należy w pliku suncode-plugin.xml dodać wpis:

<!-- Udostępnianie walidatorów --> 
<workflow-components key="components" />

Callback przy błędzie walidatora

Możliwe jest dodanie JavaScriptowej funkcji, która zostanie wywołana zamiast wyświetlenia okienka systemowego po zgłoszeniu błędu przez walidator.

Jeżeli przycisk posiada wiele walidatorów, na pierwszym miejscu zostają wyświetlone błędy (okienka z błędami, podkreślanie zmiennych itp.) pochodzące ze zwykłych błędów walidatorów, a w tym czasie walidatory, który zgłosiły wywołanie callbacka zostaną zignorowane. Jeżeli użytkownik pozbył się wszystkich standardowych błędów, każda kolejna akceptacja zadania wywoła tylko i wyłącznie jeden pojedynczy callback.

Aby dodać callback do komponentu, obok adnotacji 

@Validator
@ValidatorsScript( value = "scripts/peselValidatorCallback.js" )
public class PeselValidator

Aby zgłosić callback na formularzu, należy wywołać invokeCallback z 

public void validate( @Param( value = "param" ) Variable param, ValidationErrors errors )
    {
		//...
        if ( validatorFailed )
        {
            errors.invokeCallback();
        }
    }

Jeżeli walidator jednocześnie doda błędy oraz zgłosi wywołanie callbacka, błędy zostaną zignorowane przez serwer (zostanie wywołany JavaScriptowy callback). Jeżeli walidator nie posiada adnotacji 

Implementacja callbacka w JavaScripcie jest analogiczna do tworzenia skryptów Akcji.

PW.FormValidators.create('pesel-validator', {
    callback : function() {
        console.log('Pesel validator callback');
    }
});

Pierwszy argument funkcji create musi być taki sam, jak id walidatora. Drugim argumentem jest obiekt implementujący metodę callback, która jest wywoływana przy dodaniu błędu w walidatorze.

Komunikat błędu lub potwierdzenia walidacji

Możliwe jest określenie w PWE komunikatu błędu walidacji oraz komunikatu potwierdzenia akceptacji formularza pomimo błędu walidacji. Aby w PWE wyświetlone zostały te pola należy w builderze walidatora określić, jakie typy komunikatów mogą zostać skonfigurowane.

@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 )
            .messageTypes( ValidatorMessage.CONFIRMATION, ValidatorMessage.ERROR ) // możliwe będzie skonfigurowanie komunikatu potwierdzenia oraz błędu walidacji
            .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() );
        }
    }
}

Enum 

W metodzie execute walidatora możliwe jest pobranie dwóch nowych obiektów:

• Javadoc
  displayValue DefinedConfirmation property javadoc.plusworkflow className com.suncode.pwfl.workflow.form.validator.error.DefinedConfirmation

   - obiekt przechowujący tytuł i tekst potwierdzenia

• Javadoc
  displayValue DefinedError property javadoc.plusworkflow className com.suncode.pwfl.workflow.form.validator.error.DefinedError

   - obiekt przechowujący tekst błędu

Obiekty te należy samemu dodać do błędów oraz potwierdzeń walidacji. Przykładowe użycie:

public void validate( @Param( value = "param" ) Variable param, ValidationErrors errors,
                      Translator translator, DefinedError error, DefinedConfirmation confirmation )
    {
        String value = param.getValue().toString();
        if ( /* warunek - błąd walidacji */ )
        {
            errors.add( error );
        }
        else if ( /* warunek - mimo błędu zapytanie o potwierdzenie akceptacji zadania */ )
        {
            errors.addConfirmation( confirmation );
        }
    }