Indice articolo

In questo articolo vedremo quali sono i passi da compiere per installare uno Sme.UP Provider e come risolvere i problemi più comuni.

Ci concentreremo sull’ultima versione Roma REV.1 e daremo per assodato i requisiti necessari al funzionamento. Maggiori dettagli si trovano qui.

In qualche caso utilizzeremo l’abbreviazione provider invece di Sme.UP Provider .

Premessa

Sme.UP Provider è un’estensione del server applicativo AS400, in quanto svolge funzionalità applicative che non può svolgere il server AS400.

Per questo motivo, è necessario avere un’anagrafica dei provider con indicato:

  • il  server dove è installato
  • i parametri di connessione al server AS400
  • la versione
  • le funzionalità applicative assolte.
  • eventuali risorse utilizzate ( es. a quali server windows deve accedere)
  • gli orari di avvio e spegnimento del provider.
  • gli orari di avvio e spegnimento del server AS400

Queste informazioni banali, risultano però importanti quando si deve aggiornare un provider o quando un provider smette di funzionare improvvisamente.

Qualche concetto

Il provider nasce come applicazione interattiva. Successivamente è stato possibile installarla anche come servizio. In realtà il provider non ha due modalità di installazione ma ha due modalità di funzionamento: o come applicazione interattiva o come servizio.

Queste due modalità prevedono la stessa installazione di base (setup + upgrade). Si differenziano per la modalità di configurare l’avvio.

La modalità interattiva prevede l’utilizzo di bat, quella come servizio si appoggia ad un programma di terze parti (wrapper.exe).

Il wrapper viene installato come servizo e legge dal file wrapper.conf i parametri di avvio del provider.

NOTA: Il wrapper non è il provider: il wrapper è il lanciatore del provider, se il provider non si avvia correttamente è possibile che il wrapper rimanga attivo ma che il provider non stia funzionando correttamente.

Per verificare che il provider sia attivo e risponda correttamente è necessario interrogarlo tramite la pagina di debug e (se disponibile) tramite la scheda dell’oggetto V3 LSE.

Requisiti di base

Il provider può essere installato su server con versione  Windows Server 2008 e successive. Sono però emersi dei problemi di accesso a file in rete, legati a specifiche versioni, pertanto si consiglia l’installazione su  Windows Server 2012 o successivi.

Tralasciamo Windows Server 2003 in quanto non possibile installare Sme.UP Provider come servizio e Microsoft ha dismesso il supporto.

Passi della prima installazione

Completata l’installazione (setup + upgrade eseguiti come amministratore), verificate che le credenziali di accesso al server AS400 siano valide (utilizzate lo SmeupGo nella cartella di installazione del provider).

Fatta questa prima verifica andremo a configurare il servizio o l’avvio in modalità interattiva tramite file CMD(1 ).

NOTA 1: quando il provider viene avviato in modalità interattiva tramite file CMD su un server Windows, risulta quasi come fosse un servizio: l’interfaccia grafica non risulta visibile, ma, a differenza di quando è avviato come servizio, risulta essere un’applicazione con meno limitazioni, può ad esempio eseguire il comando per montare unità di rete. Per contro, non essendo un servizio, in caso il server venga riavviato, non ripartirà automaticamente.

Gestione e configurazione del servizio

Nella cartella di installazione di Sme.Up Provider sono presenti i file ServiceXXXXX.bat.

Questi file, insieme al file wrapper_default.conf (si trova in serviceNT\conf), sono il punto di partenza per la gestione e la configurazione del servizio.

I file Servicexxxxx.bat servono per la gestione del servizo del provider. Anche se si vuole configurare un solo provider, è necessario ridenominato il file wrapper_default.conf in wrapper_NOME_PROVIDER.conf.

Quindi se avremo un solo provider, ad esempio PRVL01, andremo a creare wrapper_PRVL01.conf,  mentre con due o più provider, ad esempio  PRVL01 e PRVL02, andremo a creare wrapper_PRVL01.conf e wrapper_PRVL02.conf.

