Wprowadzenie
Usługę Business Integration Service (BIS) można wykorzystywać nie tylko interaktywnie za pośrednictwem aplikacji dialogowych, lecz także w sposób zautomatyzowany.
W przypadku zautomatyzowanego wykorzystania BIS konieczna jest częściowa znajomość interfejsów programistycznych tej usługi.
W niniejszym artykule opisano aplikacje działające w tle oraz zdarzenia w procesach workflow wraz z ich interfejsami, które są udostępniane przez BIS.
Interfejsy służące do zdalnego wywoływania BIS opisano w artykule Zdalne interfejsy BIS.
Grupa docelowa
- Programiści
- Konsultanci techniczni
Opis
Aplikacje działające w tle
Aplikacje działające w tle Import danych (nazwa techniczna: com.cisag.pgm.bi.Import)oraz Eksport danych (nazwa techniczna: com.cisag.pgm.bi.Export) mogą być wykorzystywane do wywoływania procesów importu lub eksportu danych z poziomu workflow lub konfigurowalnych aplikacji.
Obie aplikacje udostępniają interfejsy opisane poniżej.
Aplikacja importu
Parametry
Aplikacja w tle Import danych jest wywoływana z użyciem akcji IMPORT (wartość: 1) i akceptuje następujące parametry wywołania:
| Parametr | Opis |
| ImportFile (String) |
Plik źródłowy, z którego mają zostać zaimportowane dane. Należy podać pełną ścieżkę w formacie file:// lub kstore://. Jeśli plik ma rozszerzenie .gz, zostanie rozpoznany jako plik skompresowany w formacie GZIP i automatycznie zdekompresowany przy otwarciu. Zwracana wartość: przekazany parametr. |
| ContentType (String) |
Typ pliku. Dla:
Zwracana wartość: przekazany parametr. |
| DefaultLocale (String) |
Ustawienie języka i formatu liczb oraz dat. Pozostawienie pustej wartości powoduje użycie domyślnej lokalizacji odpowiedniej dla typu pliku. Dla:
Jeśli plik XML zawiera własne ustawienie lokalizacji, ma ono pierwszeństwo. Można użyć kodów językowych, np. de, en . |
| ParserProperties (CisParameterList) |
Dla plików XML i Unicode należy pozostawić pusty. Dla plików tekstowych można określić parametry formatu CSV pod kluczem com.cisag.pgm.bi.csv.CSVParser#CSV_FILE. Parametry CSV to ciąg znaków określający separator, znak tekstu i kodowanie. Domyślne wartości: przecinek, cudzysłów podwójny, standardowe kodowanie SAS. |
| ErrorFileMode (Valueset) |
Określa sposób tworzenia pliku błędów (com.cisag.pgm.bi.ImportErrorFileMode).
|
| ErrorFile (String) |
Plik używany do zapisu danych, które nie zostały zaimportowane. Należy podać pełną ścieżkę w formacie file:// lub kstore://. Należy pozostawić pusty, jeśli ErrorFileMode = Automatyczny lub włączone jest logowanie. Zwracana wartość: rzeczywiście użyty plik błędów (jeśli został zapisany). Jeśli jest pusty lub równy plikowi źródłowemu – plik błędów nie został utworzony. |
| ErrorFileNaming (Valueset) | Określa, czy plik błędów o nazwie już istniejącej ma być nadpisany, czy numerowany kolejno (com.cisag.pgm.bi.ImportErrorFileNaming). Domyślna opcja: Nadpisz. Należy pozostawić pusty, jeśli ErrorFileMode = Automatyczny lub logowanie jest aktywne. |
| WarningsMode (Valueset) |
Określa sposób obsługi ostrzeżeń podczas importu (com.cisag.pgm.bi.ImportWarningsMode):
|
| CorrectionMode (Valueset) |
Określa, czy błędne dane mają być korygowane w systemie:
|
| ObjectType (String) | Pełna techniczna nazwa obiektu biznesowego, który ma być eksportowany. Zwracana wartość: przekazany parametr. |
| Database (String) |
Baza danych, z której mają być eksportowane dane. Można użyć stałej aliasu bazy z interfejsu Java CisTransactionManager. Parametr: Opcjonalny. Domyślnie: aktywna baza OLTP sesji. Zwracana wartość: przekazany parametr. |
| FilterName (String) | Nazwa filtra, który ma być użyty przy eksporcie danych. Parametr: Opcjonalny. Domyślnie pusty (eksport wszystkich atrybutów modelu danych). |
| NLSMode (Valueset) |
Ustawienie języka dla importu bez określonego filtra (com.cisag.pgm.bi.model.ObjectInfoFilterNLSMode). Parametr: opcjonalny. Domyślna opcja: jednojęzyczny. Nie należy używać razem z parametrem FilterName. |
| DateTimeMode (Valueset) |
Format daty i czasu dla importu bez określonego filtra (com.cisag.pgm.bi.model.ObjectInfoFilterDateTimeMode). Parametr opcjonalny. Domyślnie: forma zwarta Nie należy używać razem z FilterName. |
| ProcessLogLevel (Valueset) |
Włącza lub wyłącza logowanie (com.cisag.pgm.bi.ProcessLogLevel).
|
Dodatkowe parametry zwrotne:
| Parametr | Opis |
| ImportedObjectCount (int) | Liczba zaimportowanych obiektów. |
| InvalidObjectCount (int) | Liczba obiektów błędnych. |
| NotCorrigibleObjectCount (int) | Liczba obiektów błędnych, których nie można skorygować w aplikacji korekcyjnej. Wartość jest również różna od zera, jeśli wystąpiły błędy parsera lub inne błędy. |
| ProcessUserGuid (GUID) | Identyfikator GUID użytkownika, dla którego zalogowano sesję procesu importu. |
| ProcessBegin (znacznik czasu) | Czas rozpoczęcia procesu importu. |
| ProcessEnd (znacznik czasu) | Czas zakończenia procesu importu. |
Przykładem mogą być kontrolery, które część instancji obiektów biznesowych importują poprawnie, a część oznaczają jako błędne.
Natomiast właściwości ilości wymienione w poniższej tabeli są zawsze poprawne.
Przegląd stanów wyników
Na podstawie parametrów zwracanych można określić, z jakim wynikiem zakończył się proces importu:
| Opis | Wartości zwracane / Warunki |
| Sukces. Wszystkie instancje z pliku źródłowego zostały poprawnie zaimportowane. |
|
| Błąd. W pliku źródłowym nie znaleziono żadnej instancji pasującej do procesu importu. Brak pliku błędów. | ImportedObjectCount = 0InvalidObjectCount = 0NotCorrigibleObjectCount = 0 |
| Błąd. Wszystkie błędne instancje są możliwe do skorygowania i zostały zapisane w pliku błędów. Plik źródłowy został w pełni odczytany. | InvalidObjectCount > 0NotCorrigibleObjectCount = 0ErrorFile ≠ ImportFile |
| Błąd. Wystąpił co najmniej jeden niekorygowalny błąd podczas importu lub import został przerwany (np. plik źródłowy nie znaleziony, błąd odczytu, błąd parsera itd.). Możliwy brak pełnego odczytu pliku źródłowego. Z plikiem błędów lub bez. |
|
| Błąd. Aplikacja została przerwana z powodu błędnych parametrów. Brak pliku błędów. Zdarzenie workflow nie zostało wywołane. | Lista parametrów zwracanych = null |
Można rozpoznać wystąpienie jednego z przypadków błędu po wywołaniu z poziomu aplikacji dostosowanej po tym, że metoda CisProgramMessageQueue.requiresAttention() po wywołaniu aplikacji działającej w tle zwraca wartość true.
Eksport aplikacji
Parametry
Aplikacja w tle Eksport danych jest uruchamiana za pomocą akcji EXPORT (wartość 1) i akceptuje następujące parametry wywołania:
| Parametr | Opis |
| ExportFile (String) | Plik, do którego mają zostać wyeksportowane dane. Istniejący plik docelowy zostanie nadpisany. To, czy dodatkowo utworzone pliki (np. zawartość atrybutów BLOB) zostaną nadpisane, zależy od kontrolera. Jeśli nie znaleziono żadnej instancji do eksportu, plik nie zostanie utworzony. Należy podać pełną ścieżkę w formacie file:// lub kstore:// Jeśli plik ma rozszerzenie .gz, zostanie rozpoznany jako plik skompresowany w formacie GZIP i automatycznie skompresowany podczas tworzenia. |
| ContentType (String) | Typ pliku. Dla:
|
| Locale (String) |
Ustawienie języka i formatu liczb oraz dat. Parametr opcjonalny. Pozostawienie pustego pola powoduje użycie domyślnej lokalizacji dla danego typu pliku. Dla:
Można użyć kodów językowych, np. de, en. |
| BuilderProperties (CisParameterList) | Dla plików XML i Unicode należy pozostawić pusty. Dla plików tekstowych można określić parametry formatu CSV pod kluczem com.cisag.pgm.bi.csv.CSVParser#CSV_FILE. Parametry CSV to ciąg znaków określający separator, znak tekstu i kodowanie. Domyślne wartości: przecinek, cudzysłów podwójny, standardowe kodowanie SAS. |
| ObjectType (String) | Pełna techniczna nazwa obiektu biznesowego, który ma zostać wyeksportowany. |
| Database (String) | Baza danych, z której mają zostać wyeksportowane dane. Można podać stałą aliasu bazy danych z interfejsu Java CisTransactionManager. Parametr opcjonalny. Domyślnie używana jest aktywna baza OLTP sesji. |
| FilterName (String) | Filtr używany do eksportu danych. Należy podać nazwę filtra. Parametr opcjonalny. Domyślnie eksport obejmuje wszystkie atrybuty modelu danych. |
| NLSMode (Valueset) |
Ustawienie języka dla importu bez określonego filtra (com.cisag.pgm.bi.model.ObjectInfoFilterNLSMode). Domyślna opcja: jednojęzyczny. Nie należy używać razem z parametrem FilterName. |
| DateTimeMode (Valueset) | Format daty i czasu dla importu bez określonego filtra (com.cisag.pgm.bi.model.ObjectInfoFilterDateTimeMode). Parametr opcjonalny. Domyślnie: forma zwarta Nie należy używać razem z FilterName. |
| SearchName (String) |
Ograniczenie zakresu eksportowanych instancji za pomocą wyszukiwania OQL lub polecenia OQL.
|
| SearchParameters (CisParameterList) | Parametry wyszukiwania dla ograniczenia eksportu przy użyciu OQL. Parametr opcjonalny. Domyślnie brak parametrów. Każdy element listy zawiera nazwę pola wyszukiwania i odpowiadający mu ciąg selekcji (Selection String). Dostępne formaty zależą od typu danych pola i są opisane w sekcji Format dla ciągów selekcji. Nie stosuje się przy użyciu instrukcji OQL. |
| SearchSortOrder (String) | Kolejność sortowania eksportowanych instancji w przypadku wyszukiwania OQL. Parametr opcjonalny. Domyślnie używana jest standardowa kolejność zdefiniowana w wyszukiwaniu OQL. Składnia sortowania opisana w sekcji Format sortowania. Nie stosuje się przy użyciu instrukcji OQL. |
| SearchContextOrganizationGuid (GUID) | Identyfikator GUID organizacji, dla której wykonywany jest eksport. Parametr opcjonalny. Domyślnie: organizacja powiązana z bieżącą sesją. Parametr należy ustawić jawnie, jeśli aplikacja tła jest używana w definicji aktywności workflow lub wywoływana z aplikacji dostosowanej w ramach zadania przetwarzania. |
| ProcessLogLevel (Valueset) | Włącza lub wyłącza logowanie (com.cisag.pgm.bi.ProcessLogLevel).
|
Aplikacja posiada następujący parametr zwracany:
| Parametr | Znaczenie |
|---|---|
| ExportedObjectCount (int) | Liczba wyeksportowanych instancji. Jeśli ta liczba wynosi 0, plik nie został utworzony. Jeśli w takim przypadku plik istnieje pod wskazanym adresem URI pliku docelowego, nie pochodzi on z bieżącego procesu eksportu. |
Format dla ciągów selekcji
W poniższej tabeli przedstawiono, jaka składnia ciągów selekcji (Selection-Strings) jest używana dla obsługiwanych typów danych pól wyszukiwania w zapytaniu OQL.
| Typ danych | Składnia ciągu selekcji (Selection-String-Syntax) |
| boolean | „true“ „false“ „“ |
| Valueset | Rosnąco posortowana lista wybranych identyfikatorów wartości zestawu (Valueset IDs, wartości typu short). Przykład: 1, 2, 4 |
| GUID | Ciąg szesnastkowy dla każdej wartości GUID; wiele GUID-ów oddzielonych przecinkiem i spacją. |
| Liczby | Wiele wartości oddzielonych przecinkiem i spacją. Przykład: 2, > 3, 3 -, < 3, – 3, 4 – 9 |
| String |
W ciągach tekstowych można używać symboli wieloznacznych:
Wiele takich wartości należy oddzielać przecinkiem i spacją. Przykład: abc, de*, a*c |
| Znacznik czasu / CisDate | Wartość całkowita (Long) reprezentująca znacznik czasu w milisekundach od 01.01.1970 GMT, zapisana jako ciąg dziesiętny. Dopuszczalne są również zakresy, np. liczba – liczba, – liczba, liczba –. |
Przed i po tym znaku musi znajdować się spacja, aby można go było odróżnić od znaku minus używanego przy liczbach ujemnych.
Format sortowania
Sortowanie składa się z kryteriów sortowania, które są oddzielone przecinkiem i spacją. Kryteria te podawane są w kolejności, w jakiej ma zostać wykonane sortowanie.
Każde kryterium sortowania składa się z:
-
nazwy pola w zapytaniu OQL,
-
po niej spacji,
-
a następnie kierunku sortowania:
- ASC (rosnąco)
- DESC (malejąco)
Przykład sortowania z dwoma kryteriami:
name ASC, itemNumber DESC
Przykłady (Workflow)
Aby wykonać import lub eksport w ramach aktywności workflow, należy wywołać aplikacje działające w tle w definicji aktywności workflow.
Przykładami takich definicji aktywności są cis.bis.AutomaticImport oraz cis.bis.AutomaticExport, które są dostarczane wraz z systemem i są automatycznie dostępne na każdym systemie.
Zdarzenia Workflow
Zdarzenie ImportRunCompleted
Zdarzenie com.cisag.pgm.bi.ImportRunCompleted jest wywoływane po każdym zakończonym imporcie danych — niezależnie od tego, czy podczas importu wystąpił błąd, czy nie.
Za pomocą definicji aktywności można określić, jakie działania mają zostać wykonane po wystąpieniu tego zdarzenia.
Zdarzenie jest również wywoływane niezależnie od tego, czy korekta błędów importu została zlecona poprzez workflow, czy też nie. Dzięki temu w definicji aktywności można określić, w jakich przypadkach mają być wysyłane powiadomienia.
Zdarzenie jest także wywoływane niezależnie od kanału, przez który został przeprowadzony proces importu.
Parametry
Zdarzenie posiada następujące parametry, które można wykorzystać w definicji aktywności:
| Nazwa parametru | Znaczenie |
| ObjectType | Nazwa obiektu biznesowego (Business Entity), dla którego zaimportowano dane. |
| ProcessRunType |
Typ operacji wymiany danych, dla której wywołano zdarzenie workflow.
Jeśli używana jest funkcja logowania BIS, ten parametr pozwala rozróżnić, czy zdarzenie zostało wywołane w ramach korekty. |
| ProcessLogLevel |
Określa, czy podczas importu danych logowanie było włączone.
|
| ImportFile | Plik, który został zaimportowany. Parametr ten należy stosować jedynie w razie potrzeby. Jeśli zwracana jest nazwa pliku w formacie file://, może się zdarzyć, że plik nie będzie dostępny z każdego serwera aplikacyjnego pod tą samą ścieżką. Nazwa pliku błędów ma domyślnie takie samo schema URI jak plik źródłowy. Plik może być tymczasowy — może nie istnieć w momencie analizy parametru lub mieć inny zawartość. W przypadku importu przez zdalne interfejsy wartość może być pusta. |
| ErrorFile | Plik błędów, jeśli został utworzony. Parametr ten należy stosować jedynie w razie potrzeby. Jeśli nie utworzono pliku błędów, a mimo to wystąpiły błędy, parametr zawiera nazwę pliku źródłowego. Jeśli zwracana jest nazwa pliku w formacie file://, plik może być niedostępny z każdego serwera aplikacyjnego pod tą nazwą. Plik może być tymczasowy i nie istnieć lub mieć inną zawartość w momencie odczytu. Wartość może być pusta przy imporcie z włączonym logowaniem lub przy imporcie przez zdalne interfejsy. |
| CorrectionMode |
Ustawienie trybu korekty danych podczas importu. Możliwe wartości:
|
| ImportedObjectCount | Liczba zaimportowanych instancji obiektów biznesowych. |
| InvalidObjectCount | Liczba niezaimportowanych instancji obiektów biznesowych, niezależnie od tego, czy mogą zostać skorygowane w aplikacji korekcyjnej. Wartość różna od 0 oznacza, że wystąpiły błędy i liczba błędnych instancji jest znana. |
| NotCorrigibleCount | Liczba niezaimportowanych instancji obiektów biznesowych, których nie można skorygować w aplikacji korekty. Wartość różna od 0 oznacza również, że wystąpiły błędy, przy czym liczba błędnych instancji nie jest znana (np. przy przerwanych importach lub błędach składniowych w pliku źródłowym). |
| ProcessUserGuid | Identyfikator GUID użytkownika, dla którego wykonano import danych. |
| ProcessBegin | Moment rozpoczęcia procesu importu danych. |
| ProcessEnd | Moment zakończenia procesu importu danych. |
| Parameters | Parametry wymagane do otwarcia aplikacji Import danych lub Procesy wymiany danych. Wartość tego parametru musi zostać przekazana w definicji aktywności do aplikacji Import danych. |
W definicji aktywności można używać parametrów w następujący sposób:
- Błąd importu można rozpoznać po tym, że co najmniej jeden z parametrów InvalidObjectCount lub NotCorrigibleCount ma wartość różną od 0.
- Obecność pliku błędów w przypadku błędu importu można stwierdzić po tym, że parametr ErrorFile zawiera wartość.
- Jeśli powiadomienia mają być wysyłane tylko dla procesów importu, w których korekta danych przez workflow została wyraźnie zlecona, należy w definicji aktywności ustawić warunek, że parametr CorrectionMode ma wartość 2.
- Aby przekazać zadanie workflow użytkownikowi, dla którego wykonano proces importu, należy w definicji aktywności wpisać parametr ProcessUserGuid jako osobę przypisaną do zadania.
- Aby z otrzymanego zadania workflow w obszarze nawigacji można było otworzyć aplikację Import danych, należy postępować zgodnie z przykładem dostarczonej definicji aktywności.
Przykład
Jako przykłady definicji aktywności dla zdarzenia com.cisag.pgm.bi.ImportRunCompleted dostarczane są następujące definicje aktywności:
- bis.ImportCompleted – w przypadku błędnych importów uruchomionych bez logowania, użytkownik, który rozpoczął import, otrzymuje zadanie workflow.
Po otwarciu tego zadania użytkownik zostaje automatycznie przeniesiony do aplikacji Import danych. - bis.ImportCompleted2 – w przypadku błędnych importów uruchomionych z włączonym logowaniem, użytkownik, który rozpoczął import, otrzymuje zadanie workflow. Po otwarciu tego zadania użytkownik zostaje automatycznie przeniesiony do aplikacji Rejestry protokołów wymiany danych.
