Difference between revisions of "Carecoordination Module Configuration"

From OpenEMR Project Wiki
m (→‎Purpose: correcting link)
(→‎Instructions for APT based Linux distributions: No need to manually add Node PPA to apt sources as this is done by the curl command)
 
(19 intermediate revisions by 2 users not shown)
Line 1: Line 1:
= Purpose =
= Purpose =
This document shows how to configure Z&H Healthcare's CCDA module as found in OpenEMR 4.2.x.
This document shows how to configure OpenEMR's CCDA module as found in OpenEMR 4.2 and later.  
Please look here for [[Use the Carecoordination module]].
Please look here for how to [[use the Carecoordination module]]. This document has not yet been updated for improvements and additional features in the Carecoordination module with OpenEMR 7.0. The module was again significantly updated with OpenEMR 7.0 Patch 2.


= Introduction/ Caveats =
= Introduction/ Caveats =
This document shows the installation and configuration of this module in a testing environment so may not exactly duplicate all aspects of clinical use. But they should be close.  An OpenEMR Administrator's user account is required for these activities.  
The Carecoordination module was initially contributed to OpenEMR by Z&H Healthcare.


Many thanks to Z&H Healthcare for contributing the CCDA module and to Brady Miller for most of the original instructions used to create this tutorial.
An OpenEMR Administrator's user account is required for these activities.
 
= Procedure =
== Enable the CCDA service ==
Enable the CCDA service in OpenEMR:<br/>
Admin &rarr; Globals &rarr; Connectors &rarr; Enable C-CDA Service: Care Coordination Only | Portal Only | Both
 
This service should automatically start on demand when required by OpenEMR.


- HTuck – MI-Squared


= Procedure =
== Install/ configure modules ==
[[Image:ccda-LnavModules.png|right]]
[[Image:ccda-LnavModules.png|right]]
== Install/ configure modules ==
1. In the main menu:  
1. On Left Nav menu:  


''''Modules->Manage Modules''''
''''Modules &rarr; Manage Modules''''




Line 44: Line 49:
2. Click the ''''Unregistered'''' tab
2. Click the ''''Unregistered'''' tab


[[Image:ccda-010.png|center]]
[[File:ccda-010.png|thumb|500px|center|For full sized image click pic and select 'Full resolution' link]]




Line 50: Line 55:




3. Click the ''''Registered'''' button on each, one at a time, from top to bottom.  
3. Click the ''''Registered'''' button on each of the modules that are a dependency of Carecoordination, one at a time.  


Register Carecoordination last.
Be sure to '''register 'Carecoordination' last'''.




Line 68: Line 73:




[[Image:ccda-011.png|center]]
[[File:ccda-011.png|thumb|500px|center|For full sized image click pic and select 'Full resolution' link]]




Line 77: Line 82:




[[Image:ccda-012.png|center]]
[[File:ccda-012.png|thumb|500px|center|For full sized image click pic and select 'Full resolution' link]]




Line 85: Line 90:




[[Image:ccda-013.png|center]]
[[File:ccda-013.png|thumb|500px|center|For full sized image click pic and select 'Full resolution' link]]
 
 
 
8. In the new panel click ''''Access Control'''' tab (oval above left)
 
9. Click in checkboxes of ''''Carecoordination'''' and ''''Send to HIE'''', for the ACL roles that you wish to allow to use this module; here, Administrator and Clinicians (lower rectangle above)
 
10. In Left Nav menu: ''''Modules &rarr; Manage Modules''''
 
11. Under Registered tab, Carecoordination module click on the config gear icon (oval)
 
 
 
[[File:ccda-014a.png|thumb|500px|center|For full sized image click pic and select 'Full resolution' link]]
 
 
[[Image:ccda-014.png|right]]
 
12. Click ''''Settings'''' tab (top rectangle)
 
Author:
 
Primary Care Provider:
 
 
 
13. Mirth settings are not necessary with Open EMR 6 and onwards.
 
 


14. Click ''''SAVE''''




8. In the new panel click Access Control tab (oval above left)
The CCDA module is now configured.


9. Click in checkboxes of ''''Carecoordination'''' and ''''Send to HIE'''', for the ACL roles that will be allowed to use this module; here, Administrator and Clinicians (lower rectangle above)
When you log out of OpenEMR and then back in, the Carecoordination menu item will appear in the Modules menu.


8. Logout




9. Login (as Administrator)
== Install Node.js ==


