Manorivile-Gateway diegimas

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

Reikalavimai kompiuteriui, kuriame bus diegama Manorivile-Gateway (naudojama JAVA 8 versija)

Turinys

Manorivile-Gateway diegimas

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)

    image-20200220163645418

    image-20200220163852088

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:

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).

Svarbu: failo pavadinimas turi būtinai sutapti su duomenų bazės vardu!

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ą:

    img

    Ir nustatyti TCP portą 1433:

    img

MS SQL Server vartotojo teisių nustatymai

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

img

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

img

img

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 SQL Anywhere versija ne OEM 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":

image-20200210140256494

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

image-20200210140505875

image-20200210140539457

4. Pasibandymas

Pasibandyti ar sistema veikia galite tiesiog iškviesti API užklausą per Postman ar kitą aplikaciją (reikalingas API raktas). pvz curl užklausa:

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":

clip_image007

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 SharePoint.

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

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":

image-20200210140256494

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

image-20200210140505875

image-20200210140539457

4. Pasibandymas

Pasibandyti ar sistema veikia galite tiesiog iškviesti API užklausą per Postman ar kitą aplikaciją (reikalingas API raktas). pvz curl užklausa:

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

rezultatas:

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

DUK

  • Jeigu prijungiama daugiau duomenų bazių- atitinkamai sukuriami dbxxx.properties konfigūraciniai failai su atitinkama prisijungimo prie DB informacija.

    Pastaba - kiekviena DB turi būti užregistuota MANORIVILE sistemoje.

  • Išdiegti komunikatorių tereikia paleisti remove.bat (run as administrator)

Pasitaikančios klaidos ir sprendimai

Manorivile-Gateway esant sėkingam prisijungimui ar klaidai yra galima pasitikrinti serviso būseną /log/manorivile-gateway.log faile

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.
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: "Unexpected rethrowing" Prisijungti prie senesnių MS SQL versijų naudojamas nepalaikomas algoritmas „3DES_EDE_CBC“. Direktorijoje, kurioje yra suinstaliuota Java (C:\Program Files\Java) susirasti java.security failą (\jre1.xx\lib\security arba \conf\security kataloge) ir tame faile ties eilute „jdk.tls.disabledAlgorithms=.......“ ištrinti algoritmą „3DES_EDE_CBC“
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, bandoma įdiegti į 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.

Veiksmų žurnalas (angl. log)

Manorivile-Gateway kataloge pakoreguojamas failas global.properties. Veiksmų rašymui į failą reikia įjungti parametrą: 

debug.enabled=true

APIv2 užklausų, rezultatų ir kiti pranešimai fiksuojami faile manorivile-gateway.txt, kuris standartiškai išsaugomas kataloge C:/Manorivile-Gateway/log

Po veiksmų nuskaitymo parametrą būtina atstatyti į darbinį režimą!

Atstatymas į darbinį režimą:

debug.enabled=false