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 |
| Checkbox This field enables or disables automatic mapping in the background. | Deselected
|
| Checkbox Here, if the DC field is empty (someone delete the value), all the mapped fields have to be cleared. | Deselected
|
| 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
|
| 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
|
| 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
|
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
Blocking Fields | Description | |
form criteria |  | 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 |  | All mapping fields are blocked so that the user knows that the field value will be changed by dc soon. |
datachooser |  | 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 |
 |  | It selects the first row which returns dc |
 |  | It pulls the mapping only if dc returns 1 row. |
 |  | 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:
|
 |  | 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. |
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:
Form.DataChooser.AutoMapping.Enabled=true
PWE
| Opcja | Opis | Domyślnie |
|---|---|---|
| Checkbox To pole włącza lub wyłącza automatyczne podciąganie mappingów w tle. | Odznaczone  |
| Checkbox Tutaj, jeżeli pole DC będzie puste (czyli ktoś usunie wartość) to mają się też wyczyścić wszystkie zamapowane pola | Odznaczone |
| 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  |
| 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 |
| 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
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:
|
| | 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 |