Sarà quindi necessario lavorare sui vari file Servicexxxxx.bat: nella cartella di installazione dovranno essere create delle copie di tutti. Andrà poi modificato il nome di ogni file inserendo il suffisso con il nome del provider, avremo pertanto ServiceTest_PRVL01.bat e ServiceTest_PRVL02.bat  e così via per tutti gli altri file Servicexxxxx.bat.

Una volta che si sono create le copie dei Servicexxxxx.bat, sarà necessario editarne il contenuto modificando il riferimento a wrapper.conf in wrapper_nome_provider.conf, esempio in ServiceTest_PRVL01.bat andremo a inserire wrapper_PRVL01.conf

Compiute queste operazioni preliminari andremo a lavorare sui wrapper_nome_provider.conf.

Il file wrapper.conf

Con la versione Roma REV.1, abbiamo razionalizzato la struttura del wrapper.conf, portando tutti i principali parametri all’inzio del file.

In questa sezione si trovano definite (con il comando set.) tutte le variabili previste dalla configurazione. Vanno valorizzate quelle che interessano (obbligatorie o opzionali che siano).

Quanto trovate fra parentesi quadre serve come indicazione del valore da inserire e, ove vi siano, l’elenco dei valori supportati. Es: http, https indica di scegliere fra questi due valori.

Andranno sostituite tutte le parti tra parentesi quadre (comprese).

set.SMEUP_PROVIDER_CODE= [CODICE PROVIDER]
 set.SMEUP_SYSTEM= [INDIRIZZO SISTEMA SMEUP]
 set.SMEUP_USER= [UTENTE COLLEGAMENTO SISTEMA SMEUP]
 set.SMEUP_PASSWORD= [PASSWORD UTENTE COLLEGAMENTO SISTEMA SMEUP]
 set.SMEUP_ENV= [CODICE AMBIENTE SISTEMA SMEUP]
 set.SMEUP_PROVIDER_SERVER_PORT= [PORTA TCP INTERFACCIA LOOCUP: univoca per ogni istanza Provider es. 9990]
 set.SMEUP_PROVIDER_HTTP_PROTOCOL= [PROTOCOLLO INTERFACCIA HTTP: http, https]
 set.SMEUP_PROVIDER_HTTP_PORT= [PORTA TCP INTERFACCIA HTTP: univoca per ogni istanza Provider es. 9090]
 # **********************************************************************************
 # parametri facoltativi il loro utilizzo richiede che venga decommentato il relativo
 # parametro nella sezione wrapper.app.parameter
 # **********************************************************************************
 # modifica il livello di log del provider
 # default è INFO, DEBUG= massimo dettaglio usare solo in fase di test
 set.SMEUP_PROVIDER_LOGLEVEL= [LIVELLO LOG: INFO, ERROR, WARNING, DEBUG]
 # sottosistema in cui funziona il provider migliora la gestione di eventuali disconnessioni
 set.SMEUP_PROVIDER_SUBSYSTEM= [NOME SOTTOSISTEMA LAVORI PROVIDER ]
 # gestione log su DB: valori possibili nnn(d/h/m/s)
 # dove nnn è un numero seguito da uno tra queste lettere:
 # d = day (giorni)
 # h = hour (ore)
 # m = minuti
 # s = secondi
 # es. 8h significa che vengono mantenuti i log delle ultime 8 ore
 # NOTA per attivarlo commentare il parametro wrapper.app.parameter.13=--nodblog
 set.CLEANDB_TIME= [TEMPO RIPULITURA LOG DB]

E’ poi presente la sezione di utilizzo delle variabili

