Table of Contents

outline	true

English

Datachooser – automatic mappings

Automatic mapping is a feature that will allow to use DC faster on the form. The datachooser mappings will be automatically pulled up in the background if the user enters the value and proceeds to editing the next field.

Configuration

Configuration will be possible on two levels:

PlusWorkflow.conf

Global activation / deactivation of the automatic mapping mechanism:

Form.DataChooser.AutoMapping.Enabled=true

PWE

Option

Description

Default

Activate Checkbox of mapping value

Checkbox

This field enables or disables automatic mapping in the background.

Deselected

Image Added

Clear the value for the empty

Checkbox

Here, if the DC field is empty (someone delete the value), all the mapped fields have to be cleared.

Deselected

Image Added

Only unique values

Checkbox

The selected option fills the value only if there is only one identical or matching result in the data. When the option is deselected, the function completes the field with the first matching result.

Selected

Image Added

Filter results by value

Checkbox

Enables additional filtering of results returned by DC by the value (root mapping). So if you get 20 results, you should filter additionally by the value entered in DC and choose either the unique or the first from the list.

Selected

Image Added

Suspend automatic mapping in secondary dynamic lists.

Checkbox

It disables automatic mapping for datachoosers-children for the duration of the datachooser-parent action. If this option is active, when DC1 with automatic mapping maps values to DC2 (which also has auto-mapping enabled), then after calling the first list, DC2 does not map values to any other field.

Deselected

Image Added

Starting up the mapping

Mapping starts up if it occurs:

change in the field value by the user (from the moment of entering the fields until the exit from this field)
change field value by API
press the ENTER buton in field (it will force of pulling mapping again even if the field value has not changed)

Field blocking

If the automatic mapping mechanism works, field blocking will appear in order to:

disable the user to enter the value in field, which will get soon new data resulting from DC mapping
handle queuing DC execution

Graphically blocked fields look like the following screen

fields are grayed out
the data upload icon is visible
user editing is turned off (API still allows to change data)
field still can receive focus when navigating Tab

Image Added

Blocking Fields		Description
form criteria	Image Added	All criteria fields are blocked (except DC). They are blocked due to such a scenario: Field a is a mapping field by dc1 datachooser and it is a criteria field for dc2 datachooser. If you call dc1 first and next dc2, then calling dc2 will be done after field a is completed by dc1. An additional reason is the desire to be consistent with AutoUpdate where source is also blocked.
mappings	Image Added	All mapping fields are blocked so that the user knows that the field value will be changed by dc soon.
datachooser	Image Added	You do not block the DC field itself (unless it is, for example, mapping another DC) so that the value can be changed all the time.

The right mapping selection

Each DC should support filtering results based on the given query.

After calling DC in the background, from the results one of them should be chosen. Depending on the configuration in the PWE, the selection of results is based on:

Only unique	Filter	Selected row
Image Added	Image Added	It selects the first row which returns dc
Image Added	Image Added	It pulls the mapping only if dc returns 1 row.
Image Added	Image Added	If dc returns only 1 result it is pulled up. If more then it filters the results obtained on the basis of root mapping, the check is: caseinsensitive anymatch (dc value occurs anywhere in root mapping )
Image Added	Image Added	If dc returns only 1 result it is pulled up. If more then it filters the results again and if it is unique after filtering it pull up it.

Polish

Automatyczne podciąganie mappingów to funkcjonalność która pozwoli na szybsze korzystanie z DC na formularzu. Mappingi datachooser'a będa automatycznie podciągane w tle, jeżeli użytkownik wpisze wartość i przejdzie do edycji następnego pola.

Konfiguracja

Konfiguracja będzie możliwa na 2 poziomach:

PlusWorkflow.conf

Globalne włączenie/wyłączenie mechanizmu automatycznego podciągania mappingów:

Code Block
Form.DataChooser.AutoMapping.Enabled=true

PWE

