Universal API Implementation Guide - Local Development build (v1.1.19). See the Directory of published versions

Message Structure

Message Structures

​This IG description is based on Specialty Medication Enrollment IG available here

Enrollment Message

Copay

1) Search Request

In search request it’s important to populate MessageHeader attributes correctly:

• eventCoding = copay-search
• source.name = <Name of the vendor integrating with UAPI who submits the request, ex. “Google”>
• source.endpoint = <URL of the above vendor, ex. “http://google.com”>
• focus.reference =
• sender.identifier.assigner.display = <Name of the vendor providing the solution to the Practice and responsible for managing the practice concept, including the identifier of the practice, ex. “Google”>
• sender.identifier.system = <URL of the above vendor, ex. “http://google.com”>
• sender.identifier.use = usual
• sender.identifier.value = <The ID of the practice/hospital which the searched patient belongs to, this identifier comes from the above vendor system.>

Example:

"resource" : {
        "resourceType" : "MessageHeader",
        "id" : "1905b4c5-0a91-4ee4-a721-25d224e87524",
        "meta" : {
          "profile" : [
            "https://fhir.developer.gene.com/StructureDefinition/uapi-messageheader"
          ]
        },
        "eventCoding" : {
          "system" : "http://terminology.gene.com/fhir/usix/uapi/CodeSystem/uapi-event-type",
          "code" : "copay-search"
        },
        "sender" : {
          "type" : "Organization",
          "identifier" : {
            "use" : "usual",
            "system" : "http://vendor.com/ab",
            "value" : "HOSP-12345",
            "assigner" : {
              "display" : "AB Vendor"
            }
          }
        },
        "source" : {
          "name" : "Vendor_AB",
          "endpoint" : "http://vendor.com/ab"
        },
        "focus" : [
          {
            "reference" : "urn:uuid:05402225-7b92-4ac7-8954-27a6c6e6ff02",
            "type" : "Parameters"
          }
        ]
      }

2) Search Response

Because search operation can return multiple patients the data structure in response has multiple levels:

• Level 1 - uapi-bundle-query-response-multi-patient profile has multiple:
• Level 2 - uapi-bundle-search-result-patient which represents individual patient in a practice and has multiple:
• Level 3 - uapi-bundle-search-result - query-results which are in following groupings:
  • ExplanationOfBenefit with copayCoverage and Prescriber
  • Task
  • QuestionnaireResponse

Important relations in UapiBundleSearchResult (search-response):

• EoB.patient = reference to Patient from UapiBundleSearchResultPatient
• EoB.insurer = reference to Genentech (Organization) from copayCoverage in the same UapiBundleSearchResult
• EoB.provider = reference to Prescriber in the same UapiBundleSearchResult
• EoB.insurance = reference to copayCoverage in the same UapiBundleSearchResult
• Coverage.beneficiary = reference to Patient from UapiBundleSearchResultPatient
• Coverage.subscriber = reference to Patient from UapiBundleSearchResultPatient
• Coverage.payor = reference to Genentech (Organization) - contained resource in Coverage resource

…TBD… more details…

3) Copay Request-Response Bundle - used for Enrollment Insert/Update from CRX

• GNE does not require groupNumber as it will be derived from brandId
• brandId will be passed in Task.input resource - “entry:task” in the Bundle
• Task.requester.reference SHALL point to referralPractice (Organization)
• Task.for.reference SHALL point to patient

Query Message

Query Request Message

The Query message requests patient’s service request status information from Genentech. It identifies the organization which patient belongs to, the patient, service request types, original enrollment UUID, and specifies searches to be performed on the Genentech FHIR server.

It is a message Bundle with:

• a mandatory MessageHeader resource with Vendor System information (source.name representing Vendor and sender.reference representing specific Hospital)
  • an event type (eventCoding) equal to query
• a Parameters resource as the focus (see below)
  • Search strings are specified in query-string parameter elements
• a mandatory Organization resource representing the Data Consumer’s system
• a mandatory Patient resource representing the Data Consumer system’s understanding of the patient
• optional ServiceRequest(s) to narrow down results to only specific service request types - see UAPI Code System - Service Request Type for list of available values
• optional Bundle with type equal to transaction-response and id equal to OperationOutcome identifier received as a result of original enrollment submission - to narrow down the results to only specific enrollment submission

Example:

​UAPI Query Message

In the example we are using following query parameters:

• requester-organization - required identifier of the hospital system sending the status query request
• requester-patient - required element with patient identifier to identify the patient record in Genentech FHIR Server Optional parameters included:
• requester-servicerequest - GPF sr type
• requester-servicerequest - BiPa sr type
• requester-bundle-enrollment-id - the GUID of the original enrollment request Search parameter:
• query-string - querying for CoverageEligibilityResponse records where status is active

Different combinations of above parameters can be used to retrieve other data combinations. For other SR types additional resources might need to be queried for given patient and enrollmentID combination by providing additional query-string parameters.

Query Response Message

The Query Response message returns the requested information from a Genentech FHIR Server.

It is a message Bundle with:

• an event type equal to query-response
• a Parameters resource as the focus (see below)
• a mandatory Patient resource representing the requesting party’s understanding of the patient
• a mandatory Patient representing the patient in the Genentech FHIR Server
• Searchset bundle(s) containing search results

Example:

​UAPI Query Response