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

API Manager

L'API Manager espone i servizi di messaggistica FHIR dell'OMr definiti nell'ecosistema di Regione Lombardia. Il base_url con cui accedere a tali servizi è il seguente:

<base_API_Manager> = https://api.servizirl.it/c/servizi.rl/omrfhir/v1.0.0/

L'elenco delle API esposte è:

Metodo HTTP URL
POST /order/message/$process-message
POST /daily/message/$process-message
dove:

<base_API_manager> è l’indirizzo radice del servizio che sarà esposto tramite API Manager; $process-message è l’operazione FHIR esposta.

Laboratori degli enti sanitari

I servizi FHIR richiamati da OMR ed esposti dai laboratori degli enti sanitari per i servizi di messaggistica FHIR dell'OMr devono seguire le seguenti indicazioni:

<base_PDND_LAB_ES> = https://tbd/

L'elenco delle API esposte è:

Metodo HTTP URL
POST /order/message/$process-message
dove:

<base_PDND_LAB_ES> è l’indirizzo radice del servizio che sarà esposto tramite PDND; $process-message è l’operazione FHIR esposta.