In this guide, you will;
- Register as a developer for the HI Service
- Request Test Certificates and Test Environment Data
- Install the Test Certificates locally
- Import Certificates in CIS Software
Important
This guide is currently only available in C#. If you are using other languages/platforms you may still find the content relevant although you will need to adapt it to suit your environment.
HI Service developer registration
Important
Start this registration process now as there will be some turnaround time for responses and you will need test certificates to begin development.
To gain access to the HI Service Software Vendor Test (SVT) Environment you will need to register on the Health Systems Developer Portal provided by Services Australia. This portal will be your gateway to developer resources for the HI Service. The portal is a secure platform and you will need to register your organisation to access it. You will need to be an authorised officer of your organisation and have an Individual Provider Digital Access (PRODA) account before you can register your organisation in the portal. Registering for a PRODA account takes 10 minutes if you do not already have it. Follow the steps below to register for PRODA, accept the Interface Agreement, access the API documentation (referred to as the Licenced Material), and access the HI Service SVT to begin your product development and testing.
1. Create an Individual PRODA account. This step requires 3 forms of identity documents. For most users the easiest are a Passport, Drivers Licence, and Medicare card. This process should take about 10 minutes. If you have any issues with your identification and cannot progress (such as discrepancies between maiden names, middle names, etc.) you will need to manually submit your identification using this form: https://www.servicesaustralia.gov.au/organisations/health-professionals/forms/hw080. Contact the PRODA support line for additional help: 1800 700 199 and select Option 1.
2. Once your PRODA account is created, go to the Health Systems Developer Portal and register your organisation. You will need the PRODA RA number which was sent to you from step 1 above. If you cannot find your PRODA RA number you can login to your PRODA Account, select Profile and your RA Number will be visible. Note that the Health Systems Developer Portal does not have a link from the PRODA landing page, you must use the Health Systems Developer Portal link to login. This process should take less than 20 minutes and you will need to be an authorised officer of your organisation to register. If your organisation is already registered your authorised officer will be able to grant access to additional users.
3. Once you are registered for the Health Systems Developer Portal you will be sent an email with your security credentials, you can use these to login to the portal. Registration submissions require manual review and you may not receive confirmation immediately. Continue on to HI Service Development Scope below and return to these steps once you are granted access.
4. When you first login you will accept the Interface Agreement before you can access the HI Service licensed material. Services Australia will contact you to discuss your requirements and ask you for your software name and version number so that they can register your software product in the HI Service SVT environment. You will advise them that you are connecting to the HI Service and they will then generate your testing certificates. If you are also connecting to the My Health Record system you will also notify them at this point.
5. Once you retrieve access, download the relevant Healthcare Identifiers documentation. The HI Service licensed material contains approximately 40 documents for developers interested in creating products which connect to the HI Service. It is unlikely that you will need to read all these documents. We recommend that you briefly familiarise yourself with the following 2 documents, we will refer to them as needed throughout these developer guides.
- HI Service - Developers Guide
- HI Service - IHI Searching Guide
Most of the other documents each relate specifically to an individual web service of the HI Service. Most developers will only be interested in a subset of these services, so will only require the documents relevant to the services of interest.
Webinar
If you are looking to integrate your clinical software with My Health Record system, the Australian Digital Health Agency has developed the following webinar recording for My Health Record B2B Software Developers. This webinar recording provides an introduction to integrating B2B software with the My Health Record system.
HI Service development scope
When developing to connect to the HI Service it is important to consider what functionality you will be building. These developer guides focus on important functionality and Use Cases.
We will show you how to retrieve an IHI using patient demographics (IHI Lookup) and how to retrieve a healthcare provider individual's HPI-I using their AHPRA number and name.
The HI Service provides additional functionality including the ability to find HPI-Os. For a complete list you can review HI Service Use Cases.
Conformance testing
To finalize your development and gain access to the HI Service production environment you will need to undergo 2 methods of testing; Notice of Connection (NoC) testing and Conformance, Compliance & Assessment (CCA) testing. The complete process is described on this page:
HI Service Test and Go Live
Important
When you are ready to conduct your HI Service CCA testing you will need to submit a completed Implementation Conformance Statement Proforma form. This form can be found in the Healthcare Identifiers Service - Support Documents v1.4 package. This package is additional to the resources you will access on the Services Australia Health Systems Developer Portal. Please familiarise yourself with this package and document now, for completion at a later date. The document contains a wealth of information about the HI Service web services, use cases and requirements.
Certificate setup
Within a few days you will receive your NASH Test Certificates for the HI Service and can begin building your implementation by connecting to the Software Vendor Test (SVT) Environment. It may be useful to note that up until 2019, Medicare Site Certificates were required for the HI Service. This mechanism has now been improved and you will use NASH Certificates to access the HI Service.
Setup NASH CA certificates on a Windows environment
1. Unzip the certificates zip file to extract all of the certificate files. Your ZIP file will look similar to the screenshot below.
2. First we will install the Certificate Authority (CA) certificates. In the screenshot above these are tmaoca.crt and tmarca.crt. Install each CA certificate following the steps below.
a. Double click on the CA certificate, the installation window will appear.
b. Click Next and select the Place all certificates in the following store option.
c. Click Browse… and choose Trusted Root Certification Authorities as the Certificate Store.
d. Click next and finish installation.
3. Repeat step 2 to install each certificate.
Setup NASH Organisation certificate (Personal Information Exchange)
1. Install the NASH private key certificate (typically named fac_sign.p12 file) by double clicking the file.
2. Click Next and enter the Password for private key provided by Services Australia.
3. Click Next and select the Place all certificates in the following store option.
4. Click Browse… and choose Personal for certificate store and click OK.
5. Click next and finish installation.
Find the certificate serial number
To connect to the HI Service and My Health Record system you will need a certificate for TLS and signing the Header. To identify the certificate to use in your code, you will need the serial number of the certificate. Follow the steps below to retrieve the serial number.
1. Go to Manage User Certificates from the Windows Start Menu.
2. Navigate to Personal -> Certificates to verify that the certificate is installed.
3. Double click on the certificate to view the details.
4. In the Details tab, you can find the Certificate Serial number required in developer guides.
Code sample to load the certificate
We have provided the following code below which can be reused for loading the certificate when required. This code sample will be provided again when required in our next guide.
using System.Security.Cryptography.X509Certificates;
X509Certificate2 cert = X509CertificateUtil.GetCertificate(
Certificate_Serial,
X509FindType.FindBySerialNumber,
StoreName.My,
StoreLocation.CurrentUser,
true);
return cert;
}Production certificates in your software
The steps above will prepare your development environment to connect to the SVT environment. Your users however will receive production environment certificates and you will likely want to simplify the way which they load these certificates into your software.
If you already connect to Medicare APIs then you will likely already have a UI screen which allows the user to load certificates. You may want to leverage this same process to allow them to load their NASH certificates. If you do not already have functionality to load production certificates via your UI you will want to investigate this.
Important
The CA certificates for production environments are different from the SVT. Therefore you will need to install production CA certificates for your users. These certificates can be found at https://www.certificates-australia.com.au/.
Conclusion
You should now be familiar with the HI Service. You should be registered as a developer and have your local development environment set up with certificates. You should also understand the scope of your development and be familiar at a high level with your testing obligations.
In the next guide we will begin our first calls to the HI Service web services.