ApiAutomator

ApiAutomator to narzędzie administratora  systemu ERP XL. Program obsługuje wszystkie udostępnione funkcje API, wywołuje je na podstawie danych zwracanych przez Serwer SQL. Pozwala więc na sterowanie systemem z poziomu zapytań SQL.

AA eliminuje konieczność niskopoziomowego programowania i pozwala administratorom na szybkie prototypownie i wdrażanie nowych rozwiązań funkcjonalnych. Do typowych zastosowań wystarczy podstawowa znajomość SQL i umiejętność dostosowania procedury danych przekazującej dane do bezobsługowego przetwarzania wsadowego. Bardziej zaawansowane rozwiązania, takie jak:

• integracja danych z innymi systemami,
• wsadowe przekształcanie dokumentów,
• benchmark wydajności,
• czy symulacja pracy operatora – w tle
• …

są realizowane z wykorzystaniem 2 lub 3 procedur sterujących, których zastosowanie zaprezentujemy w kolejnych przykładach.

Szybki start

W kolejnych krokach przydatna będzie baza danych, która nie jest całkiem pusta i zawiera logiczne informacje o kontrahentach, towarach, magazynach, transakcjach, rozliczeniach, księgowaniach itp., dlatego na początku ApiAutomator możemy wykorzystać do szybkiego stworzenia fikcyjnych – losowych zamówień ZZ.

Krok 1: procedura sql

Procedura postępowania w tym przypadku to symulacja pracy operatora, który wykonuje poniższe funkcje API w kolejności:

1. XLNowyDokumentZam – utworzenie nowego dokumentu zamówienia
2. XLDodajPozycjeZam – dodanie towaru – pozycji zamówienia
3. XLDodajPozycjeZam – dodanie towaru – pozycji zamówienia
4. XLZamknijDokumentZam – zamknięcie zamówienia

Wskazane funkcje wymagają podania odpowiednich parametrów, za przekazanie tych informacji odpowiada Procedura Danych. To nie jest konieczne, ale zanim ją stworzymy warto jest utworzyć osobny schemat dla ApiAutomatora, aby później łatwiej zarządzać jego procedurami:

create schema [aa];

Teraz tworzymy naszą procedurę aa.TestoweZZDane :

create procedure [aa].[TestoweZZDane] @Gid int = 0
as
begin

declare @MagNr int; -- losowy magazyn - zmienna
declare @KliNr int; -- losowy klient - zmienna

select	top 1 @MagNr=mag_gidnumer from cdn.magazyny order by newid();-- losowy magazyn
select	top 1 @KliNr=knt_gidnumer from cdn.kntkarty order by newid();-- losowy magazyn

	-- **************** nagłówek ****************	
select
	top 1
	'XLNowyDokumentZam' as _komenda, /* _komenda API którą trzeba wywołać */
	5 as Typ, -- 5 ZZ, 6 ZS ...
	knt_gidtyp as KntTyp,
	knt_gidnumer as KntNumer,
	mag_kod as Magazyn
from
	cdn.kntkarty
inner join -- połączenie z magazynem, ale bez relacji, tylko pobieramy kod potrzebny dla funkxji XLDodajPozycjeZam
	cdn.magazyny 
on
	knt_gidnumer=@KliNr and
	mag_gidnumer=@MagNr
	
	-- **************** pozycje ****************
select
	top 2
	'XLDodajPozycjeZam' as _komenda, /* _komenda API którą trzeba wywołać */
	format(abs(checksum(newid()) % 240) + 12,'G','pl-PL') as Ilosc, /* ilość w formacie tekstowym np. 1.52 */
	format(TwC_Wartosc,'G','pl-PL') as CenaOferowana, /* centa jako tekst - wymagane przez API */
	twr_gidtyp as TwrTyp,
	twr_gidnumer as TwrNumer
from
	cdn.twrkarty 
inner join
	cdn.twrceny
on
	TwC_TwrNumer = Twr_GIDNumer
where
	twc_twrlp=1 and
	twc_wartosc > 0 -- pobieraj tylko tewary, które mają przypisaną cenę
order by
	newid()

	-- **************** zamknięcie ****************
select
	'XLZamknijDokumentZam' as _komenda, /* _komenda API którą trzeba wywołać */
	2 as TrybZamkniecia -- 0 zamknięcie, 1 usunięcie, 2 potwierdzenie ...
end

Aby sprawdzić efekt działania procedury wystarczy wykonać z poziomu Sql Managera komendę:

exec aa.RandomZZData;

Efektem jej działania będzie zestaw 3 recordsetów, dających łącznie ciąg poleceń dla AA. Wykonanie tych poleceń spowoduje powstanie odpowiedniego zamówienia ZZ w systemie.

Po przygotowaniu procedury danych, należy uruchomić program ApiAutomator z parametrami, które wskażą na procedurę jaka ma być wywołana.

Krok 2: uruchomienie programu

Niezbędne informacje jakie trzeba przekazać do AA aby uruchomił przetwarzanie właściwej procedury to:

• nazwa bazy danych – wybierana przy logowaniu do systemu (tutaj 3lance)
• login do systemu – (ADMIN)
• hasło do systemu – tu brak
• nazwa bazy SQL („DRIVER={SQL Server};Server=cdnsrv\ex14;Database=ERPXL_3lance”)
• użytkownik SQL (sa)
• hasło do bazy SQL (aaaaaa)
• nazwa procedury danych (aa.TestoweZZDane)

aa.exe -z=n:1,aa.TestoweZZDane -u=sa -p=aaaaaa -l=ADMIN -c=3lance -n="DRIVER={SQL Server};Server=cdnsrv\ex14;Database=ERPXL_3lance"

Wynikiem wykonania tej komendy z linii poleceń jest stworzenie nowego dokumentu ZZ w systemie.
Więcej i bardziej rozbudowane przypadki zastosowań znajdziecie na forum https://cdn.3lance.pl/.

Procedury sterujące

ApiAutomator jest sterowany przez procedury SQL, są trzy rodzaje procedur, każdy z nich pełni inne zadanie:

• Procedura Danych – obowiązkowa – to lista czynności wraz z danymi jakie należy wykonać w systemie.
• Procedura Kolejki – opcjonalna – służy do rozdzielenia jednego procesu na niezależne podprocesy – wykonywane równolegle lub kolejności.
• Procedura Statusu – opcjonalna – służy do sterowania przebiegiem programu, obsługi błędów, logowania postępów i analizy wydajności.

Procedura Danych

Program wymaga do pracy co najmniej jednej procedury, zwracającej instrukcje sterowania. Procedura danych powinna zwracać jeden lub więcej recordset’ów z danymi zawierającymi nazwy funkcji API i dane do wykonania tych funkcji. Lista komend zwracanych przez tę procedurę, nie musi ograniczać się do jednego obiektu czy dokumentu, może przy jednym wywołaniu przekazać dane do wykonania wielu różnych operacji na obiektach ERP XL.

Definicja zwracanych danych

Wynik działania procedury danych jest przetwarzany przez AA w kolejności w jakiej jest generowany, czyli najpierw pierwszy recordset, a w nim pierwszy rekord, potem kolejne rekordy, a jeśli istnieją, to kolejne recordsety.

kolumny Procedury Danych

Kolumna	Stan	Rola
_komenda	obowiązkowa	wskazuje która funkcja API ma być uruchomiona, pole tekstowe, np XLNowyDokument, XLZamknijDokument, XLDodajVAT … jedna z 219 funkcji opisanych w dokumentacji API
_status	opcjonalna	nazwa i parametry wywołania dla Procedury Statusu
_log	opcjonalna	Tekst, który pojawi się w logu tekstowym tworzonym przez program, w wierszu podsumowującym efekty funkcji API. Może zawierać pola ze struktur API, które czasem są uzupełniane przez funkcje. Np. przy wywołaniu funkcji XLDodajPozycjeZam API uzupełnia pole tekstowe Towar, które można wyświetlić wprowadzając tu: {Towar}
[Pole] [Pole] [Pole] …	opcjonalna/ obowiązkowa	Kolejne pola ze struktury API z dokumentacji, ich opcjonalność lub obowiązkowość jest zdefiniowana w dokumentacji API. Należy pamiętać, że API obsługuje tylko 2 rodzaje danych – liczbowa LONG i tekstowa CSTRING. W takim formacie jak w dokumentacji należy przekazać dane, czyli np. zamienić wartości cen na Varchar()

Przykład procedury

Dla każdej funkcji API dokumentacja definiuje tzw. Parametry obowiązkowe, czyli np. dla funkcji:
XLNowyTowar(Sesja AS LONG, IDTowaru AS LONG, TowarInfo As XLTowarInfo) AS LONG
mamy parametry:

• Wersja
• Typ
• Kod
• Nazwa
• Jm

Oczywiście pełna struktura zawiera wiele więcej informacji, ale te powyższe wystarczą by założyć kartotekę.
Tworzymy prosty select zwracający w kolumnach wskazane pola (kolumnę Wersja pomijamy, jest wypełniana automatycznie przez AA):

