JConnector Guide v1.0

1























D
ocument Details

N
ame

JConnector

Guide

Date


12/02/2012

Author

Sunny Sharma





Version Control

Version
Number

Date

Updated by

Update summary

0.0.1

08/02
/201
2

Sunny Sharma

Initial Draft















J
Connect
o
r Guide

Version

1.0

Date

12

/

02

/ 2012


JConnector

Guide

Page
2

of
20

Document Information

Purpose

The purpose of this document is to provide a
n overview of
PCEHR
JConnector

application
covering
the
Personally Controlled Electronic Health Record
(
PCEHR) web services exposed via B2B Gateway channel
of the
PCEHR

system
.

Audience

The intended audience for this document include software
vendors

and Healthcare Organisations with an
interest in interacting

with the
PCEHR

B2B web services including:





Software vendors of products involved in medical software systems;



Organisation that implement medical software systems;



Health service providers;


3


T
able of Contents

1. Introduction

................................
................................
................................
................................
..................

4

1.1. Document Scope

................................
................................
................................
..............................

4

1.2. Docum
ent Terminology and Acronyms

................................
................................
............................

4

1.3. Links and References

................................
................................
................................
.......................

5

2.
JConnector

Design

................................
................................
................................
................................
......

6

2.1. PCHER System Specification

................................
................................
................................
..........

6

2.2. Application Design

................................
................................
................................
..........................

10

3.
JConnector

Features

................................
................................
................................
................................
.

11

3.1. V
ersion 1.0

................................
................................
................................
................................
.....

11

3.2. Future releases
................................
................................
................................
...............................

11

4.
JConnector

Implementation

................................
................................
................................
.....................

12

4.1. Tools

................................
................................
................................
................................
...............

12

4.2. DoesPCEHRExist Implementation

................................
................................
................................
.

13

5.
JConnector

Testing

................................
................................
................................
................................
...

15

5.1. SoapUI

................................
................................
................................
................................
............

15

5.2. jUnit

................................
................................
................................
................................
................

15

6.
JConnector

Download
................................
................................
................................
...............................

17

6.1. Source Code
................................
................................
................................
................................
...

17

6.2. Buildin
g the Source Code

................................
................................
................................
...............

17

Appendix A

DoesPCEHRExist Class Diagrams

................................
................................
.....................

18




JConnector

Guide

Page
4

of
20

1.

Introduction

The Personally Controlled
Electronic Healthcare Record (PCE
H
R) System will allow individuals, their
representatives, healthcare organisations and providers to manage and share electronic health records
based on a regime of personally controlled access and user entitlements that pro
mote a high level of
maturity and interoperability.


The Personally Controlled Electronic Healthcare Record (PCEHR) System will be accessible from a range of
clinical systems, including GP systems, pharmacy systems, hospital systems, aged care systems, spe
cialist
systems, etc. The PCEHR system will expose a number of system interfaces
via B2B Gateway channel
where applications such as Clinical Information Systems (CIS) can connect. How the clinical system is
integrated with the PCEHR System will vary from
system to system. Some systems may have inbuilt
features to access the PCEHR System and others may rely on a combination of backend gateways and
provider portal integration to access the PCEHR System.
The B2B Gateway channel does not provide a
comprehensiv
e list of all interactions between a Clinical Information System (CIS) and PCEHR.


This document details the sample implementation

(PCEHR
JConnector
)

that utilizes B2B Gateway channel
to interact with PCEHR system.

The scope of this implementation is limi
ted to implementing the key
interaction scenarios exposed via B2B gateway channel and the operations utilized within those scenarios to
interact with the PCEHR system. The sample implementation is an attempt to demonstrate how a local CIS
might trigger a
set of interactions between a CIS and the PCEHR system. This application does not intend to
elaborate on the internal workings of CIS, but is intended to help guide and contextualize interactions
between CIS and PCEHR.

1.1.

Document Scope

This

document provides

commentary on the following areas:



Section 1
–

Introduction
.
The introduction

o
utlines the document’s purpose,
terminology and
references.



Section 2
–

JConnector

Design
.
This section describes
JConnector

application design

and
provides references to PCEHR interface specifications
.



Section 3
–

JConnector

Features
. This section outlines
current supported
features and future
release roadmap.



Section 4
–

JConnector

Implementation
. This section
describes

implementation steps for

one of
the PCEHR B2B web services and the tools required.



Section 5
–

JConnector

Testing
. This section describes the unit testing conducted during the
development of the application.



S
ection 6

–

