CohortBuilder

This repository contains the CohortBuilder OpenMRS Open Web App.

The cohort-builder open web app module, is an OpenMRS tool used to create Ad-hoc reports. I.e build a cohort of patients based on the similarities between the patients.

For further documentation about OpenMRS Open Web Apps see the wiki page.

For further documentation about the cohort builder open web app module see the wiki page.

Getting Started

Local Setup Instructions

# Get the project
git clone https://github.com/openmrs/openmrs-owa-cohortbuilder.git

# Move into the project directory
cd openmrs-owa-cohortbuilder

# Install the dependencies
npm install

# Copy the webpack configuration from webpack.config.sample.js to webpack.config.js
cp webpack.config.sample.js webpack.config.js

# Locate the 'appdata/owa' directory and type the following command to get the path to the 'appdata/owa' directory and copy it to the clipboard.
pwd | pbcopy

An example of the path is: /Users/andeladeveloper/Downloads/referenceapplication-standalone-2.6.0/appdata/owa/

# Open the webpack.config.js file, locate the getConfig function and update the config object with the following
{
  "LOCAL_OWA_FOLDER": "PASTE_THE_PATH_YOU_COPIED_HERE",
  "APP_ENTRY_POINT": "http://localhost:8081/openmrs-standalone/owa/cohortbuilder/index.html"
}

Note: Start your cohort builder standalone server locally. Make sure you tomcat port is 8081, if not, change the APP_ENTRY_POINT localhost port to be the same as your tomcat port.

# Run the app
npm run watch

Adding the cohort builder link to the reference application

When on Reference Application Menu, enter `System Administration` -> `Manage Apps` -> `Add App Definition` and input following text inside:

{
    "id": "YOUR_OPENMRS_ID_HERE",
    "description": "A modern refresh of the OpenMRS Cohort Builder tool",
    "order": 0,
    "extensions": [
        {
            "id": "demoapp.homepageLink",
            "extensionPointId": "org.openmrs.referenceapplication.homepageLink",
            "type": "link",
            "label": "Cohort Builder",
            "url": "owa/cohortbuilder/index.html",
            "icon": "icon-list-alt",
        }
    ]
}

Save changes, now cohort builder OWA is visible at the homepage

For further documentation about adding the cohort builder link to the reference application the wiki page.

Development

Production Build

You will need NodeJS 4+ installed to do this. See the install instructions here.

Once you have NodeJS installed, install the dependencies (first time only):

npm install

Build the distributable using Webpack as follows:

npm run build:prod

This will create a file called cohortbuilder.zip file in the dist directory, which can be uploaded to the OpenMRS Open Web Apps module.

Local Deploy

To deploy directly to your local Open Web Apps directory, run:

npm run build:deploy

This will build and deploy the app to the /home/sims01/openmrs/openmrs-server/owa directory. To change the deploy directory, edit the LOCAL_OWA_FOLDER entry in config.json. If this file does not exists, create one in the root directory that looks like:

{
  "LOCAL_OWA_FOLDER": "/home/sims01/openmrs/openmrs-server/owa"
}

Live Reload

To use Browersync to watch your files and reload the page, inject CSS or synchronize user actions across browser instances, you will need the APP_ENTRY_POINT entry in your config.json file:

{
  "LOCAL_OWA_FOLDER": "/home/sims01/openmrs/openmrs-server/owa",
  "APP_ENTRY_POINT": "http://localhost:8080/openmrs/owa/cohortbuilder/index.html"
}

Run Browsersync as follows:

npm run watch

Extending

Install npm packages dependencies as follows:

npm install --save <package>

To use the installed package, import it as follows:

//import and assign to variable
import variableName from 'package';

To contain package in vendor bundle, remember to add it to vendor entry point array, eg.:

entry: {
  app : `${__dirname}/app/js/owa.js`,
  css: `${__dirname}/app/css/owa.css`,
  vendor : [
    'package',
    ...//other packages in vendor bundle
  ]
},

Any files that you add manually must be added in the app directory.

Troubleshooting

HTTP access control (CORS)

You may experience problems due to the Access-Control-Allow-Origin header not being set by OpenMRS. To fix this you'll need to enable Cross-Origin Resource Sharing in Tomcat.

See instructions here for Tomcat 7 and here for Tomcat 6.

Releasing

In order to release, set a new version in package.json, bintray.json and app/manifest.webapp. Once you commit and push changes to github, go to https://github.com/openmrs/openmrs-owa-cohortbuilder/releases and create a new release named after the version you want to release. Travis CI should pick up a newly created tag and deploy the release to Bintray at https://bintray.com/openmrs/owa/openmrs-owa-cohortbuilder

Issues

If you want help fix existing issues or you found a bug and want to tell us please go to the Cohort Builder issues page.

Community

Support

Ask questions on OpenMRS Talk.

License

MPL 2.0 w/ HD © OpenMRS Inc.