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:

Specification zip