JConnector

Download
. This section outlines
artefacts that ar
e available for download.


1.2.

Document Terminology and Acronyms

Table
1

-

Terminology

Term

Description

B2B

Business to Business (web services)

CIS

An Information System used to help support clinical activity.

CSP

Contracted Service Provider

HI

Healthcare Identifier

HPI
-
I

Healthcare Provider Identifier
–

Individual

HPI
-
O

Healthcare Provider Identifier
–

Organisation

IHI

Individual Healthcare Identifier

5


LSS

Logical Service Specification

NEHTA

National E
-
Health Transition Authority

TSS

Technical Service Specification

1.3.

Links and
References




sourceforge.net/projects/pcehrvendor




vendors.nehta.gov.au/




cxf.apache.org/docs/overview.html




github.com/KentBeck/junit/downloads




www.eclipse.org/downloads




v
endors.nehta.gov.au




www.medicareaustralia.gov.au




www.nehta.gov.au




www.healt
h.gov.au/ehealth




www.ehealthinfo.gov.au

JConnector

Guide

Page
6

of
20

2.

JConnector

Design

2.1.

PCHER System
Specification

The
PCEHR system

specifications have been published by NeHTA. The specifications

are described by multiple documents over two levels; the platform
independent Logical Service Specifications (LSS) and the platform specific implementable Technical Service Specifications (TS
S).

The LSS covers computational and informational viewpoints
of the PCEHR solution and is focused on providing all the information required for a healthcare provider,
system integrator or software vendor to plan the inclusion of this functionality within their application.

The TSS covers an implementable technical i
nterface specification for the PCEHR solution that includes service interface details, data types, input and output
message types, header information, service fault data types, XSD schemas and WSDLs.

These publications are available at
vendors.nehta.gov.au/

and have been used as the basis of
JConnector

design and implementation.

2.1.1.

Web Services Alignment with LSS/TSS

The following table lists the
JConnector

web service names mapping to LSS/TSS web services names.

Table
2

–

Web services Mapping

Logical Group

JConnector

Web
Service Name

Description

LSS Web Service
Name

TSS Web Service Name

WSDL Operation Name

Record Access
Service

DoesPCEHRExist

This operation is used to check
existence of a PCEHR record for an
Individual in the PCEHR system.

This is the only operation that doesn't
trigger an audit record. Note:
Individuals can access their audit
records

DoesPCEHRExist

DoesPCEHRExist

DoesPCEHRExist

7


Logical Group

JConnector

Web
Service Name

Description

LSS Web
Service
Name

TSS Web Service Name

WSDL Operation Name

Record Access
Service

GainPCEHRAccess

This operation is called to establish
access to a PCEHR Record. If successful
it will add the calling provider
organisation to the Provider Access List,
and make
appropriate documents and
views for that PCEHR record available to
the provider. Depending on the
authorisation controls set by the
Individual, it may require an Access
Code to be entered before access is
granted.

GainPCEHRAccess

GainPCEHRAccess

GainPCEHRA
ccess

View Service

GetAuditView

This operation is used to retrieve an
audit trail for a PCEHR record.

GetAuditView

GetAuditView

GetAuditView

View Service

GetConsolidatedView

This operation is used to retrieve the
consolidated view from a PCEHR record.

GetConsolidatedView

GetConsolidatedView

GetConsolidatedView

View Service

GetRepresentativeList

This operation is used to retrieve
representative list for an individual’s
PCEHR record.

Note this is an early version of an
interface that is likely to be upda
ted
before official specification publication.

N/A

N/A

N/A

View Service

GetChangeHistoryVie
w

This operation is used to retrieve a list
of the different versions of a document
stored in a PCEHR record.

GetChangeHistoryVie
w

GetChangeHistoryView

GetChangeHistoryView

View Service

GetDocumentList

This operation is used to retrieve a list
documents stored for a PCEHR record.

GetDocumentList

GetDocumentList
(registryStoredQuery)

DocumentRegistry_Regis
tryStoredQuery

View Service

GetDocumentList

The
findDocuments operation is used to
find or locate documents which match
specified search criteria.

findDocument

ITI
-
18 Registry Stored
Query

DocumentRegistry_Regis
tryStoredQuery

Document
Exchange
Service

GetDocument

This operation is used to retrieve a
document for a PCEHR record.

RetrieveDocument

ITI
-
43 Retrieve
Document Set

DocumentRepository_Re
trieveDocumentSet


JConnector

Guide

Page
8

of
20

Logical Group

JConnector