wrapper.app.parameter.1=Smeup.smeui.uimainmodule.MainApplication
wrapper.app.parameter.2=%SMEUP_SYSTEM%
wrapper.app.parameter.3=%SMEUP_USER%
wrapper.app.parameter.4=%SMEUP_PASSWORD%
wrapper.app.parameter.5=%SMEUP_ENV%
wrapper.app.parameter.6=–server:%SMEUP_PROVIDER_CODE%:%SMEUP_PROVIDER_SERVER_PORT%
wrapper.app.parameter.7=–service:%SMEUP_PROVIDER_CODE%
wrapper.app.parameter.8=–%SMEUP_PROVIDER_HTTP_PROTOCOL%:%SMEUP_PROVIDER_HTTP_PORT%
wrapper.app.parameter.9=–nodblog
#wrapper.app.parameter.10=–loglevel:%SMEUP_PROVIDER_LOGLEVEL%
#wrapper.app.parameter.11=–dbg
#wrapper.app.parameter.12=–enc:U8
#wrapper.app.parameter.13=–intserver
#wrapper.app.parameter.14=–sbs:%SMEUP_PROVIDER_SUBSYSTEM%
#wrapper.app.parameter.15=–cleandb:%CLEANDB_TIME%

Nella configurazione di base non c’è nulla da toccare. Per ogni parametro verrà usato il valore impostato nella variabile cui fa riferimento.
I parametri obbligatori sono già attivati, quelli opzionali sono commentati tramite il carattere # ad inizio riga.
Qualora si voglia attivare uno dei parametrii opzionali va gestito il valore della variabile nella sezione di definizione, sostituendo alla spiegazione fra parentesi quadre il valore desiderato.
Es:
la specifica

set.SMEUP_PROVIDER_LOGLEVEL= LIVELLO LOG - INFO, ERROR, WARNING, DEBUG

diventerà

set.SMEUP_PROVIDER_LOGLEVEL=DEBUG

Va quindi tolto il commento al relativo parametro perchè venga passato al Provider

Attenzione al mantenimento dell’ordine nei parametri: se ad esempio l’ultimo parametro non commentato è il 9 (wrapper.app.parameter.9=…) e si decommenta il 12  (wrapper.app.parameter.12=…) di dovrà ridenominare il parametro .12 in .10 ( wrapper.app.parameter.10=…).

Il wrapper, nella ricerca dei parametri, parte da 1 e incrementa se il parametro non viene trovato si ferma.

Prima di installare il servizio

Prima di installare il servizio, verifichiamo che il wrapper.conf sia stato configurato correttamente. Avviare il provider con lo script ServiceTest.bat. Deve aprirsi la finestra del Provider. Se questo non accade, verificare i parametri di connessione. Una volta avviato il provider, aprire un browser e digitare “protocollo://localhost:port/debug”, ad esempio se il provider lavora in http sulla porta 9090 (default) avremo http://localhost:9090/debug.

Nelle release recenti (dalla Roma REV.1) la pagina di debug mostra le informazioni di base sul provider (senza eseguire richiami al server AS400). Per avere un test completo utilizzare il pulsante “Lettura info dettaglio (interroga server AS400) “. Questo richiama il provider sia utilizzando la  porta http che la coda server.

Per testare inoltre esegue un test di raggiungibilità dei percorsi definiti in PROVIDER_PATHS.

Il test dei path è visibile come estensione delle informazioni di base, mentre la lettura delle informazioni di dettaglio è visibile in fondo alla pagina.

NOTA: L’interrogazione tramite porta server presuppone che la versione di Sme.Up sia una V4R1 aggiornata.

Se la pagina risponde, fare il test da un’altra macchina.

Installare il servizio

Se vengono superati questi test, chiudere il provider e installare il servizio con ServiceInstall.bat eseguito come amministratore.

Nell’elenco dei servizi troverete Smeup Service Provider. E’ obbligatorio modificare l’utente Windows con cui funzionerà: andate nelle proprietà e nel tab “Connessione“,  spuntate “Account” ed inserite  le credenziali di un utente di dominio che sia amministratore o che abbia adeguate credenziali per scrivere in appdata e accedere a file in rete.

A questo punto avviare il servizio e ripetere i test.

