MEDIC Client Registry - MARC-HI Everest - marc

MEDIC Client Registry
Operations and Deployment Guide
Version 1.0.1
Justin Fyfe
2/11/2015
Table of Contents
1.
2.
Introduction .......................................................................................................................................... 4
1.1.
Purpose ......................................................................................................................................... 4
1.2.
About the MEDIC Client Registry .................................................................................................. 4
1.3.
Data Paradigm............................................................................................................................... 4
1.4.
Standards ...................................................................................................................................... 5
Deployment........................................................................................................................................... 7
2.1.
Planning your Client Registry Deployment ................................................................................... 7
2.1.1.
Assigning Authorities ............................................................................................................ 7
2.1.2.
Security ................................................................................................................................. 8
2.1.3.
Planning for Scale .................................................................................................................. 9
2.2.
Installation .................................................................................................................................. 11
2.2.1.
Obtaining the Software ....................................................................................................... 11
2.2.2.
Basic Configuration ............................................................................................................. 11
2.2.3.
Advanced Configuration ..................................................................................................... 14
2.2.4.
Auditing Configuration ........................................................................................................ 24
2.2.5.
Messaging Configuration .................................................................................................... 25
2.3.
Verifying Your Deployment ......................................................................................................... 28
2.3.1.
2.4.
3.
Verifying Security ................................................................................................................ 28
Administrative Interface ............................................................................................................. 29
2.4.1.
Setup the CR Service ........................................................................................................... 29
2.4.2.
Setup an IIS Site................................................................................................................... 29
2.4.3.
Configure the Website ........................................................................................................ 30
Administering the Client Registry ....................................................................................................... 32
3.1.
Reviewing Patient Data ............................................................................................................... 32
3.2.
Conflict View ............................................................................................................................... 34
3.2.1.
3.3.
Resolving Conflicts .............................................................................................................. 35
Obtaining Diagnostic Information............................................................................................... 37
3.3.1.
Versions............................................................................................................................... 37
3.3.2.
Obtaining Log Files .............................................................................................................. 38
3.3.3.
Reviewing Assigning Authorities ......................................................................................... 39
Operations and Deployment Guide
Page 2 of 39
Operations and Deployment Guide
Page 3 of 39
1.
Introduction
This section seeks to introduce the client registry reference implementation, the history of the project as
well as the architecture of the reference implementation.
1.1.
Purpose
This guide is intended to serve as a deployment and operations manual for the MEDIC Client Registry
reference implementation. The guide does not discuss specific details of integration with the client
registry beyond mentioning of base standards.
1.2.
About the MEDIC Client Registry
The MEDIC Client Registry (previously known as MCAAT CR) began as a reference implementation of the
pan-Canadian Standards (pCS) Client Registry messages in early 2010. It was part of the reference
implementation revamp project which sought to improve the performance, flexibility, reuse and
standards compliance of several early reference implementations.
The MEDIC CR is based on, and heavily leverages the MEDIC service core framework. This framework
provides a series of plugins which allow a particular piece of software to “act as” a reference
implementation. The service core provides an application host which loads a series of “service
providers”, each implementing a particular contract or interface. Figure 1 provides a high level overview
of the service classifications implemented in the Client Registry.
Figure 1 - Client Registry Components
This architecture has allowed the client registry to evolve over time and it has since grown to support a
multitude of features and standards.
1.3.
Data Paradigm
The MEDIC Client Registry (and Shared Health Record) sees the world in an interesting manner. Instead
of storing data in a model which is tied to one particular messaging format or information model, it
instead breaks apart data into a series of components. Using this component model, the client registry
Operations and Deployment Guide
Page 4 of 39
expresses data as a hierarchy of component types who participate in their container through as site
relationship. For example: An encounter where a physician “observes” a patient’s estimated date of
delivery would be interpreted as : An Event occurred, an observation (estimated delivery date) was
made which is the subject of the event, an observation of last menstrual period supports the primary
observation, and a health worker is the author of the event.
Figure 2 - Component Pattern
By viewing data through this lense, MEDIC is able to reuse not only application components between
reference implementations, but also the data model components between them.
This component architecture is then normalized into a series of relational tables stored in PostgreSQL.
1.4.
Standards
The MEDIC CR supports a variety of standards, some of which have been validated at the IHE North
American 2015 Connectathon. Table 1 provides a list of standards which the MEDIC CR officially
supports and the options implemented.
Table 1 - Client Registry Interfaces
Standard
HL7v3 pCS
Actor
CR-001 – Add/Revise Client
Fulfiller
IHE PIX
PAT_ID_X_REF_MGR – PIX
HL7v2
Manager
PAT_IDENTITY_SRC – Patient
Identity Source
IHE PDQ
PDS – Patient Demographics
HL7v2
Supplier
IHE PIX
PAT_ID_X_REF_MGR – PIX
HL7v3
Manager
PAT_IDENTITY_SRC – Patient
Identity Source
IHE PDQ
PDS – Patient Demographics
HL7v3
Supplier
Operations and Deployment Guide
Verified As
R02.04.02
Options
None
Module
Messaging > Everest
NA2015
None
Messaging > NHAPI
NA2015
None
NA2015
Continuation Messaging > NHAPI
Not Tested
Pediatric
Not Tested
None
Not Tested
Continuation Messaging > Everest
Pediatric
Page 5 of 39
Messaging > Everest
IHE PDQm
PDS – Patient Demographics
Supplier for Mobile
Operations and Deployment Guide
NA2015
Continuation Messaging > FHIR
Pediatric
Page 6 of 39
2.
Deployment
This section seeks to discuss the steps required to deploy the MEDIC Client Registry in a variety of
environments. It describes the basic considerations that should be undertaken prior to installing the
Client Registry in a production environment including hardening.
2.1.
Planning your Client Registry Deployment
Prior to deploying the Client Registry it is important to understand the environment into which it is
being deployed. Operationalizing a Client Registry takes much time and consideration and rushing this
process can lead to greater issues during maintenance and migration.
2.1.1. Assigning Authorities
The first task for planning is the assigning authorities and security configuration. In a client registry, an
Assigning Authority is a device or organization which holds authority over identifiers within that domain.
It is important to gather an understanding of organizations which will be the sources of identities as well
as the domain for which they will contribute identifiers and demographics.
To assist in the organization of this, it is useful to maintain a list of domain identifier and assigning
authority information. While this can be done within the CR, it is recommended that implementers use a
spreadsheet or table for tracking authority and domain information. The following step-by-step guide
can be used as a method for doing this work, it is not, by any means the only way to assign OIDs.
Root
Suffix
Use
Device
Notes
The steps for completing this pre-setup task are:
1. Register a Root: You should register a root OID which you can subdivide for the Client Registry.
If you’re deploying an HIE, you should have a root authority for the HIE which you can subdivide
into the CR components. To register a root OID, you can contact IANA’s Private Enterprise
Number (PEN) service.
Root
1.3.6.1.4.1
Suffix
0000
Authority
PROJECT
Device
Notes
Our ROOT OID for Project
2. Subdivide your OID for each system: Create a root OID for each of the systems in your
infrastructure including the Client Registry. Typically the Client Registry will have its own “root”
which it can subdivide.
Root
Suffix
Authority
Device
Notes
1.3.6.1.4.1
0000
PROJECT
N/A
Our ROOT OID for Project
1.3.6.1.4.1.0000
10
CR
CR
Client Registry’s OID
1.3.6.1.4.1.0000.10
1
Hosts
N/A
Cluster – Physical Devices
1.3.6.1.4.1.0000.10.1
1
CR
CR1
Application Host 1
Note that this example assumes you may want to have multiple App Servers, in which case
you’d subdivide again for each physical host.
3. Subdivide your OID for logical identifiers: You will also have to subdivide OIDs for your logical
identifiers used within the client registry:
Operations and Deployment Guide
Page 7 of 39
Root
1.3.6.1.4.1
1.3.6.1.4.1.0000
1.3.6.1.4.1.0000.10
1.3.6.1.4.1.0000.10.2
1.3.6.1.4.1.0000.10.2
Suffix
0000
10
2
1
2
Authority
PROJECT
CR
CR
ECID
EVT
Device
N/A
CR
N/A
CR
CR
Notes
Our ROOT OID for Project
Client Registry’s OID
Logical identifiers
Enterprise Client IDs
Event Identifiers
4. Obtain third party OIDs for each Assigning Authority: Finally the client registry will need to
know of other assigning authorities for identifiers which it won’t have authority over. These can
be assigned under different root OIDs (for example PHN or SSN in a jurisdiction) or can be
assigned out of your own pool of OIDs.
Root
Suffix
Authority
Device
Notes
1.3.6.1.4.1
0000
PROJECT
N/A
Our ROOT OID for Project
1.3.6.1.4.1.0000
99
PROJECT
N/A
Other Client Identifiers
1.3.6.1.4.1.0000.99
1
CLINIC1
OSCAREMR
OSCAR Clinic 1 Identifiers
2.16.840.1.113883.4
59
anyone
CA-ON
Ontario Personal Health #s
This example illustrates OSCAR EMR local identifiers from CLINIC1 will have an OID of
1.3.6.1.4.1.0000.99.1, opposed to a an Ontario PHN which can be assigned by anyone. This is
important to distinguish as you’ll need to configure the CR to use these identifiers.
The MEDIC CR uses the “Golden Record” paradigm which means that each patient is assigned an internal
client registry identifier (the CR_CID or CR Client ID) and that identity will have one set of demographics
for that patient. The MEDIC CR is the only recognized assigning authority for that domain, and it is the
only actor which can register identifiers and/or merge identifiers.
2.1.2. Security
Another important note is the installation and obtaining of security certificates and auditing tools. The
MEDIC CR distinguishes between log events and audit events. Log events are recorded via application
logs and deal primarily with application information which is useful for debugging problems, whereas
audits are records of clinical and security events. The MEDIC CR relies on third party audit tools for
collecting audit information, if you haven’t already done so, you’ll have to install and configure one.
The following security questions should be answered prior to deploying the CR.
1. Is the Client Registry physically segregated from public traffic? i.e. Will I rely on the firewall to
block access to the CR? If the answer is no, you’ll need to setup TLS.
2. Does my environment already have a certification authority? If yes, you’ll have to obtain a
signed certificate from that authority, otherwise you’ll have to set one up.
3. Is there a need to know which machines (CN from certificate) are accessing records? If the
answer is yes, you’ll have to use TLS.
4. Does my audit record repository reside on a separate machine? If yes, you’ll most likely have to
setup TLS.
Additionally you should consider governance principals surrounding access to the physical machines
where the client registry application server and databases are located. Consider using a centralized
authentication service such as Active Directory as it will make your access controls easier to maintain.
Operations and Deployment Guide
Page 8 of 39
2.1.3. Planning for Scale
The MEDIC CR is broken into a series of components which can be scaled out quite easily. There are four
types of deployments of the CR supported.
2.1.3.1. Single System
In this deployment the Client Registry is deployed on a single machine. This is the deployment supported
by the bundled installers from the Technology Exchange and is the easiest of the three to setup.
Logically this setup is pictured in Figure 3.
Figure 3 - Single Server Deployment
This type of deployment is recommended for development machines, test environments and small
environments (< 50,000 patients and < 4 simultaneous transactions).
2.1.3.2. Separate Application / Database Host
In this deployment the Client Registry Service (Application) is deployed on one physical machine whilst
the database is deployed on another. This separation allows an implementer to scale up each system
separately.
Figure 4 - Separate application and database
This type of deployment is recommended for small to medium (between 100,000 and 1,000,000
patients) production deployments.
Operations and Deployment Guide
Page 9 of 39
2.1.3.3. Separate Application / Component Database Hosts
In this deployment, the Client Registry Service (Application) is deployed on a physical machine whilst the
primary patient store and ancillary data sources scaled to separate database hosts. This allows the Client
Registry service to quickly access patient information while offloading more mundane tasks such as
message persistence, query persistence and code lookups to another server.
This type of deployment is recommended for medium production deployments where high transaction
volumes are common, as it is typically these that cause contention on query and message persistence
tables.
2.1.3.4. Clustered Deployment
Perhaps the most complex deployment, this option sees the client registry application services deployed
across multiple hosts with the primary datastore separated from ancillary services and replicated in a
master/slave configuration. In this configuration all new patient data is written to the master database
(say master.db.project.com) and all reads / queries are performed against the slaves setup in a
streaming replication scheme (say slave1.db.project.com, slave2.db.project.com). It may also be
possible to balance the load further by performing round-robin DNS for each of the slaves and each of
the application hosts. This deployment is illustrated in Figure 5.
Figure 5 - Clustered deployment option
Operations and Deployment Guide
Page 10 of 39
This deployment is recommended for large production deployments with high transaction volumes. The
MEDIC’s demonstration service (http://cr.marc-hi.ca) uses this configuration with two primary slaves
and one database for ancillary services and one application server. It is capable of servicing query
responses under 1,000 ms and has a population size of 250,000.
2.2.
Installation
2.2.1. Obtaining the Software
The MEDIC CR software can be obtained from the Mohawk College Applied Research Centre’s
Technology Exchange (http://te.marc-hi.ca). There are two options available for download:


Bundled – Use this installer if you’re deploying the MEDIC CR on a single server for development
or testing purposes. This setup includes PostgreSQL 9.2 and handles setup of the database
infrastructure.
Standalone – Use this installer for any other type of installation as it only includes the client
registry code.
Note: When installing the MEDIC CR on Windows 8 or Server 2012 you may receive a Windows
Defender alert. This is due to the setup package being unsigned and can be fixed by right clicking on the
setup executable and “Unblocking” the installer.
Figure 6 - Unblock Installer
After installing the MEDIC CR it will have to be configured. The “Client Registry Configuration” tool
provides an opportunity to do this configuration in a graphical manner and is well suited for basic
configuration tasks. There may be times when manual configuration is required. Implementers are
advised that they may use the configuration tool even after hand-editing the configuration file.
2.2.2. Basic Configuration
The basic configuration of the Client Registry will deploy the necessary schema and application services
to start a basic Client Registry. To perform a basic configuration select “Basic Configuration” from the
configuration tool:
Operations and Deployment Guide
Page 11 of 39
Figure 7 - Easy installation option
You may create a new database for the client registry if you haven’t already done so by clicking the
“New…” button next to the database name field.
To create a new database in the tool supply the server name, a super user’s credentials, the database
name and owner of the client registry database schema.
Operations and Deployment Guide
Page 12 of 39
Figure 8 - Creating a database
After deploying the basic services the configuration tool will open the main configuration interface. This
will allow you to further configure the instance. The Client Registry, by default, only has the
administrative interface enabled. To configure other interfaces see the section related to messaging
configuration.
Operations and Deployment Guide
Page 13 of 39
Figure 9 - Client Registry after Basic Configuration
2.2.3. Advanced Configuration
The “Advanced Configuration” option in the configuration tool will not setup any data schemas or
services in the client registry. It is intended to be used for production deployments with more complex
database server architectures.
After selecting “Advanced Configuration” and pressing “Continue” the main configuration window is
opened. This allows you to configure each component individually.
Operations and Deployment Guide
Page 14 of 39
Figure 10 - Client Registry with no Configuration
2.2.3.1. Core Service Configuration
The first step of configuring your Client Registry instance is to setup the Service Configuration. If this
step is performed first, it will make the rest of the configuration process simpler. Start by selecting the
“Service Core > OID Registrar” node in the tool. You will be presented with a list of default OIDs for the
client registry.
It will make your job easier if you setup a new OID for your project called “PROJECT” or “ROOT” with
your root OID in the OID field.
Operations and Deployment Guide
Page 15 of 39
Figure 11 - Creating an OID
Now you can configure the OIDs used by the CR. This task is performed by selecting an OID and pressing
the edit button. The fields on the Object Identifier form are as follows:





Name: An informative name for the identifier, should have no spaces
OID: The object identifier you had created in your OID plan
Note: Human readable sentence describing the oid
URL: The url where the identifier is described. This is a mandatory field and may be a URN in the
form : urn:oid:xxxxx
Extension Attributes: One or more additional attributes about the OID which assist the client
registry in determining how to OID should be used. They are as follows:
o AssigningAuthorityName: The CX.4 in HL7v2.x messages which maps to the OID
o OIDType: The CX.4.3 of the OID, this is usually fixed to ISO
o AssigningDevFacility: The MSH-3|MSH-4 of an HL7v2.x which is allowed to assign
identifiers (if not present no one may issue identifiers from HL7v2 messages in this
domain)
o IsMergeSurvivor: Indicates that the identifier survives a merge. This controls the way
that the identifier is returned in queries after a merge. If set to false then the victim
identifiers continue to be reported in responses to queries. Not recommended if
IsUniqueIdentifier = true, however in some cases it may be beneficial to do this.
o IsUniqueIdentifier: Indicates whether the identifier is unique or if communities of
patients can share the identifier (example: Cohort number)
o GloballyAssignable: Indicates whether the identifier can be assigned by a system
outside of its authority (example: driver’s license numbers or SSN)
o CustodialDeviceId: Indicates the OID of the device which is allowed to assign the
identifier from HL7v3 messages.
Operations and Deployment Guide
Page 16 of 39
o
o
o
CustodialDeviceName: Indicates the name of the device which is allowed to assign the
identifier from HL7v3 messages
CustodialOrgName: Indicates the name of the organization which is responsible for
custodianship of the identifier
CustodialOrgContact: Indicates a contact method (phone number, email, etc.) of the
organization which is responsible for the custodianship of the identifier.
A sample of an ECID OID configured is found in Figure 12.
Figure 12 - Setting up the CR_CID OID
You may also edit the OIDs using the configuration file. The Client Registry configuration file is located in
“%InstallDir%\ClientRegistry.exe.config” and should be configured as follows:
<add name="TEST" oid="2.16.840.1.113883.3.72.5.9.1" desc="OHIE Integration Tests
Domain">
<attribute name="AssigningAuthorityName" value="TEST"/>
<attribute name="OIDType" value="ISO"/>
<attribute name="AssigningDevFacility" value="TEST_HARNESS|TEST"/>
<attribute name="IsUniqueIdentifier" value="true"/>
</add>
When this step is complete, select the “Configuration Options” button and press “Ok”.
After your OIDs are configured you will configure the service attributes. These are attributes which
dictate how audit messages are formulated and general service settings. To configure this select
“Service Core” from the navigation tree. The options presented are as follows:

Service Language: Dictates the language of messages the service uses.
Operations and Deployment Guide
Page 17 of 39






Device ID: Identifies the device (physical machine) of the current application instance. In a
cluster these should be unique.
Group ID: Identifies the cluster (logical identifier) of systems. If in standalone mode then this is
not needed.
Name: Identifies the device identifier (MSH-3 in v2) that this application host sends
Jurisdiction Id: A unique identifier of the jurisdiction to which the client registry serves
Jurisdiction Name: The name that appears for the jurisdiction (MSH-4 in v2)
Other fields: Are not used by the client registry
Figure 13 - Configuring the ServiceCore
After configuring the service core, you may wish to customize other features such as application logging
and auditing.
2.2.3.2. Windows Service Configuration
The MEDIC CR can be run from the command line as an application with the following command:
ClientRegistry.exe --console
Operations and Deployment Guide
Page 18 of 39
However in production you would typically run the Client Registry as a windows service. This can be
done under the “Client Registry > Service” configuration panel. This panel allows you to configure the
credentials and startup mode of the ClientRegistry service.
Figure 14 - Setting up the Windows Service
“Configure Options” will install the service.
2.2.3.3. Data Persistence, Merging and Duplicate Detection
The client registry’s persistence service is a plugin and must be configured for clients to be persisted and
retrieved from the database. Configuring the persistence mode used for the client registry is similar to
that done at the “welcome” screen.
Note: If deploying to a cluster you will have to point this connection string to the “master”. In the
application configuration section of the config file you can setup a pointer to the readonly slaves:
<marc.hi.ehrs.cr.persistence.data>
<connectionManager connection="PSQL" readOnlyConnection="CLUSTER">
</connectionManager>
</marc.hi.ehrs.cr.persistence.data>
After configuring persistence you may continue to configure the core service behavior of the persistence
layer. The configuration options are as follows:



Permit Duplicate Registrations: Should be selected and true, this is an underlying service core
framework option that allows the HL7v2 EVN / v3 controlAct to be persisted and updated.
Query Control: Controls the default algorithms used for querying, note that a consumer may
override this in their request message, however these are the defaults if none are specified.
Registration of Duplicate Patient Causes Update: This option will handle cases where identity
sources send registration events for existing patients instead of proper update messages.
Matching is performed on the primary identifier in the request message (that which the sender
has identified authority over).
Operations and Deployment Guide
Page 19 of 39


Automerge Duplicates: This option instructs the client registry to automatically resolve
duplicate records when they’re received. If false the client registry only marks duplicate records
and does not merge them.
Duplicate Detection: Identifies the fields which are used to detect duplicate registrations. By
default the Minimum Matching Criteria elements option controls the number of selected fields
which at minimum, exactly match to result in a duplicate.
Figure 15 - Setting up match criteria
Note: The duplicate detection setup by the user interface can be quite primitive, to setup more complex
rules you may edit the persistence configuration section in the ClientRegistry.exe.config file. The options
are as follows:



@autoMerge = “true|false” – Instructs auto-merging to occur
@updateIfExists = “true|false” – Instructs the update on registration behavior
@minimumAutoMergeCriteria = number – Identifies the minimum number of exactly matching
criterion which must be met
Operations and Deployment Guide
Page 20 of 39

mergeCriterion/@field = “string” – Indicates a field which must be matched to trigger a merge. If
a mergeCriterion element has child mergeCriterion elements it indicates an “or” condition, and
the entire “or” condition counts as a hit towards the @minimumAutoMergeMatchCriteria.
The following example illustrates a client registry setup to perform an autoMerge if a new client
matches an existing client which :




Has a name exactly matching the name of an existing patient,
Has a gender matching the existing patient,
Has a birthTime matching the existing patient,
Has either “OtherIdentifiers” or “Addresses” matching
<marc.hi.ehrs.cr>
<registration autoMerge="true" updateIfExists="true"
minimumAutoMergeMatchCriteria="3">
<mergeCriterion field="Names"/>
<mergeCriterion field="GenderCode"/>
<mergeCriterion field="BirthTime"/>
<mergeCriterion>
<mergeCriterion field="OtherIdentifiers"/>
<mergeCriterion field="Addresses"/>
</mergeCriterion>
</registration>
</marc.hi.ehrs.cr>
Also note that the merge algorithms can be customized by implementing the
“IClientRegistryMergeService” interface and registering the service with the service host
2.2.3.4. Query Persistence & Retention
Query Persistence is used to keep track of stateful queries executed by clients against the client registry.
This functionality is vital to supporting query continuation required by HL7v3 or HL7v2 systems and
without it enabled, the CR does not support that functionality.
Operations and Deployment Guide
Page 21 of 39
Figure 16 - Configuring Query Persistence
The user interface does not setup culling and merely indicates the maximum length of time for queries
to be persisted. In order to enable culling you’ll have to setup the clean up timer job manually. This is a
bug in the 1.0 configuration tool.
To setup query culling with the timer add the following line to the <configSections> element in
ClientRegistry.exe.config:
<configSections>
...
<section name="marc.hi.svc.core.timer"
type="MARC.HI.EHRS.SVC.Core.Timer.Configuration.TimerConfigurationSectionHandler,
MARC.HI.EHRS.SVC.Core.Timer, Version=1.0.0.0"/>
...
</configSections>
Then register the timer service in <marc.hi.svc.core>:
<marc.hi.ehrs.svc.core>
...
<serviceProviders>
<add type="MARC.HI.EHRS.SVC.Core.Timer.TimerService, MARC.HI.EHRS.SVC.Core.Timer,
Version=1.0.0.0"/>
</serviceProviders>
...
</marc.hi.ehrs.svc.core>
Finally configure the timer job to run at a specified interval. Note that the max age parameter is still
adhered to.
Operations and Deployment Guide
Page 22 of 39
<marc.hi.svc.core.timer>
<job timer="1:00:00" type="MARC.HI.EHRS.QM.Persistence.Data.QueryPersistenceCleanJob,
MARC.HI.EHRS.QM.Persistence.Data, Version=1.0.0.0"/>
</marc.hi.svc.core.timer>
2.2.3.5. Message Persistence
Message persistence is a feature of the client registry which allows it to detect if it has already executed
a transaction and what the original response for that action was. This is desirable if you’re debugging
message traffic or if it is desired to only execute any write transaction once.
Note: While testing client systems you may receive complaints about failed messages continuing to be
failed due to this feature (i.e. the CR is not actually executing the new message). This can be remedied
by changing the message identifier or by turning off the feature.
2.2.3.6. Notifications
Notifications provide a capability for the MEDIC CR to send messages to other systems whenever a client
is created, updated, merged. To configure notifications enable the “PIXv3 Notifications” panel (note: the
CR supports v2 as well through this interface). You may add as many targets for as many domains as you
wish.
The “Add PIX Notification Target” window has the following fields:







Name: Identifies a unique name for the target which appears in the logs
Address: The address of the notification target. This can be one of the following schemes:
o http:// : For HTTP traffic
o https:// : For secure HTTP traffic
o llp:// : For HL7v2 Lower-Layer protocol traffic
o sllp:// : For HL7v2 Lower Layer protocol traffic secured with TLS
Node Id: Identifies the receiver information in the message sent. For HL7v2 this should be in the
format DEVICE|FACILITY for HL7v2 it should be an OID.
Authority: The authority with which the Client Registry is reporting the identifier. This is usually
the ECID but can be any client identifier registered in the CR.
Send As: Identifies the actor which should be send. The following configurations apply
Actor
Create
Update
Merge
PAT_IDENTITY_SRC
ADT^A04
ADT^A08
ADT^A40
PAT_IDENTITY_SRC_HL7v3
PRPA_IN201301UV PRPA_IN201302UV PRPA_IN201304UV
PAT_ID_X_REF_MGR
ADT^A34
ADT^A34
ADT^A34
PAT_ID_X_REF_MGR_HL7v3 PRPA_IN201302UV PRPA_IN201302UV PRPA_IN201302UV
Service Requires Client Authentication: Will force the CR to send a client certificate to the
remote service
Validate Service’s Certificate Against A Trusted Issuer: Restricts the CAs that the CR will accept
as valid CAs for the services certificate.
Operations and Deployment Guide
Page 23 of 39
Figure 17 - Adding a notification target
2.2.4. Auditing Configuration
The client registry’s audit functionality is configured via the “Service Core > Auditing” control panel. This
panel controls the mechanism and destination of the audit.
Figure 18 - Configuring an Audit Repository
Note: The MEDIC CR supports both DICOM and RFC3881 audits. By default the CR sends RFC-3881 audits
to the audit repository, however it can be configured to send DICOM format audits by editing the
following flag in the configuration file:
<marc.hi.ehrs.svc.auditing.atna messagePublisher="..." format="DICOM">
Operations and Deployment Guide
Page 24 of 39
Note: Selecting “BSD Syslog over Secured TCP” requires an additional parameter for the certificate hash
of the local certificate with which to secure traffic.
<destination endpoint="142.222.45.74:514" certificateThumbprint="hashgoeshere"/>
2.2.5. Messaging Configuration
2.2.5.1. HL7v3 Messaging
HL7v3 Messaging in the MEDIC CR is handled by the MARC-HI Everest Framework 1.2.6. This framework
allows the Client Registry to receive, parse, and respond with HL7v3 messages. All HL7v3 message traffic
is supported by the MARC-HI Everest Messaging interface implementation (configuration for which is in
the <marc.hi.ehrs.svc.messaging.everest> section). You can configure which messages are received and
interpreted by editing this configuration by hand, however it is recommended to stick to the user
interface for this configuration.
Each interface (pCS messages, PIX and PDQ) can be enabled or disabled separately. To configure set the
options as follows:




Address: The HTTP endpoint on which the service should be enabled. It is recommended that
this be set to 0.0.0.0 with HTTPS enabled if you plan on allowing external systems to access the
client registry.
Enable Debugging on this endpoint: Instructs WCF to return stack traces to clients when an
internal server error occurs.
Enable meta-data publishing on this endpoint: Instructs WCF to return a WSDL and additional
connection information when a GET is performed against the URL.
Security Configuration: Allows you to select a server certificate to be used for the service host.
Figure 19 - Enabling an Everest based endpoint
Note: Everest services use WCF for web services handling, this means that you can setup additional WCF
functions outside of the realm of what is available in the configuration tool.
Operations and Deployment Guide
Page 25 of 39
Note: The WSDLs produced by Everest are very minimal (basically <xs:any/>), and it is recommended
that you provide the WSDLs in the %InstallDir%\WSDL directory to any consumers wishing to
communicate with the HL7v3 services.
2.2.5.2. HL7v2 Messaging
HL7v2 messaging is supported by the nHAPI framework and represents socket based configuration of
HL7v2 endpoints within the CR. The MEDIC CR can listen to any number of ports for HL7v2 messages and
it is possible to mimic the functionality of OpenEMPI (separate ports for PIX and PDQ).
To configure HL7v2 messaging select “New…” and configure the endpoint as follows:






Name: A friendly name for the endpoint
Transport: The transport to be used for receiving messages, can be:
o ER7 over TCP: Accepting ER7 encoded messages over plain TCP sockets
o ER7 over LLP: Accepting ER7 encoded messages using standard LLP header/trail bytes
o ER7 over Secured LLP: Accepting ER7 encoded messages using LLP with TLS
Bind Address/Port: The IP Address to bind to
Timeout: Indicates the length of time the connection should remain open. By default the client
registry will keep the channel open for a client to stream HL7v2 messages
Handlers: Indicates the types of messages which should be handled at the specified endpoint.
Transport Options: Any additional options for transport, currently SLLP only supports this for
certificate options. Options are as follows:
o CheckCrl : When true, indicates that the CR should check client certificates for
revocation
o Enable Client Cert Negotiation: When true, requires clients to send a certificate prior to
sending messages
o ServerCertificateFile: A path to a P12 file which contains the server’s private key and
certificate
o ServerCertificatePassword: Identifies the password for the certificate file
o TrustedCaCertificateFile: Identifies a PEM file which contains the certificate of the CA
which should be trusted for clients.
o Server Certificate: Can be used in lieu of the file and configures the endpoint against the
windows central certificate store.
o Trusted Client Certificate: Used in lieu of TrustedCaCertificateFile and uses the windows
central certificate store.
Operations and Deployment Guide
Page 26 of 39
Figure 20 - Adding an LLP endpoint
2.2.5.3. Fast Health Interoperability Resources (FHIR)
HL7 FHIR is RESTful based interchange format which can be used to communicate patient data with the
MEDIC CR. The MEDIC CR supports the IHE PDQm profile, however also supports creation of patients
using FHIR in either JSON or XML formats. To configure the FHIR interface simply select “Messaging ->
FHIR” and configure as follows:






Address: The binding address, port and path of the FHIR service
Enable debugging on this endpoint: Instructs WCF to send stack traces in HTTP 500 error pages
Enable metadata publishing on this endpoint: Enables the WCF help page on the endpoint
specified.
Security Configuration: Allows the selection of a server certificate and, if required, enabling of
client side certificates as well.
Landing Page Index: An HTML file which can be served at the endpoint provided in the Address
field. If not populated the default “You’ve Discovered FHIR” page appears
Resource Handlers: Enables or disables the servicing of particular resources on the FHIR
endpoint.
Operations and Deployment Guide
Page 27 of 39
Figure 21 - Enabling the FHIR endpoint
2.3.
Verifying Your Deployment
2.3.1. Verifying Security
You may verify security of the endpoints you’ve configured from any Linux based client by using the
following command:
openssl s_client -connect <host>:<port> -debug
If configured properly you should see your server certificate and challenge returned:
Acceptable client certificate CA names
/C=US/O=DigiCert Inc/OU=www.digicert.com/CN=DigiCert Assured ID Root CA
/C=US/ST=Arizona/L=Scottsdale/O=GoDaddy.com, Inc./CN=Go Daddy Root Certificate A
uthority - G2
/C=US/O=VeriSign, Inc./OU=VeriSign Trust Network/OU=(c) 2006 VeriSign, Inc. - Fo
r authorized use only/CN=VeriSign Class 3 Public Primary Certification Authority
- G5
Operations and Deployment Guide
Page 28 of 39
/C=US/O=VeriSign, Inc./OU=Class 3 Public Primary Certification Authority
/C=US/O=DigiCert Inc/OU=www.digicert.com/CN=DigiCert High Assurance EV Root CA
/C=IE/O=Baltimore/OU=CyberTrust/CN=Baltimore CyberTrust Root
/C=US/O=GeoTrust Inc./CN=GeoTrust Global CA
/C=TZ/ST=Arusha/O=BID/OU=IZ/CN=atna.bid.ecg.marc-hi.ca/emailAddress=info@bidtest
.org
/OU=Copyright (c) 1997 Microsoft Corp./OU=Microsoft Corporation/CN=Microsoft Roo
t Authority
/DC=com/DC=microsoft/CN=Microsoft Root Certificate Authority
/CN=NT AUTHORITY
---
Note: To reduce this list of acceptable certificate names, simply remove root certificate authorities from
the Client Registry’s service account. This can be done via the Microsoft Management Console (mmc).
2.4.
Administrative Interface
The Client Registry Administrative interface is provided as a separate download to the MEDIC CR
program. This section will discuss the setup of the administrative interface.
2.4.1. Setup the CR Service
First, the Client Registry service must be configured to accept administrative traffic. This is done by
enabling the administrative interface in the configuration tool. Because this service has access to client
registry internal functions it is recommended it be bound to localhost only, setup with HTTPS and client
certificates required.
Figure 22- Enabling the Administrative Service
2.4.2. Setup an IIS Site
Download the administrative interface ZIP file from the Technology Exchange, and unzip it somewhere
on the hard drive ensuring that the IUSR (or application pool account has access).
Operations and Deployment Guide
Page 29 of 39
Next, ensure that you have created a Windows group named “CR Administrators” and a windows user
“cradmin” with appropriate password in that group.
Configure an IIS site to run against the directory where you’ve unzipped the administrative interface
being sure to select the ASP.NET 4.0 application pool with HTTPS selected as the transport and your
server certificate selected
Figure 23 - Configuring the IIS administration site
After the site is created enable Windows Authentication on the site:
Figure 24 - Enabling Windows Authentication
Finally it is a good idea to require client side SSL certificates:
Figure 25 - Enabling client certificates in IIS
2.4.3. Configure the Website
The final step is to ensure the configuration of the administrative website is correct. Open the
Web.Config file in the IIS site directory and ensure that Windows mode authentication is enabled
Operations and Deployment Guide
Page 30 of 39
<authentication mode="Windows">
</authentication>
And that the administrative service is bound to the appropriate IP address and port.
<system.serviceModel>
<bindings>
<basicHttpBinding>
<binding name="BasicHttpBinding_IClientRegistryAdminInterface"
maxReceivedMessageSize="10293293" >
<security mode="None"/>
</binding>
</basicHttpBinding>
</bindings>
<client>
<endpoint address="http://localhost:9999/admin" binding="basicHttpBinding"
bindingConfiguration="BasicHttpBinding_IClientRegistryAdminInterface"
contract="ClientRegistryAdminService.IClientRegistryAdminInterface"
name="BasicHttpBinding_IClientRegistryAdminInterface" />
</client>
</system.serviceModel>
If configured appropriately the welcome site should appear when navigation to https://<host> is
performed and a client certificate provided.
Figure 26 - Administrative Interface Landing Page
Operations and Deployment Guide
Page 31 of 39
3.
Administering the Client Registry
3.1.
Reviewing Patient Data
The Client Registry stores data using a component model. In this pattern, data is broken into containers
and components related by a site role. For example; a patient with a mother would be interpreted as a
Patient (Container) having a mother (Component) related via “Relationship” role.
The viewer for client registry data will format the client registry’s component model into a hierarchy of
data element for you to browse. The general view screen is pictured below:
Figure 27 - Patient Summary View
This is the “interpreted” view, that is to say the Client Registry administrative interface has interpreted
the components and extracted the most important data. The detail view of the patient is as follows:
Operations and Deployment Guide
Page 32 of 39
Figure 28 - Patient Detail View
This is a rendered view of the component model and it illustrates that the current version of the patient
record came into being because of an administrative merge (ADMIN_MRG), the person associated with
the event is Active and has a full name of Scott, Isabella Isabella. This view can be used to track the
history of an item, for example, we can view that the event revised the older version of the patient
394601 record (version from 516287 -> 516291) and also replaced (subsumed) patient 392382 at version
516288.
Operations and Deployment Guide
Page 33 of 39
Figure 29 - Viewing Patient Record History
3.2.
Conflict View
The current version of the client registry auto-detects merges on a series of parameters and can be
configured to merge on these automatically. However, if not configured this way, or if a match is
ambiguous, the CR will mark the merge as a conflict and you (the administrator) may view them:
Figure 30 - Viewing flagged conflicts
Operations and Deployment Guide
Page 34 of 39
This page shows the Source (patient who is conflicting) as well as conflicts (the patient(s) who the CR has
detected a conflict with).
3.2.1. Resolving Conflicts
Reviewing conflicts must be taken with care as these are irreversible. To resolve a conflict, select the
conflict record which will provide details about the conflicting patients.
Figure 31 - Resolving patient conflicts
The Client Registry uses a component model to store information about conflicts. This information is
displayed for each patient and can be reviewed by expanding the “Components”:
Operations and Deployment Guide
Page 35 of 39
Figure 32 - Patient Detail View
You may review this data with the detected conflicts on the right hand side:
Figure 33 - How to compare Patient Demographic Data
Operations and Deployment Guide
Page 36 of 39
If the data is determined to be a match check the box next to the title of the section.
Figure 34 - Indicating a Merge Target
When the appropriate merge instructions are indicated selecting the “Resolve” button will provide a
summary of the actions to be taken. Note: If you do not select any candidate (all conflicts are marked
“ignore”) then the records are not merged.
Figure 35 - Confirm conflict resolution
Confirming will perform the actions listed. It is important to note that once a merge is complete there is
no way to un-merge the clients.
3.3.
Obtaining Diagnostic Information
3.3.1. Versions
You can determine what version of the Client Registry RI you’re running via the Admin menu. This will
also display the current version of components and services installed in the Client Registry.
Operations and Deployment Guide
Page 37 of 39
Figure 36 - Obtaining Service Information
3.3.2. Obtaining Log Files
You may also obtain log files from the Client Registry. Please note that these log files may contain PHI
and should be secured appropriate if downloading them.
Figure 37 - Viewing Service Logs
Operations and Deployment Guide
Page 38 of 39
3.3.3. Reviewing Assigning Authorities
Assigning authorities are OIDs that are understood by the Client Registry. You may review the assigning
authorities currently configured on the Client Registry through the web interface, however you can only
modify them through the administrative “Configurator” interface locally installed on the server. This is
because modifying an AA presents a security risk and should not be performed after initial configuration
is performed (unless adding a new actor to your infrastructure).
Figure 38 - Reviewing registered OIDs
You may also get further details about the OID configuration by selecting the OID:
Figure 39 - Viewing OID details
Operations and Deployment Guide
Page 39 of 39