Web
Service Name

Description

LSS Web Service
Name

TSS Web Service Name

WSDL Operation Name

Document
Exchange
Service

RemoveDocument

This operation is used to logically
remove a document from an
individual’s PCEHR record.

The author of the document should still
be able to access the document
metadata through GetDocumentList,
but will no longer be able to access th
e
document itself

DeregisterDocument

RemoveDocument

RemoveDocument

Document
Exchange
Service

UploadDocument

This operation is used to store/upload a
new document for a PCEHR record.

SubmitDocument

ITI
-
41 Provide &
Register Document Set
–

b

DocumentRepository_Pr
ovideAndRegisterDocum
entSet
-
b

Document
Exchange
Service

UploadDocumentMet
adata

The registerDocument operation
registers a document stored within a
Conformant Repository within the
PCEHR index.

registerDocument

ITI
-
42 Register
Document Set
–

b

DocumentRegistry_Regis
terDocumentSet
-
b

Document
Exchange
Service

GetDocument

This operation allows the PCEHR System
to retrieve a document from a
Conformant Repository.

This interface is not intended to allow
Clinical Information Systems or Portals
to retrieve documents directly from a
Conformant Repository.

retrieveRemoteDocum
ent

ITI
-
43 Retrieve
Document Set

DocumentRepository_Re
trieveDocumentSet

Document
Exchange
Ser
vice

N/A

The setDocumentAccessLevel operation
is used to change the access level
associated with a document.

This service is not available to CIS, CSP
or CRP roles, and is hence not availble
in this initial connector.

setDocumentAccessLe
vel

setDocumentAccessLev
el

setDocumentAccessLevel

9


Logical Group

JConnector

Web
Service Name

Description

LSS Web Service
Name

TSS Web Service Name

WSDL Operation Name

N/A

SearchTemplate

This operation is used to find
information about one or more
instances of

a Template
-
Package. If
successful, the search operation returns
a list of all templates within the
template repository which have
attributes matching the search criteria

SearchTemplate

SearchTemplate

SearchTemplate

N/A

GetTemplate

This operation is used
to retrieve a copy
of a Template
-
Package from the
repository. If successful, the operation
returns the template package and
associated metadata.

RetrieveTemplate

RetrieveTemplate

GetTemplate


JConnector

Guide

Page
10

of
20

2.2.

Application Design

The application architecture consists of loosely coupled layers as shown in figure below
–


2.2.1.

U
ser
I
nterface (UI)

Layer


This layer provides the user interface for to enter request information pertaining to the PCEHR web services
exposed via B2B Gateway chan
nel implemented in the PCEHR system. The UI layer is developed based on
the Model View Controller (MVC) design pattern and consists of multiple views, models and controllers. The
technology used for developing the UI layer is Java Swing.


2.2.2.

Service Invocatio
n

(SI)

Layer

This layer provides the interfaces between the UI layer and Web Services. It provides an interface to pass
the request object and receive the response object. The logic obtains references to the web service clients
and invokes web service methods. The serv
ice invocation layer receives the request from the controller in
the UI layer, validates the request, applies the business logic in order to process the request and provides
the response to the controller. The service invocation layer encapsulates the impl
ementation details of the
specific web services to the UI layer.


2.2.3.

Web Services Stubs

(WSS) Layer

This layer contains the actual proxy stubs generated from the WSDLs of the web services exposed via B2B
Gateway channel. This layer includes the WSDL files a
nd the schemas used to generate the stubs. The
stubs are in turn used by the SI layer to invoke the web services and handle the response. Apache CXF is
used as the run time to generate the web service stubs and marshall/unmarshall the data from the web
ser
vices.


2.2.4.

Application Components

The
JConnector

implementation includes

following
components
–


Table
3

–

Application Components

Component

Description

Thick Client (desktop
application)

The user interface
allowing the users to interact with the
application.

B2B Service Handlers

The SI layer that encapsulates the UI triggers and builds appropriate
request objects and handles response objects.

B2B Util Helper

The relevant helper classes of the application that packages the WSDLs,
SSL and NASH
certificate for mutual authentication.

Request Models

Request objects for UI of the application.

Response Models

Response objects for UI of the application.

Stubs

Apache CXF generated classes from the WSDLs to invoke the web
services.




11


3.

JConnector

Fe
atures

3.1.

Version 1.0

PCEHR
JConnector

release 1.0 features
-




Web Service Clients for PCEHR B2B Web Service operations based on the Apache CXF framework
(refer to Appendix A for complete list of operations).