Superati anche questi test, schedulare avvio e spegnimento del servizio rispettando gli orari di avvio e spegnimento del server applicativo AS400 (il provider va spento prima dello spegnimento e avviato dopo l’accensione). Attenzione a eventuali schedulazioni notturne che fanno operazioni di pulizia (es. cancellazione della SMEUPUIDQ), quando il provider è in funzione.

Configurare il servizio per versioni precedenti alla Roma REV.1

  • andare nella cartella di installazione e nella sottocartella serviceNT\conf
  • se non si è già in possesso di un proprio file wrapper.conf precedentemente configurato, creare una copia del file wrapper_default.conf chiamandola wrapper.conf
  • aprire il file wrapper.conf con un editor di testo
  • modificare le parti tra parentesi quadre. I parametri sono gli stessi dell’avvio:
    • wrapper.app.parameter.2= AS400 : Server AS400 Smeup
    • wrapper.app.parameter.3= UTENTE : Utente di avvio
    • wrapper.app.parameter.4= PASSWORD : La password
    • wrapper.app.parameter.5= INGRESSO UTENTE : Ambiente di esecuzione
    • wrapper.java.additional.1=-DSmeup.smeui.uiserverside.name=: Definisce la coda di comunicazione con l’as400 (6 CARATTERI ALFABETICI) La coda serve all’AS400 per richiedere l’esecuzione di funzioni al provider. Chiedere ad un installatore SmeUp se questa funzionalità serve oppure no, se non serve è comunque obbligatorio indicare un nome. Utilizzare ad esempio SMEPRO (verificare che nella libreria SMEUPUIDQ prima dell primo avvio del provider non esistano oggetti ECTSSMEPRO e ESTCSMEPRO)
    • wrapper.app.parameter.8=–http(s):PORTA : Definisce l’attivazione della modalità http(s) e la porta di accesso all’http(s) (opzionale, se non specificata assume 9090)
    • wrapper.app.parameter.9=–loglevel:LIVELLO: Definisce il livello di log. Valori possibili per LIVELLO: DEBUG,INFO(default), WARN, ERR, OFF.
    • wrapper.app.parameter.10=–enc:XX: definisce l’encoding del provider. Identifica il codice dell’encoding da usare. es U8
    • wrapper.app.parameter.11=–intserver_n_:modalità interattiva del provider
    • wrapper.app.parameter.12=–sbs_n_:sottosistema_lavori_default_QBATCHUI
    • wrapper.app.parameter.13=–nodblog_n_: disabilitazione loggatura su database
    • wrapper.app.parameter.14=–cleandb:nnnnF_n_:pulitura database log
  • lanciare ServiceTest.bat. Se è tutto configurato bene si aprirà la finestra si smeup provider. Fare gli opportuni test. Chiudere la finestra dos.
  • lanciare ServiceInstall.bat.
  • Aprire il gestore dei servizi windows (Strumenti di amministrazione, Servizi) e verificare che SmeupProvider sia presente.
  • Modificare le proprietà del servizio impostando l’utente di avvio. Deve essere come minimo un utente amministratore locale, ma non LOCAL SYSTEM, che di fatto non è un utente!. Se il provider deve accedere alIFS o ad altri server, utilizzare un opportuno utente di windows.
  • lanciare ServiceStart.bat. Fare gli opportuni test.

A partire dai Provider versione Roma REV.1 (rilasciata in data 06/07/2017) o successive
Il file wrapper.conf è stato riorganizzato per rendere più agevole gestire la configurazione.
N.B.: I vecchi file wrapper.conf CONTINUANO A FUNZIONARE CORRETTAMENTE

Avvio in modalità interattiva tramite file cmd

L’avvio in modalità interattiva avviene partendo dai file start_server.cmd e stop_server.cmd, si trovano in LOOCUP_SCP.

Per evitare che vengano sovrascritti, vanno copiati in una cartella diversa da quella di installazione e personalizzati (una coppia per ogni provider).

La schedulazione di avvio e spegnimento avverrà con questi due file.

Ricordiamo che questo tipo di installazione richiede maggiori attenzioni: se il server Windows che ospita il provider viene riavviato, il provider va riavviato manualmente.

