HI Service - Search for HPI-I

Introduction

It is highly recommended that your software conducts Healthcare Provider Identifier-Individual (HPI-I) searches for users of your system. This is because most healthcare providers know their Ahpra number, but not their HPI-I number.

The Australian Digital Health Agency (the Agency) has received significant negative user feedback on products that have not implemented HPI-I searches. This feedback specifically mentions the advantages of conducting HPI-I searches using Ahpra numbers, where possible.

Pre-requisites

Ensure you have access to the HI Service licenced material and specifically the document for TECH.SIS.HI.31 which will describe the specifications of the SearchForProviderIndividual web service used in this guide. Page 7 provides a detailed description of the request and response parameters.

Steps in previous HI Service Guides, such as HI Service - IHI Lookup, HI Service - IHI Lookup - Test Cases, are required to be completed, before following this guide.

Overview

At the end of this walkthrough, you'll have a Windows form that conducts an HPI-I search using the registration id (Ahpra number) and family name values. Within your application this functionality would likely be combined into your existing user setup screen with HPI-Is searched when:

• a new user is added,  
• a user is updated, or  
• as part of another workflow when there are users who do not have an HPI-I in the local system.

We have added a Search HPI-I button to our main form in the first screenshot below. In the 2nd screenshot you will see our fields for searching for the provider’s HPI-I. In your application this would likely be added to an existing user settings screen. 

Step 1: Add a new Form

Step 1.1. Add a new Windows Form called “Search HPI-I Form” in the existing project that we have created in the previous guide, HI Service – IHI Lookup. If you have not followed previous guides, such as HI Service – IHI Lookup and HI Service – IHI Lookup – Test Cases there are prerequisite steps you will have missed.  

Step 1.2. Add the following fields to the form and name them accordingly. 

Step 2: Add code to conduct an HPI-I search

Step 2.1. Right click on SeachHPI-IForm and click view code to open the class file. Add the following additional namespaces. 

using System.ServiceModel;
using System.ServiceModel.Channels;
using System.Security.Cryptography.X509Certificates;
using Nehta.VendorLibrary.Common;
using nehta.mcaR50.ProviderSearchForProviderIndividual;
using System.Configuration;
using Nehta.VendorLibrary.HI;

Step 2.2. Open App.Config from the Solution explorer and copy the SOAP client configuration inside the App.Config file, replacing the values which have been provided to you by Services Australia.  

App.Config 

App.Config

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
    <startup> 
        <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.7.2" />
    </startup>
	<appSettings>
		<!--Certification Seial No-->
		<add key="CertSerial" value="" />
		<!--Product Type Info-->
		<add key="Platform" value="Windows 10" />
		<add key="ProductName" value=" " />
		<add key="ProductVersion" value="" />
		<add key="VendorId" value=" " />
		<add key="VendorQualifer" value="http://ns.electronichealth.net.au/id/hi/vendorid/1.0" />
		<!--Qualifier Info-->
		<add key="QualifierId" value=" " />
		<add key="Qualifier" value="http://yourcompany.com.au/id/yoursoftware/hpio/1.0" />
	</appSettings>
</configuration>

Step 2.3. Add the following code to the SearchHPI-IForm.cs class file to prepare the variables and assign the values from the App.Config file.

private readonly static string Certificate_Serial = ConfigurationManager
      .AppSettings.Get("CertSerial");
private readonly static string Product_Platform = ConfigurationManager
      .AppSettings.Get("Platform");
private readonly static string Product_Name = ConfigurationManager
     .AppSettings.Get("ProductName");
private readonly static string Product_Version = ConfigurationManager
     .AppSettings.Get("ProductVersion");
private readonly static string Vendor_Id = ConfigurationManager
      .AppSettings.Get("VendorId");
private readonly static string Vendor_Qualifier = ConfigurationManager
     .AppSettings.Get("VendorQualifer");
private readonly static string Qualifier_HPIO_Id = ConfigurationManager
     .AppSettings.Get("QualifierId");
private readonly static string Qualifier_HPIO = ConfigurationManager.
      AppSettings.Get("Qualifier");

Step 2.4. The code should look like the screenshot below. 

Step 2.5. Double click on the Search HPI-I button to add the following code on the button click event. 

