Pharmacy Integration

This documentation is intended for pharmacies, and is not relevant for Residex users.

• In addition to installing the Residex Pharmacy Connect application, you​r pharmacy software w​ill also need to be configured to transmit data.

Requirements
The Residex Pharmacy Connect application can be installed on Windows systems: Windows 7 and later (32 bit and 64 bit), Windows Server 2003 and later (32 bit and 64 bit). The application must be installed on the same server or the same network as your pharmacy software.

Firewalls
If the Residex Pharmacy Connect application is installed on a separate machine from your pharmacy software, you may have to create exceptions within internal Firewalls and Antivirus programs to allow communications between the systems.

If you need to make any firewall changes to allow outgoing traffic to leave your network, an exception to allow outgoing traffic to residexapi.com will be needed.

Installation Process

1. Download the installer
2. Run the installer, & follow prompts to allow the installer to proceed.

1. The Residex Pharmacy Connect application will listen for messages on a Port (the default Port it will use is "6000"). You will be given the option to change the Port number used; you may optionally change this if you prefer a different default Port. Press OK to proceed.

FYI Regarding the Port: If the port is unavailable or If you are unsure if the default Port is available, you can check by using the Command Prompt system to run the following command.

CHECK TO SEE IF A PORT IS IN USE
netstat -na | find “​6000”​

If this command returns no results, the default Port is available.
If it returns any results that say "LISTENING," the port is not available.

You can repeat this command for different Port numbers until you find an available port. For example: 6001, 6002, 6003 and so on.

The installation should take just a moment, and will notify you when complete. You're done! You can delete the installer .exe at this point.

The installer will create:

• A directory, C:\ResidexPharmacyConnect, which will contain all relevant files needed by the installer, including a log file which can be reviewed to view the application's activity.
• A Windows Service called "Residex Pharmacy Connect" that will run in the background.

Reviewing the Log

You can optionally confirm the system is up and running by checking the log file, located at C:\ResidexPharmacyConnect\log.txt.

This log is a continually updated text file. It contains basic metadata about the Residex Pharmacy Connect application's activity; it does NOT ever contain any sensitive information The log will display a message like the below if it is up and running. The log will also indicate when messages are received, and if any errors are encountered.

EXAMPLE LOG
2021-03-15 10:35:00,147 - INFO - Listening on 127.0.0.1:6000
2021-03-15 10:35:19,538 - INFO - Message received on 127.0.0.1:6000.
2021-03-15 10:35:19,977 - INFO - Message received for facility code TEST.

Configure your Pharmacy Software

Your pharmacy software system will need to be configured to transmit data to the Residex Pharmacy Connect application. Residex Staff cannot assist much with this step, so we refer you to your pharmacy software's support team.

They will need to know:

