Download epiCentre_UserManual_ITAdministrators

epiCentre User Manual
Information for IT Administratorsv1.1
Nicolas Fenwick and David Webster, August 2013
Reviewed by Nicolas Fenwick, October 2013
epiCentre User Manual – Information for IT Administrators – v1.1
1
Contents
Introduction ............................................................................................................................................ 3
Supported Database Platform ................................................................................................................. 4
Requirement: SQL Port 1433 Open ..................................................................................................... 4
Requirement: SQL Server configured to allow SQL Login Authentication .......................................... 4
Creating and configuring the epiCentre Database .................................................................................. 4
Database and Settings Security ............................................................................................................... 4
SQL Logins ........................................................................................................................................... 4
Encryption ........................................................................................................................................... 5
RedCap Security ...................................................................................................................................... 5
Communication between RedCap and epiCentre ............................................................................... 6
RedCap Tokens .................................................................................................................................... 6
Installing and Configuring epiCentre....................................................................................................... 6
Pre-requisites ...................................................................................................................................... 6
Installing the epiCentre Application ................................................................................................ 8
Configuring epiCentre ......................................................................................................................... 8
Database Configuration Wizard ...................................................................................................... 9
Finally ............................................................................................................................................ 14
Configuring an epiCentre Client ........................................................................................................ 15
Client Configuration Wizard .......................................................................................................... 15
Step 1: Database Connection ........................................................................................................ 16
Step 2: Proxy Server ...................................................................................................................... 16
Congratulations ................................................................................................................................. 16
epiCentre User Manual – Information for IT Administrators – v1.1
2
Introduction
Welcome to epiCentre! epiCentre is the software for entering and managing data relating to ePPOC
(the electronic Persistent Pain Outcomes Collaboration).
ePPOC is a program whose purpose is to provide outcomes based benchmark reporting for pain
management clinics throughout Australasia. It involves a development of a standardised dataset,
data collection protocol and regular submissions of de-identified data for analysis and reporting.
As the software at the heart of ePPOC, epiCentre provides an easy-to-use way of collecting data
which conforms to the ePPOC dataset. In the ePPOC dataset, there are really two types of data
collection: clinician provided data and patient reported outcomes. In order to create a flexible
solution epiCentre is integrated with an online data collection tool called ‘REDCap’.
REDCap is written and maintained by Vanderbuilt University in Tennessee, USA and is an online
survey tool. REDCap is hosted on a web server in a secure data centre at University of Wollongong.
epiCentre is able to create instances of these questionnaires on the REDCap server, and to
automatically synchronise the data between REDCap and your hospitals epiCentre database. This
integration has been implemented in such a way that REDCap never stores, or even sees, any
identifiable data about the patient.
The “Information for IT Administrators” booklet is dedicated to the IT specialist in which facility
who wish to learn more about epiCentre, its system requirements, security specifications as well as
its installation process.
epiCentre User Manual – Information for IT Administrators – v1.1
3
Supported Database Platform
epiCentre uses the industry standard database server SQL Server 2008. It supports SQL Server 2008,
SQL Server 2008 R2 and SQL Server Express 2008. This software is not included with the epiCentre.
For small installations or where your facility has limited IT resources, SQL Server Express will be the
best option because it is free. You will be able to install SQL Server Express and the epiCentre
program on the same machine if necessary.
Requirement: SQL Port 1433 Open
epiCentre requires that all client machines running the client application are able to communicate
directly with the database server. This means the SQL Server port (1433) must be available between
the database server and the computers running the epiCentre client.
Requirement: SQL Server configured to allow SQL Login Authentication
epiCentre also requires that your SQL Server is configured to allow SQL Logins (as opposed to
Windows Authentication). Mixed mode authentication will also work, but epiCentre uses SQL Logins
to connect to the server.
Creating and configuring the epiCentre Database
epiCentre has a built-in database configuration wizard for creating and configuring the epiCentre
database in order to streamline the installation process. The installation package also includes the
SQL Scripts for creating the database, SQL Server logins, tables and structural table data which you
can modify and run manually if you prefer.
By far the simplest approach is to use the configuration wizard which allows you to specify your own
SQL database name, SQL logins and passwords and an encryption key specific to your facility. This
ensures that the configuration of the database at your site will be able to comply with your own
naming standards and password security policies. The configuration wizard takes less than 10
minutes run, including data entry time. This process is described later under the section Installing
and Configuring epiCentre.
Database and Settings Security
SQL Logins
As already mentioned epiCentre uses SQL Logins to authenticate to the database. It requires 3 logins
to exist, and they are created and mapped to database users in the epiCentre database by the
configuration wizard. The next table describes the logins, their purpose and the user roles which use
them (user roles are explained in the next section – Application Level Security)
Login Name
Example
SQL Server Database Roles
{prefix}_dbo
{prefix}_user
eppoc_dbo
eppoc_user
{prefix}_reader
eppoc_reader
dbo
db_datareader
db_datawriter
db_datareader
User Roles
(Application)
Administrator
Manager
User
Reader
The purpose of having different levels of users access the database with different SQL Logins is to add
security. It makes it literally impossible for a user logged in with the Application Role of ‘Reader’ to
epiCentre User Manual – Information for IT Administrators – v1.1
4
alter data, and ensures that only a user logged with the Application Role of ‘Administrator’ could
ever make changes to database structure. It also means that from the outset, the business engine of
epiCentre is designed to be able to be used safely by both a Windows Application and potentially in
the future, a web application.
Encryption
All identifying data in epiCentre is encrypted in the database. The data dictionary identifies which
fields are regarded as ‘identifying’, examples include First Name and Family Name. Additionally user
passwords are encrypted in the database, meaning it is safe for users to use a password that they use
for other systems.
As part of the epiCentre configuration wizard, each client is asked for an encryption key. This
encryption key is used for all database encryption. Every client at a facility must be configured with
the same encryption key so that they can encrypt and decrypt the data in a common fashion. The
benefit of having a unique encryption key for each facility is that it makes the identifiable data in the
database completely un-decryptable to anyone who doesn’t have this key. A facility could safely
hand a full copy of their database back to UOW staff without fear of identifiable data being
compromised. Additionally, should the database server itself be compromised the identifiable data
is secured.
epiCentre stores connection information for client machines in a local settings file. This file stores
the database server name, SQL Login names, SQL Logins passwords and the encryption key. The
security-critical items in this file (SQL passwords and the encryption key itself) are encrypted with a
constant encryption key. This means that people with access to the file system on client machines
will not have access to SQL Login passwords or the ‘identifiable data encryption key’.
RedCap Security
The RedCap server is operated by the University of Wollongong. It is a virtual machine running
Windows Server 2008 R2 and housed in a secure data warehouse. Only university systems admin
staff and ePPOC IT staff have direct access to this server in any way.
RedCap is a PHP application which is running on Apache. It uses a MySQL database also running on
the RedCap server. Apache, PHP and MySQL are the latest versions as of August 2013. At present
only ePPOC IT staff have the necessary passwords for accessing the MySQL data, though at times it
may be necessary for central IT staff to access this database.
The server is operating a fully certified SSL certificate for the domain name:
https://eppoc.ahsri.uow.edu.au. All communications between RedCap and epiCentre are run over
HTTPS. The questionnaires are also run over HTTPS.
No identifiable data is ever kept or transferred via the RedCap server and so even though UOW hosts
the database and application for RedCap, Patient confidentiality is never at any risk. When epiCentre
requests a questionnaire it sends an API call to RedCap, and RedCap responds with a link which a
patient can follow to the questionnaire. This link data is stored in the epiCentre database at your
facility so it is not possible to re-link the questionnaire data to a patient without access to the
Facilities local epiCentre database. The point being, although UOW is hosting the RedCap database,
it essentially exists as a collection of records disconnected from any data which could identify the
patients who complete the questionnaire.
epiCentre User Manual – Information for IT Administrators – v1.1
5
RedCap does not perform any kind of data encryption in its database, and does not need to because
all data is de-identified.
Communication between RedCap and epiCentre
When a questionnaire is requested via the RedCap API by epiCentre, a record is created in RedCap
and an email containing a link URL is sent to a specified email address at the Facility which requested
the questionnaire. The link url is of the format:
https://eppoc.ahsri.uow.edu/redcap/survey/?s=<unique_code>
Additionally, this link is return by the API call and stored against that questionnaire record in
epiCentre, meaning that a user can access the data entry directly from epiCentre. Following this link
opens the Questionnaire in RedCap, allowing either the patient or the hospital staff member to enter
the patient’s questionnaire responses.
epiCentre uses the details returned by the API call to request the data from completed
questionnaires. When a questionnaire has been completed, the data is synchronised and stored in
the epiCentre database. The relevant status fields for the questionnaire are also updated.
RedCap Tokens
Every facility which uses epiCentre will have its own set of ‘tokens’ which enable epiCentre to
communicate with RedCap to create questionnaires, and to receive the data from questionnaire
responses. Using individual tokens for each facility means that facilities will not be able to request
each other’s data by any means (including by forging data in Questionnaire records in epiCentre)
because in RedCap, the questionnaire record is effectively ‘owned’ by the user who owns the token
that created it.
This means that a unique token is required for each questionnaire that a facility uses. Adult Services
will use two questionnaires (Adult Initial and Adult Follow up). Paediatric Services will use 6
questionnaires (Parent, Adolescent and Child / Initial and Follow Up questionnaires). These tokens
will be provided by ePPOC technical staff to hospital IT staff as part of delivery of the epiCentre
product documentation.
Installing and Configuring epiCentre
Installation of epiCentre is intended to be simple and safe. As already mentioned the built in
database configuration wizard can create and configure the SQL database and logins for you with a
bare minimum of customisable data entry. Once the database configuration wizard has been run
once, the client configuration wizard can be run to connect a client machine to the epiCentre
database. Alternatively, the configuration wizards create a configuration file which can be deployed
to client machines, eliminating the need for running the client configuration wizard.
Pre-requisites
epiCentre uses the .NET Extended Framework v4. Testing indicates that most Windows XP and 7
machines do not have this framework pre-installed.
For reporting, epiCentre uses the Crystal Reports for Visual Studio 2010 runtime. Crystal Reports
requires that the Visual C++ 2005 SP1 32-bit Runtime and the ATL Security Update for Visual C++
2005 have been installed. All of these have been included in the distribution disk. The following
procedure should be followed to install the pre-requisites.
epiCentre User Manual – Information for IT Administrators – v1.1
6
Pre-Requisite Install Procedure
If preferred, pre-requisites should be able to be deployed automatically as there are no configuration
steps required by them. Some of the pre-requisites may already be installed on the client machine
and if so, the installer will inform you of this and you can move on to the next step. Depending on
which pre-requisites are required, and the speed of the client machine this procedure should take
between 5 and 15 minutes per client machine.
Note that epiCentre is a 32 bit application, as are all pre-requisites. This decision was made to allow
support for older Windows XP machines. epiCentre and its dependencies have been tested on
Windows XP (32 and 64 bit), Windows 7 (32 and 64 bit) and Windows 8 (64 bit).
All these steps should be performed by a user logged in to the computer with Administrator
privileges.
1. From the folder ‘1_NETFrameworkV4’ run the program ‘dotNetFx40_Full_x86_ia64.exe’ and
follow the prompts.
2. From the folder ‘2_VCRuntime’ run the program ‘vcredist.exe’ and follow the prompts. This
will install the Visual Studio C++ 2005 SP1 32-bit Runtime.
3. From the folder ‘3_ATLSecurityUpdate’ run the program ‘vcredist.exe’ and follow the
prompts. This will install the ATL Security Update for the Visual Studio 2005 SP1 32-bit
runtime.
4. From the folder ‘CrystalReports’ run the program ‘CRRuntime_32bit_13_0_4.msi’ and follow
the prompts.
epiCentre User Manual – Information for IT Administrators – v1.1
7
Installing the epiCentre Application
The epiCentre installer is very simple.
1. From the folder ‘epiCentre’ run the program ‘setup.exe’.
2. You will be prompted for an install folder. epiCentre will work when installed in ‘C:\Program
Files (x86)\ePPOC’ (the default) though we recommend considering installing to a folder like
‘C:\ePPOC\’. This creates the possibility that in the future non-administrator users could
apply updates to the software under the guidance of ePPOC staff without taking up valuable
hospital IT staff time.
3. You will be prompted for a folder in which to store the configuration file. This path should be
a location where ordinary users have read and write access. Again, we recommend
‘C:\ePPOC\’ however we have allowed this as a configuration option in order to support
different partitioning configurations, or even installation of the software and configuration to
a network drive.
Note that while in principle, installation to a network drive could work, the pre-requisites will still
need to be installed on each client machine.
Configuring epiCentre
When you run epiCentre for the first time on a machine you will be presented with a question:
Answering ‘Yes’ will start the Client Configuration Wizard. This wizard has two steps, detailed under
the heading ‘Installing an epiCentre Client’.
Answering ‘No’ will start the Database Configuration Wizard. This wizard has more steps and is
detailed in the following section. If you haven’t already created and configured the database, this is
the option you should choose.
epiCentre User Manual – Information for IT Administrators – v1.1
8
Database Configuration Wizard
The database configuration wizard has 6 simple steps, outlined below.
Step 1: System Administrator Connection
This form asks you to provide the following information.
-
-
Server name: the name of the machine running SQL Server on which you want to create the
database.
Database name: the name of the database you want to create on the SQL Server. The
default is ‘ahsri_eppoc’ but you can use any database name according to your own naming
conventions.
SA Username: the name of a SQL Server login which has ‘System Administrator’ priveleges
on the SQL Server. On a standard SQL Server installation, this user is called ‘sa’.
SA Password: the password for the SA username referred to above.
After entering these details, click ‘Next’. epiCentre will attempt to use these details to connect to
the SQL Server using the login details provided. If there is any problem with the information you’ve
entered, an error message will be displayed and the items causing the problem are highlighted.
If epiCentre is able to connect to the SQL Server using the login details provided, a message box
indicating success will be displayed and the wizard will move to the next step. Note that epiCentre
does not keep any record of the SA username and password you have entered on this screen, they
are simply used to establish the connection.
epiCentre User Manual – Information for IT Administrators – v1.1
9
Step 2: Creating and preparing the epiCentre Database
This form asks you to provide the following information:
-
-
-
Server name: the name of the machine running SQL Server on which you want to create the
database.
Database name: the name of the database you want to create. Note that these details are
actually repeated from the previous screen and you should not change them.
Username prefix: As described under the heading ‘Database and Settings Security’ epiCentre
relies on 3 SQL logins. So that you can conform to your own naming standards, epiCentre
asks for a prefix to use for these logins. The default is ‘ahsri_eppoc’ which will create logins
‘ahsri_eppoc_dbo’, ‘ahsri_eppoc_user’ and ‘ahsri_eppoc_reader’. You can use any prefix you
like which would result in a valid SQL login.
Dbo password, User password, Reader password: you may use the same password for all 3
logins or different passwords. For higher security we recommend using a different password
for each SQL login. For each password, there is a password and confirm password textbox.
Note that these passwords are encrypted before being saved in the configuration file,
ensuring your password security. Make a note of these passwords because you will need to
use them again in the ‘Client Configuration Wizard’. Ordinary users will never need to use or
know these passwords.
Database path: this is the path on the SQL Server (not on the client machine) where the
database .MDF and .LDF files will be created. The default is C:\ePPOC\ but you will probably
have a specific folder where SQL Database files are kept.
After entering these details, click ‘Next’. epiCentre will use the built-in database create SQL scripts
and the SA login details provided on the previous step to connect to the SQL Server and create the
epiCentre database.
Steps epiCentre uses to create and configure the database
The database is created and configured in 3 steps:
-
-
Create database and SQL logins: this is the step that is most likely to have an issue (such as
the ones described below). If it fails, the most likely outcome is that the database won’t be
created on the SQL Server. However, you should check on the SQL Server to see if the
database or logins were in fact created.
Create tables and database users: this step creates the data structures of the epiCentre
database in the database created by the previous step. If this first step succeeded it is highly
epiCentre User Manual – Information for IT Administrators – v1.1
10
-
unlikely there will be any problems with this step. It also creates the users with database
level roles based on the logins created by the previous step.
Create records: this step populates the tables created in the previous step with structural
records (constants, status lookups, and ePPOC codesets).
Potential Errors when trying to create and configure the database
If there were any problems with the data you entered, or with executing the database create scripts,
the items which caused the problem will be highlighted and/or an appropriate error message will be
displayed. A few errors you may encounter here:
-
-
-
Not entering matching passwords for dbo, user and reader SQL logins.
o epiCentre will catch this error, highlight the problem items and display an
appropriate error
Entering a database path that does not exist.
o If the path you enter in ‘Database path’ doesn’t exist, the create database script will
‘fail’ cleanly and report an error message. If it reports this error, correct the
database path and try again.
Entering a ‘user prefix’ that results in illegal login names.
o For example, if your prefix contained an illegal character, the create database script
will again ‘fail’ cleanly and report an error message. If it reports this error, correct
the user prefix and try again.
If you successfully created the database
If the create and configure step was successful a message will be displayed indicating success and
you will be moved to the next step. You should also check that the database and SQL logins were in
fact created on your SQL Server and that the .MDF and .LDF files were written to the expected
location. If you see any problem on the SQL Server, you should manually delete the database and
logins on SQL Server, click ‘Previous’ on the Wizard, and try again.
epiCentre User Manual – Information for IT Administrators – v1.1
11
Step 3: Database Connection
When using the Database Configuration Wizard this step is very simple. You have already told the
system the server, database name and user prefix so epiCentre has all the information it needs to
connect to the database. The only additional information you will need to provide is:
-
Encryption Key: this is your facility encryption key (see the heading ‘Encryption’ above for
more details. Its very important that you make a note of this encryption key because
without it the identifiable data recorded in the database cannot be decrypted. The
encryption key is itself encrypted before being written to the configuration file so you won’t
be able to inspect this file to find out what your encryption key was.
After you have entered the correct information for all the items on this screen, click ‘Next’.
epiCentre will check that it is able to connect to the database and if so, will move you to the next
step. If not, the problem item will be highlighted and an appropriate error message will be displayed.
Step 4: Proxy Settings
Many facilities machines require web requests to go through a proxy server. This screen provides an
opportunity to enter proxy server details. epiCentre uses web API requests to communicate to and
from RedCap which is why these details are required.
If your facility does not use a proxy server, you can leave the check box ‘Use a Proxy Server’
unchecked and all other items blank. If you facility does use a proxy server, you will need to check
epiCentre User Manual – Information for IT Administrators – v1.1
12
this box and enter the proxy server name (do not include ‘http’) e.g. if your proxy server is
‘http://proxy.uow.edu.au:8080’ you would enter
-
Proxy Server: proxy.uow.edu.au
Proxy Port: 8080
If your proxy server requires direct user authentication, you can provide your account details here.
Check the box ‘Requires authentication’ and enter your proxy server username and password. If not,
don’t check this box and leave those items blank. These items are encrypted before being written to
the configuration file so you can be confident your password will be safe.
Fill out the details on this screen as appropriate and click ‘Next’. epiCentre will attempt to make a
connection to the RedCap server and will report an error message if it cannot. This would indicate
the either there is something wrong with your network or something wrong with the proxy settings
you entered. If it is able to successfully communicate with the RedCap server using the proxy
settings you provided, a success message will be displayed and you will move to the next step.
Step 5: Administrator Account
At this point, you have created a working epiCentre database, and configured the connection to that
database. However you now need to create the first account which will have ‘Administrator’
privileges. Later you will be able to use this user account to create other user accounts. Please refer
to the heading ‘Application Level Security’ for an explanation of user roles and role types.
On this screen you are required to provide a name, username, email address and password/confirm
password. After you have entered this information, click ‘Next’. epiCentre will create a user account
and assign it a user role with ‘Administrator’ ‘All Facilities’ privileges.
epiCentre User Manual – Information for IT Administrators – v1.1
13
Step 6: Facility
In epiCentre, all ePPOC data records (Patient, Episode, Pathway, Questionnaire and Service Event)
belong to a Facility. In most cases an epiCentre database will only be used to manage one facility,
however the system supports multiple Facilities being used by a single database.
Consequently it is essential to create the first facility before any patient data can be entered. The
facility record includes a name, a unique code and a set of tokens used for communicating securely
with RedCap. This information will be provided to hospital IT staff as part of their epiCentre product
documentation.
Enter the information provided on to this form and click ‘Next’. epiCentre will then attempt to
validate any RedCap tokens you have entered by communicating with the RedCap server. This can
only work if you have set up the proxy server correctly in Step 4. Any tokens which fail to validate
will be highlighted.
If you are unable to get the tokens to validate you can delete the information from these items and
click ‘Next’ again. The Facility will be created and the wizard will complete, however you will need to
resolve this problem before Questionnaires can be generated and synchronised with the RedCap
server. Please contact ePPOC IT staff if you are unable to resolve issues with validating RedCap
tokens.
Finally
Congratulations, you have completed the Database Setup Wizard. An XML file called
‘epicentre.config’ will be created in the folder you specified during the install procedure (the default
is C:\ePPOC). The Database Configure Wizard only needs to be run once to create and configure the
epiCentre database. After this has been run, all epiCentre clients can be configured using the
following procedure ‘Configuring an epiCentre Client’.
epiCentre User Manual – Information for IT Administrators – v1.1
14
Configuring an epiCentre Client
Client Configuration Wizard
As previously mentioned the database only needs to be created and configured once. All other
clients can be configured using one of two approaches. One is to copy the epicentre.config file from
machine on which you ran the database configuration wizard and the second is to run the Client
Configuration Wizard.
Copying the Configuration File
The simplest approach is to copy the ‘epicentre.config’ file from the machine on which the database
configuration wizard was run and copy it to the relevant folder on each client machine after
installation of pre-requisites and the epiCentre application. To do this:
1. On the machine from which you ran the ‘Database Configuration Wizard’, go to the folder
you specified in step 3 of the procedure ‘Installing the epiCentre Application’. (The default
folder is C:\ePPOC\)
2. On the client machine, install the epiCentre pre-requisites and application.
3. Copy the file ‘epicentre.config’
4. Paste it into the same folder on each client machine.
If you follow this procedure, the database configuration, encryption key and proxy configuration
stored in that file will be applied to each client machine and this will avoid the need for using the
Client Configuration Wizard.
Running the Client Configuration Wizard
If you prefer, you can just run the Client Configuration Wizard on each client machine by following
this procedure:
1.
2.
3.
4.
On the client machine, install the epiCentre pre-requisites and application.
Run the epiCentre application.
The dialog pictured below will be displayed.
Answer ‘Yes’ and click ‘Next’
epiCentre User Manual – Information for IT Administrators – v1.1
15
Step 1: Database Connection
This form asks you to provide the following information:
-
Server name: the name of the machine running SQL Server on which the database is set up
Database name: the name of the database you want to connect to
Username prefix: the prefix used for SQL logins in the database create wizard
Dbo password, User password, Reader password: the passwords used for each SQL login in
the database create wizard
Encryption Key: the encryption key which was used when the database was configured. This
must match the original encryption key.
After entering this information, click ‘Next’. epiCentre will attempt to connect to the SQL database
on the server specified using each of the logins. Any errors will be reported. If everything was
successful, you will move to the next step.
Step 2: Proxy Server
This step allows you to enter the details of your proxy server, if necessary. Please see ‘Step 4: Proxy
Server’ in the Database Configuration Wizard section for further information.
Congratulations
If you have made it this far, you have successfully installed epiCentre, configured the database and
set up epiCentre client machines. We hope the process was relatively painless and are happy to hear
any feedback you have about the installation and configuration process.
epiCentre User Manual – Information for IT Administrators – v1.1
16