Ambienti in lingua

Il provider Roma REV.1 viene distribuito con impostato file encoding UTF-8 e come conversione caratteri U8 (parametro –enc:U8).

Nel caso in cui il provider debba eseguire flussi in encoding differenti, sarò necessario configurare più provider, ognuno dei quali si collegherà ad un ambiente con una lingua specifica.

Potremo avere un’installazione unica, ma se dovremo andare a gestire flussi in tre lingue, dovremo installare e configurare 3 servizi.

Ogni servizio avvierà un provider connesso a un ambiente differente (uno per ogni lingua).

Poniamo il caso si debbano produrre documenti tramite flussi batch in italiano, polacco e cinese. Sarà necessario che l’utente del provider abbia i tre ambienti in linea, dopo di che andremo a creare tre wrapper, esempio wrapper_ITA, wrapper_POL e wrapper_CIN.

in wrapper_ITA  metteremo:

wrapper.java.additional.1=-Dfile.encoding=ISO-8859-1

wrapper.app.parameter.10=--enc:IT

in wrapper_POL metteremo

wrapper.java.additional.1=-Dfile.encoding=ISO-8859-2

wrapper.app.parameter.10=--enc:PL

in wrapper_CIN metteremo:

wrapper.java.additional.1=-Dfile.encoding=UTF-8

wrapper.app.parameter.10=--enc:CI

Accesso a risorse di rete

E’ importante capire che ci sono due utenti in gioco: quello che utilizza il provider per collegarsi all’AS400 e c’è poi l’utente di Windows.

L’utente di collegamento all’AS400 va considerato solamente per la lettura dell’XML iniziale e per l’interazione con Sme.UP.

Per le funzionalità che riguardano l’accesso a risorse esterne, ad esempio IFS o a file, quello che deve essere considerato è l’utente di windows.

Se il provider funziona come servizio va considerato l’utente di collegamento del servizio.

Se il provider sta funzionando come applicazione interattiva, va considerato l’utente di windows che ha schedulato l’operazione pianificata.

Se il provider è stato avviato da una console, l’utente in console.

NOTA: se per accedere all’IFS o a una risorsa di rete è necessario usare il servizio JA_00_15, NET.AUT, il provider non potrà essere avviato come servizio o con tramite operazione pianificata usando start_server.cmd. Windows Server impone delle limitazioni al funzionamento delle applicazioni non interattive.

In questo caso le soluzioni possibili sono due:

  1. si definisce un utente su AS400 che ha lo stesso nome utente e password di quello di windows
  2. si avvia il provider in modalità interattiva, in una sessione in console

Troubleshooting

Quando un provider non si avvia vanno compiuti dei passi molto simili a quelli che si compiono nell’installazione.

Sia che si abbia o non si abbia dimestichezza con i log del provider che del wrapper, suggeriamo come primo passo di aumentare il livello di dettaglio dei log (dettagli in fondo) 

Si comincia dal verificare che il servizio sia attivo. Se il servizio non lo è, avviarlo. Dopo circa un minuto verificare che risponda alla pagina di debug. Qui controllare le informazioni di connessione (utente/ambiente/ data ora di avvio) e che risponda sia tramite porta http che tramite coda server.

Se le risposte sono congruenti, per capire il motivo del mancato avvio è necessario consultare i file di log del provider e del wrapper.

Se le risposte non sono congruenti, ad esempio:

  • la data-ora di avvio è di oltre cinque minuti indietro a quanto atteso
  • l’utente e o l’ambiente è diverso da quanto presente nel wrapper
  • non risponde alle interrogazioni su coda server

si è molto probabilmente di fronte a un caso di provider zombie: si tratta di un provider attivo ma non più connesso all’AS400. La pagina di debug interroga lo zombie, mentre il provider avviato manualmente non risponde in quanto le porte http e server sono già occupate dallo zombie.

