Manorivile-Gateway diegimas

Manorivile-Gateway instaliuojamas kompiuteryje, kuris turi prieigą prie Rivile GAMA duomenų bazės. Aplikacija diegiama kaip Windows Service paketas.

Manorivile-Gateway diegimas

Reikalavimai kompiuteriui

• Operacinės sistemos reikalavimai https://www.java.com/en/download/help/sysreq.html
• Interneto prieiga prie adreso gateway.manorivile.lt porto 5671.
• Prieiga prie jūsų sukonfigūruoto SQL duomenų bazės porto. Duomenų bazės portas turi būti statinis.

Prieš pradedant

Prieš diegiant REST API v2 ryšio kanalą turite užsakyti REST API paslaugą ir gauti prisijungimo kodus, kurie bus reikalingi tolimesniems nustatymams. Sukuriant pirmąją jungtį reikalinga pateikti informaciją:

• Rivile GAMA programos valdytojo įmonės pavadinimas, įmonės kodas, e-mail

• Rivile GAMA įmonės identifikacijos nr (pvz: 01)

• Rivile GAMA įmonės bazinės valiutos kodas (pvz: EUR)

• Rivile GAMA duomenų bazės vardas (pvz: NAU_IMONE)

• DB: MSSQL ar SYBASE (pvz: MSSQL)

• Rivile GAMA WEB adresas (pvz: 55245597)

  

  

Diegimo instrukcija

1. Sudiegiamas komunikatorius (gateway)

1.1. Parsisiunčiama naujausia versija iš Rivile SharePoint.

Norint parsisiųsti naujausią ManoRivile-Gateway versiją, priklausomai nuo operacinės sistemos spauskite ant nuorodos:

• Jeigu operacinė sistema 32bit
• Jeigu operacinė sistema 64bit

ManoRivile-Gateway instaliacinių failų archyvas.

1.2. Išpakuojami failai į C:/Manorivile-Gateway katalogą

1.3. Sukonfigūruojamas prisijungimas prie ryšio kanalo gateway.manorivile.lt

išpakuotame kataloge pakoreguojamas failas global.properties su teksto redaktoriumi (pvz. Notepad). Įterpiami nustatymai gauti užsakant paslaugą, pvz.:

broker.username=*******
broker.password=**************************************

Nuo 1.2.0 Gateway versijos taip pat parenkama tinkama parametro response.returnStrings reikšmė (žemesnėse versijose šis parametras visada lygus false ir jo keisti negalima). Jeigu parametro reikšmė - true, visi JSON formatu grąžinamo atsakymo laukai yra string tipo.

Rekomenduojama šią reikšmę nustatyti į true, jeigu dirbama su JSON formato failais. Šis nustatymas padeda spręsti problemą, kai prekių, paslaugų, klientų grupių ir t.t. kodavimui naudojami skaičiai ir taškas.

response.returnStrings=true

Pavyzdys. Jeigu Rivile GAMA sistemoje yra du skirtingi prekių kodai – „301“ ir „301.“, parametro reikšmė response.returnStrings – false, JSON formatu gautame atsakyme prekių kodai bus automatiškai paversti į skaičių.

{
    "N17": [
        {
            "Row_number": 1,
            "N17_KODAS_PS": 310,
            ...
            "N17_PAV": "Arbata",
            ...
        },
        {
            "Row_number": 2,
            "N17_KODAS_PS": 310,
            ...
            "N17_PAV": "Arbata su vaisiais",
            ...
        }
    ]
}

Tuo atveju, kai parametro response.returnStringsreikšmė nustatotma true:

{
    "N17": [
        {
            "Row_number": "1",
            "N17_KODAS_PS": "310",
            ...
            "N17_PAV": "Arbata",
            ...
        },
        {
            "Row_number": "2",
            "N17_KODAS_PS": "310.",
            ...
            "N17_PAV": "Arbata su vaisiais",
            ...
        }
    ]
}

2. Nustatomas prisijungimas prie DB

Išpakuotame kataloge kiekvienai DB sukuriamas atskiras dbxxx.properties failas su prisijungimo informacija, kur dbxxx - atitinkamos SQL duomenų bazės vardas (pavyzdiniai nustatymus galima rasti gama_example.properties faile).

Priklausomai kokį DB serverio MS SQL ar SYBASE (SQL Anywhere) nustatymai detalizuoti žemiau:

2.1. Prisijungimas prie MS SQL DB

Sukurtame faile dbxxx.properties su teksto redaktoriumi (pvz. Notepad) nustatome prisijungimus:

• Jeigu jungiamasi prie DB "Windows authentification".

  db.url=jdbc:sqlserver://localhost:1433;databaseName=dbxxx;integratedSecurity=true;applicationName=ManoRivile

Svarbu atkreipti dėmesį, kad jungiantis šiuo metodu SQL Serveryje turi būti suteiktos teisės "ManoRivile-Gateway" servisui, kokiu vartotoju jis paleistas. Pagal nutylėjimą startuojamas kaip "Local system account", tuomet SQL'e turi būti suteiktos teisės "NT AUTHORITY\SYSTEM" vartotojui.

• Jeigu jungiamasi vartotoju ir slaptažodžiu

  db.url=jdbc:sqlserver://localhost:1433;databaseName=dbxxx;applicationName=ManoRivile
  db.username=sukurto_vartotojo_vardas
  db.password=sukurto_vartotojo_slaptažodis

• Jeigu reikalinga nurodyti SQL serverio instance, nutatymai atrodytų taip:

  db.url=jdbc:sqlserver://server1;instanceName=instance1;integratedSecurity=true;databaseName=dbxxx;applicationName=ManoRivile

MS SQL Server TCP/IP nustatymai

Įsitikinkite, kad MS SQL server yra sukonfigūruotas priimti užklausas per TCP/IP protokolą:

1. Sql Server Configuration Manager reikia įjungti TCP/IP protokolą:

   

   Ir nustatyti TCP portą 1433:

   

MS SQL Server vartotojo teisių nustatymai

SQL serveryje turi būti įjungta SQL autentifikacija (esant poreikiui jungtis vartotoju vardu):

Sukurtas arba esamas vartotojas turi būti su db owner teisėmis prie norimos duomenų bazės:

2.2. Prisijungimas prie SYBASE (SQL Anywhere)

Sukurtame faile dbxxx.properties su teksto redaktoriumi (pvz. Notepad) nustatome prisijungimus:

db.type=sybase
db.host=localhost
db.port=2638
db.db=dbxxx
db.username=username
db.password=password
db.connectionInitSQL=
db.timestampFormat=YYYY-MM-DD HH:NN:SS.SSS //Nuo 1.2.3 versijos. Parametras nėra privalomas.

• Jeigu naudojama ne OEM SQL Anywhere versija, eilutę db.connectionInitSQL= reikia ištrinti.
• Parametras db.timestampFormat= leidžia pakeisti datos formatą.

3. Paleidimas

Komunikatorius paleidžiamas kaip Windows Servisas

Paleidžiamas install.bat failas administratoriaus teisėmis "run as administrator":

Tuomet susikuria ir startuojasi naujas Windows Servisas "ManoRivile-Gateway":

4. Testavimas

Ar sistema veikia galite įsitikinti tiesiog kviesdami API užklausą per Postman ar kitą aplikaciją (reikalingas API raktas). curl užklausos pavyzdys:

curl --location --request GET 'https://api.manorivile.lt/client/ping' \
--header 'ApiKey: **************************************'

rezultatas:

{
    "message":"Sėkmingai prisijungta",
    "connectedSuccessfully":true
}

Manorivile-Gateway atnaujinimas

1. Išdiegiamas esamas komunikatorius

1.1. Paleidžiamas remove.bat failas administratoriaus teisėmis "run as administrator":

1.2. Iš katalogo C:/Manorivile-Gateway pašalinami visi failai išskyrus *.properties failus.