• Port Number (this will be 6000 unless you've specified a different Port)
• IP Address of the machine on which the Residex Pharmacy Connect application is installed If you don't know the IP Address, you can find this by using the Command Line on that machine to run the command "ipconfig"
• What homes you want to begin transmitting data to Residex for.

Find your IP Address
ipconfig

Among the results this command returns will be your "IPV4 Address," which is the IP Address of the machine you're connected to.

Facility Codes

When you begin transmitting data, please provide Residex Software with any Facility Codes you are transmitting data for. These are identification codes for homes that we need in order to ensure correct routing of the data you send us.

Get Help

Please email pharmacyconnect@residexsoftware.com or call 866.512.8369 with any questions or for assistance.

Troubleshoot, Update, Remove

Reading the log

The Residex Pharmacy Connect application maintains a log file at C:\ResidexPharmacyConnect\log.txt.

This log is a continually updated text file. It contains basic metadata about the application's activity; it does NOT ever contain any sensitive information The log will display a message like the below if it is up and running. The log will also indicate when messages are received, and if any errors are encountered.

EXAMPLE LOG
2021-03-15 10:35:00,147 - INFO - Listening on 127.0.0.1:6000.
2021-03-15 10:35:19,538 - INFO - Message received on 127.0.0.1:6000.
2021-03-15 10:35:19,977 - INFO - Message received for facility code TEST.
2021-03-15 10:35:37,913 - INFO - Service stopped.

Every time the application receives and successfully processes an HL7 message, it will be indicated in the log. The message received logs will indicate the date & time of each successful message receipt, the IP Address and Port the application was listening on when the message was received, and the Facility Code contained within the message.

Service stopped: Last time Residex Pharmacy Connect application was stopped.
If the last post to the log is 'Service stopped', the needs to be restarted before data transmission can resume.

Port busy: The Residex Pharmacy Connect application needs to be reconfigured to use a new port.
If the log indicates a port is busy, another system is already using the specified Port number. The application needs to be reconfigured to use a different Port.

Can't connect to Residex API: The ResiDex application cannot send messages outside of your network.
If the application cannot connect to residexapi.com, outbound firewalls or other security systems are likely blocking outbound traffic, OR there could be an authentication issue resulting from a missing Windows Update.

To resolve:

• Check to see if the machine running the Residex application needs any Windows Updates, apply any needed
• Verify there are no firewalls or security systems blocking outbound connections to residexapi.com

Connection aborted / ConnectionResetError/ An existing connection was forcibly closed by the remote host
If you see these Error messages in the log file, it most likely means your network has a firewall that is blocking outbound connections from your network to Residex.

Example error message
ERROR - Message rejected for facility code 45.
('Connection aborted.', ConnectionResetError(10054, 'An existing connection was forcibly closed by the remote host', None, 10054, None))

• Verify there are no firewalls or security systems blocking outbound connections to residexapi.com

Stop / Restart the Residex Pharmacy Connect Application

When properly configured, the ResiDex Pharmacy Connect application will automatically be restarted each time the server it is installed on reboots.

As part of any troubleshooting process, you can restart the Residex application on demand. If changes are made to the Config file, you will need to restart the application for the changes to take effect.

Restart

• Go to the Start menu and search for “Services"
• Select “Services” from the search results
• From the Services screen, select the “Residex Pharmacy Connect” Windows Service
• Press Restart

Stop the application
The Pharmacy can disable data transfer all together or for an individual client at any time with no notice, completely independently and without assistance from Residex Software.
Disabling data transfer for an individual client is done within Pharmacy Software settings.

Disabling data transfer to the Residex application all together can be done via the Pharmacy Software settings, OR can be done by turning off the ResiDex application

• Go to the Start Menu and select Services
• From the Services screen, select "Residex Pharmacy Connect" and press Stop)

Outbound Firewall Troubleshooting

For the Residex Pharmacy Connect application to connect with us from your network, it needs to be able to reach out of your network to residexapi.com. If your network blocks this URL, it will result in errors and failure to transmit messages from your network.

To resolve this, please allow network traffic to reach the domain residexapi.com

Notes:

• Residex does not use static IP addresses for our API; any IP addresses for residexapi.com will change over time. Exceptions must be made for the domain, not specific IP addresses.
• The Residex Pharmacy Connect application does not require any special ports be opened.

Testing
You can test any firewall rules you create by using one of the following commands in the Terminal, if Curl is installed (should be installed by default on current versions of Microsoft Windows).

Command line test of accessibility of residexapi.com
curl https://residexapi.com/clients

• OR -

VERBOSE Command line test
curl -v https://residexapi.com/clients

Successful Response
Either of the Curl prompts above should return the message "The server could not verify that you are authorized to access the URL requested." This indicates a successful connection to our API (since you are not connecting with any permissions, we expect this rejection.

Unsuccessful Response
If residexapi.com is blocked, you will see a failure message like the below example. This means your network is not able to connect to residexapi.com.

Configure your Pharmacy Software

Configure your pharmacy software to transmit messages to the IP Address of the server running Residex Pharmacy Connect, and Port 6000 (or a custom Port number if specified). Your pharmacy software support team will be able to help you with this.

Ideally, Pharmacy Software will be configured to send only NW (New Order) and XO (Changed Order) messages to Residex; if additional types of orders are transmitted to Residex, they will be ignored.

Specifications for what facilities have data transmitted to the application is always controlled in the Pharmacy Software, so data is only ever transmitted only for appropriate clients.

Facility Codes
When you begin transmitting data, please provide Residex Software with any Facility Codes you are transmitting data for. These are identification codes for homes that we need in order to ensure correct routing of the data you send us.

Update Residex Pharmacy Connect Application

Updating your version of the Residex Pharmacy Connect application is very simple and should just take a few minutes.

• No uninstallation step is required
• No Reboots / restarts are required
• Updating Pharmacy Connect will not impact your pharmacy software or normal operations.

Updating your installed version of the Residex Pharmacy Connect application is as simple as repeating the installation process!

Uninstall Residex Pharmacy Connect Application

The Pharmacy can disable Residex Pharmacy application entirely on demand at any time without notice, completely independently without assistance from Residex.

1. Download the Uninstaller
2. Run the uninstaller and follow prompts to uninstall the Pharmacy Connect application.

Uninstalling the Residex Pharmacy Connect application

Get Help

Please email integrations@residexsoftware.com or call 866.512.8369 with any questions or for assistance with the interface.

HL7 Specifications