@startuml seq-fhir-screening-publicAPI-termsacceptanceflow

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

'scale 300 width
scale 300*500

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

' box "HNZ digital services hub" #WhiteSmoke
'   entity "API auth. server" as ROSIE #IndianRed
'   entity "API gateway" as APIG #IndianRed
' end box

box "HNZ FHIR APIs" #WhiteSmoke
  entity "**Screening FHIR API**" as SCRAPI #SkyBlue
  database "Health Provider Index" as HPI #LightSalmon
  entity "HNZ FHIR API" as FHIR #LightSalmon
  entity "HNZ Application Form API" as MAGICFORM #Orchid
end box

title "Cervical screening API data access - Practitioner terms acceptance form flow"

== API first time use by new practitioner/user ==

USER -> APIC++ #Orange: request screening summary for a patient

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 -> SCRAPI++ #SkyBlue: Get screening summaries by NHI\n  <size:12>""GET /**DocumentReference**?<params>""

SCRAPI -> FHIR++: Search for completed Terms Acceptance \nForm by Practitioner at current Org | Facility\n
note left of FHIR
  <size:16>""GET /v1/**QuestionnaireResponse**""
    ""?**questionnaire**=**https://fhir-ig.digital.health.nz/screening/Questionnaire/TermsOfUsePractitioner**""
        ""&**author:identifier**=91ZABY""
        ""&**subject:identifier**=GZZ956-B""

Or where facility identified rather than org
      ""&**subject:identifier**=FZZ958-K""
end note

return Empty ""Bundle""

alt#Orange The practitioner user has not previously accepted the Terms of Access

  group Validate HPI identifiers
    SCRAPI -> HPI++: Validate Practitioner, Org / Facility identifiers
    return HPI match ""Bundle""

    break#Red Practitioner | Organisation | Facility Id not valid
      SCRAPI -x APIC: HTTP ""400"" Bad Request (""**HPI_INVALID**"")
    end
  end

  group Prepare Terms Acceptance Form

    SCRAPI -> MAGICFORM++ #Orchid: Generate Terms Acceptance Form\n  <size:12>""POST /v1/auth/{formName}/generate-questionnaire-link""
    
    note left of MAGICFORM
      The facade prepares a Terms Acceptance form by sending information
      about the practitioner, organisation | facility in magic link
      claims. 
    end note

    MAGICFORM -> MAGICFORM: Prepare Form
    return Prepopulated Form Url (aka 'magic link')

    SCRAPI -> SCRAPI : Prepare ""OperationOutcome"" 403 response containing 'magic link' 
    
    SCRAPI -> APIC--: HTTP ""403 Forbidden""\n(""**PRACTITIONER_TOU_ACCEPT_NEEDED**"")\n + 'magic link'

    note right of APIC
      On receipt of a 403 response, the App/PMS must check for magic link 
      in the FHIR ""OperationOutcome.diagnostics"" property.
    end note

  end
  
  APIC -> USER++-- #LightBlue : Display form in browser using magic link
   
  USER -> MAGICFORM++ #Orchid: Read special terms of access; complete form; submit to accept

  MAGICFORM -> FHIR : Record practitioner's acceptance of terms

  MAGICFORM -x USER--: Practitioner terms acceptance complete

  deactivate USER
  
end

== API request processing can now proceed - see Typical Operation diagram ==
... <size:16>Now that terms acceptance has been recored, the practitioner/user can retry their request for screening summaries in the PMS. ...

@enduml