PHINMS 2.8.02 receiver and RNR documentation
ChristinaC
Eduardo Gonzalez Loumiet
Eduardo Gonzalez Loumiet, MBA, PMP, CPHIMS
(786) 315-9828 | GetToKnowEduardo.com
egonzale...@gmail.com
Partner | Uber Operations, LLC
Assistant Professor |
Health Information Systems | Florida
A&M
Does anyone have any PHINMS 2.8.02 documentation on how to setup a receiver, especially to work with another lab not via CDC? PHINMS documentation is not really clear on now it all works.Also, documentation on RNR on how it works with CDC or an external lab. PHINMS help desk said they have an internal RNR document but I have not received it yet.
--
---
You received this message because you are subscribed to the Google Groups "PHINMS User Community" group.
To unsubscribe from this group and stop receiving emails from it, send an email to phinms+un...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Preacher Man
From: egonzale...@gmail.com
Date: Tue, 19 May 2015 18:40:37 -0400
Subject: Re: PHINMS 2.8.02 receiver and RNR documentation
To: phi...@googlegroups.com
Preacher Man
From: preac...@hotmail.com
To: phi...@googlegroups.com
Subject: RE: PHINMS 2.8.02 receiver and RNR documentation
Date: Wed, 20 May 2015 07:57:22 -0500
ChristinaC
Priority: 1 - Fatal
Category: network
Error Code: NW0001
Time: 2015-08-26 17:34:01.893
Description: The Receiver is not up at phinms.phila.gov:443 or the firewall is blocking outgoing requests.
Next Steps: (1) Correct the receiver host and/or port. (2) Unblock the firewall which is preventing outgoing requests.
Martin, Steve
Christina,
I was just dealing with them earlier and they have a new SSL cert. You can hit that site from the browser and pull down the new cert.
Thanks,
Steve
Grrr...
Tom
Tom
Partner | Uber Operations, LLC
-This e-mail and any attachments may contain CONFIDENTIAL information, including PROTECTED HEALTH INFORMATION. If you are not the intended recipient, any use or disclosure of this information is STRICTLY PROHIBITED; you are requested to delete this e-mail and any attachments, notify the sender immediately, and notify the LabCorp Privacy Officer at privacy...@labcorp.com or call (877) 23-HIPAA / (877) 234-4722.
ChristinaC
Priority: 1 - Fatal
Category: network
Error Code: NW0001
Time: 2015-08-26 17:34:01.893
Description: The Receiver is not up at phinms.phila.gov:443 or the firewall is blocking outgoing requests.
Next Steps: (1) Correct the receiver host and/or port. (2) Unblock the firewall which is preventing outgoing requests.
Martin, Steve
If you’ve made changes to a route in PhinMS you will need to export the CPA file and send to the receiver and have them import it using PhinMS. That should clear up the CPA not found error.
From: phi...@googlegroups.com [mailto:phi...@googlegroups.com] On Behalf Of ChristinaC
Sent: Thursday, August 27, 2015 3:56 PM
To: PHINMS User Community
Grrr...
Tom
Tom
Partner | Uber Operations, LLC
-This e-mail and any attachments may contain CONFIDENTIAL information, including PROTECTED HEALTH INFORMATION. If you are not the intended recipient, any use or disclosure of this information is STRICTLY PROHIBITED; you are requested to delete this e-mail and any attachments, notify the sender immediately, and notify the LabCorp Privacy Officer at privacy...@labcorp.com or call (877) 23-HIPAA / (877) 234-4722.
Preacher Man
The URL is good (just tried it myself) and that receiver is up and running. It may be that your browser is allowed but everything else is blocked (as your error message suggests). Firewalls can be configured to be application specific and it may be that only IE is allowed to start outgoing HTTPS.
This could be either a setting on your PC, or at one of your organization's firewalls.
The other possibility is that your IE is pre-configured to use a proxy host. Check with your network/infrastructure people to see what (if any) restrictions there may be on outgoing 443/SSL connections.
And just for sanity, double check that you have HTTPS (and not HTTP) configured for your PHINMS route (:-).
Tom
ChristinaC
ChristinaC
Preacher Man
Date: Thu, 27 Aug 2015 14:03:43 -0700
From: ccrawf...@gmail.com
To: phi...@googlegroups.com
CC: Mar...@labcorp.com
ChristinaC
Preacher Man
For the receivers I manage, I provide an on-line step by step SOP for making connections as a web page. It includes screen shots and bullets with the details that can be copied and pasted into the PHINMS console of the sending client. Those details are unique to our receiver and won't work for anyone else. CDC has similar instructions for their receivers.
Steve's instructions below are helpful, but again may include specifics that are not relevant to the receiver you are sending to. In fact I am certain that it does not require step number 3, since I can reach their receiver from my browser with no client cert at all.
And Steve is assuming they are using an IIS proxy. That may be true, but others receivers commonly use Apache, or even CISCO or other firewall appliances that perform proxy functions. I've had experience setting up and connecting to all three. Each is a little different.
Again, the only one(s) who can know for sure will be the folks managing the receiver.
If you provide the appropriate snippet(s) of your sender logs, I can probably be of more assistance regarding the exact issue you are currently having. But your best bet is to talk to your receiver's managers...
Tom
Lowe, Phillip (DOH)
I have pretty good documentation for someone new to set up a sender to WA DOH. Down side is it was written for 2.7. While the main page has changed drastically, the rest of it is pretty much unchanged. I could send a copy to you as a starting place for you to customize for your site and to update to 2.8.
Phill Lowe 360 236-4261
Systems Development Office, Department of Health, Washington State
Working to improve the health of the people of Washington State
ChristinaC
Preacher Man
A PHINMS message exchange can involve up to five certificates, listed here in typical order of importance. They are all optional, but provide various security functions. Most PHINMS messages use at least two of the five.
1. Receiver SSL certificate - sent by the receiver (proxy) and installed in the sender's certificate authority Java KeyStore (often just the signer, rather than the actual certificate). Used to authenticate the receiver to the sender. This is required if using HTTPS protocol in the sender route.
2. Encryption certificate - contains a public key used by the sender to encrypt a message. The receiver must have the private key to decrypt it. In PHINMS this is typically held in a private encrypted .PFX file by the receiver, and in a publicly distributed .DER file by the sender.
3. Sender SSL certificate - sent by the sender and installed in the receiver's (proxy) certificate authority (again possibly just a signer). Used to authenticate the sender to the receiver. This may be optionally required depending on how the receiver is configured.
4. Digital Signature certificates - used by either sender or receiver to digitally sign messages and provide non-repudiation.
5. LDAP server SSL certificate - similar to #1 above, but optionally sent by the LDAP server providing online certificates (as opposed to locally held file based certificates).
The same certificate may be used for multiple functions (for example receiver SSL and encryption, or sender authentication and digital signature). While a certificate may be used for numerous functions, its content is generally the same and only the storage format varies. Note that the private key is not part of an X509 certificate, but may be stored with it depending on the format. If you are not schooled in X509 certificates or basic encryption, you might want to study up a bit on formats, content, etc. There is a wealth of good information available on the web.
Tom
ChristinaC
Travis Mayo
Christina Crawford
Preacher Man
I haven't heard of an "automatic script" being used to support a forward proxy (e.g. a proxy to handle outgoing requests), but perhaps you are referring to a script that configures your browser (IE) to use the proxy. Generally you configure a client (e.g. IE, Firefox, or PHINMS) ONCE to use a forward proxy when required by internal firewall security.
If your infrastructure blocks all direct outgoing requests and instead uses a forward proxy, then you need to configure PHINMS to use the same configuration. Your "IE Script" won't work here, but your infrastructure folks should be able to provide you with the needed proxy information:
Host
Port
User
Password
You enter this information into the PHINMS Sender's General Configuration under Proxy. Now if your infrastructure is doing something unusual like changing the proxy credentials (User/Password) on a regular basis that would explain an "automatic script", since your browser would need to continuously update its configuration. If that is the case you will have to see if you can talk your organization into making a firewall exception for your PHINMS server.
In any event, if you were to provide the appropriate part of your PHINMS sender log (with logLevel set to detail in sender.xml) that would help us diagnose your issue.
Tom
Date: Tue, 27 Oct 2015 07:21:04 -0700
Christina Crawford
Lowe, Phillip (DOH)
The URL in the CPA isn’t critical, it is only used as the “Shared Secret” so as long as your copy and theirs match you are good to go.
The biggest challenge is getting an inbound path to your PHINMS server. Ours resides in the DMZ behind the WA state gateways.
The gateways provide the termination of the SSL link from the outside so our PHINMS doesn’t need to do that. You will find the Tomcat configuration that allows that to be handled by Tomcat.
Under Configure/receiver/WorkerQueues, choose the database and update it. Click on the “Queue Maps for this Database” button and set up a Queue_ID pointing to a db table.
The go to the service map and create a new one. You can select the service and action and either check the “Payload to disk” box or select the Queue_ID so the data goes into a specific table.
We send stuff to different tables so we know what kind of data it is and if it is QA or PROD.
You can set up a local PHINMS instance on a local VM (on your personal machine even) so you can work both sides of the PHINMS setup. If you are local, you can ignore the SSL component and concentrate on the other certificates. We have a couple of servers using the same certificate to talk to each other and it works fine.
Phill Lowe – 260 236-4261
From: phi...@googlegroups.com [mailto:phi...@googlegroups.com]
On Behalf Of Christina Crawford
Sent: Monday, April 03, 2017 1:41 PM
To: PHINMS User Community <phi...@googlegroups.com>
Subject: Re: PHINMS 2.8.02 receiver and RNR documentation
I finally got my development PHINMS to send a file to the other state agency last week. The other state agency moved their PHINMS to another server. They noticed that other states that send them files had their CPA XML file contents URL different than the public URL.
--
Preacher Man
AFAIKT, the PHIN-MS receiver only checks for the existence of a matching CPA (file) and doesn't really look at the contents. So Phil is right in that. However, they don't even need to match. Since that sender doesn't actually send the CPA there would be no way a receiver could confirm the contents.
However, the receiver's URL in the sender's copy of ;the CPA is critical (as are the other parts like encryption, etc). The sender does use the receiver's URL (domain and path) and encryption information in the CPA to connect to the destination host. For most receivers, this is a DMZ proxy host rather than the actual PHIN-MS server (which explains why the receiver doesn't care about CPA URL's or authentication information - it's for someplace else... the proxy!).
So you need to coordinate with your infrastructure folks managing the proxy host to arrange for the appropriate "receiver" URL and certificates to provide remote senders. If you are not using a proxy... well just stop (:-).
Tomcat/PHIN-MS is simply not secure enough to run in a DMZ "naked". Alternatively you could use a restrictive set of firewall rules (typically IP restrictions with NAT depending on your appliance), but in any event you still have to deal with your network infrastructure folks to get it worked out. PHIN-MS should really live in a private subnet.
Good luck setting up your receiver. Getting it "right" (especially the security) is definitely more involved than configuring a sender. This BTW is the reason for RNR (route not read) - so you can receive files without the need for all the security cruft associated with a receiver (and let someone else do all that work :-).
Sent: Monday, April 3, 2017 4:07 PM
To: phi...@googlegroups.com
Subject: RE: PHINMS 2.8.02 receiver and RNR documentation
Christina Crawford
I am totally confused now.
The PHINMS Technical Guide has the scripts for SQL Server for a sender and receiver.
This might be a stupid question.
Exactly what database tables does the PHINMS sender use (besides the transportq_out)? What database tables should be created in SQL Server for a PHINMS sender?
Exactly what database tables does the PHINMS receiver use? What database tables should be created in SQL Server for a PHINMS receiver?
The PHINMS Technical Guide has the scripts in it to create the tables for a sender and a receiver. The descriptions are also confusing.
When setting up our PHINMS receiver configuration, I believe the database name it defaulted to was testworkerqueue. But the CDC scripts don’t have that name I just reliazed.
On Tuesday, May 19, 2015 at 6:18:21 PM UTC-4, Christina Crawford wrote:
Preacher Man
Christina,
If the standard Sender/Receive tables are confusing you I would suggest you don't even consider RNR until you have those working.
Start with just the sender. Section 2.1 Page 10 of the tech guide lists the fields and provides descriptions. The sender can have multiple queues, but only one is typically useful. Each time you "queue" a payload for transport (using folder polling), it gets placed in ALL of the defined transport Q's, so you want to disable/delete the default HSQL queue if you switch to MSSQL. The multiple sender queues are only useful if you DON'T use folder polling, and instead use some other method of placing entries in a transport queue (JMS for example). Very few people do this, since folder polling is simple to understand, it works, and provides an easy and common "interface" (the file system).
Here the simplest way is to just edit the default database in your sender's configuration and change the dB URL/user and password to be your MSSQL dB. You can leave the queue table name the same, but whatever table name you use must match the one used when you create the table. The script 6.1.1 on page 18 will create a sender queue and uses the same table name as the HSQL dB.
Once you get this working, you know your MSSQL dB is set up correctly (e.g. passwords, permissions, accounts, URL's, etc.). Then you are ready to move on to the receiver's queue.
2.2 on page 11 describes the receiver's "worker" queue. It does have most of the same fields as the sender, but varies a little bit. That is because both share the "meta data" for each message (dates, times, ID's, etc.) so that you can coordinate which received messages go with which sent messages should things go wrong. The MSSQL script 6.1.6 on page 20 again shares the same name as the default HSQL queue, so like the sender you should just edit the database entry and change the dB URL/user and password if you want to keep things simple.
So you only need to create two MSSQL tables: one for the sender and one for the receiver. There rest are for RNR and error messages. However, a receiver can have multiple "worker" queues, each associated with a particular service/action. Each table would need it's own unique name (modify the script 6.1.6). This is so a receiver can put different sender messages into separate queues (a convenience - assuming you give each sender a unique service/action). But you can use any of the meta data to sort things out as you see fit, so in theory you only need the one queue.
You need to figure out what (if any) differences there will be in processing incoming message (data brokering) and set things up accordingly. This will likely depend on your choice of down stream systems (message consumers). So you should really know what your incoming data will look like, what needs to be done to it, and where it should end up BEFORE setting up the receiver (otherwise you have a cart before the horse situation - you will just be going back and forth trying to hit a target you can't even see).
Like I wrote earlier, a receiver is way more complex than a sender. If a sender has a complexity of say "1", as receiver is probably more like "100". And RNR is more like "1000". Don't even think about going there unless you fully understand a basic receiver and have it working.
Finally, I'll just note that the receiver's I managed were handling around 1000 messages per day using the stock HSQL dB without issue. I understand there are often "enterprise" reasons for selecting alternative PHINMS dB's, but frankly I don't see a technical advantage unless you are getting LOTS of messages (say greater than a million per year).
Tom
Sent: Wednesday, June 14, 2017 4:15 PM
To: PHINMS User Community
Subject: Re: PHINMS 2.8.02 receiver and RNR documentation
I am totally confused now.
Christina Crawford
http-5088-1|05/24|04:03:11|Started ebxml.receivefile servlet|
http-5088-1|05/24|04:03:11|Loading decryption keystore|
http-5088-1|05/24|04:03:11|Processing database node|
http-5088-1|05/24|04:03:11|dbType=hsqldb|
http-5088-1|05/24|04:03:11|Initialized SSL context .... |
http-5088-1|05/24|04:03:11|Error resolving secret parameter|
http-5088-1|05/24|04:03:11|incomingDir=D:\Program Files\PHINMS\shared\receiverincoming//|
http-5088-1|05/24|04:03:11|cpaLocation=D:\Program Files\PHINMS/config/receiver/CPA/|
http-5088-1|05/24|04:03:11|myPartyId=2.16.840.1.114222.4.3.2.2.3.657.1|
http-5088-1|05/24|04:03:11|myDomain=cdc.gov|
http-5088-1|05/24|04:03:11|Log directory=D:\Program Files\PHINMS\logs\receiver/////////////////////|
http-5088-1|05/24|04:03:11|Logging level=3|
http-5088-1|05/24|04:03:11|Receiver PartyID=2.16.840.1.114222.4.3.2.2.3.657.1|
http-5088-1|05/24|04:03:11|Receiver ServiceMap=D:\Program Files\PHINMS/config/receiver/serverServicemap.xml|
http-5088-1|05/24|04:03:11|Receiver truststore=D:\Program Files\PHINMS\security\receiver\cacerts|
http-5088-1|05/24|04:03:11|Receiver signatureRequired=false|
http-5088-1|05/24|04:03:11|Receiver signingcertslocation=D:\Program Files\PHINMS\security\receiver\signingcerts|
http-5088-1|05/24|04:03:11|ReceiverFileServlet Initialization done|
2. Can one test their PHINMS receiver configuration by setting up a PHINMS sender route map in the same PHINMS instance?
Christina Crawford
Preacher Man
Christina,
Without additional research I'm guessing there is a (SSL context related) entry missing in the passwords file. However, I see the same in my "test" instance on my development box here at home (along with several others) that doesn't prevent the receiver from working. But I typically do payload processing (including decryption) in a custom servlet so many of my receiver security parts are deferred and left blank.
I will make a couple of general security comments. As installed the PHINMS Tomcat SSL connector is miss-configured and does not work. You will need to hand modify appserver/conf/server.xml to include something like this:
As for testing, a workstation instance of a PHINMS sender should work fine. You can simply check access first with a browser - e.g.:
https://My_Phinms_Server_or_Proxy:5089/receiver/receivefile
To: PHINMS User Community
Subject: Re: PHINMS 2.8.02 receiver and RNR documentation