Setup & configure Terminology Server

Owned by Angshuman Sarkar
Last updated: Oct 14, 2015
3 min read

Once you have deployed the Terminology Server/Registry (TR), there are few things you have to do manually.

  • Setup - access http://<hostname>/openmrs  which will take you through the initial setup. Follow the "advanced options" steps. Note, that in vagrant setup, TR is hosted at http://<ipaddress>:9080/openmrs
    • Installation wizard: step 1
      • choose "yes" for "Do you currently have an OpenMRS database installed .... ?" enter database name "terminologies".
    • Installation wizard: step 2
      • choose "yes" for "Do you need OpenMRS to automatically create the tables ... ?" 
      • choose "no" for "Do you want to also add demo data to your database.... ?"
      • choose "Yes" for "Do you currently have a database user other than root .... ?".  By default, a username "terminologies" would be already filled in for the username.
        • Alternatively, you may create a different user with read/write permission to the "terminologies" database from mysql command prompt. 
    • Installation wizard: step 3
      • Do you want updates to the database to be automatically applied on startup when a new web application is deployed? - YES
    • Installation wizard: step 4
      • choose a password for "admin" user. note this down.

    • Installation wizard: skip step 5, optionally fill in details

    • review installation instructions and proceed. The wizard should "create openmrs tables", "Add OpenMRS core data" and "Update the database" before redirecting you to the login page.

    Troubleshooting

    In some cases, we have seen OpenMRS throwing up error while upgrading and applying additional changes post installation step, in the "The following database updates are required:" screen. A restart of the service service solves the problem, provided in the step 3 of the installation, you mentioned to automatically apply changes on startup.

  • Additional setup for TR to broadcast information to HIE systems. Not needed if you have deployed using ansible or vagrant or using the Go server, then all these are automated already.
    • You have to deploy 3 additional 'OpenMRS' modules to get TR serving APIs for other systems
      • webservices-rest-2.12.omod. You can download the omod from here
      • openmrs-atomfeed-2.5.0.omod. You can download the jar from here and rename the extension to ".omod"
      • freeshr-terminology-feed-1.0.omod. This can be downloaded from sharedhealth Go server.
      • These 3 omods need to be placed in OpenMRS "modules" directory of the TR installation.
      • Restart TR server. 
      • Verify that the modules are loaded properly by going to menu->administration->modules.

  • Configuration
    • Go to menu->administration->settings->Webservices. Enter the "Rest Uri Prefix" value as you want them to be exposed. example: http://tr.sharedhealth.org/openmrs
    • Go to menu->administration->schedulers. Reset "OpenMRS event publisher task" to run at 2 minutes interval (default is 2 sec!). This is the scheduler that publishes the events of any terminology modifications. 
    • Although the TR information is meant to be public, administration and API accesses should be limited. Hence you should create a public user account which you can share with others. To do this
      • Go to menu->administration->manage users and create a user with username/password. example: trapiuser/Trapiuser123.
        • Note, this is the default credentials with which development versions of SHR connect to TR.
      • assign the above user the role "TR API CONSUMER". This role has very restricted access but allows API Clients to access relevant data. 
      • TR API CONSUMER role should be configured with the following permissions

        • View Concept Classes

        • View Concept Datatypes

        • View Concept Sources

        • Get Concept Reference Terms

        • View Concepts

        • Get Concepts

        • View RESTWS

    • Setup languages
      • Go to menu->administration->settings>locale. Set list of languages in 'allowd list' to en,bn
      • If you want to search by another language, you need to setup your profile preferences. You can do this my clicking "My Profile" link in the top right. Change 'Default Locale' to 'English (US)' and change prefererred locale to 'bn' or so.
    • Create the following privileges in OpenMRS.
      • Add Concepts
      • Edit Concepts
      • Delete Concepts
    • Create a role TR_ADMIN with the below privileges

      1. Add Concept Proposals

      2. Add Concepts        

      3. Add People

      4. Add Users 

      5. Delete Concept Proposals      

      6. Delete Concepts     

      7. Delete People       

      8. Delete Users        

      9. Edit Concept Proposals        

      10. Edit Concepts       

      11. Edit People

      12. Edit User Passwords 

      13. Edit Users

      14. Form Entry

      15. Get Concept Classes 

      16. Get Concept Datatypes

      17. Get Concept Map Types

      18. Get Concept Proposals

      19. Get Concept Reference Terms   

      20. Get Concept Sources 

      21. Get Concepts        

      22. Manage Alerts       

      23. Manage Concept Classes        

      24. Manage Concept Datatypes      

      25. Manage Concept Map Types      

      26. Manage Concept Name tags      

      27. Manage Concept Reference Terms

      28. Manage Concept Sources        

      29. Manage Concept Stop Words     

      30. Manage Concepts     

      31. Manage HL7 Messages 

      32. Manage Implementation Id      

      33. View Administration Functions 

      34. View Concept Classes

      35. View Concept Datatypes        

      36. View Concept Proposals        

      37. View Concept Sources

      38. View Concepts       

      39. View Forms

      40. View Navigation Menu

      41. View Observations   

      42. View People

      43. View Privileges     

      44. View Problems       

      45. View RESTWS

      46. View Roles

      47. View Users

  • Manual steps to add concepts -
    • Concept drugs corresponding to concepts (of class drug) needs to be set up. 
    • Valueset for Dosage forms (medication form)  needs to be set up. (Create few forms first - Syrup, Tablet, Pill, Powder etc. Class is Misc, datatype is N/A. Now create a concept with class - valueset and dataype - Coded and add the forms as answers to it).
      • Add answers manually for PNC Number (First, second, Third, four or more).
    • Add answers manually for "Delivered by" (Doctor, Nurse, Midwife, FWA, FWV, HA, CHCP, CSBA, Others)
    • Add answers manually to "Urine albumin" & "Urine sugar" (positive and negative)
  • List of valuesets to be created in TR - 
    • Units of time
    • Quantity units
    • Route of administration
    • Immunization reason
    • No Immunization reason
    • Relationship type
    • Encounter type
    • Medication form