select 1 as Typ, 'NOWYTOWAR1' as Kod, 'Nazwa nowego towaru' as Nazwa, 'szt' as Jm

Dodajemy kolumnę z komendą API – XLNowyTowar:

select 'XLNowyTowar' as _komenda, 1 as Typ, 'NOWYTOWAR1' as Kod, 'Nazwa nowego towaru' as Nazwa, 'szt' as Jm

i mamy dane niezbędne do utworzenia nowej kartoteki towaru przez API, teraz wystarczy „opakować” ten select w proceduę (CREATE PROCEDURE) by móc wywołać ją z poziomu ApiAutomatora.

Procedura Kolejki

Zadaniem procedury kolejki jest poprawa wydajności pracy, którą uzyskujemy przez rozbicie zadań AA na mniejsze elementy i umożliwienie pracy konkurencyjnej kilku instancji programu jednocześnie. Procedura kolejki sprawia również, że AA wykorzystuje licencję ERP XL tylko w sytuacji gdy ma jakieś zadania do przetworzenia. W sytuacji gdy w danej chwili żadna licencja nie jest dostępna ApiAutomator może czekać na zwolnienie się licencji i wtedy automatycznie będzie kontynuował przetwarzanie.
Procedura kolejki przekazuje odpowiedni numer GID danych, który program wykorzysta do pobrania instrukcji z procedury danych. Procedura może blokować wybrany GID, tak by nie dopuścić do przetwarzania tych samych dych przez wiele sesji ApiAutomatora.

kolumny Procedury Kolejki

Kolumna	Stan	Rola
gid	obowiązkowa	podaje numer kolejny, który posłuży do wywołania procedury danych z tym numerem
procedura	obowiązkowa	nazwa procedury danych, która ma być wywołana z parametrem @gid

Procedura Statusu – callback

Procedura spełnia dwie funkcje, zapisuje efekty działania funkcji API, decyduje też o dalszych krokach jakie podejmie program po wykonaniu każdej funkcji. Jest więc interfejsem zwrotnym przekazującym serwerowi SQL informacje o wyniku wykonania żądanej funkcji.

kolumny Procedury Statusu

Kolumna	Stan	Rola
decyzja	opcjonalna	Decyduje o dalszych krokach podejmowanych przez ApiAutomator, może być uzależniona do parametru @Res zwracanego przez funkcję API (czyli nr błędu).

ApiAutomator rozpoznaje następujące decyzje:

• [Continue] – kontynuacja przetwarzania (domyślna decyzja)
• [Repeat] – powtórzenie ostatniej operacji
• [NextGid] – przejście do następnej pozycji kolejki
• [Logout] – wylogowanie z systemu, ponowne zalogowanie jeśli są kolejne pozycje do przetworzenia
• [Exit] – wylogowanie i wyjście niezależnie od tego czy są kolejne pozycje

Parametry wywoływane standardowo jako argumenty procedury:

• @res – wynik wywołania funkcji API – int – zazwyczaj = 0 – inny nr oznacza błąd
• @flagi – flagi zwracane przez funkcję API – int – j.w. – zazwyczaj = 0 – inny nr oznacza ostrzeżenie
• @czas – czas wykonania fukcji w milisekundach – int
• @komenda – nazwa wywołanej funkcji API – varchar(40)
• @proba – numer próby (przydatne gdy z powodu błędów daną funkcję chcemy powtórzyć) – int
• @Sesja – numer sesji ERP XL – int
• @opis – dodatkowe informacje tekstowe ze środowiska uruchomieniowego (nazwa koputera, użytkownik)
• @login – login CDN

Nazwę Procedury Statusu przekazujemy do AA w Procedurze Danych w kolumnie _status. AA wywołuje ją z zadanymi parametrami po wykonaniu każdej funkcji API, dla której tę kolumnę zdefiniowano.

Sterowanie programem z linii poleceń

Po uruchomieniu programu z opcją –help, uzyskamy następujący ekran pomocy:
Poszczególne elementy oznaczają:

E:\CDN>aa --help
Usage: aa [options]
ApiAutomator - mechanizm automatyzacji pracy ERP XL
przykład użycia:
c:\aa.exe -z=p:dbo.GetGid -u dbo -p pass -l ADMIN -w PASS -c CDN_XL

