$questionnaire-packageOperazione FHIR per HealthLake

L'$questionnaire-packageoperazione recupera un pacchetto completo contenente un questionario FHIR e tutte le sue dipendenze necessarie per il rendering e l'elaborazione del questionario. Questa operazione implementa la Da Vinci Documentation Templates and Rules (DTR) Implementation Guide, che consente il rendering dinamico dei moduli per i requisiti di documentazione nei flussi di lavoro sanitari.

Come funziona

Casi d'uso

Endpoint API

POST /datastore/{datastoreId}/r4/Questionnaire/$questionnaire-package  
Content-Type: application/fhir+json

Parametri della richiesta

Parametri di input

Il corpo della richiesta deve contenere una risorsa FHIR Parameters con i seguenti parametri:

Regole di convalida dei parametri

È necessario fornire almeno UNO dei seguenti elementi (oltre a quelli obbligatoricoverage):

Combinazioni di richieste valide:

Richiesta di esempio

POST /datastore/example-datastore/r4/Questionnaire/$questionnaire-package  
Content-Type: application/fhir+json  
Authorization: Bearer <your-token>  
  
{  
  "resourceType": "Parameters",  
  "parameter": [  
    {  
      "name": "coverage",  
      "resource": {  
        "resourceType": "Coverage",  
        "id": "example-coverage",  
        "status": "active",  
        "beneficiary": {  
          "reference": "Patient/example-patient"  
        },  
        "payor": [{  
          "reference": "Organization/example-payer"  
        }],  
        "class": [{  
          "type": {  
            "coding": [{  
              "system": "http://terminology.hl7.org/CodeSystem/coverage-class",  
              "code": "group"  
            }]  
          },  
          "value": "12345"  
        }]  
      }  
    },  
    {  
      "name": "questionnaire",  
      "valueCanonical": "http://example.org/fhir/Questionnaire/home-oxygen-therapy|2.0"  
    },  
    {  
      "name": "order",  
      "resource": {  
        "resourceType": "ServiceRequest",  
        "id": "example-service-request",  
        "status": "active",  
        "intent": "order",  
        "code": {  
          "coding": [{  
            "system": "http://www.ama-assn.org/go/cpt",  
            "code": "94660",  
            "display": "Continuous positive airway pressure ventilation (CPAP)"  
          }]  
        },  
        "subject": {  
          "reference": "Patient/example-patient"  
        }  
      }  
    },  
    {  
      "name": "changedSince",  
      "valueDateTime": "2024-01-01T00:00:00Z"  
    }  
  ]  
}

Formato della risposta

Risposta riuscita (200 OK)

L'operazione restituisce una risorsa FHIR Parameters contenente uno o più Package Bundle. Ogni pacchetto Package include:

