Oracle® Healthcare Master Person Index Working With IHE Profiles Release 1.1 Part Number E18591-01 |
|
|
View PDF |
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 allows you to 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 choose New Project.
The New Project dialog appears.
In the Projects section of the Choose Project panel, choose IHE Profiles Application and click Next.
The New IHE Profiles Application dialog appears.
In the Name and Location panel, do the following:
In the Project Name field, type 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 list, choose a server (GlassFish 2.1 or WebLogic 11gR1).
Note:
While the OHMPI Installer installs GlassFish 2.1, WebLogic 11gR1is a separate installation. See the Oracle Healthcare Master Person Index WebLogic User's Guide (Part Number E18593-01).In the Database list, choose a database (for example, Oracle).
In the V2 Service Port field, type 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 allows you to 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 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 Master Index Data Manager (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 (Part Number E18473-01).
If you modify the configuration of the Master Person Index, you need to do the following:
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.The Actions menu that you access by right-clicking an IHE Profiles Application project in the left panel of NetBeans IDE provides you with 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 (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, where you can change the HL7 V2 Service Port and Web Service Security Setting.
The information provided in this section is the same for GlassFish and WebLogic. Before building an IHE Profiles Application project you need to 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 the Oracle Healthcare Master Person Index Configuration Guide (Part Number E18473-01) for information about using the editor.
If the web service endpoints of the IHE Profiles Application needs to be secured with TLS, check the Secure Application check box. This will disable the plain HTTP access to the web service endpoints, and only allow HTTP over TLS access with mutual authentication. See "To Configure Secure PIXv2 Manager and PDQv2 Supplier" and "Configuring Secure Web Services on GlassFish Enterprise Server v2.1.1" 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
enncodingCharacters
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.
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 to enforce a to be closed action.
maxConnectRetries
The maximum number of connection retires the outbound connector will attempt 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 NAKs the server sends to the client before executing the recourse action. A negative acknowledgment 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 (MLLP) version 1 property.
llpType: MLLPv1 indicates Minimal Lower Layer Protocol v1.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 (MLLP) version 2 property.
llpType: MLLPv2 indicates Minimal Lower Layer Protocol v2.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, you need to do:
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
What follows is a partial list of user-configurable properties for HL7 v3 web services. As this release does not have a nice UI support for editing these properties, you need to manually edit the services.properties file before building the IHE project.
Open the services.properties file from within NetBeans IDE and make the appropriate edits to the following.
PIX-V3-Device-Namespace-ID=OHMPI
PIX-V3-Device-Universal-ID=100.200.300.400
PIX-V3-Organization-Namespace-ID=n/a
PIX-V3-Organization-Universal-ID=n/a
PDQ-Continuation-Timeout=60
Identifies the PIX Manager V3 Device:
PIX-V3-Device-Namespace-ID
PIX-V3-Device-Universal-ID
Identifies the PIX Manager V3 Organization:
PIX-V3-Organization-Namespace-ID
PIX-V3-Organization-Universal-ID
Sets the default Patient Demographics Query Continuation timeout (in seconds):
PDQ-Continuation-Timeout
This section provides the steps to build a project, along with the differences between GlassFish and WebLogic.
In the left panel of NetBeans IDE, right-click the project icon (for example, IHEProject1).
An Actions menu appears.
To build an IHE Profiles Application project, click Build on Actions menu.
When you build the IHE Profiles Application project for GlassFish, two 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.