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
Enter the password to open this PDF file:
File name:
-
File size:
-
Title:
-
Author:
-
Subject:
-
Keywords:
-
Creation Date:
-
Modification Date:
-
Creator:
-
PDF Producer:
-
PDF Version:
-
Page Count:
-
Preparing document for printing…
0%
Comments 0
Log in to post a comment