Lista wyboru (WebService)

Podsumowanie:
Lista wyboru WebService to lista rozwijana, dla której źródłem danych jest akcja WebService. Odpowiedź zwrócona przez akcję jest przetwarzana zapytaniem SQL na format akceptowany przez listy wyboru w nAxiom (wynik zapytania o kolumnach [key]/[value]).

Oprócz właściwości typowych dla większości kontrolek, lista wyboru WebService wymaga ustawienia właściwości:

Pole wartości ustalonej: wybierz z listy kolumnę w tabeli źródłowej formularza, w której zostanie zapisana wartość wyświetlana na liście rozwijanej (wartość z kolumny [value] zwracanej przez zapytanie w konfiguracji listy). Po zapisaniu instancji dokumentu ta wartość będzie wyświetlana na formularzu nawet wtedy, gdy odpowiadająca wartość w źródle danych listy rozwijanej zostanie zmieniona. W takiej sytuacji, po rozwinięciu listy podświetlana będzie zaktualizowana wartość odpowiadająca wartości ustalonej.

Pole wartości ustalonej nie jest widoczne w kontekście formularza ( ), a przypisana do niego kontrolka formularzu nie będzie wyświetlać danych.

Ustawienia: kliknięcie przycisku Konfiguracja listy wyboru wyświetla okno dialogowe, w którym należy określić właściwości:
Akcja web serwisu: akcja WebService, która będzie źródłem danych dla listy. W konfiguracji listy wyboru Webservice należy określić osobną procedurę obsługi odpowiedzi, która przetworzy dane zwrócone przez akcję tak, aby mogły być wyświetlane na liście wyboru. Procedura obsługi odpowiedzi określona w definicji akcji jest ignorowana.

Tryb obsługi odpowiedzi: dostępne wartości:
- domyślny: zapytanie SQL określone jako procedura obsługi odpowiedzi jest wykonywane w przypadku, gdy zostanie zwrócony status HTTP z zakresu 200-299; w przeciwnym razie akcja zwróci wyjątek.
- własny warunek obsługi odpowiedzi: w ramach procedury odpowiedzi możesz obsłużyć każdy status HTTP odpowiedzi; patrz przykład poniżej.

Procedura obsługi odpowiedzi: zapytanie zwracające listę wartości z kolumnami [key]/[value]. W zapytaniu można korzystać ze zmiennych {@_Response}, {@_HTTPResponseStatusCode}, {@_HTTPResponseStatusName} i {@_HTTPResponseHeader}.

W zapytaniu dostępne są następujące zmienne:

@_Response: treść (body) odpowiedzi; jeśli dla zwracanych danych określono format JSON, w zapytaniu użyj funkcji OPENJSON.
@_HTTPResponseStatusCode: status odpowiedzi (int) np. 404.
@_HTTPResponseStatusName: nazwa statusu odpowiedzi np. NotFound dla statusu 404.
@_HTTPResponseHeader: nagłówki odpowiedzi w formacie JSON o następującej strukturze:
```
{
"header_1": ["value_1"],
"header_2": ["value_2", "value_3"]
}
```
gdzie header_x to nazwa nagłówka odpowiedzi, a value_x to jego wartość. Wartości nagłówków można pozyskać używając funkcji SQL OPENJSON. W przypadku, kiedy nazwa nagłówka zawiera myślnik (-), odpowiadający mu klucz należy ująć w cudzysłów, na przykład:
```
(SELECT top(1) value
 FROM OPENJSON({@_HTTPResponseHeader}, '$."Content-Type"')
```
Lista zależności: kolumna - pole formularza: tabelka, która pozwala przypisać kolumnie zapytania źródłowego listy wyboru pole formularza. Kliknij ikonę edycji i wybierz pole formularza z rozwijanej listy. Przypisanie spowoduje, że po wybraniu pozycji z listy w powiązanym polu zostanie ustawiona wartość zwracana przez listę dla tej pozycji w odpowiedniej kolumnie.

Zamiast wybierać pola formularza, w kolumnie Powiązane pole formularza można także wpisać dowolną nazwę; spowoduje to utworzenie zmiennej w kontekście formularza, w której będzie przechowywana wartość zwrócona przez listę. Do takiej zmiennej można odwoływać się w wyrażeniach, używając standardowej składni {@nazwaZmiennej}.

Tryb aktualizacji pól zależnych: dostępne wartości:
- Zawsze: każda operacja otwarcia i odświeżenia formularza oraz zmiana na liście wyboru powoduje aktualizację wartości w polach zależnych.
- Tylko po zmianie na liście wyboru: aktualizacja wartości w polach zależnych odbywa się tylko po zmianie pozycji w liście rozwijanej (zmiana przez użytkownika lub np. przez akcję).
- Tylko gdy wskazane pole jest puste: wartości zwrócone przez listę wyboru są przekazywane do pól zależnych tylko wtedy, kiedy są one puste.

Na efekty działania tej funkcji ma wpływ zachowanie nAxiom przy odświeżaniu formularza. Kliknięcie ikony odświeżania w prawym górnym rogu formularza inicjuje działanie zależnie od typu okna formularza:

Dialog: zostaje ponownie wykonana akcja otwierania formularza z użyciem przekazywanych w niej parametrów.
Link wewnętrzny: formularz i dane rekordu zostają ponownie wczytane z bazy danych; ewentualne parametry przekazywane w akcji otwierania formularza zostają utracone. Tak samo działa przeładowanie strony w przeglądarce klawiszem F5.

Akcja odświeżenia formularza działa tak samo, niezależnie od typu okna formularza, to jest wczytuje ponownie formularz i dane rekordu z bazy danych. Jeśli formularz został otwarty akcją z przekazaniem parametrów, parametry zostaną utracone.

Przykład 1

Zapytanie przetwarzające odpowiedź ze źródła SOAP API w celu wyświetlenia wartości na liście wyboru (wymagane skonfigurowanie źródła danych i akcji zapytania do webserwisu).

DECLARE
  @xmlRes XML = REPLACE(ISNULL({@_Response},'ERROR'), '<?xml version="1.0" encoding="utf-8"?>',''),
  @msg AS nvarchar (1000);
WITH XMLNAMESPACES (DEFAULT 'http://www.oorsprong.org/websamples.countryinfo')
SELECT
  l.value('sName[1]','varchar(30)') AS [key],  -- wartość zapisywana do bazy danych
  l.value('sName[1]','varchar(30)') AS [value]   -- wartość wyświetlana
FROM @xmlRes.nodes('//ListOfContinentsByNameResult') r(n)
CROSS APPLY r.n.nodes('tContinent') lines(l)

Przykład 2

Zapytanie przetwarzające odpowiedź ze źródła REST API w celu wyświetlenia wartości na liście wyboru (wymagane skonfigurowanie źródła danych i akcji zapytania do webserwisu).

SELECT code AS [key],
  CONCAT(currency,' - ',mid,' PLN') AS [value]
FROM OPENJSON ({@_Response}, '$[0].rates')
  WITH (
    currency VARCHAR(200)
   ,code VARCHAR(200) 
   ,mid VARCHAR(200) 
   )
  AS JSON

|← Lista wyboru (SQL) |↑ Do góry |→ Obszar tekstowy (TextArea) |