Options:
  -?, -h, --help                           Displays this help.
  -s, --symulacja                          Symulacja działania, bez
                                           uruchamiania API
                                           program pokazuje czynności jakie
                                           wykona należy pamiętać, że w tym
                                           trybie także uruchamia procedury SQL
  -v, --wersja                             Pokazuje informację o wersji
  -z, --zrodlo <parametry>                 Dane sterujące do pobrania, moze
                                           przybrac wartosci
                                           n:[nr],[procedura danych]... gid i
                                           PROCEDURA DANYCH po przecinku
                                           p:[procedura kolejki] PROCEDURA
                                           KOLEJKI - zwracajaca kolumne gid
                                           x:[plik xml] ~nieaktywne~ nazwa pliku
                                           xml zawierającyego komendy API
  --logFile <plik>                         plik logu
  --logInfo <parametry>                    parametry logowania programu
  -u, --dbUser <login>                     nazwa użytkownika bazy danych
  -p, --dbPass <pass>                      hasło użytkownika bazy danych
  -n, --dbString <odbc Connection String>  połączenie danych ODBC
  -l, --cdnLogin <login>                   użytkownik cdn
  -w, --cdnPass <password>                 hasło cdn
  -c, --cdnName <baza>                     baza cdn

Program przyjmuje pewne wartości domyślne, wyświetla je przy starcie przetwarzania.

Praca z Logami

Czasem zachodzi potrzeba znalezienia przyczyny jakiegoś problemu z bazą lub API, w tym celu AA udostępnia kilka metod logowania efektów swojej pracy. Logi są generowane automatycznie i mogą być:

• wyświetlane w konsoli
• zapisywane do pliku
• zapisywane w bazie danych – z wykorzystaniem Procedury Statusu

Program rozpoznaje kilka kategorii logowanych informacji, są to:

• api.func – informacje związane z wykonywaniem funkcji API
• api.strk – informacje o strukturze danych przekazywanych do API
• prc.func – informacje sterujące głównego procesu AA
• sql.conn – informacje o połączeniu z bazą danyuch MsSQL
• sql.quer – informacje związane z zapytaniami wysyłanymi na serwer
• sql.resp – dane zwracane przez serwer

Każda kategoria może zwracać informację o różnym poziomie szczegółowości:

• debug najwięcej szczegółów
• info informacje podstawowe
• warning gdy pojawi się problem, np. funkcja API zwróci kod błędu
• critical gdy pojawi się problem i nie można kontynuować

Na podstawie powyższych informacji, można wybrać jakie informacje nas interesują i przekazać je do AA za pomocą parametru --loginInfo. Konstrukcja może zawierać znak gwiazdki „*” oznaczający dowolną kategorię lub typ informacji, natomiast średnik „;” oddziela kolejne kryteria. Przykłady:

--logInfo="*.*=false"

wyłączenie wszystkich komunikatów

--logInfo="*.*=true"

włączenie wszystkich komunikatów

--logInfo="*.debug=false;api.strk.debug=true"

wyłączenie wszystkich szczegółowych komunikatów, włączenie komunikatów szczegółowych o strukturze danych API

--logInfo="*.debug=false;*.info=true"

wyłączenie wszystkich szczegółowych komunikatów, włączenie komunikatów informacyjnych

Konsola

Poniższy przykład pokazuje informacje generowane przez program przy wystawianiu Zamówienia Zakupu z procedury aa.TestoweZZDane:

Pliki

Nazwę pliku log podajemy w parametrze --logFile przy wywołaniu AA. Program stworzy wtedy plik o nazwie podanej w parametrze dodając sufix w postaci daty, tak, że codziennie tworzy się osobny log, nie nadpisując logów z dnia poprzedniego. Dodatkowo, jeśli w trakcie pracy pojawi się błąd, powstaje jeszcze jeden plik – również z datą, ale też z kolejnym sufixem „err”, co przydaje się w sytuacji gdy chcemy szybko zweryfikować, czy po jakimś okresie pojawiły się błędy przetwarzania.

Wersje API

Wraz z kolejnymi wersjami systemu ERP XL zmieniają się funkcjonalności i struktury danych, kolejne wersje systemu definiują kolejne wersje API. ApiAutomator jest przypisany do konkretnej wersji jednak obsługa wersjonowania pozwala mu bezbłędnie działać na wersjach wyższych, tzn. że ApiAutomator z wbudowaną obsługą API 20160 poprawnie będzie wystawiał dokumenty w systemie w wersji 2018.5. Natomiast nie ma możliwości by AA działał poprawnie na wersjach niższych niż wbudowana.
Wersję wbudowanego API można podejrzeć wydając komendę:

aa.exe --wersja

Jeśli konieczne jest by ApiAutomator obsługiwał jakąś konkretną wersję, to proszę to zgłosić przez formularz kontaktowy.