3. Installing and configuring the client

3.1. Hardware and operating system requirements

See Android clients: hardware requirements.

3.2. CamCOPS client installation

3.2.1. Android

Install the Android app directly from the Google Play Store:

3.2.2. Android: manual installation

This method is now deprecated. Use the Google Play Store method instead.

Manual installation of an Android package is possible like this:

  1. Ensure your Android device permits the installation of third-party apps: e.g. Settings ‣ Security ‣ Unknown sources (Allow installation of apps from unknown sources).

  2. Download and install the CamCOPS client (see download) as an .APK (Android Package Kit) file.

3.2.3. iOS

Install the iOS app directly from the Apple App Store:

3.2.4. Windows

Download the Windows application from the CamCOPS download page.

If you have trouble see client troubleshooting.

Under Windows 10, you may see the warning:

Windows protected your PC

Windows Defender SmartScreen prevented an unrecognised app from
starting. Running this app might put your PC at risk.

[ More info ]

                            [ Don't run ]

Choose “More info” then “Run anyway”.

If it says

User Account Control

Do you want to allow this app from an
unknown publisher to make changes to your
device?

camcops_2.2.7_windows.exe [or similar]

...

then choose “Yes”.

3.2.5. Linux

Todo

Package CamCOPS client for easier Linux distribution.

3.3. Launching the CamCOPS client

Launch the app in the normal way. For Windows, run it from the desktop shortcut or the Start menu. For Android, launch it from the Apps screen.

3.3.1. Advanced launch options

In operating systems that allow you to launch applications with options (e.g. Windows, Linux), there are some additional advanced options offered, as follows.

Options:

Usage: /path/to/camcops/client/executable [options]

Options:
  -h, --help                                             Displays this help.
  -v, --version                                          Displays version
                                                         information.
  --dbdir <DBDIR>                                        Specify the database
                                                         directory, in which the
                                                         databases
                                                         "camcops_data.sqlite"
                                                         and
                                                         "camcops_sys.sqlite"
                                                         are used or created.
                                                         Order of precedence
                                                         (highest to lowest) is
                                                         (1) this argument, (2)
                                                         the
                                                         CAMCOPS_DATABASE_DIRECT
                                                         ORY environment
                                                         variable, and (3) the
                                                         default, on this
                                                         particular system, of
                                                         "/path/to/client/databa
                                                         se/dir".
  --default_single_user_mode <DEFAULT_SINGLE_USER_MODE>  If no mode has
                                                         previously been
                                                         selected, do not
                                                         display the mode
                                                         selection dialog and
                                                         default to single user
                                                         mode.
  --default_server_location <DEFAULT_SERVER_LOCATION>    If no server has been
                                                         registered, default to
                                                         this URL e.g.
                                                         https://server.example.
                                                         com/camcops/api
  --default_access_key <DEFAULT_ACCESS_KEY>              If no patient has been
                                                         registered, default to
                                                         this access key e.g.
                                                         abcde-fghij-klmno-pqrst
                                                         -uvwxy-zabcd-efghi-jklm
                                                         n-o
  --print_icd9_codes                                     Print ICD-9-CM
                                                         (DSM-IV) codes used by
                                                         CamCOPS, and quit.
  --print_icd10_codes                                    Print ICD-10 codes
                                                         used by CamCOPS, and
                                                         quit.
  --print_terms_conditions                               Print terms and
                                                         conditions applicable
                                                         to CamCOPS, and quit.

Specifying a non-standard database location

By default, the CamCOPS client stores its encrypted databases in the “user data” area; see Where does the client store my data? You can use the --dbdir option (see above) to change this. This is an advanced option. You cannot change the filenames of the databases, which are fixed to camcops_data.sqlite and camcops_sys.sqlite.

3.4. Clinician vs single user mode

The CamCOPS app has two modes of operation. You select the mode when you start CamCOPS.

When in Clinician Mode, you have full access to all settings and tasks (subject to copyright restrictions).

Single User Mode is designed for a patient using the app at home on their own tablet and offers a much simpler user interface. Only those tasks that appear in the patient’s task schedule are available.

3.5. Terminology: usernames and passwords in CamCOPS

Note

We will often refer to the client as a “tablet”, because it often is, but it might equally be your laptop or desktop running Windows/Linux/OS X.

In a low-security environment, you’ll be your own administrator. In a high-security environment, we’ll distinguish the user (“clinician” or “patient“) from the technical security person (“administrator”).

CamCOPS uses the following usernames and passwords:

  • TABLET PASSWORD. Your tablet will need a password to unlock it. This is nothing to do with CamCOPS.

  • CAMCOPS APP PASSWORD. The CamCOPS application will also need a password to unlock it. Without this, no access to CamCOPS encrypted data is possible.

  • CAMCOPS PRIVILEGED-MODE PASSWORD. This password unlocks the deep dark secrets of the app. Whoever has this can, for example, change the server that the app sends its data to. In a high-security environment, this password is typically known to the administrator, but not the clinician.

  • CAMCOPS SERVER USERNAME and CAMCOPS SERVER PASSWORD. These authenticate a user (who might be a clinician or an administrator) to the web interface, hosted by the CamCOPS server. You will use this username/password combination to (a) log in to the web site, and (b) upload data from your tablet, or register the tablet with the server. In more detail:

    • The CamCOPS app needs to know a username/password combination to register with a new server. (Registration is typically done by the administrator using their username/password.)

    • The CamCOPS app needs to know a username/password combination to upload data to the server. (Uploading is typically done by the clinician using their username/password. The app may or may not be allowed to store the password — that’s a local security policy decision — but it will store the username.)

    • When operating in Single User Mode, where the CamCOPS app user is typically a patient using the app on their own tablet, the username and password are generated automatically. First of all the administrator creates a patient record on the server and this includes a unique key, which is shared with the patient. When the patient starts the app for the first time, they register themselves and their device with the server by entering this key. At this point the server creates a username and password and these are stored on the tablet.

    • You will type in your username and password to access the CamCOPS web viewer. This interface is used to view tasks that have been uploaded from tablets. Administrators can also use this interface to create or edit authorized users.

3.6. Configuring your tablet before using CamCOPS

This section has nothing specifically to do with CamCOPS, but describes general good security measures to take (or measures that your institution may oblige you to take) with any mobile device holding sensitive information.

3.6.1. iPad

  • Set up appropriate security on your tablet. For a research environment with no patient-identifiable data, this may involve no work. But for a secure environment:

    • Home ‣ Settings ‣ General ‣ Passcode Lock

      • … ‣ Simple passcode = OFF. Why? Because 4-digit passcodes are weak; use a strong password 1, and don’t forget it! We’ll call this the TABLET PASSWORD.

      • … ‣ Turn passcode on

      • … ‣ Require passcode = immediately

      • … ‣ Erase data = ON (which will erase all data on the iPad after 10 failed passcode attempts).

  • Setting a passcode lock automatically encrypts data on the iPad 2 3.

  • Install CamCOPS; see above.

3.6.2. Android

  • Set up appropriate security on your tablet. For a research environment with no patient-identifiable data, this may involve no work. But for a secure environment:

    • Plug in the tablet; charge its battery fully. (Encryption takes a while and requires a charged tablet that’s plugged in.)

    • Settings ‣ Security ‣ Screen lock ‣ Password

    • Enter a strong password 1, and don’t forget it! We’ll call this the TABLET PASSWORD.

    • Settings ‣ Security ‣ Encryption ‣ Encrypt tablet ‣ Encrypt tablet … which may take a while.

  • Install CamCOPS; see above.

3.7. Configuring CamCOPS before using it

Using the CamCOPS server’s web interface, the administrator should:

  • Create a username and password for the new user.

  • Add that user to one or more groups.

  • For each group, edit the user’s group permissions. Normal settings:

    • Permitted to upload from a tablet/device. Almost certainly YES.

    • Permitted to register tablet/client devices. May be NO in very high security environments (in which case the administrator will have to use the tablet to register it on behalf of the final user); YES is more convenient.

    • May log in to web front end YES if the user needs access to any of the below functions of the admin interface. Otherwise NO.

    • May add, edit or delete patients created on the server. YES if the user needs this function, otherwise NO. See Manage patients and their tasks.

    • May send emails to patients created on the server. YES if the user needs this function, otherwise NO. See Manage patients and their tasks.

    • May view (browse) records from all patients when no patient filter set. Almost certainly NO, for confidentiality reasons.

    • May perform bulk data dumps. YES for researchers needing this function; otherwise NO.

    • May run reports. Reports cover a mixture of administrative and patient-finding functions. If in doubt, choose NO.

    • May add special notes to tasks. Likely to be YES for senior users.

    • User is a privileged group administrator for this group. Usually NO. If you say yes, the user will be able to create new users and manage this group.

  • If you intend to run the app in Single User Mode, you will need to create patients and schedule tasks for them.

On the tablet, when operating in Clinican Mode, the administrator should:

  1. Touch the padlock (top right) to unlock. (The first time CamCOPS is run, there will be no lock passwords; you need to set them, as below.)

  2. Settings ‣ Set privileged mode (for items marked †) (the icon at the top right will now show a golden pair of padlocks).

  3. Settings ‣ (†) Change privileged-mode password. Enter a password for this tablet; do NOT tell the clinician; keep it in your Administrator’s Safe.

  4. Settings ‣ Change app password. Enter a starting password for the clinician (their CAMCOPS APP PASSWORD); tell the clinician what this is.

  5. Settings ‣ (†) Configure server settings.

    • Set the server hostname

    • Set the server path

    • Ensure “Validate SSL certificates?” is set to “Yes”.

    • Choose the “Store user’s server password?” option. Your users will probably thank you for choosing “Yes”. The especially security-conscious may want “No”. (This setting determines whether the tablet will store an encrypted version of the user’s password; it allows the user to unlock CamCOPS with their CamCOPS app password, but then not to have to re-enter their CamCOPS server password each time they upload.)

    • Other values can typically be left as the default.

    • Save those settings.

  6. Assuming you will not allow the user to register devices with the server, you’ll have to do it yourself:

    1. Settings ‣ User settings ‣ Username on server. Enter your administrative CAMCOPS SERVER USERNAME. (Don’t enter a password here, even if you allow users to store their password; you don’t want your administrator’s password saved.)

    2. Save those settings.

    3. Settings ‣ (†) Register this device with the server. (It will ask for your administrative CAMCOPS SERVER PASSWORD, and then should initiate communication with the server, and succeed). Until registration has succeeded, the app will not be able to upload.

    4. Optionally, to be nice to the user: Settings ‣ User settings ‣ Username; enter the clinician’s CAMCOPS SERVER USERNAME; save those settings.

  7. Ensure you haven’t accidentally stored your administrative password in the app (Settings ‣ User settings). If you followed the instructions above, you won’t have done.

  8. Touch the padlock until it shows the red, locked icon. You can now give the tablet to your clinician.

The clinician should then:

  • If the whole tablet is locked, unlock it with the TABLET PASSWORD.

  • Touch the padlock to unlock. You will need your CAMCOPS APP PASSWORD, supplied to you by your administrator.

  • Settings ‣ Change app password. Change the password to a strong password that you like 1. Remember it.

  • Settings ‣ Intellectual property (IP) permissions. Answer all the questions honestly and save your changes.

  • Settings ‣ User settings. Set these:

    • Device friendly name: e.g. “Joe Smith’s LPS iPad”.

    • Username on server: your CAMCOPS SERVER USERNAME, supplied to you by your administrator.

    • If your administrator has allowed you to store your server password: Password on server: your CAMCOPS SERVER PASSWORD, supplied to you by your administrator.

    • Default clinician’s specialty, name, professional registration, post, contact details: set values that you would typically enter in patients’ notes. For example, a UK doctor might have: specialty = “Liaison psychiatry”; name = “Dr John Doe”; professional registration = “GMC# 123456”; post = “Consultant”; contact details = “extension 1234; bleep 5678”.

Note

The clinician’s name that you enter will be automatically processed into prefix/forename/surname components for HL-7 diagnosis (DG1) segments, if you use a recognized format. Recognized formats include, for example, Prefix Forename Surname (where prefix is Dr, Prof, Miss, Mrs, Ms, Mr, Sr, with or without full stops); Forename Surname; Surname, Forename. If the software doesn’t recognize the format, it will put the whole name verbatim into the surname field for DG-1 codes.

Good to go! See using the tablet app.

3.8. If your CamCOPS server is upgraded

Use Settings ‣ Fetch all server info to inform the client of changes. (This is exactly like client registration, but doesn’t require registration permissions.)

When in Single User Mode, switch first to Clinician Mode with More options ‣ Change operating mode.

3.9. Other CamCOPS app settings (Clinician Mode)

3.9.1. Language

Settings ‣ Choose language language

You can choose the language in which CamCOPS operates.

3.9.2. Questionnaire font size and DPI settings

Settings ‣ Questionnaire font size and DPI settings. Choose a font size that you like.

You can also override the system’s DPI settings (DPI = dots per inch – more strictly, PPI or pixels per inch). You are unlikely to need to change the logical DPI (and note that getting it wrong can make CamCOPS look dreadful!). However, some computers do not accurately report their physical DPI. Some CamCOPS tasks use visual analogue scale (VAS) sliders set to a real physical length (e.g. 10cm for the ORS). To get these right, CamCOPS needs to know the physical DPI of your screen. If your computer isn’t reporting it right, you can override the settings here. Changes take effect when CamCOPS is restarted.

3.9.3. Upload after each task is complete?

Settings ‣ User settings ‣ Offer to upload every time a task is edited?

3.10. Other tablet settings that can affect CamCOPS

3.10.1. Turn off auditory interruptions

If beeps and buzzes from other apps would interfere with your use of CamCOPS, disable them.

  • For Android: Android Settings ‣ Sound ‣ Volume; then turn off things like “Ringtone” (for phones), “Notifications”, and “System”.

  • For iOS: iOS Settings ‣ Notifications, and turn “Sounds” off.


Footnotes

1(1,2,3)

xkcd Password Strength: http://xkcd.com/936/.

2

http://support.apple.com/kb/ht4175

3

The iPad’s keychain is still vulnerable to attack: see summary at http://www.maravis.com/ios-device-encryption-not-effective/, or PDF at http://www.maravis.com/blog/wp-content/uploads/iOS-device-encryption-security.pdf. However, CamCOPS does not store its passwords in the keychain, and app storage is separate from the keychain.