SSL Mutual Authentication using National
Authentication Service for Healthcare (NASH) certificates.



User Interface based on the Java Swing framework.



Request Model Objects to capture the raw request data from the UI.



Service Handlers to translate the request models into B2B objects.



Web Service S
tubs and Client wrappers to process the request/response using the Apache CXF
runtime.



Java Util logging to capture SOAP requests and SOAP responses.



Junit4 for Junit test cases.

3.2.

Future releases

PCEHR Java Connector future releases will feature
-




CDA Doc
ument generator :

o

Generate CDA documents via template as input

o

Generate CDA documents via libraries



Multi
-
threading framework.



Smart stubs
–

to enable simulation of PCEHR B2B web service response



Enhanced error handling and logging.



Enhanced UI.



Improved v
alidation of the requests/response messages.





JConnector

Guide

Page
12

of
20

4.

JConnector

Implementation

The follo
w
ing figure shows inner working of the application that is flow of request and response objects in the
PCEHR Java connector application.



Figure 1

–

JConnector

Application


The model

described in figure 1

has been used to implement all the web services within the application.

4.1.

Tools

This section provides details of the tools utilized and the setup steps for building
JConnector

application.
Following table lists the tools
–

Table
4

-

Tools

Tool

Description

Version

Eclipse IDE

An open source development platform written in Java comprised of
extensible frameworks, tools and runtimes for building, deploying and
managing software across the lifecycle.

Helios
Service
Release 2

Apache CXF

An open source services framework for building and developing services
using frontend programming APIs, like JAX
-
WS and JAX
-
RS.

2.5.1

Junit

A

unit testing

framework

for the

Java programming language

4.0

SoapUI

A
n

open source

web service testing tool for

service
-
oriented
architectures

(SOA)
. Its functionality covers

web service

inspection,
invoking, development, simulation and

mocking
,

functional

testing, load
and compliance testing
.

4.0.1

Netbeans IDE

A
n open source integrated development environment available for
Windows

and an

application platform

that enable developers to
rapidly
create using the Java platform.

7.01

CDA library

Sample j
ava code
for creating CDA documents available on NeHTA
vendor
web
site
.

1.1.2


The steps required to setup the development environment are as follows
–


Stubs Wrapper

Stubs

Apache CXF library

Invocation Layer

Handlers

Services

UI Layer

Java Swing

NetbeansIDE

13



1.

Install eclipse IDE or any other
Java IDE to set up a new Java project (
www.
eclipse
.org/
downloads
)

2.

Configure Apache CXF runtime within the eclipse IDE runtime configurations.
(
http://cxf.apache.org/docs/overview.html
).

4.2.

DoesPCEHRExist Implementation

DoesPCHERExist is record access web service of the PCEHR system. This operation is used to check
existence of a PCEHR record for an Individual in the PCEHR system. This is the only op
eration that doesn't
trigger an audit record.
This section provides step by step guide for implementing connectivity to PCEHR
system B2B web services.



Following are the steps for implementing connectivity to doesPCEHRExist B2B web service in the java
co
nnector are as follows
-


1.

Create a new java project. Refer to the PCEHRProfileServiceStubs project in code base of this
project.

2.

Generate the web service stubs for the doesPCEHRExist web service using the B2B PCEHR Profile
Service WSDL available at
https://vendors.nehta.gov.au/
.

NOTE:
-

The stubs can be generated using the eclipse IDE web service client generation option or
the wsdl2java command detailed at
http://cxf.apache.org/docs/overview.html
.

3.

Create a new java project for the web service client wrapper. Refer to the DoesPCEHRExist in the
B2BInboundServiceHandlers code base of this project.

The wrapper extends the B2BDefaultService and implements
B2BServiceDefaultInterface. The
service retrieves the port from the stubs based on the service interface and port type and invokes
the doesPCEHRExist operation on the port.

4.

In the project created in step 3 create a package for the handler. Refer to the
DoesPCEHRExistHandler in the code base of this project.

The handler extends the B2BServiceDefaultHandler and implements the 2BHandlerInterface.The
handler class accepts the request object from the UI and creates the corresponding B2B request
object based o
n the schema definition of the object. The handler class also returns the SOAP
response from the service to the UI. All the handler classes contain and executeSync method which
executes the web service operation. The soap requests and responses are captur
ed by the handler
in the log. The handler also sets the soap response on the response model object for UI to display
the results.

5.

Add the following dependencies to the Handler and Services project created in step 3 and 4 above.

a.

