Paradigma FHIR messaging
Il paradigma scelto per lo scambio dei dati con OMr è quello del FHIR messaging. Il paradigma messaging prevede un sender, un receiver, un evento di trigger che innesca la creazione e l’invio di un messaggio, un messaggio di richiesta e uno messaggio di risposta.
Un messaggio FHIR è un Bundle con Bundle.type=message, avente come prima risorsa MessageHeader. Tale Risorsa contiene i metadati del messaggio:
- EventCoding: evento che porta all'inizio del flusso (MessageHeader.eventCoding);
- Sender: applicazione che invia il messaggio (MessageHeader.source);
- Receiver: applicazione che riceve il messaggio (MessageHeader.destination);
- Message Identifier: identificativo univoco del messaggio (MessageHeader.id);
- Date/Time: data e ora di creazione del messaggio (Bundle.timestamp).
Un messaggio contiene due identifier obbligatori ed univoci per il mittente, ovvero Bundle.id e MessageHeader.id. Ogni volta che viene inviato lo stesso messaggio il Bundle.id deve cambiare mentre MessageHeader.id rimane invariato.
Quando il destinatario elabora il messaggio, risponderà con:
- un nuovo Bundle, avente un nuovo Bundle.id;
- la prima risorsa sarà MessageHeader con source e destination opportuni e un nuovo MessageHeader.id
- l'attributo MessageHeader.response.identifier sarà valorizzato con il MessageHeader.id del messaggio di richiesta.
Il receiver può restituire un codice di stato 200 OK se il messaggio è stato elaborato con successo. Mentre, i codici di errore sono:
- 4xx che indica che l’errore è contenuto nel messaggio e il messaggio non va inviato nuovamente;
- 5xx, il quale indica che l’errore è lato server e il messaggio va inviato nuovamente.
NB: “xx” rappresenta una coppia di numeri che identificano in modo più dettagliato la tipologia di errore.
Qualora ci siano stati degli errori nell'elaborazione del messaggio, il dettaglio dell'errore è riportato in maniera testuale nella risorsa OperationOutcome.
Struttura della richiesta HTTP
L'invio della richiesta a OMr deve essere strutturata seguendo il metodo POST del paradigma HTTP. Le chiamate HTTP devono contenere il seguente header:
| Nome header | Valore | Descrizione |
|---|---|---|
| Content-Type | application/fhir+json | Mime type del formato di scambio |
I servizi FHIR esposti dai Sistemi Informativi degli Enti Erogatori sono accessibili attraverso i canali protetti. Per inviare a OMr è necessario inviare una richiesta con la seguente struttura:
POST [Endpoint-OMr]?async=true&response-url=[URL-target]
dove:
- Endpoint-OMR rappresenta l'url che espone OMr per ricevere i messaggi in FHIR per questo progetto.
- async=true è un parametro opzionale che permette di indicare la modalità asincrona.
- response-url è un parametro opzionale che indica URL-target come endpoint per la restituzione della risposta se diverso dall'enpoint inviante.