private void btnSearchHPI-I_Click(object sender, EventArgs e)
{
   // Obtain the certificate by serial number
    X509Certificate2 tlsCert = X509CertificateUtil.GetCertificate(
        Certificate_Serial,
        X509FindType.FindBySerialNumber,
        StoreName.My,
        StoreLocation.CurrentUser,
        true
        );
    // The same certificate is used for signing the request.
    // This certificate will be different to TLS cert for some operations.
    X509Certificate2 signingCert = tlsCert;
    // Set up client product information (PCIN)
    // Values below should be provided by Medicare
    ProductType product = new ProductType()
    {
        platform = Product_Platform,     // Can be any value
        productName = Product_Name,                               // Provided by Medicare
        productVersion = Product_Version,                         // Provided by Medicare
        vendor = new QualifiedId()
        {
            id = Vendor_Id,                                       // Provided by Medicare               
            qualifier = Vendor_Qualifier                          // Provided by Medicare
        }
    };
    // Set up user identifier details
    QualifiedId user = new QualifiedId()
    {
          // User ID internal to your system
        id = "User Id",
         // Eg: http://ns.yourcompany.com.au/id/yoursoftware/userid/1.0                                          
        qualifier = "http://<anything>/id/<anything>/userid/1.0"  
    };
    // Set up organisation identifier details, only required for CSP software.
    // If run as a CSP software, the certificate needs to be a CSP certificate
 
    // Set up user identifier details
    QualifiedId hpio = new QualifiedId()
    {
        id = Qualifier_HPIO_Id, // HPIO internal to your system
        // Eg: http://ns.yourcompany.com.au/id/yoursoftware/userid/1.0
        qualifier = Qualifier_HPIO    
    };
    // ------------------------------------------------------------------------------
    // Client instantiation and invocation
    // ------------------------------------------------------------------------------
    // Instantiate the client
    var client = new ProviderSearchForProviderIndividualClient(
        new Uri("https://www5.medicareaustralia.gov.au/cert/soap/services/"),
        product,
        user,
        hpio,
        signingCert,
        tlsCert);
    // Create the search request 
    var request = new searchForProviderIndividual()
    {
        familyName = txtFamilyName.Text,
        registrationId = txtRegistrationId.Text,
    };
    try
    {
        // Invokes provider individual search.
        var response = client.ProviderIndividualSearch(request);
        var hpiSearchResult = response.searchForProviderIndividualResult;
        txtSearchResult.Text = "";
        if (hpiSearchResult.hpiiNumber != null)
        {
            txtSearchResult.Text = hpiSearchResult.hpiiNumber
                 .Substring(hpiSearchResult.hpiiNumber.Length - 16, 16);
        }
        else
        {
            txtError.Text = hpiSearchResult.serviceMessages
                 .serviceMessage[0].reason;
        }
        txtSOAPRequest.Text = client.SoapMessages.SoapRequest;
        txtSOAPResponse.Text = client.SoapMessages.SoapResponse;
    }
    catch (FaultException fex)
    {
        string returnError = "";
        MessageFault fault = fex.CreateMessageFault();
        if (fault.HasDetail)
        {
            ServiceMessagesType error = fault.GetDetail<ServiceMessagesType>();
            // Look at error details in here
            if (error.serviceMessage.Length > 0)
                returnError = error.serviceMessage[0].code + ": " + error
                   .serviceMessage[0].reason;
        }
        txtError.Text = returnError;
        // If an error is encountered, client.LastSoapResponse often provides a more
        // detailed description of the error.
        string soapResponse = client.SoapMessages.SoapResponse;
        txtSOAPResponse.Text = soapResponse;
    }
    catch (Exception ex)
    {
        txtSOAPResponse.Text = ex.StackTrace;
        txtError.Text = ex.Message;
    }
}

Step 2.6. Add a button on your Main Form and following code to show the new “Search HPI form” Form.

private void button3_Click(object sender, EventArgs e)
{
   SearchHPI-IForm hpi-iForm = new SearchHPI-IForm();
   hpiForm.Show();
}

Step 2.7. Run the application, open the Search HPI-I Form, and search for an HPI-I using the Registration Id and Family Name.

Step 2.8. Conduct the search with both valid and invalid data to see the responses from the HI Service. 

Step 3: Use Case 131 (UC.131)

We will now review several important & recommended test cases from UC.131. As usual it is important to note that the Test Cases identified below is not the complete list. View the complete list of Test Cases here: HI Service Use Cases.