Opcja	Opis	Domyślnie
Włącz mapowanych wartości	Checkbox To pole włącza lub wyłącza automatyczne podciąganie mappingów w tle.	Odznaczone
Wyczyść wartość dla pustego	Checkbox Tutaj, jeżeli pole DC będzie puste (czyli ktoś usunie wartość) to mają się też wyczyścić wszystkie zamapowane pola	Odznaczone
Tylko unikalne wartości	Checkbox Zaznaczona opcja powoduje uzupełnienie wartości tylko wtedy, gdy w danych znajduje się tylko jeden identyczny bądź pasujący wynik. Gdy opcja jest odznaczona funkcja uzupełnia pole pierwszym pasującym wynikiem.	Zaznaczone
Filtruj wyniki po wartości	Checkbox Włącza dodatkowe filtrowanie wyników zwróconych przez DC po wartości (root mapping). Czyli jeżeli dostaniemy 20 wyników, to filtrujemy dodatkowo po wartości wpisanej w DC i wybieramy albo unikalny albo pierwszy z listy	Zaznaczone
Zawieś automapowanie w podrzędnych listach dynamicznych	Checkbox Wyłącza automatyczne podciąganie mappingów dla datachooserów-dzieci na czas działania datachoosera-rodzica. Jeśli ta opcja jest aktywna, to w sytuacji gdy DC1 z automapowaniem mapuje wartości na DC2 (który również ma włączone automapowanie), to po wywołaniu pierwszej listy DC2 nie zamapuje wartości na jakiekolwiek inne pole.	Odznaczone

Uruchomienie podciągania mappingów

Podciąganie mappingów uruchamiane jeżeli nastąpi:

zmiana wartości pola przez użytkownika (od momentu wejścia w pola do momentu wyjścia z tego pola)
zmiana wartości pola przez API
naciśniecie klawisza ENTER w polu (wymusi to ponowne podciągnięcie mappingów nawet jak wartość pola się nie zmieniła)

Blokowanie pól

Gdy zadziała mechanizm automatycznego podciągania mappingów następuje blokada pól, aby:

uniemożliwić użytkownikowi wpisanie wartości w pole, które zaraz dostanie nowe dane wynikające z mappingów DC
obsłużyć kolejkowanie wykonywania DC

Graficznie zablokowane pola wyglądają tak jak na poniższym screenie:

pola są wyszarzone
widoczna jest ikona ładowania danych
edycja przez użytkownika jest wyłączona (API nadal pozwala zmienić dane)
pole nadal może otrzymać focus przy przechodzeniu tabulatorem

Pola

Blokowane

Opis

kryteria (form criteria)

Wszystkie pola kryteriów są blokowane (oprócz samego DC). Blokowane są one ze względu na taki scenariusz:

Pole a jest polem mapowanym przez datachooser'a dc1 oraz jest polem kryterium dla datachooser'a dc2. Jeżeli wywołamy najpierw dc1 a następnie dc2, to wywołanie dc2 zostanie wykonane dopiero gdy pole a zostanie uzupełnione przez dc1.

Dodatkowym powodem jest chęć zachowania spójności z AutoUpdate gdzie source także są blokowane.

mappingi

Wszystkie pola mappingów są blokowane żeby użytkownik wiedział, że zaraz wartość pola zostanie zmieniona przez dc.

datachooser

Nie blokujemy pola samego DC (chyba że jest on np. mappingiem innego DC) żeby umożliwić zmianę wartości cały czas.

Wybór właściwego mappingu

Warning
Każdy DC powinien wspierać filtrowanie wyników na podstawie podanego zapytania.

Po wywołaniu DC w tle z otrzymanych wyników należy wybrać jeden z nich. W zależności od konfiguracji w PWE wybór wyników bazuje na:

Tylko unikalne	Filtruj	Wybrany wiersz
		Wybiera pierwszy wiersz który zwróci DC
		Podciąga mappingi tylko jeżeli dc zwrócić 1 wiersz
		Jeżeli dc zwróci tylko 1 wynik to jest on podciągany. Jeźeli wiecej to filtruje otrzymane wyniki na podstawie root mappingu, sprawdzanie jest: caseinsensitive anymatch (wartość dc występuje gdziekolwiek w root mappingu )
		Jeżeli dc zwróci tylko 1 wynik to jest on podciągany. Jeżeli wiecej to filtruje te wyniki i jeżeli po przefiltrowaniu jest unikalny to go podciąga