2. Specifications

2.1. Record formats

2.1.1. Metadata

The Metadata table must be included in file uploads in order to identify the type and version of the uploaded data.

Table 2.1 Metadata record layout

Data Element (Field Name)

Type (min,max)

Required

Format / Values

Key (key)

string

yes

A metadata key name.

Value (value)

string

yes

The metadata value.

For this version of the specification the required content is shown in the following table:

Table 2.2 Metadata file

key

value

type

YES-INVITATION

version

1.0


2.1.2. Invitation

Table 2.3 Invitation record layout

Data Element (Field Name)

Type (min,max)

Required

Format / Values

Organisation Path (organisation_path)

string

yes

A sequence of colon separated Organisation Keys that fully specifies the Provider Organisation providing a service to the client.

Client Key (client_key)

string (2,50)

yes

This is a number or code assigned to each individual client referred to the commissioned organisation. The client identifier is unique and stable for each individual within the Provider Organisation.

Episode Key (episode_key)

string (2,50)

yes

This is a number or code assigned to each episode. The Episode Key is unique and stable for each episode at the level of the Provider Organisation.

Episode - End Date (episode_end_date)

date

The date on which an Episode of Care is formally or administratively ended

Episode - Completion Status (episode_completion_status)

string

An indication of the completion status of an Episode of Care.

Mobile Number (mobile_number)

string

The mobile phone number of the client.

Email (email)

string

The email address of the client.

Reminders (reminders)

string

YES, Yes, yes, Y, y, NO, No, no, N, n


2.2. Definitions

2.2.1. Client Key

This is a number or code assigned to each individual client referred to the commissioned organisation. The client identifier is unique and stable for each individual within the Provider Organisation.

Field name:

client_key

Data type:

string (2,50)

Required:

yes


2.2.2. Email

The email address of the client.

Field name:

email

Data type:

string

Required:

no

Notes:

Either a mobile number or an email address must be provided for each client so that a link can be sent to the client inviting them to complete a survey as specifies in the metadata file.

After the invitation has been sent, the email address will be discarded.


2.2.3. Episode - Completion Status

An indication of the completion status of an Episode of Care.

Field name:

episode_completion_status

Data type:

string

Required:

no


2.2.4. Episode - End Date

The date on which an Episode of Care is formally or administratively ended

Field name:

episode_end_date

Data type:

date

Required:

no

Notes:
  • The episode end date must be in the format YYYY-mm-dd.

  • The episode end date must not be before 1st January 2016.

  • The episode end date must not be in the future.


2.2.5. Episode Key

This is a number or code assigned to each episode. The Episode Key is unique and stable for each episode at the level of the Provider Organisation.

Field name:

episode_key

Data type:

string (2,50)

Required:

yes

Notes:

See Episode Key.


2.2.6. Key

A metadata key name.

Field name:

key

Data type:

string

Required:

yes


2.2.7. Mobile Number

The mobile phone number of the client.

Field name:

mobile_number

Data type:

string

Required:

no

Notes:

Either a mobile number or an email address must be provided for each client so that a link can be sent to the client inviting them to complete a survey as specifies in the metadata file.

After the invitation has been sent, the mobile number will be discarded.


2.2.8. Organisation Path

A sequence of colon separated Organisation Keys that fully specifies the Provider Organisation providing a service to the client.

Field name:

organisation_path

Data type:

string

Required:

yes

Notes:

A combination of the Primary Health Network’s (PHN’s) Organisation Key and the Provider Organisation’s Organisation Key separated by a colon.

Here is an example organisation structure showing the Organisation Path for each organisation:

Organisation Key

Organisation Name

Organisation Type

Commissioning Organisation

Organisation Path

PHN999

Test PHN

Primary Health Network

None

PHN999

PO101

Test Provider Organisation

Private Allied Health Professional Practice

PHN999

PHN999:PO101


2.2.9. Reminders

Send reminders to the client?

Field name:

reminders

Data type:

string

Required:

no

Domain:

YES, Yes, yes, Y, y, NO, No, no, N, n

Notes:

Indicates whether reminders should be sent to the client.

Invitations are valid for 7 days. The following reminder emails will be sent:

  • 2 days after the invitation - Reminding the client to fill in the YES. Also reminding them of the date on which it will expire.

  • 6 days after the invitation - Reminding the client to fill in the YES. Reminding them that it will expire tomorrow.


2.2.10. Value

The metadata value.

Field name:

value

Data type:

string

Required:

yes


2.3. Download Specification Files

Available for software developers designing extracts for the PMHC MDS, please click the link below to download the PMHC MDS YES Invitation Specification files: