docSpecifiche_All A
download 
Reclamo Transcript
Specifiche_All A
Specifiche di Integrazione della Piattaforma Logistica Nazionale (PLN) con altri Sistemi Informativi (SI) Web Service Interfaces ALLEGATO A AL CAPITOLATO TECNICO Prot. n. 1813/2014 i Sommario 1 2 Introduzione .............................................................................................................................................. 1 1.1 Scopo ................................................................................................................................................... 1 1.2 Struttura del Documento .................................................................................................................... 1 Modalità di Accesso e Sicurezza ................................................................................................................ 1 2.1 3 Anagrafica .................................................................................................................................................. 1 3.1 5 6 getAziendaDaPartitaIva ............................................................................................................... 2 3.1.2 getIndirizziPerAzienda ................................................................................................................. 3 POI ....................................................................................................................................................... 4 3.2.1 getPOIPubblici.............................................................................................................................. 4 3.2.2 getPOIPrivati ................................................................................................................................ 6 3.2.3 getPOIConGeolocalizzazione ....................................................................................................... 7 Missioni...................................................................................................................................................... 9 4.1 getStatus ........................................................................................................................................... 10 4.2 createMission .................................................................................................................................... 10 4.3 modifyMission................................................................................................................................... 13 4.4 deleteMission .................................................................................................................................... 13 4.5 activeMission .................................................................................................................................... 14 4.6 closeMission ...................................................................................................................................... 14 4.7 commodityTypeList ........................................................................................................................... 14 4.8 operationTypeList ............................................................................................................................. 15 Posizioni ................................................................................................................................................... 16 5.1 getStatus ........................................................................................................................................... 16 5.2 handleMultiTruckMessage................................................................................................................ 16 Allarmi...................................................................................................................................................... 20 6.1 7 Aziende................................................................................................................................................ 1 3.1.1 3.2 4 Autenticazione .................................................................................................................................... 1 FLMServerService .............................................................................................................................. 20 6.1.1 getStatus .................................................................................................................................... 22 6.1.2 handleAlertMessage .................................................................................................................. 22 Tabellone degli Arrivi ............................................................................................................................... 25 7.1 Descrizione Servizio .......................................................................................................................... 25 7.1.1 Web Service ............................................................................................................................... 25 7.1.2 Controllo sicurezza dati in input ................................................................................................ 25 ii 8 9 7.1.3 Selezioni missioni per l’output................................................................................................... 25 7.1.4 Ordinamento missioni nell’output............................................................................................. 25 7.1.5 Informazioni sulla prenotazione ................................................................................................ 25 7.2 getStatus ........................................................................................................................................... 25 7.3 Arrivals .............................................................................................................................................. 26 Servizio di Messaggistica ......................................................................................................................... 29 8.1 Mailbox ............................................................................................................................................. 30 8.2 putMessage ....................................................................................................................................... 31 8.3 getUnreadMessages ......................................................................................................................... 34 8.4 getMessage ....................................................................................................................................... 35 8.5 replyTo .............................................................................................................................................. 37 8.6 sendDraftMessage ............................................................................................................................ 37 8.7 updateDraftMessage ........................................................................................................................ 38 8.8 deleteDraftMessage.......................................................................................................................... 38 8.9 getChildrenMessage ......................................................................................................................... 38 8.10 Gestione delle eccezioni ................................................................................................................ 39 8.11 Casi d’uso....................................................................................................................................... 40 8.11.1 Invio di un Messaggio alla PLN ............................................................................................... 40 8.11.2 Ricezione dei Messaggi dalla PLN .......................................................................................... 42 Sistema di Gestione delle Prenotazioni ................................................................................................... 43 9.1 Accesso al Catalogo dei Servizi.......................................................................................................... 44 9.1.1 ListTypologies ............................................................................................................................ 44 9.1.2 DetailTypology ........................................................................................................................... 45 9.1.3 SchemaServiceByTipology ......................................................................................................... 48 9.1.4 ListServices................................................................................................................................. 49 9.1.5 DetailService .............................................................................................................................. 51 9.1.6 SchemaBookingByService .......................................................................................................... 53 9.1.7 ServiceState ............................................................................................................................... 54 9.2 Amministrazione dei Servizi .............................................................................................................. 55 9.2.1 InsertService .............................................................................................................................. 55 9.2.2 UpdateService ............................................................................................................................ 57 9.2.3 UpdateServiceState ................................................................................................................... 59 9.3 Gestione delle Prenotazioni .............................................................................................................. 60 iii 9.3.1 InsertBooking ............................................................................................................................. 60 9.3.2 UpdateBooking .......................................................................................................................... 62 9.3.3 UpdateBookingState .................................................................................................................. 63 9.3.4 BookingState .............................................................................................................................. 65 9.3.5 ListBookings ............................................................................................................................... 66 9.3.6 ListBookingsDocuments............................................................................................................. 68 9.3.7 DetailBooking ............................................................................................................................. 69 9.3.8 DetailBookingDocuments .......................................................................................................... 71 9.3.9 BookingNotify ............................................................................................................................ 75 9.3.10 BookingForward ..................................................................................................................... 75 9.3.11 BookingReminder ................................................................................................................... 76 9.4 Gestione delle Eccezioni ................................................................................................................... 76 9.4.1 ExceptionResponse .................................................................................................................... 76 9.5 Casi d’Uso .......................................................................................................................................... 78 9.6 Messaggi Specifici dei Servizi in Catalogo ......................................................................................... 80 9.6.1 9.6.1.1 Messaggi inviati alla piattaforma UIRNet............................................................................... 81 9.6.1.2 Messaggi ricevuti dalla piattaforma UIRNet .......................................................................... 93 9.7 10 Preavviso di Arrivo APGe ........................................................................................................... 80 Servizi di Prenotazione .................................................................................................................... 101 9.7.1 GetBookingDetail ..................................................................................................................... 101 9.7.2 ListPOIBookings ....................................................................................................................... 102 9.7.3 ListPOIServices ......................................................................................................................... 103 Documentale ...................................................................................................................................... 104 10.1 getDocsByMissionPOI.................................................................................................................. 105 iv 1 Introduzione La Piattaforma Logistica Nazionale (PLN) espone servizi per l’integrazione con altri Sistemi Informativi (SI) adottati nella filiera della logistica. 1.1 Scopo Il presente documento rappresenta una guida per l’integrazione dei SI con i servizi della PLN mediante l’uso dei Web Service esposti per tale scopo. 1.2 Struttura del Documento Il documento è suddiviso in 2 macroaree, la prima relativa ai servizi di fleet management e la seconda ai servizi di Booking. 2 Modalità di Accesso e Sicurezza La PLN espone dei Web Service su protocollo HTTPS in standard XML-SOAP per l’accesso alle funzionalità presenti da SI. 2.1 Autenticazione La PLN prevede un processo di autorizzazione delle aziende gestito dal Contact Center UIRNet. Il meccanismo di autenticazione delle comunicazioni con un SI avviene mediante l’assegnazione di credenziali specifiche per l’Azienda e per il SI. Ogni SI viene identificato mediante Id Azienda/username/CIM(pin) attribuito con le modalità definite da UIRNet (cfr. www.uirnet.it). L’onere di identificare l’utente che materialmente agisce sulla PLN tramite il SI è a carico di quest’ultimo, così come lo sono la gestione delle credenziali dei singoli utenti e la storicizzazione delle transazioni per la tracciabilità interna delle procedure. La PLN assume che l’operatore che adopera il SI sia autorizzato ed autenticato. Questa procedura è a carico esclusivamente del SI e la PLN non effettua alcuna verifica in merito. 3 Anagrafica 3.1 Aziende Ambiente URL Test https://test.uirnet.it/UIRNetServices/CompanyServices?wsdl Produzione https://www.uirnet.it/UIRNetServices/CompanyServices?wsdl 1 Tutti i webservice qui esposti restituiscono, nell’eventualità di errore durante la validazione utente/cim una struttura errore del tipo: Campo Tipo Direzione Descrizione statucCode xs:string Out Codice errore = 1 statusMsg xs:string Out Motivo errore 3.1.1 getAziendaDaPartitaIva Restituisce l’azienda avente partita IVA o codice fiscale corrispondente alla stringa in input. RICHIESTA: GETAZIENDADAPARTITAIVA Campo Tipo Descrizione Obbligatori userName xs:string Identificativo utente PLN S cim xs:string Pin di accesso ai Web Services S partitaIva xs:string Partita IVA dell’azienda da cercare S I parametri username e cim (pin) sono utilizzati per identificare il SI. RISPOSTA: GETAZIENDADAPARTITAIVARESPONSE Campo Tipo Descrizione return xs: getAziendaDaPartitaIvaResponse Dati azienda AZIENDAOUTPUT Campo Tipo azienda tns:azienda Descrizione AZIENDA Campo Tipo Descrizione idAzienda xs: long ID UIRNet dell’Azienda ragSociale xs:string Ragione Sociale dell’Azienda codiceFiscale xs:string Ragione Sociale dell’Azienda partitaIva xs:long Ragione Sociale dell’Azienda indirizzo tns:indirizzo Indirizzo dell’Azienda telefono xs:string Telefono dell’Azienda telefono2 xs:string Telefono dell’Azienda categoria xs:string Categoria dell’Azienda tipologia xs:int tipologiaDescr xs:string tipologiaAzienda tns:tipologiaAzienda 2 INDIRIZZO Campo Tipo Descrizione idIndirizzo xs: long ID UIRNet dell’indirizzo indirizzo xs:string Indirizzo civico xs:string Civico interno xs:string Interno particella xs:string Particella localita xs:string Localita citta xs:string Città provincia xs:string Provincia regione xs:string Regione nazione xs:string Nazione Campo Tipo Descrizione idTipologia xs:int ID UIRNet della tipologia di Azienda categoria xs:string tipologia xs:string principale xs:boolean TIPOLOGIAAZIENDA Vero se la tipologia è quella principale dell’Azienda La risposta include anche un codice di ritorno nel formato risultato. RISULTATO Campo Tipo Descrizione statusCode xs:int 0 ok 1 nessun elemento trovato 2 parametro input nullo statusMsg xs:string 3.1.2 getIndirizziPerAzienda Restituisce l’elenco degli indirizzi dell’azienda passata in input. RICHIESTA: GETINDIRIZZIPERAZIENDA Campo Tipo Descrizione Obbligatori userName xs:string Identificativo utente PLN S cim xs:string Pin di accesso ai Web Services S idAzienda xs:long ID UIRNet dell’Azienda S I parametri username e cim, pin del Servizio di Messaggistica, sono utilizzati per identificare il SI. L’id Azienda viene restituito dalla chiamata precedente getAziendaDaPartitaIVA. RISPOSTA: GETINDIRIZZIPERAZIENDARESPONSE Campo Tipo Descrizione 3 return xs: getIndirizziPerAziendaResponse Elenco indirizzi azienda Campo Tipo Descrizione indirizzoAzienda tns:indirizzo Cfr. § 3.1.1 INDIRIZZIAZIENDAOUTPUT La risposta include anche un codice di ritorno nel formato risultato. RISULTATO Campo Tipo Descrizione statusCode xs:int 0 ok 1 nessun elemento trovato 2 parametro input nullo statusMsg xs:string 3.2 POI Ambiente URL Test https://test.uirnet.it/UIRNetServices/POIServices?wsdl Produzione https://www.uirnet.it/UIRNetServices/POIServices?wsdl 3.2.1 getPOIPubblici Restituisce la lista di tutti I POI pubblici della piattaforma. RICHIESTA: GETPOIPUBBLICI Campo Tipo Descrizione Obbligatori userName xs:string Identificativo utente PLN S cim xs:string Pin di accesso ai Web Services S I parametri username e cim, pin del Servizio di Messaggistica, sono utilizzati per identificare il SI. RISPOSTA: GETPOIPUBBLICIRESPONSE Campo Tipo Descrizione return xs: getPoiPubliciResponse Elenco indirizzi POI pubblici Campo Tipo Descrizione indirizzoAzienda tns:indirizzoPOI [0..n] Elenco degli indirizzi dei POI pubblici Campo Tipo Descrizione descrizionePoi xs:string Descrizione del POI gestorePoi xs:string idAzienda xs:long ID PLN dell’Azienda titolare del POI identificativoPoi xs:long ID PLN del POI INDIRIZZIPOIAZIENDAOUTPUT INDIRIZZOPOI 4 latitudine xs:string Latitudine longitudine xs:string Longitudine mypoiFormaGiuridica xs:string Forma giuridica dell’Azienda titolare del POI mypoiNomeAzienda xs:string Ragione Sociale dell’Azienda titolare del POI mypoiPartitaiva xs:string Partita IVA dell’Azienda titolare del POI nomePoi xs:string Nome del POI pubblicoPrivato xs:string tempoAttraversamento xs:long tipoIndirizzo xs:string visibilita xs:string Tempo stimato per le operazioni di accesso-carico-scarico nel POI La struttura dati INDIRIZZOPOI estende la struttura INDIRIZZO che definisce i parametri di base per il geocoding. TIPO DI DATI COMPOSTO INDIRIZZOAZIENDA Campo Tipo Descrizione cap xs:string cap POI citta xs:string città POI civico xs:string numero civico POI idIndirizzo xs:long identificativo indirizzo POI indirizzo xs:string indirizzo POI interno xs:string interno indirizzo POI localita xs:string località POI nazione xs:string nazione POI particella xs:string particella POI provincia xs:string provincia POI regione xs:string regione POI descrizionePoi xs:string descrizione POI distance xs:double distanza del POI gestorePoi xs:string gestore del POI idAzienda xs:long id Azienda POI identificativoPoi xs:long identificativo del POI latitudine xs:string coordinata lat. POI longitudine xs:string coordinata long. POI mypoiFormaGiuridica xs:string forma giuridica myPOI mypoiNomeAzienda xs:string nome azienda myPOI mypoiPartitaiva xs:string partita iva del myPOI 5 nomePoi xs:string nome del POI pubblicoPrivato xs:string POI pubblico/privato ragioneSociale xs:string ragione sociale del POI statoIndirizzo xs:string stato dell’indirizzo del POI statoPoi xs:string stato del POI tempoAttraversamento xs:long tempo attraversamento del POI tipoIndirizzo xs:string tipo indirizzo POI visibilita xs:string visibilità POI 3.2.2 getPOIPrivati Restituisce la lista di tutti i POI dell’azienda ai quali l’utente in input ha diritti di accesso filtrati per la tipologia in ingresso. Se la tipologia è nulla verranno restituiti tutti i POI visibili. RICHIESTA: GETPOIPRIVATI Campo Tipo Descrizione Obbligatori userName xs:string Identificativo utente PLN S cim xs:string Pin di accesso ai Web Services S RISPOSTA: GETPOIPRIVATIRESPONSE Campo Tipo Descrizione return xs: getPoiPrivatiResponse Elenco dei POI privati dell’Azienda del SI (cfr. § 3.2.1) TIPO DI DATI COMPOSTO INDIRIZZOAZIENDA Campo Tipo Descrizione cap xs:string cap POI citta xs:string città POI civico xs:string numero civico POI idIndirizzo xs:long identificativo indirizzo POI indirizzo xs:string indirizzo POI interno xs:string interno indirizzo POI localita xs:string località POI nazione xs:string nazione POI particella xs:string particella POI provincia xs:string provincia POI regione xs:string regione POI descrizionePoi xs:string descrizione POI distance xs:double distanza del POI 6 gestorePoi xs:string gestore del POI idAzienda xs:long id Azienda POI identificativoPoi xs:long identificativo del POI latitudine xs:string coordinata lat. POI longitudine xs:string coordinata long. POI mypoiFormaGiuridica xs:string forma giuridica myPOI mypoiNomeAzienda xs:string nome azienda myPOI mypoiPartitaiva xs:string partita iva del myPOI nomePoi xs:string nome del POI pubblicoPrivato xs:string POI pubblico/privato ragioneSociale xs:string ragione sociale del POI statoIndirizzo xs:string stato dell’indirizzo del POI statoPoi xs:string stato del POI tempoAttraversamento xs:long tempo attraversamento del POI tipoIndirizzo xs:string tipo indirizzo POI visibilita xs:string visibilità POI 3.2.3 getPOIConGeolocalizzazione Restituisce una lista di tutti i POI in base ai parametri di input: se i parametri in input latitudine, longitudine, maxDistance (o uno di essi) sono nulli il WS restituisce la lista dei POI appartenenti all’azienda specificata con partitaIva e codiceFiscale in input; se invece viene fornito in input il solo punto (latitudine, longitudine, maxDistance) il WS fornirà la lista dei POI con distanza inferiore od uguale alla distanza massima specificata in input; se tutti i parametri in input sono presenti il WS restituirà lista dei POI con distanza inferiore od uguale alla distanza massima specificata in input ed appartenenti all’azienda specificata in input. RICHIESTA: GETPOICONGEOLOCALIZZAZIONE Campo Tipo Descrizione Obbligatori userName xs:string Identificativo utente PLN S cim xs:string Pin di accesso ai Web Services S companyPIVA xs:sring PIVA azienda S companyFC xs:string Codice fiscale azionda S latitude xs:string Latitudine S longitude xs:string Longitudine S maxDistance xs:string Distanza massima dal POI S RISPOSTA: GETPOICONGEOLOCALIZZAZIONE Campo Tipo Descrizione 7 getPoiConGeolocalizzazioneResponse xs: getPoiConGeolocalizzazioneResponse Elenco indirizzi POI VALORI DI RITORNO: Campo Tipo 0 ok 1 Nessun elemento trovato 10 Errore generico 11 Richiesta di input vuota 12 Coordinate omesse 14 Dati posizione non validi 15 Lista di POI troppo grande RETURN Campo Tipo Descrizione risultato xs:risultato Struttura “risultato” indirizzi xs:indirizzi Struttura elenco “indirizzi” INDIRIZZI Campo Tipo Descrizione cap xs:string cap POI citta xs:string città POI civico xs:string numero civico POI idIndirizzo xs:long identificativo indirizzo POI indirizzo xs:string indirizzo POI interno xs:string interno indirizzo POI localita xs:string località POI nazione xs:string nazione POI particella xs:string particella POI provincia xs:string provincia POI regione xs:string regione POI descrizionePoi xs:string descrizione POI distance xs:double distanza del POI gestorePoi xs:string gestore del POI idAzienda xs:long id Azienda POI identificativoPoi xs:long identificativo del POI latitudine xs:string coordinata lat. POI longitudine xs:string coordinata long. POI mypoiFormaGiuridica xs:string forma giuridica myPOI mypoiNomeAzienda xs:string nome azienda myPOI 8 mypoiPartitaiva xs:string partita iva del myPOI nomePoi xs:string nome del POI pubblicoPrivato xs:string POI pubblico/privato ragioneSociale xs:string ragione sociale del POI statoIndirizzo xs:string stato dell’indirizzo del POI statoPoi xs:string stato del POI tempoAttraversamento xs:long tempo attraversamento del POI tipoIndirizzo xs:string tipo indirizzo POI visibilita xs:string visibilità POI 4 Missioni Il MISSIONLISTENER è un WebService per l’acquisizione di messaggi di missione dei mezzi mobili. Il SI di fleet management invierà, attraverso il WebService esposto della piattaforma, informazioni su nuove missioni pianificate per i veicoli, modifica, cancellazioni, operazioni sugli stati della missione (attivazione, chiusura). Tutte le informazioni di anagrafica correlate alle missioni devono essere già note alla piattaforma (veicoli, conducenti, POI, ecc…). Il processo prevede l’invio di una missione pianificata, l’attivazione della stessa al momento della partenza. La chiusura della missione al momento della conclusione può essere effettuata dal SI tramite il Web Service di closeMission o demandare la chiusura al meccanismo automatico. Il meccanismo automatico, una volta che il veicolo ha raggiunto l’ultimo POI, verifica che tutti i punti di missione siano stati raggiunti e superati per procedere alla chiusura della missione. La regola per l’inserimento delle missioni è la seguente: La nuova missione viene scartata se il numero di missioni acquisite dall’azienda nel periodo corrente (il periodo è un parametro univoco su ALR, fissato di default a 7 giorni) è superiore a quello tollerabile; il numero di nuove missioni tollerabile è fissato come fattore-di-tolleranza (parametrico univoco su ALR, fissato di default a 1.1) * il numero massimo di missioni attese. Quest’ultimo valore è calcolato come nMaxMissioniPerVeicoloPerGiorno (parametro univoco di ALR, fissato a 4) * numero giorni del periodo corrente (7) * numero veicoli al momento in uso all’azienda. L’aggiornamento di missione viene scartato se il numero di aggiornamenti acquisiti dall’azienda nel periodo corrente ha raggiunto il livello tollerabile. La misura del numero di aggiornamenti tollerabile è dato dal numero di missioni tollerabile (calcolato come al punto 1) * numero massimo di aggiornamenti per singola missione (parametro univoco di ALR, fissato di default a 10). Ambiente URL Test https://test.uirnet.it/MDW-EA-MDW_EGW/EGWMissionService?wsdl Produzione https://www.uirnet.it/MDW-EA-MDW_EGW/EGWMissionService?wsdl 9 4.1 getStatus Restituisce lo stato di operatività dell’interfaccia software stessa. RICHIESTA: GETSTATUS Il messaggio GETSTATUS non prevede alcun parametro. RISPOSTA: GETSTATUSRESPONSE Campo Tipo Descrizione result xs:boolean Stato del servizio 4.2 createMission Il metodo inserisce una nuova missione nella PLN. RICHIESTA: CREATEMISSION Campo Tipo Descrizione Obbl. credentials tns:egwCredential Username PLN per l’accesso al servizio S missionRequest tns:egwMissionServiceRequest Dati della missione S Campo Tipo Descrizione Obbl. username xs:string Username PLN per l’accesso al servizio S cim xs:string Pin di accesso ai Web Services S Campo Tipo Descrizione mission tns:egwMission Parametri operativi della missione S missionCommodity tns:egwMissionCommodity Informazioni sulle merci e gli stakeholder N missionPoint tns:egwMissionPoint Elenco dei waypoint e dei punti missione S Campo Tipo Descrizione ownerId xs:long ID azienda S missionExtId xs:string ID della missione attribuito dal SI S missionName xs:string Nome della missione S missionDescription xs:string Descrizione della missione S fleetExtId xs:string ID della flotta attribuito dal SI (nella fase di registrazione al CRM) S vehicleExtId xs:string ID del veicolo attribuito dal SI (nella fase di registrazione al CRM), il veicolo deve avere stato “in uso” per essere utilizzato S hasCommodity xs:short Indica se la missione ha merce associata valori ammessi (0,1) S driverUname1 xs:string Username PLN del primo autista S driverUname2 xs:string Username PLN del secondo autista N EGWCREDENTIAL EGWMISSIONSERVICEREQUEST Obbl. EGWMISSION Obbl. 10 dateStart xs:dateTime Data e ora di inizio missione S dateEnd xs:dateTime Data e ora di fine missione S arrivalTs xs:dateTime data e ora di compilazione della missione S deliveryTs xs:dateTime Data e ora di invio da parte del SI S EGWMISSIONCOMMODITY Campo Tipo Descrizione Obbl. commodityExtId xs:string Identificativo della merce attribuito dal SI N charge_mission_point xs:long ID UIRNet del POI di carico (deve essere presente nella struttura EGWMISSIONPOINT) N discharge_mission_point xs:long ID UIRNet del POI di scarico (deve essere presente nella struttura EGWMISSIONPOINT) N commodityType xs:int Identifica il tipo di merce, i valori ammessi dalla piattaforma sono restituiti dal metodo COMMODITYTYPELIST (cfr. § 4.7) N commoditySubType xs:string Specifica la tipologia della merce N o Casse/Fusti/…/Altro se commodityType = merci varie o testo generico (libero) se commodityType = rotabili, cisterne, pallet commoditySubTypeDescription xs:string Descrizione testuale del tipo di merce N commodityIsoCode xs:string Codice ISO del contenitore N orderId xs:string bookingId xs:string Numero di prenotazione associato N seal xs:string Identificativo del sigillo N amount xs:long Quantità o numero N volume xs:double Volume della merce weight xs:double Peso della merce isEmpty xs:short Indica se che contenitore è vuoto, assume significato solo per container e casse mobili N stakeholder tns:egwStakeholder Elenco degli stakeholder della merce N note xs:string N N EGWSTAKEHOLDER Campo Tipo Descrizione Obbl. vatId xs:string P.Iva dello Stakeholder S volume xs:double Volume S weight xs:double Peso S hasVisibility xs:short visibilità missione allo Stakeholder S Campo Tipo Descrizione arrivalTs xs:dateTime Orario di arrivo pianificato EGWMISSIONPOINT Obbl. S 11 operationType xs:short Valore reperibile dal metodo commodityTypeList S POIId xs:long ID UIRNet del POI reperibila GetPOIPubblici - GetPOIPrivati servizio S operationTime (stoppingDischargeMin) xs:short Tempo presunto di esecuzione delle attività nel POI S wayPoint xs:short Identifica se il POI è un waypoint valori ammessi (0,1) S dal Restituisce una struttura dati di Acknowledgement RISPOSTA: CREATEMISSIONRESPONSE Campo Tipo Descrizione return tns:egwMissionServiceResponse Elenco dei codici di ritorno EGWMISSIONSERVICERESPONSE Campo Tipo Descrizione missionExtId xs:long ID della missione attribuito dal SI responseCode xs:string Codice di risposta responseDescription xs:string Descrizione della risposta Esempio di missione base (senza merce e senza stakeholder) <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:bl="http://bl.mission.egw.mdw.uirnet.telespazio.com"> <soapenv:Header/> <soapenv:Body> <bl:createMission> <credentials> <cim>xxxxxx</cim> <username>XXXXXXXXXX</username> </credentials> <missionRequest> <mission> <arrivalTs>2013-05-03T00:00:00.000+02:00</arrivalTs> <dateEnd>2013-05-17T00:00:00.000+02:00</dateEnd> <dateStart>2013-05-10T00:00:00.000+02:00</dateStart> <deliveryTs>2013-05-17T00:00:00.000+02:00</deliveryTs> <driverUname1>xxxxx</driverUname1> <fleetExtId>xxxxxx</fleetExtId> <hasCommodity>0</hasCommodity> <missionDescription>xxxxxx</missionDescription> <missionExtId>xxxxxxx</missionExtId> <missionName>xxxxxxxi</missionName> <ownerId>xxxxx</ownerId> <vehicleExtId>xxxxxx</vehicleExtId> </mission> <!--Zero or more repetitions:--> <missionPoint> <arrivalTs>2013-05-10T00:00:00.000+02:00</arrivalTs> <operationType>2</operationType> <poiId>xxxxxxxxxxxx</poiId> 12 <stoppingDischargeMin>2</stoppingDischargeMin> <waypoint>0</waypoint> </missionPoint> <missionPoint> <arrivalTs>2013-05-17T00:00:00.000+02:00</arrivalTs> <operationType>2</operationType> <poiId>xxxxxxxxxx</poiId> <stoppingDischargeMin>1</stoppingDischargeMin> <waypoint>0</waypoint> </missionPoint> </missionRequest> </bl:createMission> </soapenv:Body> </soapenv:Envelope> Response <env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"> <env:Header/> <env:Body> <ns2:createMissionResponse xmlns:ns2="http://bl.mission.egw.mdw.uirnet.telespazio.com"> <return> <missionId>XXXXX</missionId> <responseCode>0</responseCode> <responseDescription>OK</responseDescription> </return> </ns2:createMissionResponse> </env:Body> </env:Envelope> 4.3 modifyMission Modifica i dati di una missione identificata mediante il campo missionExtId della struttura EGWMISSION all’interno della struttura EGWMISSIONSERVICEREQUEST. RICHIESTA: MODIFYMISSION Campo Tipo Descrizione Obbl. credentials tns:egwCredential Username PLN per l’accesso al servizio (cfr. § 4.2) S missionRequest tns:egwMissionServiceRequest Dati della missione (cfr. § 4.2) S Il servizio restituisce una struttura dati di Acknowledgement RISPOSTA: MODIFYMISSIONRESPONSE Campo Tipo Descrizione return tns:egwMissionServiceResponse Elenco dei codici di ritorno (cfr. § 4.2) 4.4 deleteMission Elimina una missione identificata mediante il campo missionId. 13 RICHIESTA: DELETEMISSION Campo Tipo Descrizione Obbl. credentials tns:egwCredential Username PLN per l’accesso al servizio (cfr. § 4.2) S missionId xs:long Identificativo della missione S Il servizio restituisce una struttura dati di Acknowledgement RISPOSTA: DELETEMISSIONRESPONSE Campo Tipo Descrizione return tns:egwMissionServiceResponse Elenco dei codici di ritorno (cfr. § 4.2) 4.5 activeMission Attiva una missione identificata mediante il campo missionId. RICHIESTA: ACTIVEMISSION Campo Tipo Descrizione Obbl. credentials tns:egwCredential Username PLN per l’accesso al servizio (cfr. § 4.2) S missionId xs:long Identificativo della missione S Il servizio restituisce una struttura dati di Acknowledgement. RISPOSTA: ACTIVEMISSIONRESPONSE Campo Tipo Descrizione return tns:egwMissionServiceResponse Elenco dei codici di ritorno (cfr. § 4.2) 4.6 closeMission Chiude una missione identificata mediante il campo missionId. RICHIESTA: CLOSEMISSION Campo Tipo Descrizione Obbl. credentials tns:egwCredential Username PLN per l’accesso al servizio (cfr. § 4.2) S missionId xs:long Identificativo della missione S Il servizio restituisce una struttura dati di Acknowledgement RISPOSTA: CLOSEMISSIONRESPONSE Campo Tipo Descrizione return tns:egwMissionServiceResponse Elenco dei codici di ritorno (cfr. § 4.2) 4.7 commodityTypeList Restituisce l’elenco dei tipi di merce supportati dalla piattaforma. RICHIESTA: COMMODITYTYPELIST Il messaggio COMMODITYTYPELIST non prevede alcun parametro. 14 RISPOSTA: COMMODITYTYPELISTRESPONSE Campo Tipo Descrizione return tns:egwNameValuePairResponse Coppie di codice commodity e descrizione EGWNAMEVALUEPAIRRESPONSE Campo Tipo Descrizione name xs:string Descrizione del valore value xs:int Valore identificativo dell’oggetto nella PLN 4.8 operationTypeList Restituisce l’elenco dei tipi di operazioni su POI supportati dalla piattaforma. RICHIESTA: OPERATIONTYPELIST Il messaggio OPERATIONTYPELIST non prevede alcun parametro. RISPOSTA: OPERATIONTYPELISTRESPONSE Campo Tipo Descrizione return tns:egwNameValuePairResponse Coppie di descrizione e codice operazione (cfr. § 4.7) 15 5 Posizioni Il POSITIONLISTER è il WebService per l’acquisizione di messaggi di posizione dei mezzi mobili e di eventuali altre informazioni collegate. Il SI di fleet management invierà, attraverso il WebService esposto della PLN, informazioni sulle posizioni dei mezzi mobili interessati precedentemente registrati sulla piattaforma stessa. Le posizioni dei veicoli che verranno trasmesse dal SI alla PLN ogni 10 minuti circa per ogni azienda (usando la coppia username-cim dell’azienda per l’autenticazione) e devono contenere tutti i messaggi di posizione acquisiti (al più uno ogni 5 minuti per veicolo) per tutti i veicoli in uso all’azienda. La regola è la seguente: Il burst viene scartato se il numero di messaggi in esso contenuto è maggiore di quello tollerabile; il numero di messaggi tollerabile è fissato come fattore-di-tolleranza (parametrico univoco su ALR, fissato di default a 1.5) * il numero dei messaggi attesi. Quest’ultimo valore è calcolato come nMessaggiNominaliPerMinutoPerVeicolo * numero minuti dall’invio dell’ultimo burst ‘accettato’ * numero veicoli al momento in uso all’azienda. Un burst non può comunque superare (indipendentemente da quanto alto è l’intervallo dal precedente burst accettato) un valore massimo pari a nMessaggiMaxPerVeicoloInUnicoBurst (parametro univoco su ALR, fissato di default a 2.5) * numero veicoli al momento in uso all’azienda. Ambiente URL Test https://test.uirnet.it/MDW-EA-MDW_EGW/EGWFEBean?wsdl Produzione https://www.uirnet.it/MDW-EA-MDW_EGW/EGWFEBean?wsdl 5.1 getStatus Restituisce lo stato di operatività dell’interfaccia software stessa. RICHIESTA: GETSTATUS Il messaggio GETSTATUS non prevede alcun parametro. RISPOSTA: GETSTATUSRESPONSE Campo Tipo Descrizione result xs:boolean Stato del servizio 5.2 handleMultiTruckMessage Acquisisce un insieme di messaggi di posizione, con eventuali attributi di carattere logistico, di un numero arbitrario di veicoli monitorati. RICHIESTA: HANDLEMULTITRUCKMESSAGE Campo Tipo Descrizione Obbl. userName xs:string Identificativo utente PLN S cim xs:string Pin di accesso ai Web Services S globalPositionPacks tns:globalPositionPack[0..N] Sequenza di messagi di posizione S 16 GLOBALPOSITIONPACK Campo Tipo Descrizione Obbl. currPositionMess tns:positionMessageS Messaggio di posizione del veicolo S currPositionMessAttributes tns:positionMessageAttributes Attributi di carattere logistico del messaggio N Campo Tipo Descrizione Obbl. companyId xs:string ID PLN dell’Azienda comunicato da UIRNet al momento della sottoscrizione del contratto o reperibile attraverso il Servizio getAziendaDaPartitaIVA S deliverytime xs:string Data e ora di invio del messaggio, espresse in UTC col formato ISO8601 “YYYY-MM-DDThh:mm:ssZ” S fleetExtId xs:string Codice univoco che il SI utilizza per identificare la flotta inserito al momento della registrazione nel CRM S unitExtId xs:string Codice univoco che il SI utilizza per identificare il suo mezzo mobile inserito al momento della registrazione nel CRM – il veicolo per essere utilizzato deve essere nello stato “in uso” S messageExtId xs:string Codice univoco che il SI utilizza per identificare il messaggio inviato alla PLN S position tns:positionS Dati di latitudine e longitudine, con datum WGS84, direzione, velocità ed altitudine S positiontime xs:string Data e ora di acquisizione dell’informazione sulla posizione del mezzo (es. acquisizione GPS), espresse in UTC col formato ISO8601 “YYYY-MMDDThh:mm:ssZ” S Campo Tipo Descrizione Obbl. latitude xs:string Valore decimale di latitudine S longitude xs:string Valore decimale di longitudine S elevation xs:string Altezza in metri slm N degree xs:string Direzione (0.0-360.0°, il Nord indicato con 0°) N speed xs:string Velocità espressa in Km/h S Campo Tipo Descrizione Obbl. attributeList tns:positionAttribute Attributidi carattere logistico S Campo Tipo Descrizione Obbl. attributeCode xs:string Codice per classificare l’informazione georeferenziata che viene trasmessa insieme al messaggio di posizione S attributeValue xs:string Valore eventualmente associato all’attributo N POSITIONMESSAGES POSITIONS POSITIONMESSAGEATTRIBUTES POSITIONATTRIBUTE 17 Esempio messaggio di posizione per un solo veicolo <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:bl="http://bl.egw.mdw.uirnet.telespazio.com/"> <soapenv:Header/> <soapenv:Body> <bl:handleMultiTruckMessage> <username>xxxxxx</username> <cim>xxxxxx</cim> <globalPositionPacks> <currPositionMess> <companyId>xxxxx</companyId> <deliverytime>2013-05-15T13:05:37Z</deliverytime> <fleetExtId>xxxxx</fleetExtId> <messageExtId>123141234</messageExtId> <position> <degree>0</degree> <elevation>0</elevation> <latitude>45.00</latitude> <longitude>9.0</longitude> <speed>45</speed> </position> <positiontime>2013-05-15T13:05:37Z</positiontime> <unitExtId>xxxxxx</unitExtId> </currPositionMess> <currPositionMessAttributes> <!--Zero or more repetitions:--> <attributeList> <attributeCode>0</attributeCode> <attributeValue>0</attributeValue> </attributeList> </currPositionMessAttributes> </globalPositionPacks> </bl:handleMultiTruckMessage> </soapenv:Body> </soapenv:Envelope> Response <env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"> <env:Header/> <env:Body> <ns2:handleMultiTruckMessageResponse xmlns:ns2="http://bl.egw.mdw.uirnet.telespazio.com/"> <result> <correct>true</correct> <note>Msgs-[Successful=1] [Failure=0]</note> <responseCode>0</responseCode> </result> </ns2:handleMultiTruckMessageResponse> </env:Body> </env:Envelope> 18 La PLN attualmente riconosce e gestisce i seguenti attributi al messaggio di posizione: attributeCode attributeValue descrizione INFOTRAFFIC_DATEX_CODE Codice DATEX Codice DATEX dell’evento scatenante il messaggio di Infotraffico POIEVENT_POI_NAME Nome POI Nome POI non operativo POIEVENT_DESCRIPTION Descrizione Descrizione dell’anomalia sul POI in esame POIEVENT_POIALTERNATIVE_NAME Nome POI Nome del POI alternativo proposto in vece di quello non operativo GEOFENCING_AREA_ID Id area UIRNet Identificativo dell’area relativa all’allarme GEOFENCING_AREA_DESCRIPTION Descrizione area UIRNet Descrizione dell’area relativa all’allarme GEOFENCING_AREA_TYPE assume i valori: VIETATA o OBBLIGATORIA Tipo dell’area relativa all’allarme GEOFENCING_THRESHOLD Valore in metri Soglia impostata per il geofencing GEOFENCING_DISTANCE Valore in metri Distanza dal confine dell’area di geofencing CORRIDOR_MISSION_ID Id missione Identificativo della missione dal cui percorso il veicolo si è discostato CORRIDOR_THRESHOLD Valore in metri Soglia impostata per il servizio CORRIDOR_DISTANCE Valore in metri Distanza dal percorso DOC_MISSION_ID Id missione Identificativo della missione DOC_CONTAINER_ID Id container (codice ISO) Identificativo del container con documentazione carente Il servizio restituisce una struttura dati di acknowledgement: RISPOSTA: HANDLEMULTITRUCKMESSAGERESPONSE Campo Tipo Descrizione result tns:wsAck Elenco di acknowledgement Campo Tipo Descrizione correct xs:boolean note xs:string responseCode xs:int WSACK 19 6 Allarmi La PLN invia ai SI messaggi di informazione ed allarme sui veicoli mediante l’invocazione di un Web Service su protocollo HTTPS realizzato sulla base del WSDL allegato ed esposto da ciascun SI. L’identificazione dell’interfaccia pubblica da contattare è realizzata a livello di Flotta mediante l’indicazione della Gateway. La PLN prevede due modalità di gestione delle Gateway: 1. Gateway privata: ciascuna azienda può inserire nella PLN, mediante le funzioni offerte dal modulo CRM, una o più Gateway da associare alle proprie flotte. Tali Gateway hanno carattere privato, ossia sono disponibili esclusivamente per l’Azienda che le implementa. 2. Gateway pubblica: le Gateway pubbliche possono essere inserite solo dal Back Office UIRNet secondo le procedure vigenti. Tali Gateway rappresentano interfacce pubbliche disponibili per più Aziende afferenti alla PLN (ad es. Gateway offerte da Sistemi di Gestione Flotta sul Cloud). Tipicamente tali Gateway sono implementate dal gestore di un servizio multi-tenant. La PLN, contestualmente all’apertura o alla chiusura di un evento d’allarme per un servizio configurato e per il quale sia stata anche configurato il dispatch verso legacy, genera il messaggio d’allarme (v. formato e dettagli), contatta attraverso un client ad-hoc il Web Service esposto dal SI ed invia il messaggio. L’invio delle informazioni legate alle segnalazioni d’allarme avviene richiamando il metodo handleAlertMessage esposto dal Web Service FLMServerService del SI. Sebbene a carico del SI, l’interfaccia del Web Service deve essere quella stabilita dalla PLN (v. paragrafo seguente). 6.1 FLMServerService Il presente paragrafo illustra il Web Service che deve essere esposto dal SI per la ricezione dei messaggi di informazione e di allarme. Il WSDL del servizio è riportato di seguito: WSDL - Allarmi <?xml version="1.0" encoding="UTF-8"?> <definitions name="FLMServerService" targetNamespace="http://ws.fleetman.uirnet.telespazio.com" xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tns="http://ws.fleetman.uirnet.telespazio.com" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <types> <xs:schema targetNamespace="http://ws.fleetman.uirnet.telespazio.com" version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="getStatus" type="tns:getStatus"/> <xs:element name="getStatusResponse" type="tns:getStatusResponse"/> <xs:element name="handleAlertMessage" type="tns:handleAlertMessage"/> <xs:element name="handleAlertMessageResponse" type="tns:handleAlertMessageResponse"/> <xs:complexType name="getStatus"> <xs:sequence/> </xs:complexType> <xs:complexType name="getStatusResponse"> <xs:sequence> <xs:element minOccurs="0" name="return" type="xs:string"/> </xs:sequence> 20 </xs:complexType> <xs:complexType name="handleAlertMessage"> <xs:sequence> <xs:element minOccurs="0" name="alarmMessage" type="tns:wsAlarmMessage"/> </xs:sequence> </xs:complexType> <xs:complexType name="wsAlarmMessage"> <xs:sequence> <xs:element minOccurs="0" name="alarmDescription" type="xs:string"/> <xs:element minOccurs="0" name="alarmId" type="xs:long"/> <xs:element minOccurs="0" name="alarmTS" type="xs:dateTime"/> <xs:element maxOccurs="unbounded" minOccurs="0" name="attributeList" nillable="true" type="tns:wsAlarmAttribute"/> <xs:element minOccurs="0" name="companyId" type="xs:long"/> <xs:element minOccurs="0" name="eventId" type="xs:long"/> <xs:element minOccurs="0" name="fleetExtId" type="xs:string"/> <xs:element minOccurs="0" name="serviceId" type="xs:string"/> <xs:element minOccurs="0" name="vehicleExtId" type="xs:string"/> </xs:sequence> </xs:complexType> <xs:complexType name="wsAlarmAttribute"> <xs:sequence> <xs:element minOccurs="0" name="attributeCode" type="xs:string"/> <xs:element minOccurs="0" name="attributeValue" type="xs:string"/> </xs:sequence> </xs:complexType> <xs:complexType name="handleAlertMessageResponse"> <xs:sequence> <xs:element minOccurs="0" name="return" type="tns:wsAlarmResponse"/> </xs:sequence> </xs:complexType> <xs:complexType name="wsAlarmResponse"> <xs:sequence> <xs:element minOccurs="0" name="responseCode" type="xs:string"/> <xs:element minOccurs="0" name="responseDescription" type="xs:string"/> </xs:sequence> </xs:complexType> </xs:schema> </types> <message name="FLMServer_handleAlertMessage"> <part element="tns:handleAlertMessage" name="handleAlertMessage"/> </message> <message name="FLMServer_getStatusResponse"> <part element="tns:getStatusResponse" name="getStatusResponse"/> </message> <message name="FLMServer_getStatus"> <part element="tns:getStatus" name="getStatus"/> </message> <message name="FLMServer_handleAlertMessageResponse"> <part element="tns:handleAlertMessageResponse" name="handleAlertMessageResponse"/> </message> <portType name="FLMServer"> <operation name="getStatus" parameterOrder="getStatus"> <input message="tns:FLMServer_getStatus"/> <output message="tns:FLMServer_getStatusResponse"/> </operation> 21 <operation name="handleAlertMessage" parameterOrder="handleAlertMessage"> <input message="tns:FLMServer_handleAlertMessage"/> <output message="tns:FLMServer_handleAlertMessageResponse"/> </operation> </portType> <binding name="FLMServerBinding" type="tns:FLMServer"> <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/> <operation name="getStatus"> <soap:operation soapAction=""/> <input> <soap:body use="literal"/> </input> <output> <soap:body use="literal"/> </output> </operation> <operation name="handleAlertMessage"> <soap:operation soapAction=""/> <input> <soap:body use="literal"/> </input> <output> <soap:body use="literal"/> </output> </operation> </binding> <service name="FLMServerService"> <port binding="tns:FLMServerBinding" name="FLMServerPort"> <soap:address location="http://94.95.24.70/FLMServer"/> </port> </service> </definitions> 6.1.1 getStatus Il metodo consente di verificare la piena operatività della Gateway. RICHIESTA: GETSTATUS Il messaggio OPERATIONTYPELIST non prevede alcun parametro. RICHIESTA: GETSTATUSRESPONSE Campo Tipo Descrizione return xs:string Stato del servizio. Valori ammessi: OK, 6.1.2 handleAlertMessage Il metodo consente al SI di ricevere un messaggio di informazioni o di allarme. RICHIESTA: HANDLEALERTMESSAGE Campo Tipo Descrizione alarmMessage tns:wsAlarmMessage Messaggio informativo o di allarme trasmesso al SI 22 WSALARMMESSAGE Campo Tipo Descrizione alarmId xs:long ID PLN del messaggio alarmDescription xs:string Descrizione del messaggio companyId xs:long ID PLN dell’azienda impattata dall’evento d’allarme fleetExtId xs:string ID SI della flotta impattata dall’evento d’allarme come registrato nel CRM vehicleExtId xs:string ID SI del veicolo impattato dall’evento d’allarme come registrato nel CRM eventId xs:long ID PLN dell’evento d’allarme serviceId xs:string Identificativo del servizio d’allarme che ha generato l’evento (cfr. tabella seguente) attributeList tns:wsAlarmAttribute Lista di attributi che veicolano le informazioni proprie dello specifico messaggio dall’allarme del quale effettuare il dispatching alarmTS xs:dateTime timestamp relativo alla (apertura/chiusura evento) comunicazione inerente l’allarme SERVICEID Valore Descrizione CORRIDOR MONITORING servizio di Corridor Monitoring (S/S ALR) INFOTRAFFIC servizio di Infotraffico base e su missione (S/S ALR) DOC servizio di Monitoraggio stato documentazione (S/S ALR) TIME MONITORING servizio di Time Monitoring (S/S ALR) GEOFENCING servizio di Geofencing (S/S ALR) SENSOR servizio di monitoraggio sensori (S/S ALR) TERMINAL servizio di monitoraggio stato terminali (S/S ALR) POIEVENT servizio di monitoraggio stato POI (S/S ALR) WSALARM ATTRIBUTE Campo Tipo Descrizione attributeCode xs:string Codice dell’attributo (cfr. tabella seguente) attributeValue xs:string Valore dell’attributo ATTRIBUTECODE Campo CORRIDOR INFOTRAFFIC Tipo Descrizione CORRIDOR_MISSION_ID identificativo della missione CORRIDOR_THRESHOLD soglia impostata sul servizio d’allarme CORRIDOR_DISTANCE distanza effettivamente misurata tra posizione e percorso INFOTRAFFIC_DATEX_CODE codice DATEX dell’evento perturbatore scatenante INFOTRAFFIC_EVENT_START_TS timestamp apertura evento INFOTRAFFIC_EVENT_CLOSE_TS timestamp chiusura evento INFOTRAFFIC_ORIGINAL_EVENT_NODE1_LAT latitudine del primo/unico nodo 23 DOC TIME INFOTRAFFIC_ORIGINAL_EVENT_NODE1_LON longitudine del primo/unico nodo INFOTRAFFIC_ORIGINAL_EVENT_NODE2_LAT latitudine del secondo (eventuale) nodo INFOTRAFFIC_ORIGINAL_EVENT_NODE2_LON longitudine del secondo (ev.) nodo INFOTRAFFIC_ORIGINAL_EVENT_DESCRIPTION descrizione evento scatenante DOC_MISSION_ID identificativo della missione DOC_CONTAINER_ID identificativo del container impattato (nel solo caso di missioni derivate) TIME_MISSION_ID identificativo missione TIME_DELAY ritardo/anticipo accumulato TIME_THRESHOLD soglia configurata nel servizio TIME_POI_ID identificativo del POI della missione (eventualmente) impattato dall’evento TIME_POI_ARRIVAL_PLANNED tempo pianificato d’arrivo al POI TIME_POI_ARRIVAL_ESTIMATED tempo stimato d’arrivo al POI GEOFENCING_AREA_ID identificativo dell’area GEOFENCING_AREA_DESCRIPTION descrizione dell’area GEOFENCING_AREA_TYPE tipologia di area in relazione al servizio (obbligatoria, critica o vietata) GEOFENCING_THRESHOLD soglia di geofencing GEOFENCING_DISTANCE distanza misurata tra la posizione del veicolo e il confine dell’area SENSOR_ID identificativo del sensore SENSOR_TYPE tipo di sensore, legato alla grandezza misurata SENSOR_VALUE valore misurato dal sensore SENSOR_THRESHOLD_L limite inferiore della soglia (unica, per i sensori digitali) SENSOR_THRESHOLD_R limite superiore della soglia (solo per sensori analogici) GEOFENCING SENSOR TERMINAL POIEVENT RISPOSTA: HANDLEALERTMESSAGERESPONSE Campo Tipo Descrizione return tns:wsAlarmResponse Struttura dati di risposta all’invio del messaggio informativo o di allarme Campo Tipo Descrizione responseCode xs:string responseDescription xs:string WSALARMRESPONSE 24 7 Tabellone degli Arrivi Il S/S ALR deve esporre un WS verso sistemi legacy per fornire le funzionalità del tabellone arrivi a sistemi esterni. L’azienda del sistema esterno deve essere dotato di pacchetto Control Tower. Ambiente URL Test https://test.uirnet.it/ALR_ExportWS/ArrivalsTabEnhancedWS?wsdl Produzione https://www.uirnet.it/ALR_ExportWS/ArrivalsTabEnhancedWS?wsdl 7.1 Descrizione Servizio 7.1.1 Web Service Il WS riceve in ingresso i seguenti dati: Id azienda, username, cim Dati del filtro di ricerca e restituisce in uscita i seguenti dati: Lista missioni in arrivo al POI selezionato, ordinate per arrivo stimato. Per ogni missione: informazioni generali sulla missione, sullo stato documentale, sulla merce da movimentare, ecc.. 7.1.2 Controllo sicurezza dati in input Sono implementati i controlli di sicurezza sulla base dei dati in input, come da paragrafo seguente 7.1.3 Selezioni missioni per l’output La selezione degli arrivi (missioni) viene effettuata su filtro di date (inserite esplicitamente dal legacy o considerando il range di default); vengono prese in considerazione tutte e sole le missioni che hanno data pianificata o data stimata/effettiva d’arrivo al POI selezionato inclusa nell’intervallo. Le missioni che presentano il POI ma non hanno né data stimata né data prevista in relazione al POI selezionato, non vengono prese in considerazione nel risultato. Il range temporale dovrà avere un’ampiezza massima di M giorni, M parametro di sistema non configurabile dall’utente (default=7) 7.1.4 Ordinamento missioni nell’output La lista degli arrivi (missioni) sarà ordinata per data di arrivo stimato al POI (per tutte quelle missioni che non presentato tale valore, ad esempio per tutte quelle pianificate, viene considerata la data pianificata). 7.1.5 Informazioni sulla prenotazione Le informazioni sulle prenotazioni associate al POI e alla missione sono accessibili da una Vista condivisa in dBLink dal S/S PRT (ALR_BOOKINGS). 7.2 getStatus Restituisce lo stato di operatività dell’interfaccia software stessa. RICHIESTA: GETSTATUS Il messaggio GETSTATUS non prevede alcun parametro. 25 RISPOSTA: GETSTATUSRESPONSE Campo Tipo Descrizione result xs:boolean Stato del servizio 7.3 Arrivals RICHIESTA:GETARRIVALSBOARD Campo Tipo Descrizione Obbl. userName xs:string Identificativo utente PLN S cim xs:string Pin di accesso ai Web Services S ReqId xs:string Identificativo richiesta N IdAzienda xs:long identificativo azienda S IdPOI xs:long identificativo POI S Targa veicolo xs:string targa veicolo N Stato missione xs:string N Data Inizio xs:dateTime Stato missione: (se non inserito considera “A”) ‘A’=attive, ‘P’=pianificate, ‘C’=chiuse, ‘AP’=attive o pianificate ‘T’=tutte data e ora di inizio range temporale N se non presente considerare default=now Data Fine xs:dateTime data e ora di fine range temporale N se inizio range valorizzato: inizio range + 1 giorno se inizio range non valorizzato: now +1 giorno) RISPOSTA:GETARRIVALSBOARDRESPONSE Campo Tipo Descrizione resultId xs:integer Id risultato resultCode xs:string codice risultato ReqId xs:string Identificativo richiesta Arrivi Lista di arrivo Lista delle missioni di arrivo Campo Tipo Descrizione Id missione xs:long Id missione nome missione xs:string nome della missione pianificazioneArrivo xs:string Identificativo richiesta Stima arrivo Lista di arrivo Lista delle missioni di arrivo Stato missione xs:string stato della missione ARRIVI 26 Targa xs:string targa del veicolo primo conducente xs:string primo conducente secondo conducente xs:string secondo conduente tel ref azienda xs:string telefono referente aziendale stato doc xs:string stato documentazione associata alla missione note doc xs:string note documentazione associata alla missione doc associati xs:string documentazione associata n prenotazioni xs:int numero prenotazioni della missione associata al POI selezionato posizione veicolo tns:posizioneVeicolo Posizione del veicolo Lista merce lista merce lista della merce da movimentare al POI Campo Tipo Descrizione Latitude xs:double Latitudine longitude xs:double longitudine indirizzo veicolo xs:string indirizzo posizione veicolo Campo Tipo Descrizione idMerce xs:string id merce tipo Merce xs:string tipologia della merce id ordine xs:string identificativo dell’ordine id prenotazione xs:string identificativo della prenotazione associata alla merce POSIZIONE VEICOLO MERCE VALORI DI RITORNO resultId 0 resultCode descrizione OK Operazione eseguita con successo 1000 TOO_MANY_REQUEST Troppe richieste nell’unità di tempo effettuate dall’azienda per il POI 1001 VOID_REQUEST_INPUT Dati in ingresso non valorizzati 1002 INVALID_USERNAME 1003 INVALID_CIM 1010 AUTHENTICATION_FAILURE 2000 POI_NOT_ALLOWED 2010 INPUT_NOT_COMPLETED 2020 RANGE_TOO_BIG Username non valido CIM non valido Autenticazione negata: username-cim-azienda non compatibili Il POI inserito non è consentito, perché non pubblico, non di proprietà diretta e non appartenente ad aziende figlie Parametri obbligatori in input non forniti Range temporale troppo ampio (max=7 giorni) 27 2030 RANGE_WRONG 2031 INVALID_MISSION_STATE 2032 INVALID_COMPANY_ID 2033 INVALID_POI_ID Identificativo POI non valido 9999 GENERIC_ERROR Errore generico, non specificato da altri codici Range temporale errato (data iniziale successiva a quella finale, date non valide,..) Stato missioni richieste sconosciuto Identificativo azienda non valido Esempio messaggio per il tabellone degli arrivi <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://ws.export.alr.uirnet.telespazio.com/"> <soapenv:Header/> <soapenv:Body> <ws:arrivals> <!--Optional:--> <arrivalsInput> <!--Optional:--> <reqID>emihfsakjh</reqID> <username>xxxxxxx</username> <cim>xxxxxx</cim> <idAzienda>xxxxx</idAzienda> <idPOI>xxxxxx</idPOI> <!--Optional:--> <targaVeicolo></targaVeicolo> <!--Optional:--> <statoMissione>T</statoMissione> <!--Optional:--> <dataIniziale> xxxx-xx-xxTxx:xx:xxZ </dataIniziale> <!--Optional:--> <dataFinale>xxxx-xx-xxTxx:xx:xxZ</dataFinale> </arrivalsInput> </ws:arrivals> </soapenv:Body> </soapenv:Envelope> Response (presenza di una sola missione pianificata) <env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"> <env:Header/> <env:Body> <ns2:arrivalsResponse xmlns:ns2="http://ws.export.alr.uirnet.telespazio.com/"> <arrivalsOutput> <reqID>emihfsakjh</reqID> <resultId>0</resultId> <resultCode>OK</resultCode> <listaArrivi> <arrivo> <idMissione>xxxxx</idMissione> <nomeMissione>xxxxxxx</nomeMissione> <pianificazioneArrivo>2013-09-06 18:00</pianificazioneArrivo> <statoMissione>P</statoMissione> <targa>xxxxxx</targa> <telRefAziendale>xxxxxxxx</telRefAziendale> <statoDocumentazione>KO</statoDocumentazione> <documentiAssociati>NO</documentiAssociati> 28 <nPrenotazioni>0</nPrenotazioni> <listaMerce> <merce> <id>xxxxxxxxx</id> <tipo>CONTAINER</tipo> <idPrenotazione>xxxxxxxx</idPrenotazione> </merce> </listaMerce> </arrivo> </listaArrivi> </arrivalsOutput> </ns2:arrivalsResponse> </env:Body> </env:Envelope> 8 Servizio di Messaggistica La PLN espone un Servizio di Messaggistica basato su Web Service sicuri su protocollo HTTPS. Tale servizio è deputato alla gestione delle comunicazioni da e verso il SI ed è il supporto di comunicazione per i Servizi di Prenotazioni (§ 8.11). I messaggi nel MDW EDI sono organizzati mediante dei Centro Messaggi, ovvero raggruppamenti logici di folder opportunamente nominati. Un centro messaggi è composto dai folder Inbox, Outbox e Draft e viene assegnato ad ogni azienda (utenza) che intenda scambiare messaggi con gli altri utenti della piattaforma. Il metodo di gestione dinamica dei messaggi è del tipo store-and-forward a 2 passi; un messaggio diretto da un utente ad un altro viene depositato (store) nel folder Outbox dell'utente mittente e poi spostato (forward) nel folder Inbox dell'utente destinatario. Le aziende che usufruiscono del servizio Middleware hanno 2 centro messaggi di default: INFO ed ERROR e una serie di centro messaggi dipendenti dai servizi sottoscritti forniti a supporto dalle applicazioni interne; questi centro messaggi vengono stabiliti dalle applicazioni stesse e sono specificati nei paragrafi dedicati alle applicazioni interne. Sia le aziende censite nel CRM che le applicazioni interne vengono identificate tramite codice univoco assegnato dal CRM. Per la comunicazione con i Servizi di Messaggistica sono esposti tre servizi fondamentali: putMessage per l’invio di un messaggio al MDW EDI. getUnreadMessages per ottenere la lista degli ID dei messaggi non letti getMessage per il recupero del messaggio identificato dall’ID. Sono inoltre presenti servizi per l’accesso a funzioni non essenziali per la realizzazione della comunicazione, ma utili per la gestione del processo: replyTo per rispondere ad un messaggio sendDraftMessage per inviare un messaggio “draft” updateDraftMessage per aggiornare lo stato di un messaggio “draft” getChildrenMessage per ottenere la lista degli ID dei messaggi correlati a quello specificato Le funzionalità ed i servizi della piattaforma sono usufruibili dai SI mediante invio e ricezione di messaggi strutturati; a questo scopo ciascun servizio pubblica una serie di messaggi ben definiti. Essi sono in formato 29 standard, ovvero XML, e sono veicolati dal Servizio di Messaggistica nel campo bodyXml della struttura travellingMessage. Richieste e risposte vengono elencate nei paragrafi che seguono con evidenziati classesottoclasse-codice. Inoltre, come già accennato, i moduli interni hanno un identificativo CRM che li contraddistingue nella comunicazione mediante il Servizio di Messaggistica; esso viene qui indicato assieme al centro messaggi usato per l’invio e la ricezione dei messaggi. Acronimo Applicazione Centro messaggi di invio/ricezione Id CRM ALR ALERT MANAGEMENT SERVER_ALERT_MNGMT 1 PRT PRENOTAZIONE SERVER_PRENOTAZIONE 7 MRP MARKETPLACE SERVER_MRP 8 MPE MERCI PERICOLOSE SERVER_MPE 9 I Web Server sicuri sono accessibili ai seguenti indirizzi: Ambiente URL Test https://test.uirnet.it/B2BBusinessLogic/publishedServices/b2BWsMessage?wsdl Produzione https://www.uirnet.it/B2BBusinessLogic/publishedServices/b2BWsMessage?wsdl 8.1 Mailbox La PLN assegna a ciascuna Azienda le Mailbox predefinite collegate ai Moduli di Gestione dei Servizi attivi. Le Mailbox vengono utilizzate da ciascun Modulo per inviare le comunicazioni inerenti la propria operatività. MAILBOX Nome Modulo Descrizione ALR_CM Corridor Monitor Mailbox per la ricezione degli allarmi relativi al corridor monitoring ALR_DM_EF Documentazione incompleta containerEasy fleet Mailbox per la ricezione degli allarmi relativi alla documentazione incompleta lato Azienda di trasporto (Smart Truck) ALR_DM_CT Documentazione incompleta containerControl Tower Mailbox per la ricezione degli allarmi relativi alla documentazione incompleta lato nodo logistico ALR_GF Geofencing Mailbox per la ricezione degli allarmi relativi al geofencing ALR_PE Routing Mailbox per la ricezione degli allarmi relativi a eventi in corso su POI di missione ALR_SM Sensor monitoring ALR_TE Evento traffico, traffico su missione ALR_TM Ricalcolo stimato tempo di arrivo Mailbox per la ricezione degli allarmi al tempo stimato di arrivo ALR_TS Stato terminali Mailbox per la ricezione degli allarmi relativi allo stato dei terminali ALR_VE Traffico anomalo verso nodo logistico Mailbox per la ricezione degli allarmi relativi al numero di veicoli diretti verso un nodo logistico ERROR MDW Mailbox dedicata alla comunicazione dei messaggi di errore del Sistema di Messaggistica Mailbox per la ricezione degli allarmi relativi al Monitoraggio sensori Evento Mailbox per la ricezione degli allarmi relativi ad eventi perturbativi della viabilità 30 INFO MDW MARKETPLACE MRP PRENOTAZIONI PRT NEWSLETTER Mailbox dedicata alla comunicazionecon il Sistema di Gestione delle Prenotazioni Mailbox per la ricezione della newsletter informativa periodica TRANSLATION 8.2 putMessage Il servizio putMessage consente l’invio di un messaggio ad uno o più destinatari, siano questi utenti o servizi della PLN. La chiamata prevede una serie di parametri: RICHIESTA: PUTMESSAGE Campo Tipo Descrizione message tns:TravellingMessage Messaggio da inviare userName xs:string Identificativo utente PLN cim xs:string Pin di accesso ai Web Services folderType xs:string Folder (Outbox,Inbox,Draft) Il parametro folderType identifica la cartella a cui effettuare il delivery della putMessage (per messaggi in uscita il valore del campo deve essere Outbox, per il salvataggio di una bozza del messaggio il valore deve essere Draft) Il parametro message contiene le indicazioni circa il destinatario del messaggio ed il contenuto del messaggio da inviare. Tale struttura dati, rappresentata da un complexType XML, è così costituita: TRAVELLINGMESSAGE Campo Tipo Descrizione header tns:header Informazioni sul routing del messaggio body tns:body Corpo del messaggio La struttura dati HEADER contiene le informazioni per l’instradamento del messaggio e la descrizione del suo formato: HEADER Campo Tipo Descrizione messageCode xs:string Codice messaggio messageClass xs:string Classe messaggio messageSubClass xs:string Sottoclasse messaggio priority xs:long Priorità messaggio (default 1) timestamp xs:dateTime Data-ora invio originalFormat xs:string Formato messaggio callerId xs:long Id Azienda (CRM CompanyId) composer xs:string Utente (CRM userName = userId) 31 mailboxSender xs:string Centro messaggi di riferimento receivers tns:msgReceiverWithFormat Lista destinatari subject xs:string Soggetto messaggio Il parametro MSGRECEIVERWITHFORMAT è una sequence che identifica i destinatari del messaggio, consentendo anche di impostare formati di transcodifica differenti per ciascun destinatario: MSGRECEIVERFORMAT Campo Tipo Descrizione receiverId xs:long Identificativo del destinatario mailboxName xs:string Centro messaggi formatName xs:string Formato del messaggio La struttura dati BODY contiene il corpo del messaggio ed eventuali attachment: BODY Campo Tipo Descrizione bodyNatural xs:string Messaggio da inviare: formato nativo body Xml xs:string Messaggio da inviare: formato xml di piattaforma incapsulato in un tag CDATA attachments tns:attachments Lista allegati Ciascun ATTACHMENT è identificato da due parametri: ATTACHMENT Campo Tipo Descrizione fileName xs:string Nome allegato file Body xs:string Corpo allegato entrambi obbligatori e di lunghezza non inferiore ad 1. Il parametro fileBody deve essere codificato Base64 per la trasmissione. RISPOSTA: PUTMESSAGERESPONSE Campo Tipo Descrizione return xs:long Progressivo del messaggio inserito Tale valore deve essere memorizzato dal SI per identificare il messaggio inviato per eventuali riferimenti in future comunicazioni. Nell’esempio sotto viene riportata una chiamata per uno specifico messaggio diretto al sistema Prenotazione; in particolare si tratta di una richiesta della lista dei servizi prenotabili. Da notare che il campo <bodyXml> contiene a sua volta un messaggio in formato XML di piattaforma così come si attende il sistema Prenotazioni. Esempio 32 <pub:putMessage> <message> <header> <msgId xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xsi:nil='true'/> <messageCode>LISTA_SERVIZI</messageCode> <messageClass>PRT</messageClass> <messageSubClass>INQUIRY</messageSubClass> <priority>0</priority> <timestamp>2012-05-02T12:00:00</timestamp> <originalFormat>UirnetFormat</originalFormat> <callerId>xxxxx</callerId> <composer>xxxx</composer> <mailboxSender>PRENOTAZIONI</mailboxSender> <!—Zero or more repetitions:--> <receivers> <receiverId>7</receiverId> <mailboxName>SERVER_PRENOTAZIONE</mailboxName> <formatName>UirnetFormat</formatName> </receivers> <subject>Lista dei servizi di booking</subject> </header> <body> <bodyXml><![CDATA[<?xml version="1.0" encoding="UTF-8"?> <ns0:ListServices xmlns:ns0="com.elsagdatamat.uirnet.prenotazioni.messageclass" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <requestId>R123ap</requestId> <serviceState>1</serviceState> </ns0:ListServices>]]></bodyXml> </body> </message> <folderType>Outbox</folderType> <userName>xxxxx</userName> <cim>xxxxx</cim> </pub:putMessage> Response <env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"> <env:Header/> <env:Body> <ns2:putMessageResponse xmlns:ns2="http://ws.bll.b2b.elsagdatamat.com/"> <return>1079180</return> </ns2:putMessageResponse> 33 </env:Body> </env:Envelope> 8.3 getUnreadMessages Il servizio fornisce l’elenco degli ID dei messaggi da leggere per la mailbox indicata di proprietà dell’utente autenticato. RICHIESTA: GETUNREADMESSAGES Campo Tipo Descrizione companyId xs:long ID Uirnet dell’azienda mailboxContainer xs:string Centro messaggi (PRENOTAZIONI, ERROR, INFO,..) folderType xs:string Folder (Outbox, Inbox) userName xs:string Nome utente – username accesso PLN cim xs:string Pin di accesso ai Web Services I seguenti parametri sono utilizzati per individuare il centro messaggi da cui recuperare la lista dei messaggi non letti: companyId: identifica l’azienda (Id Azienda) mailboxSender: identifica il centro messaggi da interrogare folderType: identifica la cartella da interrogare RISPOSTA: GETUNREADMESSAGESRESPONSE Campo Tipo Descrizione return xs: List<Long> Lista degli ID dei messaggi non letti La risposta è costituita dall’elenco dei messaggi non letti del centro messaggi specificato dal parametro return, una sequenza di messageId dei messaggi non letti. Se ai parametri della richiesta non corrisponde alcun messaggio la risposta è una lista vuota. Qui sotto viene riportato un esempio di chiamata per ottenere la lista dei messaggi non letti contenuti nel folder Inbox del centro messaggi INFO. Esempio <pub:getUnreadMessages> <companyId>xxxxx</companyId> <mailboxSender>INFO</mailboxSender> <folderType>Inbox</folderType> <userName>xxxx</userName> <cim>xxxxx</cim> </pub:getUnreadMessages> Response 34 <env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"> <env:Header/> <env:Body> <ns2:getUnreadMessagesResponse xmlns:ns2="http://ws.bll.b2b.elsagdatamat.com/"> <return>155866</return> <return>155871</return> <return>155876</return> <return>155883</return> <return>155886</return> <return>155893</return> </ns2:getUnreadMessagesResponse> </env:Body> </env:Envelope> 8.4 getMessage Il servizio restituisce il messaggio con l’id specificato nella richiesta. RICHIESTA: GETMESSAGE Campo Tipo Descrizione middlewareMsgId xs:long ID messaggio userName xs:string Username PLN per l’accesso al servizio cim xs:string Pin di accesso ai Web Services Il parametro middlewareMsgId identifica il messaggio da recuperare. RISPOSTA: GETMESSAGERESPONSE Campo Tipo Descrizione return xs:ExtendedTravellingMessage Messaggio Il parametro return della risposta contiene il messaggio caratterizzato dai seguenti parametri: EXTENDEDTRAVELLINGMESSAGE Campo Tipo Descrizione travellingMessage xs:travellingMessage Vedi descrizione in par. 0Errore. L'origine riferimento non stata trovata. mifId xs:long wrongMsgInFolder xs:long ancestorMsgInFolder xs:long globalAncestorMsgInF older xs:long replyOfMsgInFolder xs:long Inserted xs:date firstAccess xs:date Campi ad uso interno (riservati) 35 error xs:boolean errorManaged xs:date ruleNotApplied xs:date read xs:date deleted xs:date L’esempio sotto mostra una chiamata per ottenere il messaggio numero 970044 (in grigetto i campi dell’ ExtendedTravellingMessage recanti informazioni inerenti le elaborazioni subìte dal messaggio). Esempio <pub:getMessages> <middlewareMessageId>970044</middlewareMessageId> <userName>xxxxx</userName> <cim>xxxxx</cim> </pub:getMessages> Response <env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"> <env:Header/> <env:Body> <ns2:getMessageResponse xmlns:ns2="http://ws.bll.b2b.elsagdatamat.com/"> <return> <header> <msgId>970044</msgId> <messageCode>WSRESPONSE</messageCode> <messageClass>TAA</messageClass> <messageSubClass>EPORT</messageSubClass> <priority>0</priority> <timestamp>2012-03-20T15:32:59.518+01:00</timestamp> <originalFormat>UirnetFormat</originalFormat> <callerId>xxx</callerId> <composer>xxx</composer> <mailboxSender>INFO</mailboxSender> <receivers> <receiverId>11081</receiverId> <mailboxName>INFO</mailboxName> <formatName>UirnetFormat</formatName> </receivers> <subject>Invio integrazione 001</subject> </header> <body> 36 <bodyNatural>Prova invio massivo da az. 313 verso az.11081</bodyNatural> </body> <mifId>970044</mifId> <wrongMsgInFolder>0</wrongMsgInFolder> <ancestorMsgInFolder>969334</ancestorMsgInFolder> <globalAncestorMsgInFolder>969334</globalAncestorMsgInFolder> <replyOfMsgInFolder>0</replyOfMsgInFolder> <inserted>2012-03-20T15:33:03.477+01:00</inserted> <firstAccess>2012-05-07T16:26:29.271+02:00</firstAccess> <error>false</error> <ruleNotApplied>2012-03-20T15:33:17.429+01:00</ruleNotApplied> <read>2012-05-07T16:26:29.271+02:00</read> </return> </ns2:getMessageResponse> </env:Body> </env:Envelope> 8.5 replyTo Invia una risposta al messaggio indicato. RICHIESTA: REPLYTO Campo Tipo Descrizione middlewareMsgId xs:long ID messaggio message tns:TravellingMessage Messaggio da inviare userName xs:string Username PLN per l’accesso al servizio cim xs:string Pin di accesso ai Web Services Il parametro middlewareMsgId identifica il messaggio a cui si sta rispondendo e il parametro message la risposta da inviare RISPOSTA: REPLYTORESPONSE Campo Tipo Descrizione return xs:long Progressivo del messaggio inserito Tale valore deve essere memorizzato dal SI per identificare il messaggio inviato per eventuali riferimenti in future comunicazioni. 8.6 sendDraftMessage Il servizio provvede ad inviare un messaggio bozza precedentemente salvato nella mailbox dell’utente. RICHIESTA: SENDDRAFTMESSAGE Campo Tipo Descrizione middlewareMsgId xs:long ID messaggio userName xs:string Username PLN per l’accesso al servizio 37 cim xs:string Pin di accesso ai Web Services Il parametro middlewareMsgId identifica il messaggio in bozza da inviare. RISPOSTA: SENDDRAFTMESSAGERESPONSE Il messaggio di ritorno non contempla alcun parametro. 8.7 updateDraftMessage Il servizio consente di inserire o modificare un messaggio in bozza nel Servizio di Messaggistica. RICHIESTA: UPDATEDRAFTMESSAGE Campo Tipo Descrizione middlewareMsgId xs:long ID messaggio message tns:TravellingMessage Messaggio userName xs:string Username PLN per l’accesso al servizio cim xs:string Pin di accesso ai Web Services Il parametro middlewareMsgId identifica il messaggio da aggiornare e il parametro message il contenuto aggiornato da memorizzare. RISPOSTA: UPDATEDRAFTMESSAGERESPONSE Il messaggio di ritorno non contempla alcun parametro. 8.8 deleteDraftMessage Elimina il messaggio in bozza specificato. RICHIESTA: DELETEDRAFTMESSAGE Campo Tipo Descrizione middlewareMsgId xs:long ID messaggio userName xs:string Username PLN per l’accesso al servizio cim xs:string Pin di accesso ai Web Services Il parametro middlewareMsgId identifica il messaggio in bozza da inviare. RISPOSTA:DELETEDRAFTMESSAGERESPONSE Il messaggio di ritorno non contempla alcun parametro. 8.9 getChildrenMessage Ottiene gli ID dei figli del messaggio specificato RICHIESTA: GETCHILDRENMESSAGES Campo Tipo Descrizione middlewareMsgId xs:long ID messaggio userName xs:string Username PLN per l’accesso al servizio cim xs:string Pin di accesso ai Web Services Il parametro middlewareMsgId identifica il messaggio in bozza da inviare. 38 RISPOSTA: GETCHILDRENMESSAGESRESPONSE Campo Tipo Descrizione return xs:list<long> Lista degli ID dei messaggi collegati La risposta è costituita dall’elenco dei messaggi collegati a quello specificato nel parametro return, una sequenza di messageId dei messaggi figli. Se ai parametri della richiesta non corrisponde alcun messaggio la risposta è una lista vuota. 8.10 Gestione delle eccezioni In caso di errore viene restituito la struttura dati WSEXCEPTION caratterizzato dal seguente schema: WSEXCEPTION Campo Tipo Descrizione errCode xs:string Codice eccezione message xs:string Chiave messaggio Di seguito vengono presentati i codici di errore restituiti dalle chiamate ai Web Services. L’informazione e’ completata dallo stack trace dell’errore avvenuto. ERRCODE Codice eccezione Chiave eccezione Descrizione B2B_SLE_0070 MAILBOX_NOT_FOUND Centro Messaggi indicato non esistente B2B_SLE_0071 MESSAGECODE_NOT_FOUND Codice Messaggio indicato non esistente B2B_SLE_0090 MAE_ACTION_LOADING_FAILED Errore in fase di caricamento di una azione B2B_SLE_0120 MAE_ERROR_HTTP_CONNECTION Errore di connessione HTTP B2B_SLE_0130 MAE_ERROR_CREATING_XMLDOC_FROMSTRING Errore di trasformazione XML. B2B_SLE_0150 ERROR_DURING_MESSAGEINFOLDER_LOADING Errore di caricamento messaggio B2B_SLE_0230 MESSAGE_WRONG_PARAMETER_FORMAT Errore nel formato dei parametri della chiamata B2B_SLE_0290 MESSAGE_NOT_FOUND Messaggio non trovato B2B_SLE_0300 COMPANY_NOT_FOUND Azienda indicata non esistente SLE_0000 GENERIC Errore generico SLE_0001 GENERIC_WITH_MESSAGE Errore generico nel messaggio SLE_0010 ENTITY_NOT_FOUND Entita’ non trovata SLE_0020 DB_ERROR_DATAINTEGRITY Errore di integrita’ database SLE_0030 DB_ERROR_OPTIMISTIC_LOCK Errore di lock ottimistico database SLE_0040 ENTITY_PROPERTY_NOT_FOUND Proprieta’ non trovata SLE_0050 MISSING_ARGS Argomenti alla chiamata mancanti SLE_0060 FILE_NOT_FOUND File non trovato SLE_0130 GENERIC_IO Errore generico di I/O SLE_0160 TYPING_CAST_EXCEPTION Errore di cast tipo dato SLE_0180 MANDATORY_PROPERTY_NOT_SET Proprieta’ obbligatoria 39 SLE_0200 XML_TRANFORMATION_ERROR Errore nella trasformazione XML SLE_0210 XML_STRING_TO_DOC_ERROR Errore di conversione da XML a documento. SLE_0212 XML_DOC_TO_STRING_ERROR Errore di conversione da Documento a stringa SLE_0212 XML_MARSHALLING_OBJ_ERROR Errore di Marshalling SLE_0213 XML_VALIDATION_ERROR Errore di validazione corpo messaggio xml SLE_0220 EXCEPTION_IDENTIFIER_INVALID Identificatore non valido 8.11 Casi d’uso In questo paragrafo vengono rappresentati alcuni casi d’uso del Sistema di Messaggistica della PLN al fine di meglio chiarire le modalità di implementazione dell’integrazione dei SI con tale servizio. 8.11.1 Invio di un Messaggio alla PLN Il presente caso d’uso è legato all’invio di un messaggio strutturato alla PLN per l’accesso ad uno dei servizi esposti dalla Piattoforma. Obiettivo Invio di un messaggio alla PLN Precondizioni Il SI dispone delle credenziali per interoperare con la PLN (Username e PIN di accesso e ID azienda) Postcondizione di successo Il WS restituisce un messaggio PLN Postcondizione di fallimento Il WS restituisce un errore nella forma WSEXCEPTION Estende il caso d’uso NA Specializza il caso d’uso NA Include il caso d’uso NA Sequenza di azioni 1. 2. 3. PUTMESSAGERESPONSE con l’identificativo del messaggio acquisito dalla Il SI predispone il messaggio secondo il formato previsto dalla PLN Il SI richiama il servizio PUTMESSAGE della PLN e trasmette il messaggio Il servizio PUTMESSAGE risponde alla richiesta del SI 40 Sequence Diagram 41 8.11.2 Ricezione dei Messaggi dalla PLN 42 9 Sistema di Gestione delle Prenotazioni La PLN offre un sistema di gestione delle prenotazioni a supporto degli autotrasportatori e dei nodi logistici. Il Sistema di Gestione delle Prenotazioni si integra con i SI degli autotrasportatori e dei nodi logistici mediante l’uso di messaggi strutturati. Essi sono in formato standard, ovvero XML, e sono veicolati dal Servizio di Messaggistica nel campo bodyXml della struttura TRAVELLINGMESSAGE. Richieste e risposte vengono elencate nei paragrafi che seguono con evidenziati classe-sottoclasse-codice. Inoltre, come già accennato, i moduli interni hanno un identificativo CRM che li contraddistingue nella comunicazione mediante il Servizio di Messaggistica; Per inviare messaggi al Sistema di Gestione delle Prenotazioni i parametri del messaggio PUTMESSAGE sono: HEADER Campo Valore originalFormat UirnetFormat mailboxSender PRENOTAZIONI RECEIVERS Campo Valore mailboxName SERVER_PRENOTAZIONE receiverId 7 formatName UirnetFormat Le comunicazioni del Sistema di Gestione delle Prenotazioni vengono archiviate nella MailBox PRENOTAZIONI/Inbox dell’Azienda se la policy di dispatching ai SI è attiva. Il Sistema di Gestione delle Prenotazioni permette di configurare i servizi e le richieste di prenotazione agli stessi. L’operatività dell’interfaccia Web è replicata in massima parte nella messaggistica, consentendo l’implementazione dei processi di Prenotazione anche da SI esterni. Il Sistema di Gestione delle Prenotazioni definisce i seguenti messaggi suddivisi per tipologia di attività: Catalogo dei servizi o ListTypologies o DetailTypology o SchemaServiceByTipology o ListServices o DetailService o SchemaBookingByService o ServiceState Amministrazione dei servizi o InsertService 43 o UpdateService o UpdateServiceState Gestione della prenotazioni o InsertBooking o UpdateBooking o UpdateBookingState o ListBookings o ListBookingsDocuments o BookingState o DetailBooking o DetailBookingDocuments o BookingNotify o BookingForward o BookingReminder 9.1 Accesso al Catalogo dei Servizi I messaggi di questa categoria consentono di interrogare il Catalogo dei Servizi al fine di ottenere informazioni circa le tipologie ed i servizi pubblicati, con i dettagli e le informazioni sullo stato, nonché gli schemi xsd delle componenti specifiche dei messaggi per tipologia o servizio. 9.1.1 ListTypologies Consente di ottenere la lista delle tipologie di servizi definite nella piattaforma. L’interrogazione è consentita ad utenze con ruolo Fornitore Booking. Campo Valore messageCode LISTA_TIPOLOGIE messageClass PRT messageSubClass INQUIRY RICHIESTA: LISTTYPOLOGIES Campo Tipo Descrizione Obbl. requestId xs:string Identificativo richiesta attribuito dal SI per l’individuazione della conversazione N serviceClassId xs: long Identificativo Classe di Servizi N RISPOSTA: LISTTYPOLOGIESRESPONSE Campo Tipo Descrizione requestId xs:string Identificativo richiesta attribuito dal SI per l’individuazione della conversazione 44 listTypologiesResponse xs:ServicesTypeInfo[0..n] Lista delle Tipologia di Servizi Campo Tipo Descrizione serviceClassId xs:long Identificativo Classe di Servizi serviceTypeCode xs:string Codice della tipologia di servizio serviceTypeDescription xs:string Descrizione della tipologia di servizio serviceTypeId xs:long Identificativo della tipologia di servizi serviceTypeName xs:string Nome della tipologia di servizi SERVICESTYPEINFO ESEMPIO Lista delle tipologie di servizi (bodyXml) <ns0:ListTypologiesxmlns:ns0="com.elsagdatamat.uirnet.prenotazioni.messageclass" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <requestId>Req8958</requestId> <serviceClassId>1</serviceClassId> </ns0:ListTypologies> Messaggio di risposta <ns2:ListTypologiesResponse xmlns:ns2="com.elsagdatamat.uirnet.prenotazioni.messageclass" xmlns:ns3="com.elsagdatamat.uirnet.prenotazioni.gconfErrori"> <requestId> Req8958</requestId> <return> <serviceClassId>1</serviceClassId> <serviceTypeCode>SRVTYPES 56</serviceTypeCode> <serviceTypeDescription>servizio cinquantasei</serviceTypeDescription> <serviceTypeId>56</serviceTypeId> <serviceTypeName>serv_typ</serviceTypeName> </return> <return> <serviceClassId>1</serviceClassId> <serviceTypeCode>SRVTYPES62</serviceTypeCode> <serviceTypeDescription>prova visualizzazione car.</serviceTypeDescription> <serviceTypeId>62</serviceTypeId> <serviceTypeName>provavis</serviceTypeName> </return> </ns2:ListTypologiesResponse> 9.1.2 DetailTypology Restituisce i dettagli di una tipologia. 45 Richiesta autorizzata al solo ruolo Fornitore Booking. Campo Valore messageCode DETTAGLIO_TIPOLOGIA messageClass PRT messageSubClass INQUIRY RICHIESTA:DETAILTYPOLOGY Campo Tipo Descrizione Obbl. requestId xs:string Identificativo richiesta attribuito dal SI per l’individuazione della conversazione N serviceTypeId xs:long Identificativo della tipologia di servizi S RISPOSTA:DETAILTYPOLOGYRESPONSE Campo Tipo Descrizione requestId xs:string Identificativo richiesta attribuito dal SI per l’individuazione della conversazione return xs: typologyDetail Stato del servizio Campo Tipo Descrizione serviceTypeId xs:long Identificativo della tipologia di servizi serviceClassId xs:long Identificativo Classe di Servizi code xs:string Codice del servizio name xs:string Nome del servizio description xs:string Descrizione del servizio operationDate xs:dateTime Data di inserimento/modifica regNumber xs:long Versione tipologia regNumberf xs:long Versione tipologia precedente state xs:int Stato del servizio userName xs:string Username PLN per l’accesso al servizio flagConfirmDate xs:boolean Flag conferma manuale prenotazione attributes tns:Attributes Caratteristiche proprie del servizio richiesto TYPOLOGYDETAIL ESEMPIO Dettaglio tipologia (bodyXml) <ns0:DetailTypology xmlns:ns0="com.elsagdatamat.uirnet.prenotazioni.messageclass" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <requestId>R123ap</requestId> <serviceTypeId>2</serviceTypeId> </ns0:DetailTypology> 46 Messaggio di risposta <ns2:DetailTypologyResponsexmlns:ns2="com.elsagdatamat.uirnet.prenotazioni.messageclass" xmlns:ns3="com.elsagdatamat.uirnet.prenotazioni.gconfErrori"> <requestId>R123ap</requestId> <return> <srvTypesId>2</srvTypesId> <srvClassId>2</srvClassId> <code>SRVTYPES2</code> <name>Aree di Sosta</name> <description>Aree di sosta</description> <operationDate>2011-02-14T13:24:13.181+01:00</operationDate> <regNumber>2</regNumber> <regNumberf>0</regNumberf> <state>1</state> <userName>user</userName> <flagConfirmDate>false</flagConfirmDate> <attributes> <customAttributes> <truckData> <sd type="string" /> <shipowner type="string" /> <terminalVoyageId type="string" /> <asas type="string" /> <portOfArrivalCode type="string" /> <arrivalDate type="date" /> <typevehicles type="string"> <values> <value>Autotreni</value> <value>Motrici</value> <value>Rimorchi</value> <value>Rimorchi</value> <value>Semirimorchi</value> </values> </typevehicles> </truckData> <caratteristiche> <commodityType type="string" /> 47 <prova type="string"> <values> <value>a</value> </values> </prova> <etd type="dateTime" /> <shipIMONumber type="string" /> <containerList> <container type="repeater"> <shipCallSign type="string" /> <asas type="string" /> <externalScannerInspection type="boolean" /> <shipownerBicCode type="string" /> </container> </containerList> <licenzevehicles type="string" /> <externalScannerInspection type="boolean" /> <eta type="dateTime" /> <asas type="string" /> <ADRclass type="string" /> <terminalCode type="string" /> </caratteristiche> </customAttributes> </attributes> </return> </ns2:DetailTypologyResponse> 9.1.3 SchemaServiceByTipology Consente di ottenere lo schema di un serviziodefinito sulla piattaforma, specificandone la tipologia. Campo Valore messageCode SCHEMA_SERVIZIO messageClass PRT messageSubClass INQUIRY RICHIESTA: SCHEMASERVICEBYTYPOLOGY Campo Tipo Descrizione Obbl. requestId xs:string Identificativo richiesta attribuito dal SI per l’individuazione della conversazione N typeId xs:long Identificativo Tipologia del Servizio N 48 RISPOSTA: SCHEMASERVICEBYTYPOLOGYRESPONSE Campo Tipo Descrizione requestId xs:string Identificativo richiesta attribuito dal SI per l’individuazione della conversazione return xs: string Schema del Servizio ESEMPIO Elenco prenotazioni (bodyXml) <ns0:SchemaServiceByTypology xmlns:ns0="com.elsagdatamat.uirnet.prenotazioni.messageclass" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <requestId>R123ap</requestId> <typeId>145</typeId> </ns0:SchemaServiceByTypology> Messaggio di risposta <ns2:SchemaServiceByTypologyResponse xmlns:ns2="com.elsagdatamat.uirnet.prenotazioni.messageclass" xmlns:ns3="com.elsagdatamat.uirnet.prenotazioni.gconfErrori"> <requestId>R123ap</requestId> <return> <?xml version="1.0" encoding="UTF-8"?> <xs:schema xmlns="com.elsagdatamat.uirnet.prenotazioni.messageclass" xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="com.elsagdatamat.uirnet.prenotazioni.messageclass"> Schema xml del servizio richiesto </xs:schema> </return> </ns2:SchemaServiceByTypologyResponse> 9.1.4 ListServices Restituisce l’elenco dei servizi che corrispondono alle condizioni date. Campo Valore messageCode LISTA_SERVIZI messageClass PRT messageSubClass INQUIRY RICHIESTA:LISTSERVICES Campo Tipo Descrizione Obbl. requestId xs:string Identificativo richiesta attribuito dal SI per l’individuazione della conversazione N sellerId xs:long Identificativo del Fornitore N 49 serviceTypeId xs:long Identificativo della tipologia di servizio N serviceState xs:integer Stato del servizio N poiId xs:long Identificativo del POI N RISPOSTA: LISTSERVICESRESPONSE Campo Tipo Descrizione requestId xs:string Identificativo richiesta attribuito dal SI per l’individuazione della conversazione listServicesResponse xs:ServiceInfo[0..n] Lista dei Servizi Campo Tipo Descrizione sellerId xs:long Identificativo del Fornitore serviceId xs:long Identificativo del Servizio serviceCode xs:string Codice del Servizio serviceDescription xs:string Descrizione del Servizio serviceState xs:int Stato del Servizio servicesTypeId xs:long Identificativo della Tipologia di Servizi SERVICEINFO ESEMPIO Lista dei servizi attivi (stato=1) sulla piattaforma (bodyXml) <ns0:ListServices xmlns:ns0="com.elsagdatamat.uirnet.prenotazioni.messageclass" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <requestId>Req123</requestId> <serviceState>1</serviceState> </ns0:ListServices> Messaggio di risposta <ns2:ListServicesResponse xmlns:ns2="com.elsagdatamat.uirnet.prenotazioni.messageclass" xmlns:ns3="com.elsagdatamat.uirnet.prenotazioni.gconfErrori"> <requestId>Req123</requestId> <return> <sellerId>11086</sellerId> <serviceCode>TAA-WEB</serviceCode> <serviceDescription>preavviso di arrivo web modificato</serviceDescription> <serviceId>2</serviceId> <serviceState>1</serviceState> <serviceTypeId>1</serviceTypeId> </return> 50 <return> <sellerId>11086</sellerId> <serviceCode>TAA-WAR</serviceCode> <serviceDescription> preavviso di arrivo web con acquisizione automatica </serviceDescription> <serviceId>3</serviceId> <serviceState>1</serviceState> <serviceTypeId>1</serviceTypeId> </return> </ns2:ListServicesResponse> 9.1.5 DetailService Restituisce i dettagli di un servizio presente nella piattaforma. Campo Valore messageCode DETTAGLIO_SERVIZIO messageClass PRT messageSubClass INQUIRY RICHIESTA: DETAILSERVICE Campo Tipo Descrizione Obbl. requestId xs:string Identificativo richiesta attribuito dal SI per l’individuazione della conversazione N serviceId xs:long Identificativo del Servizio N RISPOSTA:DETAILSERVICERESPONSE Campo Tipo Descrizione requestId xs:string Identificativo richiesta attribuito dal SI per l’individuazione della conversazione detailServiceResponse xs: serviceDetail Dettaglio dei servizio Campo Tipo Descrizione srvId xs:long Identificativo del Servizio srvTypesId xs:long Identificativo Tipologia di Servizio srvTypesCode xs:string Codice della Tipologia di servizio operationDate xs:dateTime Data di inserimento/modifica description xs:string Descrizione del servizio shortDescription Xs:string Descrizione sintetica del servizio code xs:string Codice del servizio SERVICEDETAIL 51 sellerId xs:long Identificativo del Fornitore state xs:integer Stato del servizio Costs xs:string Tariffe del servizio policyChanges xs:string Politiche di modifica/cancellazione locationId xs:long Identificativo indirizzo fornitura userName xs:string Identificativo utente flagOrigine xs:string Origine inserimento/modifica (W per Web, L per Legacy, C per Schedulatore CRON) startDate xs:dateTime Data di inizio validità del servizio endDate xs:dateTime Data di fine validità del servizio pv xs:string Provincia di fornitura del servizio automaticAccept xs:boolean Servizio ad accettazione automatica della prenotazione limit xs:string Limitazioni al servizio addressUrl xs:string Link al sito del fornitore times xs:string Orari del servizio closingPeriods xs:periodInfo Periodi di non prenotabilità del servizio attributes Caratteristiche proprie del servizio richiesto PERIODINFO Campo Tipo Descrizione startDate xs:dateTime Data inizio endDate xs:dateTime Data fine Dettaglio servizio (bodyXml) <ns0:DetailServicexmlns:ns0="com.elsagdatamat.uirnet.prenotazioni.messageclass" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <requestId>R676</requestId> <serviceId>3</serviceId> </ns0:DetailService> Messaggio di risposta <ns2:DetailServiceResponse xmlns:ns2="com.elsagdatamat.uirnet.prenotazioni.messageclass" xmlns:ns3="com.elsagdatamat.uirnet.prenotazioni.gconfErrori"> <requestId>R676</requestId> <return> <srvId>3</srvId> <srvTypesId>1</srvTypesId> <srvTypesCode>SRVTYPES1</srvTypesCode> 52 <operationDate>2011-09-19T14:44:29.070+02:00</operationDate> <description>preavviso di arrivo web con acquisizione automatica</description> <shortDescription>preavviso di arrivo web acq. automatica</shortDescription> <code>TAA-WAR</code> <sellerId>11086</sellerId> <state>3</state> <locationId>10607</locationId> <userName> user</userName> <flagOrigine>W</flagOrigine> <pv>TORINO</pv> <automaticAccept>false</automaticAccept> <attributes> <customAttributes> (…) Lista di attributi definiti sul servizio </customAttributes> </attributes> </return> </ns2:DetailServiceResponse> 9.1.6 SchemaBookingByService Consente di ottenere lo schema di una prenotazione specificando il servizio definito sull piattaforma. Campo Valore messageCode SCHEMA_PRENOTAZIONE messageClass PRT messageSubClass INQUIRY RICHIESTA: SCHEMABOOKINGBYSERVICE Campo Tipo Descrizione Obbl. requestId xs:string Identificativo richiesta attribuito dal SI per l’individuazione della conversazione N serviceId xs:long Identificativo del Servizio N RISPOSTA: SCHEMABOOKINGBYSERVICERESPONSE Campo Tipo Descrizione requestId xs:string Identificativo richiesta attribuito dal SI per l’individuazione della conversazione return xs: string 53 ESEMPIO Schema prenotazione (bodyXml) <ns0:SchemaBookingByService xmlns:ns0="com.elsagdatamat.uirnet.prenotazioni.messageclass" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <requestId>R123ap</requestId> <serviceId>145</serviceId> </ns0: SchemaBookingByService> Messaggio di risposta <ns2:SchemaBookingByServiceResponse xmlns:ns2="com.elsagdatamat.uirnet.prenotazioni.messageclass" xmlns:ns3="com.elsagdatamat.uirnet.prenotazioni.gconfErrori"> <requestId>R123ap</requestId> <return><?xml version="1.0" encoding="UTF-8"?> <xs:schema xmlns="com.elsagdatamat.uirnet.prenotazioni.messageclass" xmlns:xs=http://www.w3.org/2001/XMLSchema targetNamespace="com.elsagdatamat.uirnet.prenotazioni.messageclass"> Schema xml della prenotazione dipendente dal servizio richiesto </xs:schema> </return> </ns2:SchemaBookingByServiceResponse> 9.1.7 ServiceState Consente di ottenere lo stato di un servizio. Campo Valore messageCode STATO_SERVIZIO messageClass PRT messageSubClass INQUIRY RICHIESTA:SERVICESTATE Campo Tipo Descrizione requestId xs:string Identificativo richiesta attribuito l’individuazione della conversazione serviceId xs:long Identificativo del servizio Obbl. dal SI per N S RISPOSTA:SERVICESTATERESPONSE Campo Tipo Descrizione requestId xs:string Identificativo richiesta attribuito dal SI per l’individuazione della conversazione return xs: serviceStateInfo Stato del servizio 54 SERVICESTATEINFO Campo Tipo Descrizione serviceId xs:long Identificativo del servizio serviceStateCode xs:string Stato del servizio ESEMPIO Stato servizio (bodyXml) <ns0: ServiceState xmlns:ns0="com.elsagdatamat.uirnet.prenotazioni.messageclass" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <requestId>R123ap</requestId> <serviceId>262</serviceId> </ns0: ServiceState> Messaggio di risposta <ns2:ServiceStateResponse xmlns:ns2="com.elsagdatamat.uirnet.prenotazioni.messageclass" xmlns:ns3="com.elsagdatamat.uirnet.prenotazioni.gconfErrori"> <requestId>R123ap</requestId> <return> <serviceId>262</serviceId> <serviceStateCode>1</serviceStateCode> </return> </ns2:ServiceStateResponse> 9.2 Amministrazione dei Servizi 9.2.1 InsertService Inserimento di un servizio sulla piattaforma. Campo Valore messageCode INSERIMENTO messageClass PRT messageSubClass SERVIZI RICHIESTA:INSERTSERVICE Campo Tipo Descrizione Obbl. requestId xs:long Identificativo richiesta attribuito l’individuazione della conversazione sellerId xs:long Identificativo del Fornitore S locationId xs:long Identificativo indirizzo fornitura S srvTypesId xs:long Identificativo Tipologia di Servizio S code xs:string Codice del servizio S dal SI per N 55 description xs:string Descrizione del servizio S shortDescription xs:string Descrizione breve S costs xs:string Tariffe del servizio N policyChanges xs:string Politiche di modifica/cancellazione N startDate xs:dateTime Data inizio N endDate xs:dateTime Data fine N pv xs:string Provincia di fornitura del servizio N automaticAccept xs:boolean Accettazione automatica N limit xs:string Limitazioni al servizio N addressUrl xs:string Link al sito del fornitore N times xs:string Orari del servizio N closingPeriods xs:periodInfo Periodi di non prenotabilità del servizio N Caratteristiche proprie del servizio richiesto S attributes PERIODINFO Campo Tipo Descrizione startDate xs:dateTime Data inizio endDate xs:dateTime Data fine RISPOSTA:INSERTSERVICERESPONSE Campo Tipo Descrizione requestId xs:string Identificativo richiesta attribuito dal SI per l’individuazione della conversazione insertServiceResponse xs: serviceStateInfo Stato del servizio Campo Tipo Descrizione serviceId xs:long Identificativo del servizio serviceStateCode xs:string Stato del servizio SERVICESTATEINFO ESEMPIO Inserimento nuovo servizio (bodyXml) <ns0:InsertService xmlns:ns0="com.elsagdatamat.uirnet.prenotazioni.messageclass" > <sellerId>xxxxx</sellerId> <locationId>xxxxx</locationId> <srvTypesId>33</srvTypesId> <code>SRV-LAV</code> <description>Lavaggio mezzi</description> <shortDescription>Lavaggio mezzi (da legacy)</shortDescription> <pv>FI</pv> 56 <automaticAccept>1</automaticAccept> <missionDerived>1</missionDerived> <attributes> <customAttributes/> </attributes> </ns0:InsertService> Messaggio di risposta <ns2:InsertServiceResponse xmlns:ns2="com.elsagdatamat.uirnet.prenotazioni.messageclass" xmlns:ns3="com.elsagdatamat.uirnet.prenotazioni.gconfErrori"> <return> <serviceId>262</serviceId> <serviceStateCode>0</serviceStateCode> </return> </ns2:InsertServiceResponse> 9.2.2 UpdateService Aggiorna le caratteristiche di un servizio della piattaforma. Campo Valore messageCode AGGIORNAMENTO messageClass PRT messageSubClass SERVIZI RICHIESTA: UPDATESERVICE Campo Tipo Descrizione Obbl. requestId xs:long Identificativo richiesta attribuito dal SI per l’individuazione della conversazione N srvId xs:long Identificativo del servizio S sellerId xs:long Identificativo del Fornitore S locationId xs:long Identificativo indirizzo fornitura S description xs:string Descrizione estesa del servizio S shortDescription xs:string Descrizione breve del servizio S costs xs:string Tariffe del servizio N policyChanges xs:string Politiche di modifica/cancellazione N startDate xs:dateTime Data inizio N endDate xs:dateTime Data fine N pv xs:string Provincia di fornitura del servizio S automaticAccept xs:boolean Accettazione automatica S 57 missionDerived xs:boolean Servizio con creazione missione derivata S limit xs:string Limitazioni al servizio N addressUrl xs:string Link al sito del fornitore N times xs:string Orari del servizio N closingPeriods xs: periodInfo Periodi di non prenotabilità N Caratteristiche proprie del servizio richiesto S attributes PERIODINFO Campo Tipo Descrizione startDate xs:dateTime Data inizio endDate xs:dateTime Data fine RISPOSTA:UPDATESERVICERESPONSE Campo Tipo Descrizione requestId xs:string Identificativo richiesta attribuito dal SI per l’individuazione della conversazione UpdateServiceResponse xs: serviceStateInfo SERVICESTATEINFO Campo Tipo Descrizione serviceId xs:long Identificativo del servizio serviceStateCode xs:string Stato del servizio ESEMPIO Aggiorna servizio (bodyXml) <ns0:UpdateService xmlns:ns0="com.elsagdatamat.uirnet.prenotazioni.messageclass" > <srvId>262</srvId> <sellerId>xxxxxx</sellerId> <locationId>xxxxxx</locationId> <description>Lavaggio mezzi & mezzi</description> <shortDescription>Lavaggio mezzi (da legacy)</shortDescription> <pv>FI</pv> <automaticAccept>0</automaticAccept> <missionDerived>0</missionDerived> <attributes> <customAttributes/> </attributes> </ns0:UpdateService> Messaggio di risposta 58 <ns2:UpdateServiceResponsexmlns:ns2="com.elsagdatamat.uirnet.prenotazioni.messageclass" xmlns:ns3="com.elsagdatamat.uirnet.prenotazioni.gconfErrori"> <return> <serviceId>262</serviceId> <serviceStateCode>2</serviceStateCode> </return> </ns2:UpdateServiceResponse> 9.2.3 UpdateServiceState Cambia lo stato di un servizio della piattaforma (servizio in stato sospeso). Campo Valore messageCode SERVIZI messageClass PRT messageSubClass CAMBIOSTATO RICHIESTA: UPDATESERVICESTATE Campo Tipo Descrizione Obbl. requestId xs:string Identificativo richiesta attribuito l’individuazione della conversazione serviceId xs:long Identificativo servizio S stateCode xs:int Stato servizio S notes xs:string Note di cambio stato N originalResponse xs:OriginalResponse Messaggio originale inviato dal sistema del fornitore N dal SI per N RISPOSTA: UPDATESERVICESTATERESPONSE Campo Tipo Descrizione requestId xs:string Identificativo richiesta attribuito dal SI per l’individuazione della conversazione UpdateServiceStateResponse xs: serviceStateInfo Stato del servizio Campo Tipo Descrizione serviceId xs:long Identificativo del servizio serviceStateCode xs:string Stato del servizio SERVICESTATEINFO ESEMPIO Cambia lo stato di un servizio (bodyXml) <ns0:UpdateServiceState xmlns:ns0="com.elsagdatamat.uirnet.prenotazioni.messageclass" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <requestId>R123ap</requestId> <serviceId>192</serviceId> 59 <stateCode>2</stateCode> </ns0:UpdateServiceState> Messaggio di risposta <ns2:UpdateServiceStateResponse xmlns:ns2="com.elsagdatamat.uirnet.prenotazioni.messageclass" xmlns:ns3="com.elsagdatamat.uirnet.prenotazioni.gconfErrori"> <requestId>R123ap</requestId> <return> <serviceId>192</serviceId> <serviceStateCode>2</serviceStateCode> </return> </ns2:UpdateServiceStateResponse> 9.3 Gestione delle Prenotazioni 9.3.1 InsertBooking Inserisce una prenotazione sulla piattaforma. Campo Valore messageCode INSERIMENTO messageClass PRT messageSubClass PRENOTAZIONI RICHIESTA: INSERTBOOKING Campo Tipo Descrizione Obbl. requestId xs:string Identificativo richiesta attribuito l’individuazione della conversazione buyerId xs:long Identificativo del committente S locationId xs:long Identificativo indirizzo fornitura S serviceId xs:long Identificativo servizio S notes xs:string Note N expiredDate xs:dateTime Data scadenza N fruitionStartDate xs:dateTime Data inizio fruizione S fruitionEndDate xs:dateTime Data fine fruizione S flagConfirmDate xs:boolean Flag conferma manuale prenotazione N contact xs:string Contatto N phone xs:string Numero di telefono N attributes tns:Attributes Parametri specifici del servizio richiesto S dal SI per N 60 ATTRIBUTES Campo Tipo Descrizione customAttributes xs:string Parametri specifici del servizio richiesto in formato XML incapsulati in un tag CDATA RISPOSTA:INSERTBOOKINGRESPONSE Campo Tipo Descrizione requestId xs:string Identificativo richiesta attribuito dal SI per l’individuazione della conversazione return xs: bookingStateInfo Stato della prenotazione Campo Tipo Descrizione bookingId xs:long Identificativo della prenotazione bookingStateCode xs:string Stato della prenotazione BOOKINGSTATEINFO ESEMPIO Inserisce una prenotazione (bodyXml) <ns0:InsertBooking xmlns:ns0="com.elsagdatamat.uirnet.prenotazioni.messageclass" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <requestId>001-2012</requestId> <buyerId>xxxxx</buyerId> <locationId>xxxxx</locationId> <serviceId>237</serviceId> <notes>TAA WEB</notes> <fruitionStartDate>2012-05-03T11:59:00</fruitionStartDate> <fruitionEndDate>2012-05-05T23:59:00</fruitionEndDate> <attributes> <customAttributes> (…) Lista di attributi definiti sul servizio </customAttributes> </attributes> </ns0:InsertBooking> Messaggio di risposta <ns2:InsertBookingResponse xmlns:ns2="com.elsagdatamat.uirnet.prenotazioni.messageclass" xmlns:ns3="com.elsagdatamat.uirnet.prenotazioni.gconfErrori"> <requestId>001-2012</requestId> <return> <bookingId>1388</bookingId> 61 <bookingStateCode>1</bookingStateCode> </return> </ns2:InsertBookingResponse> 9.3.2 UpdateBooking Aggiorna i dati di una prenotazione sulla piattaforma (contestualmente alla risposta viene inviata al fornitore del servizio la prenotazione modificata). Campo Valore messageCode AGGIORNAMENTO messageClass PRT messageSubClass PRENOTAZIONI RICHIESTA: UPDATEBOOKING Campo Tipo Descrizione requestId xs:string Identificativo richiesta attribuito l’individuazione della conversazione bookingId xs:long Numero di prenotazione S buyerId xs:long Identificativo del Committente S locationId xs:long Identificativo indirizzo CRM S serviceId xs:long Identificativo servizio S notes xs:string Note N expiredDate xs:dateTime Data scadenza N fruitionStartDate xs:dateTime Data inizio fruizione S fruitionEndDate xs:dateTime Data fine fruizione S flagConfirmDate xs:boolean Flag conferma manuale prenotazione N contact xs:string Contatto N phone xs:string Numero di telefono N Caratteristiche proprie del servizio richiesto S attributes Obbl. dal SI per N RISPOSTA: UPDATEBOOKINGRESPONSE Campo Tipo Descrizione requestId xs:string Identificativo richiesta attribuito dal SI per l’individuazione della conversazione return xs: bookingStateInfo Stato della prenotazione Campo Tipo Descrizione bookingd xs:long Identificativo della prenotazione bookingStateCode xs:string Stato della prenotazione BOOKINGSTATEINFO 62 ESEMPIO Aggiorna una prenotazione (bodyXml) <ns0:UpdateBooking xmlns:ns0="com.elsagdatamat.uirnet.prenotazioni.messageclass" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <requestId>R123ap</requestId> <bookingId>1388</bookingId> <buyerId>xxxx</buyerId> <locationId>xxxxx</locationId> <serviceId>237</serviceId> <fruitionStartDate>2012-05-04T15:59:00</fruitionStartDate> <fruitionEndDate>2012-05-05T23:59:00</fruitionEndDate> <attributes> <customAttributes> (…) Lista di attributi definiti sul servizio </customAttributes> </attributes> </ns0:UpdateBooking> Messaggio di risposta <ns2:UpdateBookingResponse xmlns:ns2="com.elsagdatamat.uirnet.prenotazioni.messageclass" xmlns:ns3="com.elsagdatamat.uirnet.prenotazioni.gconfErrori"> <requestId>R123ap</requestId> <return> <bookingId>1388</bookingId> <bookingStateCode>1</bookingStateCode> </return> </ns2:UpdateBookingResponse> 9.3.3 UpdateBookingState Cambia lo stato di una richiesta di prenotazione che è stata effettuata nella piattaforma. Campo Valore messageCode CAMBIOSTATO messageClass PRT messageSubClass PRENOTAZIONI RICHIESTA: UPDATEBOOKINGSTATE Campo Tipo Descrizione Obbl. 63 requestId xs:string Identificativo richiesta attribuito l’individuazione della conversazione bookingId xs:string Identificativo della Prenotazione S stateCode xs:int Stato prenotazione S limitConfirmationDate xs:string Data limite di conferma prenotazione N notes xs:string Note di cambio stato N originalResponse tns:originalResponse Messaggio originale inviato dal sistema del fornitore N originalBookingId xs:string Identificativo originale della prenotazione N Campo Tipo Descrizione bookingId xs:long Identificativo della prenotazione dal SI per N BOOKINGSTATEINFO RISPOSTA: UPDATEBOOKINGSTATERESPONSE Campo Tipo Descrizione requestId xs:string Identificativo richiesta attribuito dal SI per l’individuazione della conversazione return xs: bookingStateInfo Stato della prenotazione Campo Tipo Descrizione bookingId xs:long Identificativo della prenotazione bookingStateCode xs:string Stato della prenotazione BOOKINGSTATEINFO BOOKINGSTATECODE Campo Tipo stakeholder INSERITA 0 Committente INOLTRATA 1 Committente CANCELLATA 2 Committente SCADUTA 3 RIFIUTATA 4 Fornitore ACCETTATA 5 Fornitore CONFERMATA 6 Committente IN_LAVORAZIONE 7 Fornitore CHIUSA 8 Fornitore IN_SOLLECITO 9 RITARDO_AUTORIZZATO 10 Fornitore CHIUSURA_NON_EVASA 11 Fornitore CHIUSURA_NON_CONFERMATA 12 64 ESEMPIO Cambia lo stato di una prenotazione (bodyXml) <ns0:UpdateBookingState xmlns:ns0="com.elsagdatamat.uirnet.prenotazioni.messageclass" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <requestId>R123ap</requestId> <bookingId>94</bookingId> <stateCode>8</stateCode> </ns0:UpdateBookingState> Messaggio di risposta <ns2:UpdateBookingStateResponsexmlns:ns2="com.elsagdatamat.uirnet.prenotazioni.messageclass" xmlns:ns3="com.elsagdatamat.uirnet.prenotazioni.gconfErrori"> <requestId>R123ap</requestId> <return> <bookingId>94</bookingId> <bookingStateCode>8</bookingStateCode> </return> </ns2:UpdateBookingStateResponse> 9.3.4 BookingState Consente di ottenere lo stato di una prenotazione. Campo Valore messageCode STATO_PRENOTAZIONE messageClass PRT messageSubClass INQUIRY RICHIESTA:BOOKINGSTATE Campo Tipo Descrizione requestId xs:string Identificativo richiesta attribuito l’individuazione della conversazione bookingId xs:long Identificativo della Prenotazione Obbl. dal SI per N S RISPOSTA:BOOKINGSTATERESPONSE Campo Tipo Descrizione requestId xs:string Identificativo richiesta attribuito dal SI per l’individuazione della conversazione return xs: bookingStateInfo 65 BOOKINGSTATEINFO Campo Tipo Descrizione bookingId xs:long Identificativo della prenotazione bookingStateCode xs:string Stato della prenotazione ESEMPIO Stato prenotazione (bodyXml) <ns0: BookingState xmlns:ns0="com.elsagdatamat.uirnet.prenotazioni.messageclass" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <requestId>R123ap</requestId> <bookingId>1558149</bookingId> </ns0:BookingState> Messaggio di risposta <ns2:BookingStateResponse xmlns:ns2="com.elsagdatamat.uirnet.prenotazioni.messageclass" xmlns:ns3="com.elsagdatamat.uirnet.prenotazioni.gconfErrori"> <requestId>R123ap</requestId> <return> <bookingId>1558149</bookingId> <bookingStateCode>1</bookingStateCode> </return> </ns2:BookingStateResponse> 9.3.5 ListBookings Consente di ottenere la lista delle prenotazioni che sono state effettuate nella piattaforma. Campo Valore messageCode LISTA_PRENOTAZIONI messageClass PRT messageSubClass INQUIRY RICHIESTA: LISTBOOKINGS Campo Tipo Descrizione Obbl. requestId xs:string Identificativo richiesta attribuito dal SI per l’individuazione della conversazione N sellerId xs:long Identificativo del Fornitore N buyerId xs: long Identificativo del Committente N serviceTypeId xs: long Identificativo Tipologia di Servizio N serviceId xs: long Identificativo del Servizio N bookingStateId xs: long Identificativo dello stato della prenotazione N 66 dateFrom xs:dateTime Data inizio periodo N dateTo xs:dateTime Data fine periodo.Senonspecificata ma specificata dateFrom, si assume che sia la data in cui è fatta la richiesta N Campo Tipo Descrizione requestId xs:string Identificativo richiesta attribuito dal SI per l’individuazione della conversazione listBookingsResponse xs: bookingInfo [0..n] Lista delle Prenotazioni Campo Tipo Descrizione bookingId xs:long Identificativo della Prenotazione bookingStateId xs:long Identificativo dello stato della Prenotazione buyerId xs:long Identificativo del Committente serviceId xs:long Identificativo del Servizio sellerId xs: long Identificativo del Fornitore Campo Tipo Descrizione bookingId xs:long Identificativo della Prenotazione tripId xs:long Identificativo missione Campo Tipo Descrizione bookingId xs:long Identificativo della Prenotazione alertId xs:long Identificativo notifica RISPOSTA: LISTBOOKINGRESPONSE BOOKINGINFO TRIPINFO ALERTINFO ESEMPIO Elenco prenotazioni azienda (bodyXml) <ns0:ListBookings xmlns:ns0="com.elsagdatamat.uirnet.prenotazioni.messageclass" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <requestId>R123ap</requestId> <buyerId>11058</buyerId> </ns0:ListBookings> Messaggio di risposta <ns2:ListBookingsResponse xmlns:ns2="com.elsagdatamat.uirnet.prenotazioni.messageclass" xmlns:ns3="com.elsagdatamat.uirnet.prenotazioni.gconfErrori"> <requestId>R123ap</requestId> 67 <return> <bookingId>198</bookingId> <bookingStateId>3</bookingStateId> <buyerId>xxxxx</buyerId> <serviceId>13</serviceId> <sellerId>xxxx</sellerd> </return> <return> <bookingId>199</bookingId> <bookingStateId>3</bookingStateId> <buyerId>xxxxx</buyerId> <serviceId>13</serviceId> <sellerId>xxxxx</sellerd> </return> <return> <bookingId>200</bookingId> <bookingStateId>3</bookingStateId> <buyerId>xxxxx</buyerId> <serviceId>13</serviceId> <sellerId>xxxxx</sellerd> </return> </ns2:ListBookingsResponse> 9.3.6 ListBookingsDocuments Consente di ottenere la lista dei documenti associati ad una prenotazione. Campo Valore messageCode LISTA_DOCUMENTI messageClass PRT messageSubClass INQUIRY RICHIESTA: LISTBOOKINGDOCUMENTS Campo Tipo Descrizione Obbl. requestId xs:string Identificativo richiesta attribuito dal SI per l’individuazione della conversazione N bookingId xs:long Identificativo della Prenotazione S RISPOSTA:LISTBOOKINGDOCUMENTSRESPONSE Campo Tipo Descrizione requestId xs:string Identificativo richiesta attribuito dal SI per l’individuazione della conversazione 68 return xs:documentInfo Dettaglio dei documenti Campo Tipo Descrizione bookingId xs:long Identificativo della Prenotazione documentName xs:string Nome del documento documentId xs:string Identificativo del documento documentUrl xs:string Link al documento DOCUMENTINFO ESEMPIO Lista documenti (bodyXml) <ns0:ListBookingDocuments xmlns:ns0="com.elsagdatamat.uirnet.prenotazioni.messageclass" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <requestId>R123ap</requestId> <bookingId>1558149</bookingId> </ns0:ListBookingDocuments> Messaggio di risposta <ns2:ListBookingDocumentsResponse xmlns:ns2="com.elsagdatamat.uirnet.prenotazioni.messageclass" xmlns:ns3="com.elsagdatamat.uirnet.prenotazioni.gconfErrori"> <requestId>R123ap</requestId> <return> <bookingId>1558149</bookingId> <documentName> Listino_tariffe_servizio.pdf</documentName> <documentId>workspace://SpacesStore/5722535d-311a-4802-9857-9b8f6daa1468</documentId> <documentUrl>/d/a/workspace/SpacesStore/5722535d-311a-4802-98579b8f6daa1468/Il_giornalista_hacker.pdf</documentUrl> </return> </ns2:ListBookingDocumentsResponse> 9.3.7 DetailBooking Consente di ottenere i dettagli di una prenotazione che è stata effettuata nella piattaforma. Campo Valore messageCode DETTAGLIO_PRENOTAZIONE messageClass PRT messageSubClass INQUIRY RICHIESTA:DETAILBOOKING Campo Tipo Descrizione requestId xs:string Identificativo Obbl. richiesta attribuito dal SI per N 69 l’individuazione della conversazione bookingId xs:long Identificativo della Prenotazione N RISPOSTA:DETAILBOOKINGRESPONSE Campo Tipo Descrizione requestId xs:string Identificativo richiesta attribuito dal SI per l’individuazione della conversazione detailBookingResponse xs: bookingDetail Dettaglio della prenotazione Campo Tipo Descrizione serviceId xs:long Identificativo del servizio srvTypesId xs:long Identificativo Tipologia di Servizio srvTypesCode xs:string Codice della tipologia di servizio stateId xs:int Stato del servizio userName xs:string Identificativo utente operationDate xs:dateTime Data di inserimento/modifica buyerId xs:long Identificativo del Committente locationId xs:long Identificativo indirizzo fornitura bookingId xs:long Identificativo della Prenotazione notes xs:string Note flagOrigine xs:string Origine inserimento/modifica (W per Web, L per Legacy, C per Schedulatore CRON) expiredDate xs:dateTime Data scadenza fruitionStartDate xs:dateTime Data inizio fruizione fruitionEndDate xs:dateTime Data fine fruizione flagConfirmDate xs:boolean Flag conferma manuale prenotazione confirmDate xs:dateTime Data conferma contact xs:string Contatto phone xs:string Numero di telefono BOOKINGDETAIL attibutes Caratteristiche proprie del servizio richiesto ESEMPIO Elenco prenotazioni (bodyXml) <ns0:DetailBooking xmlns:ns0="com.elsagdatamat.uirnet.prenotazioni.messageclass" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <requestId>R123ap</requestId> <bookingId>1558149</bookingId> </ns0:DetailBooking> 70 Messaggio di risposta <ns2:DetailBookingResponse xmlns:ns2="com.elsagdatamat.uirnet.prenotazioni.messageclass" xmlns:ns3="com.elsagdatamat.uirnet.prenotazioni.gconfErrori"> <requestId>R123ap</requestId> <return> <serviceId>32</serviceId> <srvTypesId>8</srvTypesId> <srvTypesCode>SRVTYPES 8</srvTypesCode> <stateId>1</stateId> <userName> user</userName> <operationDate>2012-05-09T10:38:43.861+02:00</operationDate> <buyerId>xxxxxx</buyerId> <locationId>xxxxxx</locationId> <bookingId>1558149</bookingId> <flagOrigine>W</flagOrigine> <fruitionStartDate>2012-05-09T10:40:00.000+02:00</fruitionStartDate> <fruitionEndDate>2012-05-16T00:00:00.000+02:00</fruitionEndDate> <flagConfirmDate>false</flagConfirmDate> <attributes> <customAttributes> <caratteristiche> <eta>2012-04-26T00:00:00</eta> <etd>2012-04-27T00:00:00</etd> <typevehicles>Autotreni</typevehicles> <generalCargoId>1</generalCargoId> <generalCargoItems>102</generalCargoItems> <generalCargoWeight>3</generalCargoWeight> </caratteristiche> </customAttributes> </attributes> </return> </ns2:DetailBookingResponse> 9.3.8 DetailBookingDocuments Consente di ottenere i documenti allegati ad una prenotazione effettuata nella piattaforma. Campo Valore messageCode DETTAGLIO_DOCUMENTI 71 messageClass PRT messageSubClass INQUIRY RICHIESTA: DETAILBOOKINGDOCUMENTS Campo Tipo Descrizione Obbl. requestId xs:string Identificativo richiesta attribuito l’individuazione della conversazione bookingId xs:long Identificativo della Prenotazione S documentId xs:string Identificativo del Documento N dal SI per N RISPOSTA: DETAILBOOKINGDOCUMENTSRESPONSE Campo Tipo Descrizione requestId xs:string Identificativo richiesta attribuito dal SI per l’individuazione della conversazione return xs:documentInfo Dettaglio dei documenti Campo Tipo Descrizione bookingId xs:long Identificativo della Prenotazione documentName xs:string Nome del documento documentId xs:string Identificativo del documento documentUrl xs:string Link al documento DOCUMENTINFO ESEMPIO Elenco prenotazioni (bodyXml) <ns0:DetailBookingDocuments xmlns:ns0="com.elsagdatamat.uirnet.prenotazioni.messageclass" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <requestId>R123ap</requestId> <bookingId>1558149</bookingId> <documentId> workspace://SpacesStore/5722535d-311a-4802-9857-9b8f6daa1468 </documentId> </ns0:DetailBookingDocuments> Messaggio di risposta <ns2:DetailBookingDocumentsResponse xmlns:ns2="com.elsagdatamat.uirnet.prenotazioni.messageclass" xmlns:ns3="com.elsagdatamat.uirnet.prenotazioni.gconfErrori"> <requestId>R123ap</requestId> <return> <bookingId>1558149</bookingId> <documentName>Listino_tariffe_servizio.pdf</documentName> 72 <documentId> workspace://SpacesStore/5722535d-311a-4802-9857-9b8f6daa1468 </documentId> <documentUrl> /d/a/workspace/SpacesStore/5722535d-311a-4802-98579b8f6daa1468/Listino_tariffe_servizio.pdf </documentUrl> </return> </ns2:DetailBookingDocumentsResponse> Per ottenere fisicamente il documento allegato occorre usare il servizio getMessage di MDW EDI, invocato col numero messaggio della risposta precedente. ESEMPIO Ottieni documento allegato (bodyXml) <pub:getMessages> <middlewareMessageId>1079277</middlewareMessageId> <userName>user</userName> <cim>123456</cim> </pub:getMessages> Messaggio di risposta <env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"> <env:Header/> <env:Body> <ns2:getMessageResponse xmlns:ns2="http://ws.bll.b2b.elsagdatamat.com/"> <return> <header> <msgId>1079277</msgId> <messageCode>DETTAGLIO_DOCUMENTI</messageCode> <messageClass>PRT</messageClass> <messageSubClass>INQUIRY</messageSubClass> <priority>0</priority> <timestamp>2012-05-09T11:02:06.065+02:00</timestamp> <originalFormat>UirnetFormat</originalFormat> <callerId>7</callerId> <composer>prenotazioni</composer> <mailboxSender>SERVER_PRENOTAZIONE</mailboxSender> <receivers> 73 <receiverId>10966</receiverId> <mailboxName>PRENOTAZIONI</mailboxName> <formatName>UirnetFormat</formatName> </receivers> <subject>RESPONSE</subject> </header> <body> <bodyXml><![CDATA[<?xml version="1.0" encoding="UTF-8"?> <ns2:DetailBookingDocumentsResponse xmlns:ns2="com.elsagdatamat.uirnet.prenotazioni.messageclass" xmlns:ns3="com.elsagdatamat.uirnet.prenotazioni.gconfErrori"> <requestId>R123ap</requestId> <return> <bookingId>1558149</bookingId> <documentName> Listino_tariffe_servizio.pdf</documentName> <documentId>workspace://SpacesStore/5722535d311a-4802-9857-9b8f6daa1468</documentId> <documentUrl>/d/a/workspace/SpacesStore/5722535d-311a4802-9857-9b8f6daa1468/ Listino_tariffe_servizio.pdf</documentUrl> </return> </ns2:DetailBookingDocumentsResponse>]]> </bodyXml> <attachments> <fileName> Listino_tariffe_servizio.pdf</fileName> <fileBody>JVBERi0xLjYNJeLjz9MNCjI0NCAQo (…) Gjgj7SttsHGYts56ww</fileBody> </attachments> </body> <mifId>1079277</mifId> <wrongMsgInFolder>0</wrongMsgInFolder> <ancestorMsgInFolder>1079276</ancestorMsgInFolder> <globalAncestorMsgInFolder>1079276</globalAncestorMsgInFolder> <replyOfMsgInFolder>0</replyOfMsgInFolder> <inserted>2012-05-09T11:02:06.075+02:00</inserted> <firstAccess>2012-05-09T11:24:26.944+02:00</firstAccess> <error>false</error> <ruleNotApplied>2012-05-09T11:02:07.943+02:00</ruleNotApplied> 74 <read>2012-05-09T11:24:26.944+02:00</read> </return> </ns2:getMessageResponse> </env:Body> </env:Envelope> Il campo fileBody contiene il documento richiesto in formato Base64, una stringa ASCII che dovrà essere decodificata dal legacy per ottenere il documento originale. 9.3.9 BookingNotify Messaggio di notifica cambio stato di una prenotazione inviato dal Sistema di Gestione delle Prenotazioni. Campo Tipo Descrizione issueDateTime xs:dateTime DataOra di invio bookingId xs:long Identificativo della Prenotazione booking Notes xs:string Note della prenotazione booking State xs:int Stato della prenotazione bookingStateDescr xs:string Descrizione stato sellerId xs:long Fornitore sellerDescr xs:string Ragione sociale del fornitore buyerId xs:long Identificativo committente (id CRM dell’azienda) buyerDescr xs:string Ragione sociale del committente limitConfirmationDate xs:dateTime Data limite per la conferma della prenotazione 9.3.10 BookingForward Messaggio di inoltro di una prenotazione inviato dal Sistema di Gestione delle Prenotazioni. Campo Tipo Descrizione bookingId xs:long Identificativo della Prenotazione bookingState xs:int Stato della prenotazione bookingStateDescr xs:string Descrizione stato operation xs:string Tipo operazione: insert o update o delete serviceId xs:long Identificativo servizio serviceCode xs:string Codice servizio srvTypesId xs:long Identificativo tipologia servizio srvTypesCode xs:string Codice tipologia servizio srvTypesName xs:string Nome tipologia servizio sellerId xs:long Fornitore sellerDescr xs:string Ragione sociale del fornitore buyerdId xs:long Identificativo committente (id CRM dell’azienda) buyerDescr xs:string Ragione sociale del committente 75 note xs:string Note originalResponse xs:string Eventuale risposta strutturata dal legacy fruitionStartDate xs:dateTime Data di inizio fruizione della prenotazione fruitionEndDate xs:dateTime Data di fine fruizione della prenotazione flagConfirmDate xs:boolean Se prenotazione sottoposta a conferma da partedel committente confirmDate xs:dateTime Data limite per la conferma della prenotazione contact xs:string Contatto phone xs:string Telefono detail xs:Detail Dettaglio della prenotazione 9.3.11 BookingReminder Messaggio di sollecito generato alla scadenza di una caratteristica della prenotazione inviato dal Sistema di Gestione delle Prenotazioni. Campo Tipo Descrizione issueDateTime xs:dateTime DataOra di invio bookingId xs:long Identificativo della Prenotazione bookingNotes xs:string Note della prenotazione bookingState xs:int Stato della prenotazione bookingStateDescr xs:string Descrizione stato sellerId xs:string Fornitore sellerDescr xs:string Ragione sociale del fornitore buyerId xs:long Identificativo committente (id CRM dell’azienda) buyerDescr xs:string Ragione sociale del committente reminderName xs:string Nome della caratteristica scaduta reminderDate xs:dateTime Valore della data scaduta reminderNote xs:string Testo del messaggio 9.4 Gestione delle Eccezioni Il Sistema di Gestione delle Prenotazioni restituisce, in caso di errore nell’elaborazione di una richiesta, un messaggio specifico caratterizzato da messageClass, messageSubclass e messageCode identici al messaggio che ha generato l’errore e subject pari a ERROR, inserendo nel bodyXML un messaggio di tipo EXCEPTIONRESPONSE descrittivo dell’errore generato. Il Sistema di Gestione verifica sia la conformità del messaggio alle specifiche di piattaforma, che la congruità delle informazioni inserite nello stesso. 9.4.1 ExceptionResponse Messaggio di errore generato dal Sistema di Gestione delle Prenotazioni. Campo Tipo Descrizione requestId xs:string Identificativo richiesta attribuito dal SI per l’individuazione della conversazione 76 exceptionCode xs:string Codice di errore exceptionMessage xs:string Messaggio di errore Response <ns2:ExceptionResponse xmlns:ns2="com.elsagdatamat.uirnet.prenotazioni.messageclass" xmlns:ns3="com.elsagdatamat.uirnet.prenotazioni.gconfErrori"> <requestId>req01</requestId> <exceptionCode>WS-PRT-E099</exceptionCode> <exceptionMessage> In content of element <container>: The content model does not allow element <shipVoyageId> to appear here. No further elements are allowed at this position </exceptionMessage> </ns2:ExceptionResponse> 77 9.5 Casi d’Uso 78 79 9.6 Messaggi Specifici dei Servizi in Catalogo Il presente paragrafo riporta i messaggi specifici per ciascun servizio con la spiegazione del significato dei campi. 9.6.1 Preavviso di Arrivo APGe Il Preavviso di Arrivo APGe consente di inviare una richiesta di Truck Arrival Announcement (TAA) al Porto di Genova per la verifica della fattibilità operativa e documentale della missione. FORNITORE: APGE COMMITTENTE: AUTOTRASPORTO Il servizio consente di indicare i dati del veicolo e del conducente, il terminal e le attività di carico e scarico da effettuare e restituisce, mediante l’interrogazione del sistema ePort, la fattibilità e, nel caso di risposta negativa, le motivazioni di rifiuto in un campo note. La presentazione di un Preavviso di Arrivo dà luogo alle attività derivate nella Piattaforma descritte nel Catalogo dei Servizi. I messaggi inerenti il preavviso di arrivo che possono essere inviati alla piattaforma UIRNet riguardano le seguenti operatività, contraddistinte dai parametri: PARAMETRI DEL SERVIZIO Ambiente Test Produzione Campo Valore sellerId 10996 serviceId 337 sellerId 10996 serviceId 63 Il servizio Preavviso di Arrivo APGe prevede i parametri specifici da introdurre nel campo customAttributes del messaggio INSERTBOOKING. Il Sistema di Gestione delle Prenotazioni, ricevuto il Preavviso di Arrivo, invia al SI un messaggio BOOKINGNOTIFY (cfr. § 9.3.9) per l’acknowledgment della richiesta e la notifica della sua trasmissione al sistema ePort. In seguito alla risposta da parte di quest’ultimo, il Sistema di Gestione delle Prenotazioni invia al SI un messaggio BOOKINGFORWARD (cfr. § 9.3.9) con allegata la risposta del sistema ePort nel campo originalResponse. 80 9.6.1.1 Messaggi inviati alla piattaforma UIRNet I messaggi inerenti il preavviso di arrivo che possono essere inviati alla piattaforma UIRNet riguardano le seguenti operatività, contraddistinte dai parametri: Inserimento del preavviso di arrivo Campo Valore messageCode INSERIMENTO messageClass PRT messageSubClass PRENOTAZIONI Modifica del preavviso di arrivo Campo Valore messageCode AGGIORNAMENTO messageClass PRT messageSubClass PRENOTAZIONI Cancellazione del preavviso di arrivo Campo Valore messageCode PRENOTAZIONI messageClass PRT messageSubClass CAMBIOSTATO La sezione header del Travelling Message è la seguente (nell’esempio messageCode, messageClass e messageSubClass sono riferiti all’inserimento di un preavviso di arrivo): TRAVELLINGMESSAGE:HEADER Campo Valore Descrizione messageCode INSERIMENTO Codice messaggio messageClass PRT Classe messaggio messageSubClass PRENOTAZIONI Sottoclasse messaggio timestamp xxxx Data-ora invio (aaaa-mm-ggThh:mm:ss.x+x:xx) originalFormat UirnetFormat Formato messaggio callerId xxxx Identificativo chiamante (CRM id azienda) composer xxxxx Utente compositore del messaggio (CRM user id dell’utente censito) mailboxSender PRENOTAZIONI Centro messaggi di riferimento. Non modificare receivers msgReceiverWithFormat Destinatario Subject xxxx Soggetto messaggio userName xxxx Utente compositore del messaggio (username) 81 Cim xxxx Pin CRM corrispondente a username (per autenticazione WS) TIPO DATI COMPOSTO MSGRECEIVERFORMAT Campo Tipo Descrizione receiverId 7 Identificativo ricevente –SISTEMA PRENOTAZIONI (non modificare) mailboxName SERVER_PRENOTAZIONE Nome Centro Servizi- Non modificare formatName UirnetFormat Formato desiderato- Non modificare Il campo bodyXml contiene i dati relativi all’operazione che si vuole effettuare sul preavviso di arrivo e deve sempre rispettare lo schema di riferimento dell’operazione stessa, come descritta nel file seguente: PRT_message_schema_TAA_Rev.c.xsd 9.6.1.1.1 Messaggio di inserimento Il campo bodyXml contiene i dati relativi all’inserimento di un preavviso di arrivo. Lo schema di riferimento, descritto nel file PRT_message_schema_TAA_Rev.c.xsd è InsertBooking; nella Figura 1 è riportata la schematizzazione dei dati che lo compongono. 82 Figura 1 - InsertBooking Al primo livello si trovano tutti campi-dato semplici eccetto attributes, che è una struttura articolata in vari livelli, come mostrato nella Figura 2, contenente gli attributi della prenotazione Figura 2 – attributes 83 Di seguito la descrizione dei campi che compongono la struttura InsertBooking: INSERTBOOKING Elemento Tipo Descrizione Obbligatorio requestId string Identificativo richiesta (a cura del richiedente) N buyerId long Identificativo committente (id azienda CRM) S serviceId long Identificativo servizio S notes string Note N expiredDate dateTime Data scadenza N fruitionStartDate dateTime Data inizio fruizione S fruitionEndDate dateTime Data fine fruizione S contact string Contatto N phone string Numero di telefono N attributes Attributes Attributi della prenotazione S Elemento Tipo Descrizione Obbligatorio customAttributes customAttributes TIPO DATI COMPOSTO ATTRIBUTES S Nel caso di un messaggio di tipo preavviso di arrivo l’elemento customAttributes è così composto: TIPO DATI COMPOSTO CUSTOMATTRIBUTES Elemento Tipo Descrizione Obbligatorio headerData headerData Dati dI Intestazione S truckData truckData Dati Viaggio Camion S driverData driverData Dati Conducente S pickupFull pickupFullContainerList Carico Pieno S pickupEmpty pickupEmptyContainerList Carico vuoto S releaseFullEmpty releaseFullEmptyContainerList Scarico Pieno/Vuoto S Descriviamo il dettaglio di ogni singola struttura contenuta in customAttributes. 84 Figura 3 – headerData TIPO DATI COMPOSTO HEADERDATA: Elemento Tipo Descrizione Obbligatorio issueDateTime dateTime DataOra di presentazione doc. S sender string Ragione Sociale azienda di trasporti S senderPIVA string P.IVA Ditta di trasporti S telepass string Telepass N Figura 4 – truckData 85 TIPO DATI COMPOSTO TRUCKDATA: Elemento Tipo Descrizione Obbligatorio carrier string Ditta di trasporto S carrierPIVA string Partita IVA ditta di trasporto S voyageId string Identificativo viaggio (a cura del richiedente) S arrivalDate date Data arrivo al Terminal S Fascia oraria di arrivo (AM=0-12, PM=12-18, EV=18-00) S arrivalPeriod truckLicencePlate string Targa del mezzo S trailerLicencePlate string Targa del rimorchio N Figura 5 – driverData TIPO DATI COMPOSTO DRIVERDATA: Elemento Tipo Descrizione Obbligatorio firstName string Nome S lastName string Cognome S drivingLicence string N. Patente di guida S language string Codice ISO Lingua N email string Indirizzo e-mail N cellPhoneNumber string Cellulare N portPermissionNumber string N. Permesso accesso al porto S 86 Figura 6 – pickupFullContainer TIPO DATI COMPOSTO PICKUPFULLCONTAINERLIST: Elemento Tipo Descrizione Obbligatorio pickupFullContainer pickupFullContainer Lista Container carico pieno S TIPO DATI COMPOSTO PICKUPFULLCONTAINER: Elemento Tipo Descrizione Obbligatorio containerId string Matricola container S terminal string Terminal S terminalPIVA string P.IVA Terminal S customsBroker string Spedizioniere doganale N customsBrokerPIVA string P.IVA Spedizioniere doganale N 87 Figura 7 – pickupEmptyContainer TIPO DATI COMPOSTO PICKUPEMPTYCONTAINERLIST: Elemento Tipo Descrizione Obbligatorio pickupEmptyContainer pickupEmptyContainer Lista Container carico vuoto S TIPO DATI COMPOSTO PICKUPEMPTYCONTAINER: Elemento Tipo Descrizione Obbligatorio bookingNumber string Numero booking N shipAgent string Agente Marittimo S shipAgentPIVA string P.IVA Agente Marittimo S terminal string Terminal S terminalPIVA string P.IVA Terminal S isoCode string Codice ISO container S containerId string Matricola container N customsBroker string Spedizionere doganale N customsBrokerPIVA string P.IVA Spedizionere doganale N 88 Figura 8 – releaseFullEmptyContainer TIPO DATI COMPOSTO RELEASEFULLEMPTYCONTAINERLIST: Elemento Tipo Descrizione Obbligatorio releaseFullEmptyContainer releaseFullEmptyContainer Lista Container scarico pieno/vuoto S TIPO DATI COMPOSTO RELEASEFULLEMPTYCONTAINER: Elemento Tipo Descrizione Obbligatorio containerId string Matricola container S isoCode string Codice ISO container N bookingNumber string Numero booking S shipAgent string Agente Marittimo S shipAgentPIVA string P.IVA Agente Marittimo S terminal string Terminal S terminalPIVA string P.IVA Terminal S customsBroker string Spedizionere doganale N 89 customsBrokerPIVA string P.IVA Spedizionere doganale N temperature number temperatura media container N portOfDestination string Porto di Arrivo N portOfDestinationCode string Codice Porto di Arrivo N weight number Peso N Da notare che lo schema prevede l’obbligatorietà degli elementi pickupFullContainerList, pickupEmptyContainerList e releaseFullEmptyContainerList anche se essi non contengono dati. Un esempio è riportato in Figura 9. 90 <ns0:InsertBooking xmlns:ns0="com.elsagdatamat.uirnet.prenotazioni.messageclass" xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance"> <requestId>REQ01</requestId> <buyerId>67676</buyerId> <serviceId>316</serviceId> <notes>Taa ePort 1pe+1r</notes> <expiredDate>2012-12-31T23:59:47-05:00</expiredDate> <fruitionStartDate>2012-10-27T21:00:00.000+02:00</fruitionStartDate> <fruitionEndDate>2012-10-31T20:00:00.000+02:00</fruitionEndDate> <attributes> <customAttributes> <headerData> <issueDateTime>2012-10-26T17:00:00</issueDateTime> <sender>Autotrasporto Ginone S.p.A.</sender> <senderPIVA>99575389216</senderPIVA> </headerData> <truckData> <carrier> Autotrasporto Ginone S.p.A.</carrier> <carrierPIVA>99575389216</carrierPIVA> <voyageId>V2012/07</voyageId> <arrivalDate>2012-10-28</arrivalDate> <arrivalPeriod>AM</arrivalPeriod> <truckLicencePlate>DA147GM</truckLicencePlate> </truckData> <driverData> <firstName>Omen</firstName> <lastName>Nomen</lastName> <drivingLicence>MI1234567890</drivingLicence> <portPermissionNumber>1234465678</portPermissionNumber> </driverData> <pickupFull> <pickupFullContainerList> </pickupFullContainerList> </pickupFull> <pickupEmpty> <pickupEmptyContainerList> <pickupEmptyContainer rowNumber="1"> <bookingNumber>710</bookingNumber> <shipAgent>CHINA SHIPPING SR</shipAgent> <shipAgentPIVA>03783550100</shipAgentPIVA> <terminal>VTE - Voltri Terminal Europa</terminal> <terminalPIVA>02782020107</terminalPIVA> <isoCode>00A0</isoCode> <containerId>INTU9100335</containerId> </pickupEmptyContainer> </pickupEmptyContainerList> </pickupEmpty> <releaseFullEmpty> <releaseFullEmptyContainerList> <releaseFullEmptyContainer rowNumber="1"> <containerId>INTU9100336</containerId> <isoCode>2200</isoCode> <bookingNumber>2GOAWU0600-0001</bookingNumber> <shipAgent>HAMBURG SUD</shipAgent> <shipAgentPIVA>01849470990</shipAgentPIVA> <terminal>VTE - Voltri Terminal Europa</terminal> <terminalPIVA>03211930106</terminalPIVA> </releaseFullEmptyContainer> </releaseFullEmptyContainerList> </releaseFullEmpty> </customAttributes> </attributes> </ns0:InsertBooking> Figura 9 - BodyXml di inserimento di un Preavviso di arrivo TAA ePort 91 9.6.1.1.2 Messaggio di modifica Il campo bodyXml contiene i dati relativi alla modifica di un preavviso di arrivo. Lo schema di riferimento, descritto nel file PRT_message_schema_TAA_Rev.c.xsd è UpdateBooking. Per la descrizione dei campi che compongono il bodyXml si faccia riferimento al paragrafo precedente, inserimento di un Preavviso di Arrivo. 9.6.1.1.3 Messaggio di cancellazione Il campo bodyXml contiene i dati relativi alla cancellazione di un preavviso di arrivo. Lo schema di riferimento, descritto nel file SchemaMessagePRT.xsd, è UpdateBookingState. Di seguito la descrizione dei campi per la cancellazione di un preavviso di arrivo: UPDATEBOOKINGSTATE Elemento Tipo Descrizione Obbligatorio requestId string Identificativo richiesta (a cura del richiedente) N bookingId long Identificativo della Prenotazione S stateCode int Stato in cui portare la prenotazione (per cancellazione = 2) S Notes string Note N Ecco un esempio di valorizzazione del campo bodyXml nel caso di cancellazione di un preavviso di arrivo : <ns0:UpdateBookingState xmlns="com.elsagdatamat.uirnet.prenotazioni.messageclass" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="com.elsagdatamat.uirnet.prenotazioni.messageclass"> <requestId>R102011</requestId> <bookingId>100</bookingId> <stateCode>2</stateCode> <notes></notes> </ns0:UpdateBookingState> Figura 10 - BodyXml cancellazione di un Preavviso di arrivo TAA ePort 92 9.6.1.2 Messaggi ricevuti dalla piattaforma UIRNet I messaggi che sono inviati dalla piattaforma ad un committente sono le risposte alle azioni fatte su un preavviso di arrivo, e sono: 1. Risposte a seguito delle seguenti azioni fatte dal committente: a. Inserimento di un preavviso di arrivo; b. Modifica di un preavviso di arrivo; c. Cancellazione di un preavviso di arrivo; 2. Preavviso di arrivo (messaggio BookingForward) inviato a seguito delle seguenti azioni effettuate dal fornitore del servizio: a. Rifiuto di un preavviso di arrivo; b. Accettazione di un preavviso di arrivo; c. Aggiornamento di un preavviso di arrivo per specifica della fattibilità del preavviso stesso. Il campo bodyXml contiene i dati relativi alla risposta alle azioni fatte su un Preavviso di Arrivo e sono specificati nella schema contenuto nei seguenti file: PRT_message_schema_TAA_Rev.c.xsd, SchemaMessagePRT.xsd: schema risposte a seguito di azioni descritte al punto 1; BookingForward-TAA-Eport_Rev.c.xsd: schema preavviso di arrivo a seguito di azioni descritte al punto 2; BookingForward-TAA-Eport_Rev.c.xsd 9.6.1.2.1 Risposta all’inserimento di un preavviso di arrivo Il campo bodyXml contiene i dati relativi alla risposta inviata dalla piattaforma ad un committente in seguito all’inserimento di un preavviso di arrivo. Lo schema di riferimento, descritto nel file PRT_message_schema_TAA_Rev.c.xsd è InsertBookingResponse. Di seguito la descrizione dei campi: INSERTBOOKINGRESPONSE Elemento Tipo Descrizione requestId string Identificativo richiesta (a cura del richiedente) Return bookingInfo Note BOOKINGINFO Elemento Tipo Descrizione bookingId long Identificativo della Prenotazione bookingStateCode string Codice stato della prenotazione Note 93 In Figura 11 l’esempio di valorizzazione del campo bodyXml per questo messaggio: <ns2:InsertBookingResponse xmlns:ns2="com.elsagdatamat.uirnet.prenotazioni.messageclass" xmlns:ns3="com.elsagdatamat.uirnet.prenotazioni.gconfErrori"> <requestId>R-05-2011</requestId> <return> <bookingId>100</bookingId> <bookingStateCode>1</bookingStateCode> </return> </ns2:InsertBookingResponse> Figura 11 - BodyXml risposta all’inserimento di un Preavviso di arrivo TAA ePort Il SI, nel messaggio di inserimento di una prenotazione (InsertBooking), può specificare un identificativo che è proprio di quel messaggio (requestId) e che permette di ricollegare il messaggio inviato alla piattaforma con la relativa risposta ricevuta dalla stessa (InsertBookingResponse). Nel messaggio di risposta è contenuto il numero della prenotazione assegnato dalla piattaforma (bookingId) e il SI può quindi legare il messaggio di inserimento con il numero della prenotazione creata. In ogni caso, per la piattaforma, l’unico riferimento con la prenotazione è il numero della stessa (bookingId) e non il numero della richiesta (requestId) la cui gestione rimane esclusivamente a carico del SI. 9.6.1.2.2 Risposta alla modifica di un preavviso di arrivo Il campo bodyXml contiene i dati relativi alla risposta inviata dalla piattaforma ad un committente in seguito alla modifica di un preavviso di arrivo. Lo schema di riferimento, descritto nel file PRT_message_schema_TAA_Rev.c.xsd è UpdateBookingResponse. Ecco un esempio di valorizzazione del campo bodyXml in questo caso: <ns2:UpdateBookingResponse xmlns:ns2="com.elsagdatamat.uirnet.prenotazioni.messageclass" xmlns:ns3="com.elsagdatamat.uirnet.prenotazioni.gconfErrori"> <requestId>R-06-2011</requestId> <return> <bookingId>100</bookingId> <bookingStateCode>1</bookingStateCode> </return> </ns2:UpdateBookingResponse> Figura 12 - BodyXml risposta alla modifica di un Preavviso di arrivo TAA ePort 9.6.1.2.3 Risposta in caso di accettazione di un preavviso di arrivo Il campo bodyXml contiene i dati relativi alla risposta inviata dalla piattaforma ad un committente in seguito all’accettazione o all’aggiornamento con la fattibilità container di un preavviso di arrivo da parte del 94 fornitore del servizio. Lo schema di riferimento, descritto nel file BookingForward-TAA-Eport_Rev.c.xsd è BookingForward. Di seguito la descrizione dei campi: BOOKINGFORWARD Elemento Tipo Descrizione bookingId long Identificativo della Prenotazione bookingState int Stato della prenotazione bookingStateDescr string Descrizione dello stato della prenotazione operation string Tipo operazione serviceId long Identificativo servizio serviceCode string Codice del servizio srvTypesId long Identificativo Tipologia di Servizio srvTypesCode string Codice tipologia servizio srvTypesName string Nome tipologia servizio sellerId long Identificativo Fornitore (id CRM dell’azienda) sellerDescr string Ragione sociale del fornitore buyerId long Identificativo committente (id CRM dell’azienda) buyerDescr string Ragione sociale del committente note string Note originalResponse string Eventuale risposta strutturata dal legacy del fornitore Note Valori a seconda dell’operazione effettuata: insert, update, delete Nel caso di ePort contiene il messaggio handleTruckArrivalAnnouncementRes ponse, nel caso di accettazione/rifiuto del Preavviso di arrivo; TruckVoyageFeasibilityStatus, nel caso di aggiornamento della fattibilità container. fruitionStartDate dateTime Data di inizio fruizione della prenotazione fruitionEndDate dateTime Data di fine fruizione della prenotazione confirmDate dateTime Data limite per la conferma della prenotazione contact string Contatto phone string Telefono detail detail Dettagli prenotazione 95 TIPO DATI COMPOSTO DETAIL Elemento Tipo Descrizione detail customAttributes Dettagli prenotazione Note TIPO DATI COMPOSTO CUSTOMATTRIBUTES Elemento Tipo Descrizione headerData headerData Dati dI Intestazione truckData truckData Dati Viaggio Camion driverData driverData Dati Conducente pickupFull pickupFullContainerList Carico Pieno pickupEmpty pickupEmptyContainerList Carico vuoto releaseFullEmpty releaseFullEmptyContainerList Scarico Pieno/Vuoto Note Le strutture sottostanti customAttributes sono identiche a quelle descritte nel relativo paragrafo al quale si rimanda per ulteriori dettagli. Nella Figura 13 viene riportato un esempio di messaggio BookingForward di un preavviso di arrivo inviato al committente a seguito accettazione TAA ePort. 96 <ns2:BookingForward xmlns:ns2="com.elsagdatamat.uirnet.prenotazioni.messageclass"> <bookingId>2000948</bookingId> <bookingState>4</bookingState> <bookingStateDescr>Rifiutata</bookingStateDescr> <operation>update</operation> <serviceId>63</serviceId> <serviceCode>TAA 2</serviceCode> <srvTypesId>29</srvTypesId> <srvTypesCode>SRVTYPES 29</srvTypesCode> <srvTypesName>Preavviso di arrivo e-Port - nuova versione</srvTypesName> <sellerId>10996</sellerId> <sellerDescr>APGE - Autorita' Portuale Genova</sellerDescr> <buyerId>11015</buyerId> <buyerDescr>Autotrasporto Ginone S.p.A.</buyerDescr> <note>Il messaggio UIR_PRT_2000948 ha dei pre-requisiti mancanti: DO o ODS..</note> <originalResponse> ……………… </originalResponse> <fruitionStartDate>2012-11-21T14:50:57.000+01:00</fruitionStartDate> <fruitionEndDate>2012-11-22T14:50:57.000+01:00</fruitionEndDate> <flagConfirmDate>false</flagConfirmDate> <detail> <customAttributes> <headerData> <issueDateTime>2012-11-20T14:51:02</issueDateTime> <sender>Autotrasporto Ginone S.p.A.</sender> <senderPIVA>99575389216</senderPIVA> </headerData> <truckData> <carrier>Autotrasporto Ginone S.p.A.</carrier> <carrierPIVA>99575389216</carrierPIVA> <voyageId>6522624</voyageId> <arrivalDate>2012-11-20</arrivalDate> <arrivalPeriod>PM</arrivalPeriod> <truckLicencePlate>ZA684ZL</truckLicencePlate> </truckData> <driverData> <firstName>Omen</firstName> <lastName>Nomen</lastName> <drivingLicence>XD234FFAB</drivingLicence> <language>EN</language> <portPermissionNumber>8162</portPermissionNumber> </driverData> <pickupFull> <pickupFullContainerList> <pickupFullContainer rowNumber="1"> <containerId>UACU5459561</containerId> <terminal>VTE - Voltri Terminal Europa</terminal> <terminalPIVA>03211930106</terminalPIVA> </pickupFullContainer> </pickupFullContainerList> </pickupFull> <pickupEmpty /> <releaseFullEmpty /> </customAttributes> </detail> </ns2:BookingForward> 97 Figura 13 – BookingForward di un TAA ePort Esempi di originalResponse sono riportati nella Figura 14: Lo schema del messaggio handleTruckArrivalAnnouncementResponse originalResponse è descritto nel file seguente: contenuto nel campo EportWsResponse.xsd Di seguito vengono elencati i valori ammessi per il campo answerCode e la loro transcodifca, che rappresenta la risposta del sistema E-port: Accettazione del preavviso <originalResponse> <handleTruckArrivalAnnouncementResponse> <handleTruckArrivalAnnouncementReturn> <mappedBusinessClass>com.set.eport2.ddm.documents.messages.logicalkey.Aperak</mappedBusinessClass> <alarmErrorWS xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/> <answerCode>0</answerCode> <messageId>UIR_PRT_2000989</messageId> <messageType xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/> <note xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/> <response>OK</response> </handleTruckArrivalAnnouncementReturn> </handleTruckArrivalAnnouncementResponse> </originalResponse> Rifiuto del preavviso <originalResponse> <handleTruckArrivalAnnouncementResponse> <handleTruckArrivalAnnouncementReturn> <alarmErrorWS /> <answerCode>27</answerCode> <mappedBusinessClass>com.set.eport2.ddm.documents.messages.logicalkey.Aperak</mappedBusinessClass> <messageId>UIR_PRT_2000948</messageId> <messageType>TruckArrivalAnnouncement</messageType> <note>Il messaggio UIR_PRT_2000948 ha dei pre-requisiti mancanti: DO o ODS.</note> <response>KO</response> </handleTruckArrivalAnnouncementReturn> </handleTruckArrivalAnnouncementResponse> </originalResponse> Figura 14 – originalResponse da ePort: accettazione, rifiuto I codici di risposta provenienti da ePort, contenuti nell tag answerCode di originalResponse, sono: answerCode 0 Descrizione Ok 98 1 Autotrasportatore non riconosciuto per la partita IVA fornita: " + doc.getSenderPIVA()); 2 Agente Marittimo non riconosciuto per la partita IVA fornita 3 Customs Broker non riconosciuto per la partita IVA fornita 4 Terminal non riconosciuto per la partita IVA fornita 5 MessageId gia' inserito nel DataBase 6 Inserimento con ParentMessageId 7 Modifica o annullamento senza riferimento a un ParentMessageId 10 Inserimento non possibile: il contenitore indicato ha gia' un Preavviso di Arrivo associato 20 I contenitori inseriti non possono stare in un unico viaggio camion. 21 I contenitori inseriti nel messaggio non contengono il booking number." 22 I contenitori inseriti nel messaggio indicano terminal incongruenti. 23 Il messaggio non indica nessun container. 24 Il messaggio non indica una o piu' matricole. 25 Il messaggio non indica uno o piu' isoCode. 26 Il messaggio contiene uno shipvoyage con terminal code non definita. 27 Il messaggio ha dei prerequisiti mancanti (mancanza di DeliveryOrder o Ordine di Scarico) 99 Errore inatteso 9.6.1.2.4 Risposta in caso di aggiornamento di un preavviso di arrivo con la fattibilità Il campo bodyXml contiene i dati relativi alla risposta inviata dalla piattaforma ad un committente in seguito all’aggiornamento, con la fattibilità container, di un preavviso di arrivo da parte del fornitore del servizio. Lo schema di riferimento, descritto nel file BookingForward-TAA-Eport_Rev.c.xsd è BookingForward. La figura seguente mostra originalResponse, proveniente da ePort, recante l’aggiornamento della fattibilità ed inviato al committente all’interno di un BookingForward, come già descritto al paragrafo precedente. Fattibilità del preavviso <originalResponse> <TruckVoyageFeasibilityStatus> <truckArrivalAnnouncement> …………………….. </truckArrivalAnnouncement> <alarmErrorList> <AlarmError> <code>0</code> <componentType>AlarmError</componentType> </AlarmError> </alarmErrorList> <date>2012-11-16T18:43:54</date> <componentType>TruckVoyageFeasibilityStatus</componentType> </TruckVoyageFeasibilityStatus> </originalResponse> Figura 15 – originalResponse da ePort: fattibilità 99 Per quanto riguarda i campi ed i dettagli del messaggio di fattibilità proveniente da ePort, si rimanda alla struttura contenuta nel file TruckVoyageFesibilityStatus.xsd TruckVoyageFeasibilityStatus.xsd I codice fattibilità comunicati nel campo feasibilityCode sono riassunti nella tabella: feasibilityCode Descrizione 0 Viaggio Fattibile per il Contenitore XXXX -1 Impossibile calcolare la fattibilita' del viaggio per il Contenitore XXXX -3 Condizione di terminazione anomalia (ricezione LoadingReport e mancata ricezione di GateIn) -4 Ricevuto GateOut contenitore XXXX -5 Ricevuto GateIn per il contenitore XXXX 14 Viaggio non fattibile per il contenitore XXXX per mancanza del Buono di Consegna. 15 Viaggio non fattibile per il contenitore XXXX per prenotazione non esistente. 16 Viaggio non fattibile per il contenitore XXXX per mancanza di Ordine di Scarico. 17 Viaggio non fattibile per il contenitore XXXX per mancanza di Autorizzazione Merci Pericolose. 18 Viaggio non fattibile per il contenitore XXXX per mancanza Ordine di Scarico. 19 Viaggio non fattibile per il contenitore XXXX per Buono di Consegna Scaduto. 20 Viaggio non fattibile per il contenitore XXXX per blocco imposto dalla dogana. 21 Viaggio non fattibile per il contenitore XXXX per riscontro imposto dalla dogana. 22 Viaggio non fattibile per il contenitore XXXX per blocco imposto dalla guardia di finanza. 23 Viaggio non fattibile per il contenitore XXXX per blocco imposto dall'ufficio controllo antifrode. 24 Viaggio non fattibile per il contenitore XXXX per mancata quadratura peso bolletta associata. 25 Viaggio non fattibile per il contenitore XXXX per relativa bolla non svincolata. Figura 16– BodyXml:Booking Forward inviata al SENDER per accettazione da parte di Eport di un Preavviso di arrivo 100 9.7 Servizi di Prenotazione Ambiente URL Test https://test.uirnet.it/UIRNetServices/BookingServices?wsdl Produzione https://www.uirnet.it/UIRNetServices/BookingServices?wsdl Tutti i webservice qui esposti restituiscono, nell’eventualità di errore durante la validazione utente/cim una struttura errore del tipo: Campo Tipo Descrizione faultCode xs:string Codice errore = env:Server faultString xs:string Motivo errore 9.7.1 GetBookingDetail Restituisce i dettagli della prenotazione RICHIESTA: GETBOOKINGDETAIL Campo Tipo Descrizione Obbligatori userName xs:string Utente (CRM user) S Cim xs:string Pin CRM per ws sicuro S bookingId xs: long Identificativo prentoazione S RISPOSTA: Campo Tipo Descrizione getBookingDetailResponse xs: getbookingDetailResponse Dettagli prenotazione GETBOOKINGDETAILRESPONSE Campo Tipo Descrizione serviceId xs:long Identificativo del servizio srvTypesId xs:long Identificativo Tipologia di Servizio srvTypesCode xs:string Codice della tipologia di servizio stateId xs:int Stato del servizio userName xs:string Identificativo utente 101 operationDate xs:dateTime Data di inserimento/modifica buyerId xs:long Identificativo del Committente locationId xs:long Identificativo indirizzo fornitura bookingId xs:long Identificativo della Prenotazione notes xs:string Note flagOrigine xs:string Origine inserimento/modifica (W per Web, L per Legacy, C per Schedulatore CRON) expiredDate xs:dateTime Data scadenza fruitionStartDate xs:dateTime Data inizio fruizione fruitionEndDate xs:dateTime Data fine fruizione flagConfirmDate xs:boolean Flag conferma manuale prenotazione confirmDate xs:dateTime Data conferma contact xs:string Contatto phone xs:string Numero di telefono attributes xs: List <customAttributes> Caratteristiche proprie del servizio richiesto Campo Tipo Descrizione errorCode xs:string Codice errore message xs:string Messaggio di errore WSEXCEPTION VALORI DI RITORNO ErrorCode Message WS-PRT-E099 Invalid request: user seller <userName> is not unauthorized to view bookings of other buyer WS-PRT-E089 Nessun valore trovato 9.7.2 ListPOIBookings Restituisce una lista di prenotazioni presenti sui POI oggetto della ricerca RICHIESTA: LISTPOIBOOKINGS Campo Tipo Descrizione Obbligatori userName xs:string Utente (CRM user) S Cim xs:string Pin CRM per ws sicuro S sellerId xs: long Codice fornitore servizio N buyerId xs: long Codice committente N serviceTypeId xs: long Tipo servizio N 102 serviceId xs: long Identificativo del servizio N missionId xs: long Identificativo missione N poiId xs: long Identificativo POI N dateFrom xs: anySimpleType Da data N dateTo xs: anySimpleType A data N RISPOSTA: Campo Tipo Descrizione listPOIBookingsResponse xs: listPOIBookingsResponse Elenco indirizzi POI LISTPOIBOOKINGSRESPONSE Campo Tipo Descrizione bookingId xs:long Identificativo della Prenotazione bookingStateId xs:long Identificativo stato della Prenotazione buyerId xs:long Identificativo del Committente poiId xs:long Identificativo POI sellerId xs:long Identificativo fornitore serviceCode xs:string Codice del servizio serviceId xs:long Identificativo del servizio VALORI DI RITORNO ErrorCode Message WS-PRT-E099 Invalid request: wrong parameters WS-PRT-E099 Invalid request: user seller <userName> is not unauthorized to view bookings of other seller WS-PRT-E099 Invalid request: user buyer <userName> is not unauthorized to view bookings of other buyer WS-PRT-E099 request: Mission <missionId> not found for company <idAzienda> WS-PRT-E089 Nessun valore trovato 9.7.3 ListPOIServices Restituisce POI sui quali sono presenti dei servizi prenotabili. RICHIESTA: LISTPOISERVICES Campo Tipo Descrizione Obbligatori userName xs:string Utente (CRM user) S Cim xs:string Pin CRM per ws sicuro S sellerId xs: long Codice fornitore servizio S 103 sellerPIVA xs:string Partita IVA fornitore N serviceTypeId xs:long Codice servizio offerto dai POI N poiList xs: List <poiList> Lista POI su cui effettuare la ricerca N geoRef xs: List <geoRef> Lista POI entro una determinata distanza N RISPOSTA: LISTPOISERVICESRESPONSE Campo Tipo Descrizione listPOIServicesResponse xs: listPOIServicesResponse Elenco indirizzi POI Campo Tipo Descrizione poiId xs:long Identificativo POI Campo Tipo Descrizione latPoint xs:double Latitudine POI lonPoint xs:double Longitudine POI maxDistance xs:long Distanza massima dal POI POILIST GEOREF VALORI DI RITORNO ErrorCode Message WS-PRT-E099 Invalid request: wrong parameters WS-PRT-E099 Invalid request: user seller <userName> is not unauthorized to view bookings of other seller WS-PRT-E099 Invalid request: sellerPIVA <sellerPIVA> unknown WS-PRT-E099 Invalid request: sellerPIVA <sellerPIVA> is not of the seller WS-PRT-E099 Invalid request: sellerId <sellerId> unknown WS-PRT-E099 Unable to connect to the server CRM WS-PRT-E099 Unable to connect to the server GEO WS-PRT-E089 Nessun valore trovato 10 Documentale Ambiente URL Test https://test.uirnet.it/UIRNetServices/DocServices?wsdl 104 Produzione https://www.uirnet.it/UIRNetServices/DocServices?wsdl Tutti i webservice qui esposti restituiscono, nell’eventualità di errore durante la validazione utente/cim una struttura errore del tipo: Campo Tipo Descrizione faultCode xs:string Codice errore = env:Server faultString xs:string Motivo errore 10.1 getDocsByMissionPOI Restituisce i documenti associati alle missioni afferenti al POI RICHIESTA: GETDOCSBYMISSIONPOI Obbligatori Campo Tipo Descrizione userName xs:string Utente (CRM user) Cim xs:string Pin CRM per ws sicuro password xs: string Password utente portale missionId xs:string Identificativo missione poicode xs:string Codice POI RISPOSTA: DOCSBYMISSIONPOIRESPONSE Campo Tipo Descrizione getDocsByMissionPOIResponse xs:getDocsByMissionPOIResponse Lista documenti associati al POI Campo Tipo Descrizione return xs:return Struttura “risultato” Campo Tipo Descrizione item xs:chiaveValoreVO Struttura chiave/valore Campo Tipo Descrizione message xs:string Codice errore GETDOCSBYMISSIONPOIRESPONSE RETURN WSEXCEPTION VALORI DI RITORNO 105 Message [DOC-0020]argomenti obbligatori mancanti: idMissione [DOC-1590]missione inesistente 106