1.3. Katalogas C:/Manorivile-Gateway pervadinimas. Atnaujinus versiją šis failas galės bus ištrintas.

2. Įdiegiamas naujas komunikatorius

2.1. Parsisiunčiama naujausia versija iš Rivile saugyklos.

Norint parsisiųsti naujausią ManoRivile-Gateway versiją, priklausomai nuo operacinės sistemos spauskite ant nuorodos:

• Jeigu operacinė sistema 32bit
• Jeigu operacinė sistema 64bit

ManoRivile-Gateway instaliacinių failų archyvas.

2.2. Išpakuojami failai į C:/Manorivile-Gateway katalogą.

2.3. Iš senojo komunikatoriaus katalogo nukopijuojami visi *.properties failai, išskyrus queues.properties

3. Paleidimas

Komunikatorius paleidžiamas kaip Windows Servisas.

Paleidžiamas install.bat failas administratoriaus teisėmis "run as administrator":

Tuomet susikuria ir startuojasi naujas Windows Servisas "ManoRivile-Gateway":

4. Testavimas

Ar sistema veikia galite įsitikinti tiesiog kviesdami API užklausą per Postman ar kitą aplikaciją (reikalingas API raktas). curl užklausos pavyzdys:

curl --location --request GET 'https://api.manorivile.lt/client/ping' \
--header 'ApiKey: **************************************'

rezultatas:

{
    "message":"Sėkmingai prisijungta",
    "connectedSuccessfully":true
}

Pasitaikančios klaidos ir sprendimai

Daugelį klaidų Manorivile-Gateway rašo į failą log/manorivile-gateway.log.

