New Zealand HPI Implementation Guide
1.4.4 - Release

New Zealand HPI Implementation Guide - Local Development build (v1.4.4) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Create Prac Role

Create PractitionerRole Overview

The Create PractitionerRole operation is initiated by a user who needs to create a PractitionerRole record for a person not found on the HPI.
The user has sourced the required information, searched PractitionerRole to make sure the role doesn’t currently exist, and initiates the request to create a new PractitionerRole record.

Create PractitionerRole sequence diagramIntegrating application userIntegrating application userIntegrating applicationIntegrating application<FHIR API> HPI<FHIR API> HPIHPI Practitioner Role databaseHPI Practitioner Role databaseUser specifies Practitioner,Organisation, Facility, StartdatePOST<Endpoint>/PractitionerRoleValidate[]Add request201 Created HTTP statuscode

Create new PractitionerRole processing steps:

  1. The user initiates creating a new PractitionerRole in the integrating application
  2. The integrating application sends an HTTP POST request (a FHIR create) containing the PractitionerRole details E.g. Post<Endpoint>/PractitionerRole
  3. The request is validated - ALT: Validation failure. OperationOutcome resource returned
  4. A PractitionerRole record is created and a hpi-practitionerrole-id issued
  5. The HPI FHIR API confirms a successful update – HTTP 201 Created status code
  6. The integrating application indicates to the user the create has been successful
  7. The integrating application retains the hpi-practitionerrole-id and version number for future requests relating to this record

Create PractitionerRole Example

For a Create Practitioner Role example click here

Create PractitionerRole Rules and errors

For Request rules and errors click here

Create PractitionerRole rules

  • A create PractitionerRole request must include:
    • a valid hpi-person-id,
    • an hpi-facility-id and/or hpi-organisation-id
    • a valid role code
  • A create PractitionerRole request may include:
    • Period (start date and end if applicable)
    • Messaging-address (EDI)
    • Contact details (telecom)
  • A PractitionerRole-status-reason is mandatory when a period end-date is supplied
  • A create PractitionerRole request must not create a duplicate, or overlap another PractitionerRole record See also

  • Create PractitionerRole errors
    • “hpi-person-id invalid” (HTTP 422, Unprocessable, Error, Processing)
    • “hpi-person-id is required” (HTTP 422, Unprocessable, Error, Processing)
    • “hpi-organization-id or hpi-facility-id is required” (HTTP 422, Unprocessable, Error, Processing)
    • “Resource validation error: duplicate” (HTTP 422, Unprocessable, Error, Processing)
    • “PractitionerRole-status-reason is required” (HTTP 422, Unprocessable, Error, Processing)

Create PractitionerRole - Period rules (if supplied)

  • A PractitionerRole period date must be formatted YYYY-MM-DD
  • A PractitionerRole period start date must be less than, or equal to end date

  • Create PractitionerRole - Period errors
    • Period is not valid; format must be yyyy-mm-dd
    • Period start date must be less than, or equal to end date

Create PractitionerRole - Contact rules (If supplied).

  • A request must not result in a duplicate contact
  • A contact point value must have a valid format (HISO recommends)
  • Valid mobile phone number format
    • International ITU-T E.164 numbers are variable length numeric strings without punctuation, composed of country code, area code or mobile network code and subscriber number
    • Numbers should be entered, validated and displayed as separate components, eg: 64 4 232nnnn, 64 20 412nnnnn
  • Valid email format
    • an email address must have a local-part@domain-part format
    • the address length must not exceed 256 characters
    • can contain any UTF-8 characters except control characters.
  • Contact period must be formatted YYYY-MM-DD
  • Contact period start date must be less than, or equal to end date
  • Rank may be supplied for contactpoints, Gaps in the sequence of rank are allowed, 1 is the highest rank, Rank 0 is invalid, When rank is not supplied it will be assigned the next lowest rank within the PracRole telecom contactpoints.

  • Create PractitionerRole - Contact errors
    • The contact point you are creating is a duplicate of another on this record
    • The mobile phone format is invalid
    • The email format is invalid
    • Contact period is invalid; format must be yyyy-mm-dd
    • Contact period start date must be less than or equal to a contact point period end date