10. In Left Nav menu: ''''Modules->Manage Modules''''
We will install <b>Node.js version 18.x</b> from upstream as the 18 series is the maximum version currently tested to work with OpenEMR. Node modules are run local to the service's directory, so all support dependencies are installed there. After installation, the Node.js CCDA service should start on demand.


11. Under Registered tab, Carecoordination module click on the config gear icon (oval)
=== Instructions for APT based Linux distributions ===
 
<code>cd ~</code>
 
Ensure a clean install and clean up:<br/>
<code>sudo apt remove --purge nodejs npm</code>
 
Get Node 18 from upstream and add Node PPA to apt sources so as to keep Node 18.x up-to-date:<br/>
<code>curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -</code>
 
Install nodejs:<br/>
<code>sudo apt install -y nodejs npm</code>
 
You may also need development tools to build native addons:<br/>
<code>sudo apt install gcc g++ make</code>
 
== Install the CCDA service ==
 
Navigate to OpenEMR's <code>ccdaservice</code> directory.
 
Initialize the project to create package.json, which will hold information about the app and which packages it depends on:<br/>
<code>npm init</code>
 
Select the default for all questions.
 
Shutdown running "node" processes by searching for them, finding their pid and killing them. Otherwise changes aren't included until node is restarted.
 
Install required dependencies [Editor's note: I do so without sudo (see https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=960289), though OpenEMR's ccdaservice README.md recommends running it with sudo):<br/>
<code>npm install --production</code>
 
 
== Apache Configuration ==
 
So as to get Zend to work and the Carecoordination menu option not to give a 404 error, use "<code>AllowOverride FileInfo</code>" in the Apache config file.
 
NOTE: https://www.open-emr.org/wiki/index.php/Securing_OpenEMR#Apache says "Do not allow use of .htaccess files in Apache (ie. turn off the AllowOverride setting)."
 
Enable mod_rewrite:<br/>
<code>sudo a2enmod rewrite</code>
 
Restart Apache:<br/>
<code>sudo systemctl restart apache2</code>




== Install PHP Modules ==
The following PHP modules are required:
* XML / SimpleXML / xmlreader / xmlwriter / XSL - php-xml - DOM, SimpleXML, WDDX, XML, and XSL module for PHP
* SOAP - php-soap
* Sockets - php-net-socket - Network Socket Interface


[[Image:ccda-014a.png|center]]
For example on Debian run:<br/>
<code>sudo apt install php-xml php-soap php-net-socket</code>




[[Image:ccda-014.png|right]]


12. Click ''''Settings'''' tab (top rectangle)
= Updating =


After updates of OpenEMR or of nodejs, ensure the latest libraries are installed.


Navigate to OpenEMR's ccdaservice directory.


Shutdown running "node" processes by searching for them, finding their pid and killing them. Otherwise changes aren't included until node is restarted.


13. Enter your Mirth settings:
(In some instances, it is also necessary to delete the <code>ccdaservice/node_modules</code> directory.)


(left oval)
Run the following:<br/>
<code>npm install --production</code>


MirthIP:


Client ID:


Username:
= Troubleshooting =


Password:
== Manually run the CCDA service ==
Manually run the CCDA service from the command-line, where you'll more easily be able to see if it runs OK or throws an error.


Navigate to OpenEMR's <code>ccdaservice</code> top level directory.


14. Click ''''SAVE'''' (circle at bottom)
In there run the CCDA service:<br/>
<code>node serveccda.js</code>


If it is already running then it will give the following error: "<code>Error: listen EADDRINUSE: address already in use 127.0.0.1:6661</code>"). In this case you'll have to kill the running process (<code>pkill nodejs</code> on Linux), then start it as above.


The CCDA module is now configured.
If the service starts OK at the command-line, then try a CCDA export in OpenEMR while it is running and look for messages displayed at the command-line.

Latest revision as of 13:56, 8 September 2024

Purpose

This document shows how to configure OpenEMR's CCDA module as found in OpenEMR 4.2 and later. Please look here for how to use the Carecoordination module. This document has not yet been updated for improvements and additional features in the Carecoordination module with OpenEMR 7.0. The module was again significantly updated with OpenEMR 7.0 Patch 2.

Introduction/ Caveats

The Carecoordination module was initially contributed to OpenEMR by Z&H Healthcare.

An OpenEMR Administrator's user account is required for these activities.

Procedure

Enable the CCDA service

Enable the CCDA service in OpenEMR:
Admin → Globals → Connectors → Enable C-CDA Service: Care Coordination Only | Portal Only | Both

This service should automatically start on demand when required by OpenEMR.


Install/ configure modules