Nr	Klaida	Problema / galimas sprendimas
1	nėra klaidos, bet neveikia API	a) Galimai blogai užvadintas duomenų bazės nustatymų failas dbxxx.properties - dbxxx turi būtinai sutapti su duomenų bazės pavadinimu b) Kai sudiegiate Manorivile-Gateway palaukite 5min, kol sistema sinchronizuosis c) API raktas neteisingas ar negaliojantis
2	ERROR Error for database dbxxx: JZ006: Caught IOException: java.net.ConnectException: Connection refused: connect	Blogai sukonfigūruotas prisijungimas prie SQL serverio arba duomenų bazės - patikrinkite dbxxx.properties failo nustatymus
3	ERROR Failed to initialize pool: Cannot open database "dbxxx" requested by the login. The login failed	Blogai sukonfigūruotas vartotojo prisijungimas prie DB arba nesuteiktos reikalingos teisės nustatytam vartotojui - patikrinkite dbxxx.properties failo nustatymus arba suteikite vartotojui reikalingas teises SQL serveryje
4	ERROR ACCESS_REFUSED - Login was refused using authentication mechanism PLAIN. For details see the broker logfile	a) Blogai nustatytas global.properties prisijungimo duomenys, sutikrinkite ir pataisykite prisijungimo duomenis pagal pateiktus iš Rivile. b) Nei viena DB nesužregistruota MANORIVILE posistemėje.
5	WARN Invalid length parameter passed to the RIGHT function.	Problema MS SQL duomenų bazėje, jeigu įjungtas procedūrų ir funkcijų replikavimas. Replikuojamose bazėse susikuria duomenų bazių trigeriai (Database triggers). Per Rivile API v2 kuriamos stored procedūros yra kriptuotos (WITH ENCRYPTION), todėl tiek jas kuriant tiek atnaujinant, trigerius reikia išjungti (disable). Pakeitimai turi būti daromi tik ant nereplikuojamų objektų. Atnaujinus procedūras trigerius reikia vėl įjungti. Problema MS SQL duomenų bazėje, jeigu įjungtas procedūrų ir funkcijų replikavimas. Per Rivile API v2 kuriamos stored procedūros, papildomos vidinės lentelės ir view‘ai, todėl tiek kuriant tiek atnaujinant, replikavimo trigerius reikia išjungti (disable): disable TRIGGER [MSmerge_tr_alterschemaonly] ON DATABASE disable TRIGGER [MSmerge_tr_altertable] ON DATABASE disable TRIGGER [MSmerge_tr_altertrigger] ON DATABASE disable TRIGGER [MSmerge_tr_alterview] ON DATABASE Atnaujinus procedūras trigerius reikia vėl įjungti: enable TRIGGER [MSmerge_tr_alterschemaonly] ON DATABASE enable TRIGGER [MSmerge_tr_altertable] ON DATABASE enable TRIGGER [MSmerge_tr_altertrigger] ON DATABASE enable TRIGGER [MSmerge_tr_alterview] ON DATABASE
6	WARN CREATE PROCEDURE permission denied in database 'dbxxx'.	Nustatytas SQL vartotojas neturi teisių kurti procedūras. Arba pakeiskite SQL vartotoją arba suteikite nustatytam vartotojui reikiams teises (db_owner)
7	ERROR The driver could not establish a secure connection to SQL Server by using Secure Sockets Layer (SSL) encryption. Error: "The server selected protocol version TLS10 is not accepted by client preferences [TLS13, TLS12]"	Jūsų naudojama MS SQL versija nepalaiko TLS 1.2 protokolo. Įdiekite naujausius jūsų MS SQL versijai taikomus atnaujinimus (angl. Service Pack bei Cumulative Update).
8	Entry Point Not Found: The procedure entry point K32EnumProcessModules could not be located in the dynamic link library KERNEL32.dll.	Operacinė sistema, kurioje bandote paleisti Manorivile-Gateway, yra nesuderinama su Rivile API v2, pavyzdžiui, Windows Server 2003. Suderinamų operacinių sistemų versijos nurodytos Java puslapyje.
9	SQL Anywhere Error -638: Right truncation of string data	API paduodamuose duomenyse yra perduodamas laukas, kuris yra ilgesnis nei leistinas. a) sutavrkyti duomenų perdavimą b) SQL Anywhere serveryje nustatyti “string_rtruncation OFF” (http://dcx.sybase.com/1200/en/dbadmin/string-rtruncation-option.html)
10	Java.sql.SQLException: JZ0SJ: Metadata accessor information was not found on this database. Please install the required tables as mentioned in the jConnect documentation.	Išjungti Sybase duomenų bazės Jconnect driver'iai. Reikia įjungti. Tai galima atlikti naudojant užklausą: "ALTER DATABASE Upgrade JCONNECT ON". Svarbu: tam, kad ši užklausa veiktų negali būti jokio prisijungimo (connection) prie duomenų bazės (naudojant SQL Anywhere central'ę galima atjungti visus vartotojus ir paleisti užklausą). Instaliuojant Sybase naujai yra galimybė pažymėti "Install jConnect drivers".
11	No response received from client gateway	„No response received from client gateway“ indikuoja, kad arba kliento pusėje buvo išsijungęs gateway, arba duomenų bazė neatsakė. Reiktų pažiūrėti ką tuo metu rodo gateway loguose kliento serveryje.
12	INSERT failed because the following SET options have incorrect settings: 'ARITHABORT'. Verify that SET options are correct for use with indexed views and/or indexes on computed columns and/or filtered indexes and/or query notifications and/or XML data type methods and/or spatial index operations.	Reikia pakelti MS SQL compatibility lygį iki 100.

Veiksmų žurnalas (angl. log)

Sprendžiant Rivile APIv2 problemas kartais prireikia detalesnės informacijos. Problemų sprendimui skirtą veiksmų žurnalą galite įjungti Manorivile-Gateway kataloge faile global.properties pakeitę parametrą:

debug.enabled=true

Po įjungimo API užklausos, jų rezultatai ir kiti pranešimai fiksuojami faile manorivile-gateway.log, kuris standartiškai išsaugomas Manorivile-Gateway log kataloge.

Detalaus veiksmų žurnalo išjungimas:

debug.enabled=false