Oracle® Healthcare Master Person Index Working With IHE Profiles User's Guide Release 3.0 E62314-03 |
|
|
PDF · Mobi · ePub |
This chapter provides procedures on how to create, configure, and build an IHE Profiles Application project. It also discusses the features of an IHE Profiles Application project Actions menu.
This chapter includes the following sections:
IHE design-time is a NetBeans IDE plug-in. The IHE wizard takes your input, such as database type, application server, and the V2 Service Port, and creates an IHE Profiles Application project and pre-configured Master Person Index (MPI) project. You are able to fine-tune the matching service of the Master Person Index, and configure V2 Service Port of the IHE project. When the IHE project builds, the database scripts and three artifacts are generated. The IHE Create Database dialog box lets you create a database (if needed). Once the database is created you can deploy the IHE ear to the target server using the application server administration console. The steps to create the IHE Profiles Application project and deploy it are:
Create an IHE Profiles Application project
Configure the IHE Profiles Application project
Build the IHE Profiles Application project
Run the database script
Configure the application server
Deploy the IHE Profiles Application project on an application server
The IHE wizard requires the following input to create an IHE Profiles Application project and pre-configured MPI project. The wizard also sets the database type and application server information for both the IHE project and the pre-configured MPI project.
Project name
Project location
Application server
Database
V2 Service Port
From the NetBeans IDE, click File and then select New Project.
The New Project dialog box appears.
In the Categories section of the Choose Project panel, select OHMPI and in the Projects section, select IHE Profiles Application.
Click Next.
The New IHE Profiles Application dialog box appears.
In the Name and Location panel, perform the following:
In the Project Name field, enter a name for your project (for example, IHEProject1
).
In the Project Location field, browse to the path where you want to create the IHE project.
The Project Folder field populates with the path and name of your project.
From the Server drop-down list, select the application server.
From the Database drop-down list, select a database (for example, Oracle).
In the V2 Service Port field, enter the port number (for example, 4447
).
Click Finish.
You can configure several features of the Master Person Index to customize how data is matched and processed through the IHE Profiles Application. The type and quality of data stored for a patient varies from system to system and from organization to organization. The Master Person Index takes this into account and lets you tailor the processing for your specific data requirements. For example, you may know that some systems contain more accurate data than others. You can weight those systems higher when determining which values will populate the single best record (SBR). Also, some fields might contain more accurate data than others and would thus be given a higher match weight than other, less accurate fields.
You can configure the following components of the Master Person Index:
Patient demographic queries, matching queries, and queries performed from the Master Index Data manager (MIDM).
Standardization and matching rules, including which fields to standardize, which fields to match, a range of match weights to assign to each field, and the type of algorithm to use to match each field.
Filters for match results. For example, you can configure the Master Person Index to ignore default values.
The single best record and how it is formed.
The appearance of the MIDM
Field validations
In addition, you can customize logic for the underlying process of the Master Person Index. For complete information on configuring the Master Person Index, see Oracle Healthcare Master Person Index Configuration Guide.
If you modify the configuration of the Master Person Index, you need to rebuild and redeploy the IHE Profiles Application Project. See Creating an IHE Profiles Application Project.
Note:
You cannot modify an object model in an IHE-MPI application.When you right-click an IHE Profiles Application project in the left panel of NetBeans IDE, the Action menu appears. It provides the necessary tools to manage a project.
Build - Builds an IHE Profiles Application project and generates its artifacts.
Clean and Build - Removes generated artifacts from an IHE Profiles Application project and then rebuilds the project and generates new artifacts.
Clean - Removes generated artifacts from an IHE Profiles Application project.
Create Database - Opens the Create Database dialog box (see Creating the Database and Tables Automatically).
Set as Main Project - Sets a selected IHE Profiles Application project as the main project.
Open Required Project - Opens a pre-configured Master Person Index project.
Close - Closes an IHE Profiles Application project.
Properties - Opens the Project Properties - <Project_Name> dialog box, where you can change the HL7 V2 Service Port and Web Service Security Setting.
Before building an IHE Profiles Application project you must configure it. This includes:
Editing the following configuration files to change IHE service properties:
hl7message.xml
hl7service.xml
services.properties
Using the Master Person Index editor to fine-tune matching configuration. See Oracle Healthcare Master Person Index Configuration Guide for information about using the editor.
If the web service endpoints of the IHE Profiles Application need to be secured with TLS, check the Secure Application check box. This disables the plain HTTP access to the web service endpoints, and only allows HTTP over TLS access with mutual authentication. See To Configure Secure PIXv2 Manager and PDQv2 Supplier for additional information on secure application configuration.
hl7message.xml
defines HL7 v2 native message properties according to the HL7 specification.
validateMSH
An indicator of whether MSH segment validation is enabled.
seqNumEnabled
An indicator of whether sequence number protocol is enabled.
processingId
The processing Id value of the MSH-11 segment in the received message is validated when validateMSH is enabled. MSH-11 is used to indicate whether a message is processed as defined in the HL7 processing rules. The processing Id options include the following:
D - Debugging
T - Training
P - Production
sendingApplicationNamespaceId
The sending application (MSH-03 segment) is used to create an acknowledgement or response message. This is used to help identify the application from other participating applications within the network enterprise.
sendingApplicationUniversalId
sendingApplicationUniversalIdType
sendingFacilityNamespaceId
The sending facility (MSH-04 segment) is responsible for creating an acknowledgement or response message. This is used to help further identify participating facilities within the network enterprise.
sendingFacilityUniversalId
sendingFacilityUniversalIdType
encodingCharacters
The four encoding characters used to create an acknowledgement or response message. This attribute contains the four characters in the following order:
Component separator
Repetition separator
Escape character
Subcomponent separator
The recommended value is ^~\& (that is, ASCII 94, 126, 92, and 38, respectively).
fieldSeparator
The separator is used to separate between the segment Id and the first real field. This value defines the character that is used as a separator for the rest of the message. Enter the value as a decimal ASCII number ranging from 1 to 127. The default value is 124 which is the character "|".
softwareVendorOrganization
The Software Vendor Organization field (SFT-1-Software Vendor Organization) identifies the vendor who is responsible for maintaining the application. This property only applies to HL7 versions 2.5 relevant IHE integration profile messages.
softwareCertifiedVersionOrReleaseNumber
The Software Certified Version or Release Number is the value of the HL7 segment SFT-02. The current software version number or release number for the sending system helps to provide a more complete profile of the application that is sending or receiving the HL7 messages. This property only applies to HL7 versions 2.5 relevant IHE integration profile messages.
softwareProductName
The name of the software product that submitted the transaction is the value of the HL7 segment SFT-03. The software product name is a key component for identifying the sending application. This property only applies to HL7 versions 2.5 relevant IHE integration profile messages.
softwareBinaryId
The Software Binary Id is the value of HL7 segment SFT-04. This property is available starting with HL7 version 2.5. Software Binary Ids are issued by a vendor for each unique software version instance. These Ids are used to differentiate between differing versions of the same software. Identical Primary Ids indicate that the software is identical at the binary level, but configuration settings may differ. This property only applies to HL7 versions 2.5 relevant IHE integration profile messages.
softwareProductInformation
The software product identification information is the value of the HL7 segment SFT-05. This may include a description of the software application, configuration settings, modifications made to the software, and so forth. This information is used for diagnostic purposes to help identify the application software. This property only applies to HL7 versions 2.5 relevant IHE integration profile messages.
softwareInstallDate
The Software InstallDate is the value of HL7 segment SFT-06. This is the date on which the submitting software was installed at the sending site. The install date can provide key information in regard to the behavior of an application. The date format is YYYYMMDDHHSS. This property only applies to HL7 versions 2.5 relevant IHE integration profile messages.
The following properties are related to the XDS Document Registry. See the enable_xad_pid_link_change_notification property in services.properties on how to enable XAD-PID Link Change Notification from OHMPI HL7 v2 service to XDS Document Registry.
registryApplicationNamespaceId
registryApplicationUniversalId
registryApplicationUniversalIdType
The receiving application is used to identify the participating application for the XDS Document Registry within the network enterprise.
registryFacilityNamespaceId
registryFacilityUniversalId
registryFacilityUniversalIdType
The receiving facility is used to identify the participating facility for the XDS Document Registry within the network enterprise.
registryEndpointAddress
This is the HL7 v2 endpoint address for the XDS Document Registry.
hl7service.xml
defines hl7 v2 server runtime communication protocol properties.
The runtime communication protocol properties of the OHMPI HL7 v2 server specifies the protocol information for the external HL7 system to connect to the OHMPI HL7 v2 server and vice versa.
url
A URL used for an external system to connect to the OHMPI HL7 v2 server. The format of the URL is: hl7://<host>:<port>.
threadCount
The maximum number of processing threads.
connectionTimeout
The idle time in seconds for a connection timeout.
maxConnectRetries
The maximum number of connection retires the outbound connector attempts before executing the recourse action.
Value: The value is presented in the format: n1;n2, n1;n2, ..., where n1 is the number of retry attempts to connect, and n2 is the interval in seconds between retry attempts. If the value of n1 is -1, it indicates that the number of retry attempts is indefinite.
Action: Suspend and Error.
TimeToWaitForAResponse
The amount of time the outbound connector waits for a response from the external system before executing the configured recourse action.
Value: An integer indicating the time interval in seconds.
Action: Resend, Reset, and Suspend.
maxNakSent
The maximum number of negative acknowledgements (NAKs) the server sends to the client before executing the recourse action. A NAK is sent from the HL7 inbound connection when the received message from client is invalid. An invalid message, according to the HL7 specification, is one that fails MSH segment validation or has an invalid sequence number.
Enabled: true or false
Value: An integer indicating the appropriate maximum number
Action: Suspend and Reset
maxCannedNakSent
The maximum number of Canned NAKs the server sends to the client before executing the configured recourse action. This communication control deals with the case where the message received from the client is invalid as per the HL7 specification rules for that particular message. A Canned HL7 NAK is created when a read error occurs, or when a message cannot be identified as an HL7 message.
Enabled: true or false
Value: An integer indicating the appropriate maximum number
Action: Suspend and Reset
mllpv1
The MLLP Version 1 properties configure the Minimal Lower Layer Protocol version 1 property.
llpType: MLLPv1 indicates Minimal Lower Layer Protocol version 1.0.
StartBlockCharacter: The start block character value in a decimal ASCII number from 1 to 127 specifies a block start. Unless there is a conflict, the value should be ASCII VT which is decimal 11.
EndBlockCharacter: The end block character value in decimal ASCII number from 1 to 127 specifies a block end. To be strictly compliant with the HL7 standard, this parameter must be set to a carriage return which is decimal 13.
EndDataCharacter: The end data character value in decimal ASCII number from 1 to 127 specifies a data end. To be strictly compliant with the HL7 standard, the value should be a carriage return indicated by decimal 28.
mllpv2
The MLLP Version 2 properties configure the Minimal Lower Layer Protocol version 2 property.
llpType: MLLPv2 indicates Minimal Lower Layer Protocol version 2.0.
StartBlockCharacter: The start block character value in a decimal ASCII number from 1 to 127 specifies a block start. Unless there is a conflict, the value should be ASCII VT which is decimal 11.
EndBlockCharacter: The end block character value in decimal ASCII number from 1 to 127 specifies a block end. To be strictly compliant with the HL7 standard, this parameter must be set to a carriage return which is decimal 13.
EndDataCharacter: The end data character value in decimal ASCII number from 1 to 127 specifies a data end. To be strictly compliant with the HL7 standard, the value should be a carriage return indicated by decimal 28.
RetryCountOnNak: The maximum configured number of attempts to send a message after receiving a negative acknowledgement.
RetryInterval: The duration in milliseconds to wait between each retry attempt.
timeToWaitForAckNak: The duration in milliseconds to wait for a commit positive or negative acknowledgement.
hllp
llpType: HLLP indicates Hybrid Lower Layer Protocol.
StartBlockCharacter: The start block character value in a decimal ASCII number from 1 to 127 specifies a block start. Unless there is a conflict, the value should be ASCII VT which is decimal 11.
EndBlockCharacter: The end block character value in decimal ASCII number from 1 to 127 specifies a block end. To be strictly compliant with the HL7 standard, this parameter must be set to a carriage return which is decimal 13.
EndDataCharacter: The end data character value in decimal ASCII number from 1 to 127 specifies a data end. To be strictly compliant with the HL7 standard, the value should be a carriage return indicated by decimal 28.
checksumEnabled: An indicator of whether the HLLP Checksum feature is enabled. This can only be enabled if the LLP Type is set to HLLP.
The actions supported by the IHE OHMPI HL7 v2 server can include the following values:
Reset
The server closes the connection with the HL7 external system and throws an alert.
Resend
The server component resends the last sent message to the HL7 external system.
Suspend
The server closes the connection with the HL7 external system, suspends the connection from processing the messages, and throws an alert.
To secure IHE Profiles Application you need to enable SSL support, including Mutual authentication.
Note:
This configuration step is optional.To configure secure PIXv2 Manager and PDQv2 Supplier you need to configure hl7service.xml
:
url
Define a URL used for secured connection. The formation of the URL is: hl7s://
<host>:<port>.
keyStore
Define a keyStore file full path where private keys in JKS format are stored.
keyStorePassword
Define a password to access to the keyStore.
trustStore
Define a trustStore file full path where trusted certificates in JKS format are stored.
trustStorePassword
Define a password to access to the trustStore.
keyManagerKeyStorePassword
Define a password for KeyManager.
clientAuthentication
Set true for requiring client authentication, or mutual authentication. Set false for only requiring server authentication.
protocols
Define supported SSL protocols. You can define a list of different protocols delimited by "," (that is, you can define "SSLv3,TLSv1").
cipherSuites
Define supported SSL cryptographic algorithms. You can define a list of different cipher suites delimited by "," (that is, you can define "TLS_RSA_WITH_AES_128_CBC_SHA,SSL_RSA_WITH_NULL_SHA").
To import keys and certificates into KeyStore or TrustStore, perform the following:
If your certificate or key is X509 format, transform X509 certificates and keys to pkcs#12 format using openssl tool:
openssl pkcs12 -export -out my_keystore.pkcs12 -in my_server_cert.pem -inkey my_server_key.pem
Import the pkcs#12 certificate into a JKS keystore using keytool:
keytool -importkeystore -deststorepass changeit -destkeystore my_keystore.jks -srckeystore my_keystore.pkcs12 -srcstoretype PKCS12 -srcstorepass changeit
Import the public keys into the trust store using keytool:
keytool -import -noprompt -trustcacerts -file my_client_cert.pem -keystore my_truststore.jks -alias client
The following is a list of user-configurable properties for IHE profiles and HL7 v3 web services. You need to manually edit the services.properties file before building the IHE project.
Note:
If you have to change any of these configurations after you build and/or deploy the IHE project, you can always rebuild and redeploy the IHE project after updating the services.properties file. Alternatively, you can create a runtime property file called ohmpi-ihe.properties under the <app_server_domain>/config/ohmpi directory. The properties defined in the runtime ohmpi-ihe.properties overwrite the properties defined in services.properties at build time.Open the services.properties file from within NetBeans IDE and make the appropriate edits to the following.
pixv3mgr/receiver/device/namespace=OTHER_ORACLE_HIE
pixv3mgr/receiver/device/oid=1.3.6.1.4.1.21367.13.30.92
pixv3mgr/receiver/device/org/namespace=ORACLE
pixv3mgr/receiver/device/org/oid=1.3.6.1.4.1.21367.13.50.99
pixv3mgr/sender/device/namespace=OTHER_ORACLE_HIE
pixv3mgr/sender/device/oid=1.3.6.1.4.1.21367.13.10.92
pixv3mgr/sender/device/org/namespace=ORACLE
pixv3mgr/sender/device/org/oid=1.3.6.1.4.1.21367.13.50.99
pdq/timeout=60
pdq/batch_size=20
pdq/date_format=yyyyMMddHHmmss
pdq/default_search_algorithm=ALPHA-SEARCH
enable_pix_update_notification=true
enable_euid_query=false
aa/oid=1.3.6.1.4.1.21367.13.20.165
aa/namespace=ORO6
mpi/application/name=Patient
mpi/primary_object/name=Patient
mpi/primary_object/class_name=com.sun.mdm.index.objects.patient.PatientObject
service/mapper/class_name=oracle.hsgbu.ohmpi.ihe.mapper.DefaultMapperService
enable_patient_feed=false
registry/endpoint=http://<RLS_HOST>:<RLS_PORT>/hrl/regsvc
pisv3/device/namespace=OTHER_ORACLE_HIE2015
pisv3/device/oid=1.3.6.1.4.1.21367.13.10.175
pisv3/device/org/namespace=ORACLE
pisv3/device/org/oid=1.3.6.1.4.1.21367.13.50.300088
registry/device/namespace=OTHER_ORACLE_HIE2015
registry/device/oid=1.3.6.1.4.1.21367.13.30.181
registry/device/org/namespace=ORACLE
registry/device/org/oid=1.3.6.1.4.1.21367.13.50.300088
enable_xad_pid_link_change_notification=false
xad/oid=
xad/namespace=
The following properties identify the PIXv3 Manager (as well as the PDQv3 Supplier) as a receiver:
Property Name | Property Description |
---|---|
pixv3mgr/receiver/device/namespace | PIXv3 Manager (or PDQv3 Supplier) receiver device namespace |
pixv3mgr/receiver/device/oid | PIXv3 Manager (or PDQv3 Supplier) receiver device OID |
pixv3mgr/receiver/device/org/namespace | PIXv3 Manager (or PDQv3 Supplier) receiver device organization namespace |
pixv3mgr/receiver/device/org/oid | PIXv3 Manager (or PDQv3 Supplier) receiver device organization OID |
The following properties identify the PIXv3 Manager as a sender in PIXv3 Update Notification:
Property Name | Property Description |
---|---|
pixv3mgr/sender/device/namespace | PIXv3 Manager sender device namespace |
pixv3mgr/ sender /device/oid | PIXv3 Manager sender device OID |
pixv3mgr/ sender /device/org/namespace | PIXv3 Manager sender device organization namespace |
pixv3mgr/ sender /device/org/oid | PIXv3 Manager sender device organization OID |
The following properties configure general PIX/PDQ behavior:
Property Name | Property Description |
---|---|
pdq/timeout | Patient Demographics Query Continuation timeout (in seconds) |
pdq/batch_size | Patient Demographics Query Continuation batch size |
pdq/date_format | Date format in Patient Demographics Query response. Refer to Java's SimpleDateFormat for format at http://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html . |
pdq/default_search_algorithm | Patient Demographics Query default search algorithm. Valid values are "ALPHA-SEARCH", "PHONETIC-SEARCH", "BLOCKER-SEARCH", or any user-defined query builder names. |
enable_pix_update_notification | Whether to enable PIX v2/v3 Update Notification. Valid values are "true" and "false". By default, this is enabled.
When PIX Update Notification is enabled, PIX Consumer Endpoints need to be added into the IHE_PIXCONSUMER_ENDPOINTS table, and PIX Update Notification Subscriptions from PIX Consumers to Source Domains need to be added into the IHE_PIXUPDATE_SUBSCRIPTIONS table. |
enable_euid_query | Whether to enable PIX/PDQ Query by EUID and PIX/PDQ Query for EUID. Valid values are "true" and "false". By default, this is disabled.
See aa/oid and aa/namespace for the EUID domain identification. |
aa/namespace | OHMPI Assigning Authority (i.e., EUID Domain) namespace
Note: Both aa/namespace and aa/oid need to be properly defined together when PIX/PDQ Query by/for EUID (enable_euid_query) is enabled. The OHMPI Assigning Authority Domain, that is, the EUID Domain, also needs to be added into the IHE_DOMAINS table in this case. Note: This namespace is not necessarily the same namespace for the XDS Affinity Domain. See xad/namespace. |
aa/oid | OHMPI Assigning Authority (i.e., EUID Domain) OID
Note: Both aa/namespace and aa/oid need to be properly defined together when PIX/PDQ Query by/for EUID (enable_euid_query) is enabled. The OHMPI Assigning Authority Domain, that is, the EUID Domain, also needs to be added into the IHE_DOMAINS table in this case. Note: This OID is not necessarily the same OID for the XDS Affinity Domain. See xad/oid. |
The following properties need to be updated if user-defined MPI Object Model is used along with IHE Project:
Property Name | Property Description |
---|---|
mpi/application/name | Application name in the user-defined MPI project |
mpi/primary_object/name | Primary object name in the user-defined MPI project |
mpi/primary_object/class_name | Fully qualified Java class name for the user-defined MPI project's primary object. |
service/mapper/class_name | Fully qualified name of a Java class that implements the pre-defined oracle.hsgbu.ohmpi.services.IMapperService interface. This concrete service implementation class provides two-way object mapping between the fixed IHE model and the user-defined MPI model. |
The following properties configure outbound patient feed from OHMPI to XDS Document Registry:
Property Name | Property Description |
---|---|
enable_patient_feed | Whether to enable outbound patient feed from OHMPI to XDS Document Registry. Valid values are "true" and "false". By default, this patient feed is disabled.
When outbound patient feed is disabled ("false"), you can ignore the rest of the properties in this section. When outbound patient feed is enabled ("true"), you must properly define the Registry's web service endpoint URL. Also, you must configure the identity of Registry (receiver) and the identity of OHMPI as a Patient Identity Source (sender). Note: OHMPI can have a different identity as a sender from its identity as a receiver. |
registry/endpoint | XDS Document Registry's Web Service Endpoint URL
For example, the Health Record Locator (HRL) service contained in Oracle Health Sciences Information Manager is an XDS Document Registry. It is also known as Record Locator Service. Its endpoint URL looks like the following: http://<RLS_HOST>:<RLS_PORT>/hrl/regsvc |
pisv3/device/namespace | Patient Identity Source v3 (Sender) Device Namespace.
This, along with the next three properties, identifies OHMPI as a sender in an outbound patient feed. |
pisv3/device/oid | Patient Identity Source v3 (Sender) Device OID |
pisv3/device/org/namespace | Patient Identity Source v3 (Sender) Device Organization Namespace |
pisv3/device/org/oid | Patient Identity Source v3 (Sender) Device Organization OID |
registry/device/namespace | XDS Document Registry (Receiver) Device Namespace |
registry/device/oid | XDS Document Registry (Receiver) Device OID |
registry/device/org/namespace | XDS Document Registry (Receiver) Device Organization Namespace |
registry/device/org/oid | XDS Document Registry (Receiver) Device Organization OID |
The following properties configure XAD-PID Link Change Notification from OHMPI to XDS Document Registry:
Property Name | Property Description |
---|---|
enable_xad_pid_link_change_notification | Whether to enable XAD-PID Link Change Notification from OHMPI to XDS Document Registry. Valid values are "true" and "false". By default, this notification is disabled.
Since the notification listener is defined by IHE in the XAD-PID Change Management (XPID) Profile as an HL7 v2 service on the XDS Document Registry, when XAD-PID Link Change Notification from OHMPI to XDS Document Registry is enabled. The following HL7 v2 properties must be properly defined in hl7message.xml:
|
xad/oid | XDS Affinity Domain OID
If the value of this property is left empty, it is assumed to have the same value as aa/oid, in other words, OHMPI's EUID Domain is treated as the XDS Affinity Domain. |
xad/namespace | XDS Affinity Domain Namespace
If the value of this property is left empty, it is assumed to have the same value as aa/namespace. OHMPI's EUID Domain is treated as the XDS Affinity Domain. |
This section provides the steps to build a project.
In the left panel of NetBeans IDE, right-click the project icon (for example, IHEProject1).
The Actions menu appears.
To build an IHE Profiles Application project, click Build on Actions menu.
When you build the IHE Profiles Application project for WebLogic, five artifacts are created:
Project_Name.ear
: The IHE Profiles Application.
hl7v2.zip
: The HL7 v2 lifecycle module.
The hl7v2.zip is an HL7 v2 server package that includes all artifacts required to run the IHE OHMPI HL7 v2 server and HL7 v2 lifecycle model which manages the server. You unzip it to the location where you run the server. The unzipped folder includes:
hl7v2
config
The config sub folder includes all the configuration files.
lib
The lib sub folder includes all the required jar files.
audit-repo-syslog-client.jar
: The JAR file that contains the functionality of the audit repository syslog client.
ihe-atna-audit-client.jar
: The JAR file that contains the functionality of the IHE ATNA audit client.
ohmpi_audit_client.properties
: The property file used to configure where the audit server is located.
After building a WebLogic-targeted IHE Profiles Application project (and before starting WebLogic Application Server), manually copy the following three files from the IHE Profiles Application project's dist
directory to the appropriate WebLogic domain's lib
directory (for example, user_projects\domains\
domain_name\lib
):
audit-repo-syslog-client.jar
ihe-atna-audit-client.jar
ohmpi_audit_client.properties