Ccda-LnavModules.png

1. In the main menu:

'Modules → Manage Modules'














2. Click the 'Unregistered' tab

For full sized image click pic and select 'Full resolution' link



3. Click the 'Registered' button on each of the modules that are a dependency of Carecoordination, one at a time.

Be sure to register 'Carecoordination' last.


As they're registered they appear on the 'Registered' tab so you'll go back to the 'Unregistered' tab to register each one.


4. Open 'Registered' tab (below)


5. Click the blue 'Install' button of each module, one at a time from top to bottom, installing Carecoordination module last.

Each button's blue 'Installed' caption will change to blue 'Enabled'



For full sized image click pic and select 'Full resolution' link


6. Click all modules' 'Enabled' buttons top to bottom



For full sized image click pic and select 'Full resolution' link


7. In the 'Carecoordination' item click on the gear-like config icon (far right circle below)



For full sized image click pic and select 'Full resolution' link


8. In the new panel click 'Access Control' tab (oval above left)

9. Click in checkboxes of 'Carecoordination' and 'Send to HIE', for the ACL roles that you wish to allow to use this module; here, Administrator and Clinicians (lower rectangle above)

10. In Left Nav menu: 'Modules → Manage Modules'

11. Under Registered tab, Carecoordination module click on the config gear icon (oval)


For full sized image click pic and select 'Full resolution' link


Ccda-014.png

12. Click 'Settings' tab (top rectangle)

Author:

Primary Care Provider:


13. Mirth settings are not necessary with Open EMR 6 and onwards.


14. Click 'SAVE'


The CCDA module is now configured.

When you log out of OpenEMR and then back in, the Carecoordination menu item will appear in the Modules menu.


Install Node.js

We will install Node.js version 18.x from upstream as the 18 series is the maximum version currently tested to work with OpenEMR. Node modules are run local to the service's directory, so all support dependencies are installed there. After installation, the Node.js CCDA service should start on demand.

Instructions for APT based Linux distributions

cd ~

Ensure a clean install and clean up:
sudo apt remove --purge nodejs npm

Get Node 18 from upstream and add Node PPA to apt sources so as to keep Node 18.x up-to-date:
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -

Install nodejs:
sudo apt install -y nodejs npm

You may also need development tools to build native addons:
sudo apt install gcc g++ make

Install the CCDA service

Navigate to OpenEMR's ccdaservice directory.

Initialize the project to create package.json, which will hold information about the app and which packages it depends on:
npm init

Select the default for all questions.

Shutdown running "node" processes by searching for them, finding their pid and killing them. Otherwise changes aren't included until node is restarted.

Install required dependencies [Editor's note: I do so without sudo (see https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=960289), though OpenEMR's ccdaservice README.md recommends running it with sudo):
npm install --production


Apache Configuration

So as to get Zend to work and the Carecoordination menu option not to give a 404 error, use "AllowOverride FileInfo" in the Apache config file.

NOTE: https://www.open-emr.org/wiki/index.php/Securing_OpenEMR#Apache says "Do not allow use of .htaccess files in Apache (ie. turn off the AllowOverride setting)."

Enable mod_rewrite:
sudo a2enmod rewrite

Restart Apache:
sudo systemctl restart apache2


Install PHP Modules

The following PHP modules are required:

  • XML / SimpleXML / xmlreader / xmlwriter / XSL - php-xml - DOM, SimpleXML, WDDX, XML, and XSL module for PHP
  • SOAP - php-soap
  • Sockets - php-net-socket - Network Socket Interface

For example on Debian run:
sudo apt install php-xml php-soap php-net-socket


Updating

After updates of OpenEMR or of nodejs, ensure the latest libraries are installed.

Navigate to OpenEMR's ccdaservice directory.

Shutdown running "node" processes by searching for them, finding their pid and killing them. Otherwise changes aren't included until node is restarted.

(In some instances, it is also necessary to delete the ccdaservice/node_modules directory.)

Run the following:
npm install --production


Troubleshooting

Manually run the CCDA service

Manually run the CCDA service from the command-line, where you'll more easily be able to see if it runs OK or throws an error.

Navigate to OpenEMR's ccdaservice top level directory.

In there run the CCDA service:
node serveccda.js

If it is already running then it will give the following error: "Error: listen EADDRINUSE: address already in use 127.0.0.1:6661"). In this case you'll have to kill the running process (pkill nodejs on Linux), then start it as above.

If the service starts OK at the command-line, then try a CCDA export in OpenEMR while it is running and look for messages displayed at the command-line.