@startuml seq-fhir-screening-publicAPI-typicalflow

!define COMMON .
!include COMMON/sequence-skinparams.iuml

scale max 400 width
scale 300*500

actor "health practitioner (screening)" as USER
participant "NZ health app/PMS" as APIC #Orange

box "HNZ digital services hub /\n connector plane" #LightGrey
  entity "API authn. server" as ROSIE #IndianRed
  entity "API gateway" as APIG #IndianRed
end box

box "HNZ FHIR APIs" #WhiteSmoke
  entity "**Screening FHIR API**" as SCRAPI #SkyBlue
  entity "HNZ FHIR API" as FHIR #LightSalmon
  database "National Health Index /\n Health Provider Index" as NHIHPI #LightSalmon
end box

title "Cervical screening summary API - typical sequence"

== API consumer OAUTH authentication at PMS initialisation ==

APIC -> ROSIE++: OAUTH2.0 Client Credentials Flow\n<size:12>(client creds, scopes, audiences)</size>
return OAUTH token
note right
  """scope": ["" 
    """system/DocumentReference.rs",""
    """system/Patient.r" ]""
  """aud": "https://fhir-ig.digital.health.nz/screening/StructureDefinition/nz-screening-summary"""
end note

== normal API usage ==

USER -> APIC++ #YellowGreen: enter patient name, NHI
APIC -> NHIHPI: NHI search
APIC -> USER--: present NHI matches

USER -> APIC++ #YellowGreen: request screening summaries for\n selected NHI and programme type 

note right of APIC
  App/PMS sets the following user metadata in ""Request-Context""
    """**hpiPractitioner**""" - practitioner's Common Person Number (CPN) from Health Provider Index
    """**hpiFacility | hpiOrganisation**""" - HPI facility OR organisation identifier from Health Provider Index
end note

APIC -> APIG++: ""GET /DocumentReference?{search-params}""

APIG -> APIG: validate OAUTH token\n<size:10>(issuer,sig)</size>

APIG -> SCRAPI++-- #SkyBlue: ""GET"" /**DocumentReference**?<params>

group error scenarios
  break#Red Bad/missing access OAUTH token (issuer, scope, audience, expiry)
    SCRAPI -[dashed]x APIC: HTTP ""401"" error: Unauthorized
  end
  break#Red Bad/missing ""Request-Context"" custom header
    SCRAPI -[dashed]x APIC: HTTP ""400"" error: Bad Request
  end
  break#Red Practitioner | Organisation | Facility Id not valid
    SCRAPI -x APIC: HTTP ""400"" Bad Request (""**HPI_INVALID**"")
  end
end

SCRAPI -> FHIR++: Search for Prior Terms Acceptance Forms
note left of SCRAPI
  <size:18>Search for FHIR QuestionnaireResponses  ""GET /v1/**QuestionnaireResponse**""
  <size:18>Queries based on available params:

  <size:16>**Org/facility** acceptance search by **facility**:
        ""?**questionnaire**=https://fhir-ig.digital.health.nz/screening/Questionnaire/**TermsOfUseOrgFacility**""
        ""&**subject:identifier**=FZZ958-K""

  <size:16>**Org/facility** acceptance search by **org**:
        ""?**questionnaire**=https://fhir-ig.digital.health.nz/screening/Questionnaire/**TermsOfUseOrgFacilityr**""
        ""&**subject:identifier**=GZZ956-B""

  <size:16>**Practitioner** acceptance search by **facility**:
      ""?**questionnaire**=https://fhir-ig.digital.health.nz/screening/Questionnaire/**TermsOfUsePractitioner**""
      ""&**author:identifier**=91ZABY""
      ""&**subject:identifier**=FZZ958-K""

  <size:16>**Practitioner** acceptance search by **org**:
      ""&**author:identifier**=91ZABY""
      ""&**subject:identifier**=GZZ956-B""
end note

return MATCHES

SCRAPI -> SCRAPI: Check matching Org/Facility Terms of Use acceptance

 break#Red No Terms of Use acceptance by org/fac
    SCRAPI -x APIC: HTTP ""403"" Forbidden (""**NO_TOU_ORGFAC**"")
  end

SCRAPI -> SCRAPI: Confirm matching Practitioner Terms of Use acceptance

alt #LightGreen normal report generation
SCRAPI -> SCRAPI: get data from backend APIs
SCRAPI -> SCRAPI: generate screening summary content as HTML and PDF
SCRAPI -> SCRAPI: include participant data as ""Patient"" instance
SCRAPI -> APIC: ""200 OK"", FHIR searchset ""Bundle"" 
  note left of SCRAPI #LightYellow
    In normal search response is a FHIR searchset Bundle.  Each
      Bundle entry comprises a ""DocumentReference (mode:#match)"" containing 
      the formatted screening summary, AND a ""Patient (mode:#include)"" 
      instance for the patient demographic detail
  end note

else #Orange No screening summary is available 
SCRAPI -> APIC: ""200 OK"", ""Bundle"" of ""mode: #outcome""
  note left of SCRAPI #Orange
    When screening history not available for specified subject, the Bundle contains one
    or more //OperationOutcome//s (""mode: #outcome"") describing the reason(s).
    end note
else #Red technical error
  SCRAPI -[dashed]x APIC--: HTTP ""4xx|5xx"" error code
  note left of SCRAPI #IndianRed
    In technical error scenarios, the response 
    is just a FHIR ""OperationOutcome""
  end note
end

APIC -> APIC: process results and display to user 

APIC -> USER--: present screening summary / search result

@enduml