In questo caso va chiuso il wrapper e lo zombie va abbattuto. Se ci sono più provider attivi su porte diverse, per individuare il processo corretto va analizzato il comando di avvio. Una volta eliminato lo zombie avviare il servizio del provider.

Se avviando il servizio a mano questo non riparte, provare ad avviare il provider con il bat ServiceTest. Questo ci consente di individuare eventuali problemi legati

  • credenziali di accesso all’AS400
  • ambiente SmeUp
  • Xml iniziale
  • più di un provider attivo sulle stesse porte (server o http)
  • inizializzazione dei plugin

Se con ServiceTest il provider si avvia, ripetere i test descritti poco sopra (pagina di debug e/o scheda V3 LSE).

Se i test hanno avuto esito positivo potrebbe essere un problema legato all’utente di windows. In questo caso va verificato che le credenziali  di windows siano valide, va poi verificato il registro degli eventi di Windows. Se tra gli eventi registrati sono presenti messaggi di questo tipo

The SmeupProvider service is marked as an interactive service.  However, the system is configured to not allow interactive services.  This service may not function properly.

modificare nel file wrapper.conf il valore wrapper.ntservice.interactive da true a false:

# Allow the service to interact with the desktop.

wrapper.ntservice.interactive=false

Questa modifica impone la disinstallazione e la reinstallazione del servizio (ricordarsi di modificare l’utente di collegamento).

Una volta reinstallato, avviare il servizio.

Se ancora non si avvia, è necessario indagare nei file di log / registro sistema windows.

Alcune note tecniche

Il wrapper

Lo Sme.UP Provider per funzionare come servizio utilizza il programma wrapper.exe. La seconda parte del file wrapper.conf è dedicata alla configurazione del wrapper stesso. Il wrapper scrive i file di log nella cartella di installazione, serviceNT\logs.

Questi file riportano le informazioni sul funzionamento del wrapper stesso e dell’interazione con lo Sme.UP Provider. In questo file si trova, ad esempio, quando lo Sme.UP Provider si è avviato, spento, errori non gestiti o eventuali cadute.

Se si utilizza il file di configurazione più recente (quello distribuito con la Roma Rev 1), l’organizzazione è per Sme.UP Provider e per giorno: ogni provider ha un file di log e ogni giorno c’è un file nuovo. Il file si chiamerà wrapper_PROVIDER_DATA.log.

Aumentare il livello di dettaglio dei log

Tramite il file wrapper.conf è possibile aumentare il dettaglio sia per il provider che per il wrapper.

Per il provider va modificato il parametro SMEUP_PROVIDER_LOGLEVEL:

 set.SMEUP_PROVIDER_LOGLEVEL=DEBUG

e decommentato il parametro che definisce il loglevel:

wrapper.app.parameter.10=--loglevel:%SMEUP_PROVIDER_LOGLEVEL%

Per il wrapper impostare wrapper.console.loglevel e wrapper.logfile.loglevel a DEBUG:

# Log Level for console output. (See docs for log levels)
wrapper.console.loglevel=DEBUG
...
# Log Level for log file output. (See docs for log levels)
wrapper.logfile.loglevel=DEBUG

La nomenclatura

Recentemente abbiamo iniziato a utilizzare una nomenclatura che segue questo standard per classificare i provider e gli utenti che utilizzano per la connessione al server AS400.

Suggeriamo di utilizzare il nome del provider anche per l’utente, come suffisso nel wrapper e per il servizio.

Attualmente i provider sono identificati da PRVXnn, dove X è una lettera per indicare a quale AS400 tale provider si connette, e nn è un progressivo numerico di due cifre.

La pagina di debug della Roma REV.1

Nella pagina di debug della versione Roma REV.1 sono state inserite molte funzionalità di test.

Oltre a quelle descritte prima, le funzionalità più interessanti sono:

  • riavviare la sessione di default
  • testare la connessione a un server AS400
  • verificare la raggiungibilità di un server AS400 compresi i servizi di connessione (porte 8471…8476)
  • verificare il download dgli upgrade
  • leggere i log (se attiva la loggatura su DB)