New Zealand HPI Implementation Guide - Local Development build (v1.3.1) 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 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