{  
  "resourceType": "Parameters",  
  "parameter": [  
    {  
      "name": "PackageBundle",  
      "resource": {  
        "resourceType": "Bundle",  
        "id": "questionnaire-package-example",  
        "meta": {  
          "profile": ["http://hl7.org/fhir/us/davinci-dtr/StructureDefinition/DTR-QPackageBundle"]  
        },  
        "type": "collection",  
        "timestamp": "2024-03-15T10:30:00Z",  
        "entry": [  
          {  
            "fullUrl": "http://example.org/fhir/Questionnaire/home-oxygen-therapy",  
            "resource": {  
              "resourceType": "Questionnaire",  
              "id": "home-oxygen-therapy",  
              "url": "http://example.org/fhir/Questionnaire/home-oxygen-therapy",  
              "version": "2.0",  
              "status": "active",  
              "title": "Home Oxygen Therapy Documentation",  
              "item": [  
                {  
                  "linkId": "1",  
                  "text": "Patient diagnosis",  
                  "type": "choice",  
                  "answerValueSet": "http://example.org/fhir/ValueSet/oxygen-diagnoses"  
                }  
              ]  
            }  
          },  
          {  
            "fullUrl": "http://example.org/fhir/Library/oxygen-prepopulation",  
            "resource": {  
              "resourceType": "Library",  
              "id": "oxygen-prepopulation",  
              "url": "http://example.org/fhir/Library/oxygen-prepopulation",  
              "version": "1.0",  
              "type": {  
                "coding": [{  
                  "system": "http://terminology.hl7.org/CodeSystem/library-type",  
                  "code": "logic-library"  
                }]  
              },  
              "content": [{  
                "contentType": "text/cql",  
                "data": "bGlicmFyeSBPeHlnZW5QcmVwb3B1bGF0aW9u..."  
              }]  
            }  
          },  
          {  
            "fullUrl": "http://example.org/fhir/ValueSet/oxygen-diagnoses",  
            "resource": {  
              "resourceType": "ValueSet",  
              "id": "oxygen-diagnoses",  
              "url": "http://example.org/fhir/ValueSet/oxygen-diagnoses",  
              "status": "active",  
              "expansion": {  
                "timestamp": "2024-03-15T10:30:00Z",  
                "contains": [  
                  {  
                    "system": "http://hl7.org/fhir/sid/icd-10",  
                    "code": "J44.0",  
                    "display": "COPD with acute lower respiratory infection"  
                  },  
                  {  
                    "system": "http://hl7.org/fhir/sid/icd-10",  
                    "code": "J96.01",  
                    "display": "Acute respiratory failure with hypoxia"  
                  }  
                ]  
              }  
            }  
          },  
          {  
            "fullUrl": "http://example.org/fhir/QuestionnaireResponse/example-prepopulated",  
            "resource": {  
              "resourceType": "QuestionnaireResponse",  
              "id": "example-prepopulated",  
              "questionnaire": "http://example.org/fhir/Questionnaire/home-oxygen-therapy|2.0",  
              "status": "in-progress",  
              "subject": {  
                "reference": "Patient/example-patient"  
              },  
              "basedOn": [{  
                "reference": "ServiceRequest/example-service-request"  
              }],  
              "item": [  
                {  
                  "linkId": "1",  
                  "text": "Patient diagnosis",  
                  "answer": [{  
                    "valueCoding": {  
                      "system": "http://hl7.org/fhir/sid/icd-10",  
                      "code": "J44.0",  
                      "display": "COPD with acute lower respiratory infection"  
                    }  
                  }]  
                }  
              ]  
            }  
          }  
        ]  
      }  
    },  
    {  
      "name": "Outcome",  
      "resource": {  
        "resourceType": "OperationOutcome",  
        "issue": [{  
          "severity": "information",  
          "code": "informational",  
          "details": {  
            "text": "Successfully retrieved questionnaire package"  
          }  
        }]  
      }  
    }  
  ]  
}

Flusso di lavoro operativo

Come HealthLake elabora la tua richiesta

Quando chiami$questionnaire-package, HealthLake effettua le seguenti operazioni:

Risultato: un pacchetto completo e autonomo pronto per il rendering.

Risposte agli errori

400 Richiesta non valida

Restituito quando la convalida della richiesta fallisce.

{  
  "resourceType": "OperationOutcome",  
  "issue": [{  
    "severity": "error",  
    "code": "required",  
    "details": {  
      "text": "At least one of 'questionnaire' or 'order' must be provided along with 'coverage'"  
    }  
  }]  
}

4.2.4 Dipendenza non riuscita

Restituito quando una risorsa dipendente non può essere recuperata.

{  
  "resourceType": "OperationOutcome",  
  "issue": [{  
    "severity": "warning",  
    "code": "not-found",  
    "details": {  
      "text": "Referenced Library 'http://example.org/fhir/Library/missing-library' could not be retrieved"  
    }  
  }]  
}

401 - Autorizzazione negata

Restituito quando le credenziali di autenticazione sono mancanti o non valide.

403 Non consentito

Restituito quando l'utente autenticato non è autorizzato ad accedere alle risorse richieste.

406 Non accettabile

Restituito quando non è possibile fornire il tipo di contenuto richiesto.

409 Conflitto

Restituito in caso di conflitto di versione o concorrenza.

410 Andato

Restituito quando la risorsa richiesta è stata eliminata definitivamente.

429 Troppe richieste

Restituito quando vengono superati i limiti di velocità.

500 - Errore interno del server

Restituito quando si verifica un errore imprevisto del server.

501 non implementato

Restituito quando l'operazione richiesta non è ancora implementata.

Regole di convalida

Convalida dell'input

QuestionnaireResponse convalida

Deduplicazione delle risorse

Specifiche prestazionali

Autorizzazioni richieste

Per utilizzare l'$questionnaire-packageoperazione, assicurati che il tuo ruolo IAM abbia:

SMART su FHIR Scopes

Ambiti minimi richiesti:

Note importanti sull'implementazione

Strategia di recupero delle risorse

Priorità di identificazione del questionario:

Risoluzione delle dipendenze

Librerie CQL:

ValueSets:

QuestionnaireResponse prepopolazione

L'operazione può restituire un file QuestionnaireResponse con dati precompilati quando:

Criteri di ricerca per QuestionnaireResponse:

Filtraggio delle risorse modificato

Quando viene fornito il changedSince parametro:

Pacchetti multipli

L'operazione può restituire più Package Bundle quando:

Ogni Package Bundle è autonomo con tutte le dipendenze necessarie.

Casi di utilizzo comune

Caso d'uso 1: documentazione di autorizzazione preventiva