This test case is very similar to HI_010_005873 in UC.010 as it relates to logging your interactions with the HI Service. No further comment is necessary.

This test case is very similar to HI_010_008028 in UC.010 as it relates to retaining an audit trail of all healthcare identifiers associated with a record.

This test case explains that Clinical Information Systems (CIS) software shall be capable of providing a way to validate the HPI-I on the update screen as shown in the screenshot below. It is most likely that you would incorporate an HPI-I search every time the user’s details were changed and the user pressed a Save Changes or equivalent button. You may also want to have an additional Validate HPI-I button too.

Code below to demonstrate the logic how to handle the resolved HPI-I 

// Instantiate the client
var client = new ProviderSearchForProviderIndividualClient(
    new Uri("https://www5.medicareaustralia.gov.au/cert/soap/services/"),
    product,
    user,
    hpio,
    signingCert,
    tlsCert);
// Create the search request 
var request = new searchForProviderIndividual()
{
    familyName = txtFamilyName.Text,
    hpiiNumber = HIQualifiers.HPIIQualifier + txtHPINumber.Text
};
try
{
    // Invokes provider individual search.
    var response = client.ProviderIndividualSearch(request);
    var hpiSearchResult = response.searchForProviderIndividualResult;
    if (hpiSearchResult.serviceMessages != null && hpiSearchResult.serviceMessages.serviceMessage[0].code == "WSE0134")
    {
        // Verify that the software revalidates the returned  HPI-I with the local demographic data.
        var returnedProvider = new Provider()
        {
            FamilyName = hpiSearchResult.familyName,
            GiveName = hpiSearchResult.givenName,
            DOB = hpiSearchResult.dateOfBirth,
            // so on
        }
        // assume we have data in localProvider object.  
        if(verifDemographics(localProvider, returnedProvider))
        {
            // If the returned  HPI-I can be validated successfully, ensure the returned  HPI-I is stored in the  provider record
        }
        else
        {
            // Verify that if the new  HPI-I cannot be validated with the local  provider demographic data then an alert shall be raised so an operator can determine what action should be taken.
            DialogResult dialogResult = MessageBox.Show("The provider HPI-I cannot be validated with the name and registration information provided.", "HPI-I Warning", MessageBoxButtons.OK, MessageBoxIcon.Exclamation);
                        
            // Provide options to operator to determine what action should be taken.
        }
    }
switch(hpiSearchResult.status)
{
    case "R":
        MessageBox.Show("", "", MessageBoxButtons.OK, MessageBoxIcon.Warning);
        break;
    case "D":
        MessageBox.Show("", "", MessageBoxButtons.OK, MessageBoxIcon.Warning);
        break;
}
}
catch (FaultException fex)
{
    string returnError = "";
    MessageFault fault = fex.CreateMessageFault();
    if (fault.HasDetail)
    {
        ServiceMessagesType error = fault.GetDetail<ServiceMessagesType>();
        // Look at error details in here
        if (error.serviceMessage.Length > 0)
            returnError = error.serviceMessage[0].code + ": " + error.serviceMessage[0].reason;
    }
    string soapResponse = client.SoapMessages.SoapResponse;
}

The following screenshot demonstrates when local demographic data cannot be validated with returned HPI-I

The following screenshot shows the SOAP Response when the HPI-I service message is showing an HPI-I which is resolved to a new HPI-I.

The following code demonstrates when the provider family name is changed (i.e. Marriage), it revalidates the HPI-I with the new demographics and raises an alert if the revalidation fails. Let’s assume we have a method called validate HPI-I which makes a call to the HI Service. As mentioned above this could occur as part of the Save Changes (or similarly named) button.

private void UpdateProviderDetails(Provider provider)
{
    // Before saving the provider details i.e. name, revalidate HPI-I
    if(_hiService.ValidateHPI-I(provider)
    {
        // Save new information. 
    }
    else
    {
        // Alert user
    }
}

Conclusion

If you have followed the instructions clearly for the 2 HI Service Developer Guides, then you should now be ready to integrate this functionality more thoroughly into your product and undertake the Conformance phase of integration. To progress please refer to Section 2 – “Healthcare Identifiers Conformance Testing” in the HI Service - Test and Go Live guide.  

View All | Back | Find whether a My Health Record exists