PCEHRProfileServiceStubs.ja
r
–

The subs created in step 1 above.

b.

RequestModels.jar
-

The request models which represent the model objects for the user
interface request. This contains the DoesPCEHRExistRequestModel.

c.

ResponseModels.jar
–

The response models which represent the model
objects for the user
interface response. This contains the DoesPCEHRExistResponseModel.

Note
:
-

This release currently supports viewing the SOAP response.

d.

B2BUtilHelper.jar
–

The jar file with the helper classes which contains the helper classes
such as l
oading the SSL certificates, endpoint urls, wsdl files for the application. This helper
jar also requires the Common XSD jar file required to be added to the project.

e.

Apache CXF runtime
-

The CXF runtime enables marshalling and unmarshalling of the java
obj
ects into xml and vice versa.


6.

Clean and build the above project.

7.

Create a new Java UI project or a java application client project in eclipse or any other IDE. This
project is the client which will connect to the B2B doesPCEHRExist web service. Refer to

the
DoesPCEHRExist jUnit in the code base for implementing this client. Add the following
dependencies to this project
-

a.

Jar of the service layer from step 6. This jar contains the stubs, handler, request, response
and helper classes.

b.

Apache CXF runtime li
brary as the service layer is dependent on this runtime.


JConnector

Guide

Page
14

of
20

The alternative is to create a library with the service layer jar and the CXF runtime and
adding the library to the client code.


8.

To successfully invoke the web service operation execute the followi
ng steps
-


a.

Create the instance of the request model object and set the values from the user input.

b.

Create the instance of the response model object to handle the response from the service
layer.

c.

Create the instance of the handler (created in step 6) and invoke the executeSync method
on the handler.

d.

Display the SOAP response from the response model object.

All the PCEHR B2B services have been implemented as per the steps described above.
The follow
ing
figure

shows the
class diagram

for doesPCEHRExist implementation with reference to the architecture of the
JConnector

application.


Figure 2

–

DoesPCEHRExist Class Diagram


A complete list of class diagrams for DoesPCEHRExist service is detailed in Ap
pendix A.
The class
diagrams are also available at
https://sourceforge.net/projects/pcehrvendor/







15


Figure
3

below shows PCEHR
JConnector

user interface for doesPCEHRExist interface.




Figure 3

–

Application screenshot

The input fields (parameters) in the user interface are detailed in
PCEHR
JConnector

Input Parameters v 1 0

available at
https://sourceforge.net/projects/pcehrv
endor/

5.

JConnector

Testing

5.1.

SoapUI

SoapUI is the web service testing tool that has been
implemented

to create and invoke web services
messages

during unit testing stage prior to testing the
JConnector

application

in jUnit
.


The tool also provides capability
to attach a certificate to a request in order to authenticate with PCEHR
system.

5.2.

jUnit

JUnit

framework

was used unit testing the application. All the web services have
been tested for 3 test cases
as outlined below
–



1.

Success
–

Verify that the web service is invoked successfully without errors and a success response
is received.

2.

Invalid HPI
-
O
-

Verify that an invalid HPI
-
O message is received in the response and the requ
est is
not processed.

3.

Invalid Message ID
–

Verify that an invalid Message ID message is received in the response and the
request is not processed.


Following figure shoes the jUnit class diagram for DoesPCEHRExist web service implementation.



JConnector

Guide

Page
16

of
20


Figure 4

–

DoesPCEHRExist jUnit Class Diagram


JUnit test source files, test data and test results are available at
https://sourceforge.net/projects/pcehrvendor/




17


6.

JConnector

Download

6.1.

Source Code

The foll
owing steps are required to install the JConnector.

1.

Download the JConnector jar file from
https://sourceforge.net/projects/pcehrvendor/

2.

Double click to run the application.

3.

The application
launches the user interface.

6.2.

Building the Source Code

The following steps are required to build the source code.

1.

Download the source code from
https://sourceforge.net/projects/pcehrvendor/

2.

Impor
t the code into any Java IDE preferably eclipse.

3.

Resolve the project dependencies.

Refer to the readme document
available at
https://sourceforge.net/projects/pcehrvendor/






JConnector

Guide

Page
18

of
20

Appendix A

DoesPCEHRExist

Class Diagrams




Figure 5

–

DoesPCEHRExisthandler Class Diagram

19



Figure 6

–

DoesPCEHRExist Request Model Class Diagram


JConnector

Guide

Page
20

of
20


Figure 7

–

DoesPCEHRExist Helper Class Diagram