Scenario: un fornitore deve raccogliere la documentazione per un'autorizzazione preventiva di ossigenoterapia domiciliare.

{  
  "resourceType": "Parameters",  
  "parameter": [  
    {  
      "name": "coverage",  
      "resource": { /* Patient's insurance coverage */ }  
    },  
    {  
      "name": "order",  
      "resource": {  
        "resourceType": "ServiceRequest",  
        "code": {  
          "coding": [{  
            "system": "http://www.ama-assn.org/go/cpt",  
            "code": "94660"  
          }]  
        }  
      }  
    }  
  ]  
}

Risultato: restituisce un pacco con il questionario di ossigenoterapia, precompilato con i dati anagrafici dei pazienti e i codici di diagnosi dell'EHR.

Caso d'uso 2: recupero di una versione specifica del questionario

Scenario: un provider necessita di una versione specifica di un questionario per la conformità.

{  
  "resourceType": "Parameters",  
  "parameter": [  
    {  
      "name": "coverage",  
      "resource": { /* Coverage resource */ }  
    },  
    {  
      "name": "questionnaire",  
      "valueCanonical": "http://example.org/fhir/Questionnaire/dme-request|3.1.0"  
    }  
  ]  
}

Risultato: restituisce esattamente la versione 3.1.0 del questionario di richiesta DME con tutte le dipendenze.

Caso d'uso 3: verifica la presenza di aggiornamenti

Scenario: un provider desidera verificare se alcune risorse del questionario sono state aggiornate dall'ultimo recupero.

{  
  "resourceType": "Parameters",  
  "parameter": [  
    {  
      "name": "coverage",  
      "resource": { /* Coverage resource */ }  
    },  
    {  
      "name": "questionnaire",  
      "valueCanonical": "http://example.org/fhir/Questionnaire/medication-request"  
    },  
    {  
      "name": "changedSince",  
      "valueDateTime": "2024-03-01T00:00:00Z"  
    }  
  ]  
}

Risultato: restituisce solo le risorse che sono state modificate dopo il 1° marzo 2024 o un pacchetto vuoto se non è cambiato nulla.

Caso d'uso 4: ordini multipli

Scenario: un provider invia più richieste di assistenza che possono richiedere questionari diversi.

{  
  "resourceType": "Parameters",  
  "parameter": [  
    {  
      "name": "coverage",  
      "resource": { /* Coverage resource */ }  
    },  
    {  
      "name": "order",  
      "resource": { /* ServiceRequest for imaging */ }  
    },  
    {  
      "name": "order",  
      "resource": { /* ServiceRequest for DME */ }  
    }  
  ]  
}

Risultato: restituisce più Package Bundle, uno per ogni questionario applicabile.

Integrazione con Other Da Vinci IGs

Discovery dei requisiti di copertura (CRD)

Integrazione del flusso di lavoro:

Support di autorizzazione preventiva (PAS)

Integrazione del flusso di lavoro:

Data Exchange clinico (CDex)

Integrazione del flusso di lavoro:

Guida alla risoluzione dei problemi

Problema: nessun questionario restituito

Possibili cause:

Soluzioni:

Problema: dipendenze mancanti nel pacchetto

Possibili cause:

Soluzioni:

Problema: Package vuoto con ChangedSince

Possibili cause:

Soluzioni:

Problema: QuestionnaireResponse non precompilato

Possibili cause:

Soluzioni:

Best practice

1. Usa Canonical URLs con le versioni

Specificate sempre i numeri di versione quando richiedete questionari specifici:

{  
  "name": "questionnaire",  
  "valueCanonical": "http://example.org/fhir/Questionnaire/dme|2.1.0"  
}

Perché: garantisce la coerenza e previene modifiche impreviste quando i questionari vengono aggiornati.

2. Sfrutta ChangedSince per le prestazioni

Per i questionari a cui si accede di frequente, utilizza changedSince per ridurre al minimo il trasferimento dei dati:

{  
  "name": "changedSince",  
  "valueDateTime": "2024-03-10T15:30:00Z"  
}

Perché: riduce la latenza e l'utilizzo della larghezza di banda recuperando solo le risorse aggiornate.

3. Includi informazioni complete sulla copertura

Fornisci dettagli completi sulla copertura per garantire la corretta selezione del questionario:

{  
  "name": "coverage",  
  "resource": {  
    "resourceType": "Coverage",  
    "beneficiary": { "reference": "Patient/123" },  
    "payor": [{ "reference": "Organization/payer-abc" }],  
    "class": [{ /* Group/plan information */ }]  
  }  
}

Perché: aiuta a HealthLake identificare i questionari e i requisiti specifici del pagatore.

Operazioni correlate