This section contains topic relevant to setting up the system.
Note that if you do edit Administration|Organisation items (say to change an email address), then the new values will not become available until the next time you log on (because these organisation settings are fetched once at logon time to improve performance).
To get email to work you need to do the following:
Use Administration|Organisation|Mail Server to define at least one Mail Server by setting the various parameters (ie Mail Host, Port, Username, Password, and Connection Security).
For the Practice, set the default mail server. This is used if one is not set for a Practice Location, and is also used by the email-to-SMS gateway.
If a Practice Location needs its own Mail Server record, define one for it, and set this for the Practice Location. You may want to do this for situations where you are sending mail from a gmail address specific to the location, and you want to use the gmail smtp server for this gmail address (so that gmail does not raise warning flags).
Then define the Email contact(s), and if appropriate, add different ones for each applicable purpose (eg Billing, Correspondence, Reminder). Note that you can set the Email contacts at either the Practice or Location level. If you set them at the Location level, these will be used in preference to the those set at the Practice level.
If you are having problems, you can enable debugging by editing the mailSender bean in :
$TOMCAT_HOME/webapps/openvpms/WEB-INF/openvpms-web-app.xml
Change
<bean id="mailSender" class="org.openvpms.web.component.service.MailService" scope="prototype"/>
to
<bean id="mailSender" class="org.openvpms.web.component.service.MailService" scope="prototype">
<property name="javaMailProperties">
<props>
<prop key="mail.smtp.debug">true</prop>
</props>
</property>
</bean>
You can then look in the log at $TOMCAT_HOME/openvpms.log for the debug output.
You may want to run multiple OpenVPMS systems hosted in the one server, either for test and production systems, or in cases where multiple practices share the same server.
Note that if you are running multiple systems, it is important that you do not get confused about which system you are using. You can use a different screen colour for each system (see here for how to do this). You should also use different user login names and passwords (so as to prevent an unthinking person signing in to the wrong system). You should also set different database user names and passwords for each system.
One way to run multiple systems is of course to run each in its own virtual machine with these hosted on the one piece of hardware.
However, you can also host multiple systems on the one server. (Note however that if you use the ESCI facility, then you cannot host multiple systems on the one server.) The way to set this up is as follows:
1. install the first system as per the instructions in the readme.txt file.
2. for the next OpenVPMS system, install the OpenVPMS software in its own folder/directory, now referred to as <OPENVPMS_HOME_X>
3. the database access is defined in the file <OPENVPMS_HOME_X>/conf/hibernate.properties, specifically the three lines
hibernate.connection.url=jdbc:mysql://localhost:3306/openvpms
hibernate.connection.username=openvpms
hibernate.connection.password=openvpms
Hence for this OpenVPMS system we need to change the database name in the first line from openvpms to say openvpmsX. The user name and password should be changed to say openvpmsU and openvpmsP to decrease the likelihood of you getting confused and doing database operations on the wrong database.
To create the database, we need to edit the file <OPENVPMS_HOME_X>/db/create.sql so it reads as follows:
# # Script to create the openvpmsX database, and add a single user 'openvpms', # with all privileges # CREATE DATABASE `openvpmsX` /*!40100 DEFAULT CHARACTER SET utf8 */; GRANT ALL PRIVILEGES ON openvpmsX.* TO 'openvpmsU'@'localhost' IDENTIFIED BY 'openvpmsP' WITH GRANT OPTION; GRANT ALL PRIVILEGES ON openvpmsX.* TO 'openvpmsU'@'%' IDENTIFIED BY 'openvpmsP' WITH GRANT OPTION; COMMIT;
where "openvmsX" is the name of the new database, "openvpmsU" the user name, and "openvpmsP" the password. You can now create the database as per the readme.txt, ie do
> cd <OPENVPMS_HOME_X>/db
> mysql -u admin -p < createdb.sql
You can now populate the database as per the readme.txt steps, or you can simply dump the contents of the base openvpms database, and then restore this into the new openvpmsX database.
4. Finally we need to set up the Tomcat application. The easiest way to do this is to first copy the <TOMCAT_HOME>/webapps/openvpms directory to <TOMCAT_HOME>/webapps/openvpmsX. You then need to edit two files as follows:
a) in <TOMCAT_HOME>/webapps/openvpmsX/WEB-INF/web.xml, the webAppRootKey value needs to be set to "openvpmsX" as per the following
<!-- Needed by spring if you want to deploy app more than once as different name. Change value - to something unique --> <context-param> <param-name>webAppRootKey</param-name> <param-value>openvpmsX</param-value> </context-param>
b) edit <TOMCAT_HOME>/webapps/openvpmsX/WEB-INF/classes/hibernate.properties so it matches <OPENVPMS_HOME_X>/conf/hibernate.properties - see step 3 above.
Now restart Tomcat and you can then access the new system at http://localhost:8080/openvpmsX/app
5. Repeat steps 2-4 for each addition system that you require.
While most of the country dependent settings (such as tax and currency) can be set within the application itself (for example via Administration|Lookups|Country and Administration|Organisation|Practice), some setup needs to be done outside the application. This section documents the available adjustments.
If you use Rabies Tags in your country/jurisdiction, you will need to enable them. You will need to modify the party.patientPet archetype. The best way to do this is to modify the file party.patientpet.adl and then use Administration|Archetypes to import the modified version. This file is located in <OpenVPMS-Home>update\archetypes\org\openvpms\archetype\patient. You should of course save the modified file in a different place. Change the lines
<!-- For jurisdictions that use rabies tags, uncomment the following -->
<!--
<propertyMap name="archetype">
<property name="shortName" value="entityIdentity.rabiesTag"/>
</propertyMap>
-->to
<!-- For we use rabies tags -->
<propertyMap name="archetype">
<property name="shortName" value="entityIdentity.rabiesTag"/>
</propertyMap>
Pet Tags are enabled in the standard release. If you do not use these in your country/jurisdiction, you can do the opposite of the above - ie comment out the pet tags, ie change
<propertyMap name="archetype">
<property name="shortName"
value="entityIdentity.petTag"/>
</propertyMap>to
<!-- suppress pet tags
<propertyMap name="archetype">
<property name="shortName"
value="entityIdentity.petTag"/>
</propertyMap>
-->
Warning - this requires appropriate technical skills.
There are two ways of adjusting the propercasing facility: modifying the appropriate archetype to turn it off for a specific field; and editing the properties file. For the first, modify the appropriate node in the archetype to remove the propercase Assertion Descriptor. For the second, proceed as follows.
If you want to adjust how propercasing is performed on various words, you need to edit (after saving a copy) the file propercase.properties in the folder <TOMCAT HOME>\webapps\openvpms\WEB-INF\classes\localisation
Each line of the file has the format <keyword>.N = <string> where <keyword> is one of the keywords shown in the table below, N is a digit or digits, and <string> is the propercase version the string.
| Keyword | Meaning | Examples |
|---|---|---|
| space | Strings that must appear surround by spaces. | space.1 = & |
| spaceBefore | Strings that must appear with a space before them. | spaceBefore.1 = ( |
| spaceAfter | Strings that must appear with a space after them. | spaceAfter.1 = ) spaceAfter.2 = . |
| exceptions | Strings that are to be cased as given ignoring other case rules. |
exceptions.1 = von |
| startsWith | Strings that must appear with the specified case at the start of a word. Where they appear, they force capitalisation of the next character in the word. | startsWith.1 = Mac startsWith.2 = Mc startsWith.3 = d' startsWith.4 = ( startsWith.5 = ` startsWith.6 = " |
| contains | Strings that must appear with the specified case anywhere in a word. Where they appear, they force capitalisation of the next character in the word. | contains.1 = - contains.2 = ' contains.3 = 0 contains.4 = 1 contains.5 = 2 contains.6 = 3 etc for each digit |
| endsWith | Strings that must appear with the specified case at the end of a word. | endsWith.1 = 's |
Hence the "startsWith.1 = Mac" would force Macaw to MacAw but for the "exceptions.153 = Macaw".
Note that you can functionally 'comment out' an entry by adding a leading # (or any other character) because this changes the key from say 'startsWith' to '#startsWith' which will not be recognised and will be ignored.
OpenVPMS supports SMS via provider-specific plugins, or using email-to-SMS gateways.
A plugin is included for Clickatell that enables SMS statuses to be tracked. This requires:
Clickatell accounts can be obtained at https://www.clickatell.com/sign-up/
To create a Clickatell REST API:
NOTE: Two-way messaging can be enabled but the plugin is unable to receive replies.
Plugin support is provided in Administration - System - Plugins.
See the corresponding help for instructions on enabling plugins.
To install the plugin:
To configure the plugin:
A description of the remaining fields is available at Administration - Organisation - Clickatell.
For email-to-SMS gateways, the Practice must be configured with a Mail Server.
This Mail Server should not be configured to add footers to outgoing emails, as they may be appended to SMS messages. This can:
Having done that you can proceed with the SMS setup discussed below.
Two email-to-SMS gateways are supported out of the box:
To sign up, go to: https://www.smsglobal.com/mxt-sign-up/
SMSGlobal allows you to send a small number of test messages for free after you register.
Now use Administration - Organisation - SMS Configuration: SMSGlobal Email2SMS
Clickatell allows you to send a small number of test messages for free after you register but sends a preformatted SMS until you pay.
To sign up:
After signing up, logon and click the 'Manage My Products' tab. Then click 'SMTP [Email to SMS]' link the click "Submit and Get API ID". The API ID is needed when configuring OpenVPMS.
Now use Administration - Organisation - SMS Configuration: Clickatell SMTP Connection
If you want to use another provider, then you should be able to do so using the Generic Gateway. You will need some knowledge of the gateway message format requirements and xpath expressions.
See Administration - Organisation - SMS Configuration: Generic Email Gateway
The SMSGlobal and Clickatell configuration screens hide the underlying detail, and indeed it is possible to configure an SMSGlobal or Clickatell gateway using the Generic configuration screens. Similarly, it is possible to create a tailored screen for another vendor. If you want to do this see here.
Once configured, these must be linked to the practice:
This page discusses the problems of localisation.
Time
The time in OpenVPMS is set from the time in the 'server' machine - ie the one running the MySQL database and Tomcat application. If the user and the server are all in the same timezone, then there is no problem.
However, if you are using a hosting service somewhere else, then it may be necessary to set the server time to match the local time where your users are. [For example the OpenVPMS demo system runs on a server with its time set to GMT. If you log onto this from say Sydney, then early in the day you will find that 'today' on the server (and thus the default date on invoices you create) will be yesterday your time because GMT is 10 hours behind AEST.]
If you have users spread across multiple timezones, then you will need to educate those in the 'non-home' time zones that theirs will be different. Thus if you have a practice spread across the NSW/Queensland border but with headquarters in NSW, in summer your Surfers Paradise branch will be running an hour behind. In this case you probably want to run the appointment schedule for the Surfers branch on local time, but the timestamps on any activity will be NSW, not Queensland time.
Date Format
The date format used is set in the <TOMCAT_HOME>/webapps/openvpms/WEB-INF/classes/localisation/messages.properties file (or the local version - see Language below).
Specifically, if you need to use say a US date format, then you need to adjust the settings in this file. Note that as well as the date formats, you can also adjust the numeric formats if needed.
Note that messages.properties settings affect the display on the screen. See below for Reports and Documents.
Language
OpenVPMS uses standard java i18n support so if you name your message properties file according to your locale settings, eg messages_fr.properties for France, then it will be used instead of the standard messages.properties.
Note that you can do minor language tweaks by editing the message.properties file. For example if you think that Organisation should really be Organization then you can change it here. [Though it would be better to create a message.properties-us file which includes both the spelling adjustments and the mm/dd/yy date formats.]
Reports and Documents
The standard reports and documents that are generated from Document Templates using JasperReports based content have been written to be locale sensitive for both dates and currencies. The locale used is that set for the user running the Tomcat application.
The letters and forms which use Open Office based content are not locale sensitive. The format of dates is as follows: