4.1.2.2 Oscar Fax Service

Preface

These instructions are to help you install the OSCAR Fax Web Service. 

Document Version History

• v1.0 – initial version based on documentation from Randy Jonasz published to oscarmanual.org – Mar 3, 2016

 copyright 2014-2016

Fax Web Service

A new and more robust interface for OSCAR faxing has been implemented for OSCAR 14 and subsequent versions.  The administrative part of OSCAR records the faxes sent and stores them for viewing and review.  The Fax Webservice asynchronously connects OSCAR with the Hylafax server pushing and pulling faxes into the inbox que and out to be faxed as appropriate. The actual receipt and sending of faxes is done by either Hylafax or Hylafax + on the local machine or a remote one that has the appropriate fax modem and a telephone connection.

Hylafax

1) Install Hylafax and configure it to work with your modem(s)

sudo apt-get install hylafax-server

2) For each modem and group that receives faxes in OSCAR, create a user on the Hylafax server. It does not need to be on the same server as OSCAR.

sudo adduser -disabled-login -no-create-home teamA

Each user will be the group owner of incoming faxes and the names must match the fax users you create.

3) Create Hylafax users using faxadduser. Remember to name the users the same as the users you created in step 2.

4) Create a FaxDispatch file. You need to specify the modem device id(s) and user id(s) you created above in step 2.  An example is found below.

## and/or by device
FILETYPE=pdf

case "$DEVICE" in
teamA)  
	sudo /bin/chgrp 1001 $FILE	#Team A faxes
	chmod g+rw $FILE		#Make readable
;;

teamB)  
	sudo /bin/chgrp 1002 $FILE	#Team B faxes
	chmod g+rw $FILE		#Make readable
;;
esac

Copy FaxDispatch to /etc/hylafax.

If you are using a usb modem you can write a udev rule to always name a usb slot a particular name. In effect you are creating an alias which hylafax can then use to communicate with the modem. An example is found below. Do not use this example unedited as the subsystem ids will be different on your computer. 

SUBSYSTEMS=="usb", KERNELS=="3-1:2.0", SYMLINK+="teamB"

SUBSYSTEMS=="usb", KERNELS=="3-2:2.0", SYMLINK+="teamA"

Copy the udev rule you created to /etc/udev/rules.d

4a) In some instances you may need to add the following directive to /etc/sudoers 

uucp ALL=(root) NOPASSWD: /bin/chgrp

This line will enable uucp to run chgrp via the sudo command with root permissions, thus enabling FaxDispatch to successfully change the owner of the fax files received.

Fax Web Service

5) Install tomcat6 and Oracle Java 7 on the server which will host the web service. This does not need to be the same server as OSCAR or Hylafax. Configure tomcat to accept https connections only and use BASIC authentication. Therefore the connection from OSCAR to the web service is encrypted and requires a user to log in before accessing the service. Remember the user and password you set up for step 12.

6) Export the public ssl key from OSCAR's tomcat and import it into the java trusted keystore of the web service's installation server. THIS STEP NEEDS TO BE DONE EVEN IF THEY ALL RUN ON THE SAME SERVER.

7) Clone the project FaxWS from gerrit using git and make sure maven2 is installed. 

git clone ssh://xxxx@source.oscartools.org:29418/FaxWS

Edit the file faxProperties.properties to suit your setup. The file is documented.

7a) Run setup.sh as root.  You will setup credentials to be able to login to the webservice.  You will first be asked existing credentials for mysql.  Remember these as the build process will quickly overtake the screen buffer.

$ sudo setup.sh
Mysql database username? root
password? ******
Changing context.xml using your parameters
Creating jdbc authentication database
Creating user and user_role tables
What username do you want to log in as in tomcat? [NEWusername]
What password do want for peter? [NEWpassword]

 and then copy the war file to tomcat's webapps directory 

sudo cp target/FaxWs-1.0.0-SNAPSHOT.war /var/lib/tomcat7/webapps/FaxWs.war

OSCAR Settings

8) In OSCAR's properties file ensure that the following properties are set

ModuleNames=Fax
#FAX
faxPollInterval=60000
consultation_fax_enabled=true
rx_fax_enabled=true
consultation_indivica_attachment_enabled=true

The poll interview is in milliseconds.  It specifies the interval between instances of polling the web service for new faxes and sending pending faxes. A class 3 fax typically takes about 15 s/page (plus fax protocol entraining) to receive or send so more freqent polling is not necessary.

9) All faxes are stored in the DOCUMENT_DIR as specified in OSCAR's properties file.

10) In OSCAR's admin interface fill out Clinic name and address. This is used for the cover page if selected.

11) In OSCAR's admin interface edit the facility and select store signatures in db. This will preserve the signature for specific consults and prescriptions. If not selected the signature will not display. Each signature is only valid once.

12) In OSCAR's admin interface, click on Add New Queue. For each group that receives faxes create a named queue which will be used to access received faxes in the Inbox.

13) In OSCAR's admin interface, assign all privileges to the user(s) via Assign role/Rights to Object for the people who will need access to the newly created queues.

13) In OSCAR's admin interface, select System Management and click on Configure Fax. Enter the Web Service address as https://192.168.11.100/FaxWs. Change the ip address to suit your setup.

Enter the Site user and password you created for tomcat in step 5.

For each user you created in hylafax, enter the username(s) and password(s) and select the desired queue in which to receive faxes for that user.

Save your settings.

14) To access the queues you created in step 12, open the inbox and click on Pending Docs at the top.

15) To manage faxes, in OSCAR's admin click on System Administration and Manage Fax. From here the user can see which faxes failed, are in progress or completed and received. You can view the fax, cancel in progress faxes and resend failed faxes.

16) Start hylafax, the FaxWS and restart OSCAR. You should now have a working fax system in OSCAR.

17) For accounting purposes it is useful if the sender of a fax selects the proper fax line named after the users entered in step 13. To keep things simple, use the same names for linux user names, hylafax user names and queues.