CSWeb User's Guide

Version 7.3.0

International Programs
Population Division
U.S. Census Bureau
4600 Silver Hill Road
Washington, DC 20233
cspro@lists.census.gov
 Table of Contents
Table of Contents 1
CSWeb User's Guide 2
Introduction to CSWeb 2
Server Setup 4
Minimum Server Requirements 4
Apache 5
Apache Server Setup 5
Apache CSWeb Setup 5
IIS 7
IIS Server Setup 7
IIS CSWeb Setup 8
Upgrading 10
Upgrading from Previous Versions 10
Production 11
Running CSWeb in Production 11
How to ... 12
Accessing Data 12
Adding Users 12
Troubleshooting 13
Get Help 14

Pa ge 1 of 14 Ta ble of Contents
 CSWeb User's Guide
Introduction to CSWeb
CSWeb is a web application that allows users to securely transfer cases (questionnaires) or files between client devices
running CSEntry and a web server. CSWeb requires a web server running PHP and MySQL.

Direct synchronization between interviewers and central server over the Internet

CSWeb eliminates the need to transfer data files by allowing users to instead transfer cases between client devices and a
web server. CSEntry data entry applications that are configured to use CSWeb synchronization take advantage of Smart
Synchronization, a feature that transfers only cases that are added or modified since the last successful synchronization.
Smart Synchronization reduces data transfer costs and Internet bandwidth usage.

CSWeb uses a MySQL database on the server to store the cases for the census or survey data entry instrument. Unlike a file
based synchronization that requires application designers to manage the concatenation of data files, CSWeb allows users to
download a single file containing all the cases for the data entry instrument (once the cases are transferred from the client
devices to the server).

The code to run CSWeb can be downloaded from the CSPro download webpage. More information about how to use CSPro's
synchronization features can be found in the CSPro User's Guide Synchronization Overview.

CSWeb is intended for large surveys and censuses. For small and medium surveys, Dropbox or FTP syncrhonization is sufficient
and far simpler to setup than CSWeb. For Dropbox synchroniation, no server is required at all, making it very easy to get
started. In addition, setting up CSWeb requires knowledge and experience with server administration and website
technologies. If you do not have experience setting up and maintaining web servers, you will find setting up CSWeb to be
very difficult.

This guide contains the following information:

Server Setup
Minimum Server Requirements
Apache Server Setup
Apache CSWeb Setup
Pa ge 2 of 14 CSWeb Us er's Guide
 IIS Server Setup
IIS CSWeb Setup
Running CSWeb in Production

How to ...
Accessing Data
Troubleshooting
Get Help

Pa ge 3 of 14 CSWeb Us er's Guide

 Server Setup
Minimum Server Requirements
Below are the minimum requirements to run CSWeb on an Apache or IIS server.

Manually verify:
Apache 2.0 or above or IIS 7.0 or above
URL Rewrite Module enabled

Requirements that will be verified by setup script:

MySQL 5.5.3 or greater
PHP 5.5.9 or above
Settings in php.ini
enable_post_data_reading on
post_max_size=8M
Extensions in php.ini
extension=php_curl.dll
or allow_url_fopen=On
extension=php_fileinfo.dll
extension=php_openssl.dll
extension=php_pdo_mysql.dll
extension=php_pdo.dll
extension=php_zip.dll (necessary with some installations of PHP)
Guzzle (PHP HTTP client) one of the following must be true
PHP 5.6 or above
or extension=php_curl.dll
or The CA bundle is installed
Files directory
Must exist and be writeable

The above requirements are sufficient to set up a CSWeb server for testing. To use CSWeb for a production data collection
operation see Running CSWeb in Production.

Pa ge 4 of 14 Server Setup
 Apache
Apache Server Setup
The setup of an Apache server is beyond the scope of this document. Fortunately, there already exists an extensive amount
of documentation on the topic. Below we have provided links for getting started.

Web Development Environment

There are a number of different web development environments that will simplify the setup and allow you to run and test
CSWeb locally. If you are developing using Windows you may find WampServer helpful. It will install and configure Apache,
MySQL, and PHP.

Apache Server
If you are looking to setup a server to host CSWeb you will need to install and configure Apache, MySQL, and PHP.

URL Rewrite Module

Regardless of your setup the Apache rewrite_module must be enabled. To do this you will need to edit the httpd.conf file.
There may be multiple copies of this file on your computer. Once, you have located the file make a back up and then
uncomment the following line LoadModule rewrite_module modules/mod_rewrite.so. Then restart Apache.

Apache CSWeb Setup

Below we have provided a general overview of the steps required to run CSWeb on an Apache server. In this example, it is
assumed WampServer has been installed and configured.

Add Project Files

Copy the root directory of your CSWeb project to <Drive>:\wamp64\www. The result may look like
C:\wamp64\www\csweb. Note that with Apache, the case of the folder name matters. CSWeb and csweb will require
different URLs to access the server. For simplicity, we recommend using all lowercase e.g. csweb.

Start Apache and MySQL

Make sure Apache and MySQL are running.

Add Database
Add a new database to use for CSWeb using the MySQL command line, MySQL workbench, or phpMyAdmin. Create a user
with access to the new database. For security reasons the database user should have a corresponding password.

Run Setup Script

Open a browser and in our case navigate to localhost/csweb/setup. The setup script will first check to make sure your
server meets the prerequisites. If your server does not pass, refer to the Minimum Server Requirements. Update your server
and run the script again. If your server passed the script will ask for the last few configuration details.
1. Database name: the name of the database you created earlier.
2. Hostname: this will typically be localhost.
3. Database username: by default this will be root.
4. Database password: by default this may be blank. Do not use the default password for a live server.
5. CSWeb admin password: create a password to pair with the default user admin to log into CSWeb.

Now verify the final two fields.

Pa ge 5 of 14 Apa che
 1. Path to files directory: for this setup, C:\wamp64\www\csweb\files
2. CSWeb API URL: for this setup, http://localhost/csweb/api
If everything is correct you will hit next and receive the "Setup Complete!" message. From here log in using admin as the
username and the CSWeb admin password you just created. Once you have run the setup script you will not be able to run
it again unless you delete src\api\app\config.php and src\ui\src\config.php.

Pa ge 6 of 14 Apa che
 IIS
IIS Server Setup
Below are the prerequisites for setting up an IIS server.

Install Internet Information Services (IIS)

On the lefthand column of Programs and Features select Turn Windows features on or off. Here you are able to select the
check box to turn on Internet Information Services.

Install Microsoft Web Platform Installer 5.0

You will find a shortcut to run the ISS Manager under Administrative Tools. On the righthand column of the IIS Manager
click Get New Web Platform components. This will open a browser where you will be able to download the installer for
Microsoft's web installer.

Install PHP 5.5.9+

Once installed, you can launch Microsoft's web installer from within the IIS Manager by clicking Get New Web Platform
components. Select the Products tab and install PHP 5.5.9 or above. Note that in Windows 10 the PHP Manager for IIS
may fail to install. You can ignore this message.

Handle Additional Verbs

In the IIS Manager select the Features View and then double click Handler Mappings. Right-click on PHP_via_FastCGI and
select edit. Click Request Restrictions..., select the Verbs tab, select One of the following verbs and enter
GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS. You may then be prompted to double quote the path under Executable.

Install URL Rewrite Module

Microsoft's web installer will also install the URL Rewrite module. However, if you use another installation method you may
need to install it manually. You can verify whether it is installed or not in IIS Manager's Features View. For more information
and to download the URL Rewrite module click here.

Edit php.ini
Locate the php.ini file for the new installation of PHP. You may have multiple copies on your computer. The default install
path will be under Program Files (x86) or Program Files depending one whether you installed the 32 or 64 bit version. The
root of the install directory will be PHP. You will find the php.ini file in the subdirectory that was named for the version you
installed. Open php.ini with Notepad and search for [ExtensionList]. Copy and paste extension=php_fileinfo.dll on the
next line. Save and close the file.

Install MySQL Server 5.5.3+

Download the MySQL Server here. For help with installation see the documentation. Do not forget to start the server. If you
installed MySQL Server as a service you can start it by doing the following:
1. Win + R
2. Run services.msc
3. Right-click on MySQLXX
4. Start
Alternatively, if you did not install MySQL server as a service or have a web development environment like WampServer
installed, you can start MySQL Server from the command line. You will need to open a command prompt and change
directory to the directory that contains mysqld.exe.

> mysqld

Pa ge 7 of 14 IIS
 IIS CSWeb Setup
Below are the prerequisites for running CSWeb on an IIS server.

Add Project Files

Copy the root directory of your CSWeb project to <Drive>:\inetpub\wwwroot. The result may look like
C:\inetpub\wwwroot\csweb.

Update Directory Permissions

You will find the below directories in your document root. Their permissions will need to be updated as shown.
files: Read and Write
logs: Read and Write
var: Read and Write
src\api\app: Read and Write
src\ui\src: Read and Write

Let us use the files directory as an example. Right-click on files and select Properties. Then click the Security tab. Press the
Add... button and type IUSR under Enter the names to select. Press the Check Names button and confirm your changes.
Select the user name you just added, IUSR, then update the permissions under Permissions for IUSR so that Read and
Write are allowed. Now repeat this process for logs, var, src\api\app, and src\ui\src setting the correct permissions.

Add Database
Do not forget to start the server. If you installed MySQL Server as a service you can start it by doing the following:
1. Win + R
2. Run services.msc
3. Right-click on MySQLXX
4. Start
Alternatively, if you did not install MySQL server as a service or have a web development environment like WampServer
installed, you can start MySQL Server from the command line. You will need to open a command prompt and change
directory to the directory that contains mysqld.exe.

> mysqld

Next, you can use MySQL Monitor to add a database. Connect to MySQL Server. You will need to open a command prompt
and change directory to the directory that contains mysql.exe.

> mysql -u root -p

Now, add the database.

> create database <name-of-your-database>;

As an example, I have named my database cspro.

> create database cspro;

To verify our work, we can list the databases.

> show databases;

Pa ge 8 of 14 IIS
 If you would prefer not to use the command line we recommend MySQL Workbench.

Start IIS
If IIS is installed you will find the Internet Information Services (IIS) Manager shortcut under Administrative Tools in the
Control Panel. Double click the shortcut to launch the IIS Manager. In the Connections tree on the left-hand side expand
Sites and select Default Web Site. You will see your document root below this. On the right-hand side there is an Actions
panel. Under Manage Website click Start.

Run Setup Script

Open a browser and in our case navigate to localhost/csweb/setup. The setup script will first check to make sure your
server meets the prerequisites. If your server does not pass, refer to the Minimum Server Requirements. Update your server
and run the script again. If your server passed the script will ask for the last few configuration details.
1. Database name: the name of the database you created earlier.
2. Hostname: this will typically be localhost.
3. Database username: by default this will be root. This is created during the installation of the MySQL Server.
4. Database password: by default this may be is blank. Using the default password is a security issue. This is set during
the installation of the MySQL Server.
5. CSWeb admin password: create a password to pair with the default user admin to log into the web app.

Now verify the final two fields.

1. Path to files directory: for this setup, C:\inetpub\wwwroot\csweb\files
2. CSWeb API URL: for this setup, http://localhost/csweb/api
If everything is correct you will hit next and receive the "Setup Complete!" message. From here log in using admin as the
username and the CSWeb admin password you just created. Once you have run the setup script you will not be able to run
it again unless you delete src\api\app\config.php and src\ui\src\config.php.

Pa ge 9 of 14 IIS
 Upgrading
Upgrading from Previous Versions
If you already have an older version CSWeb installed on your server and you want to upgrade to a newer version of CSWeb
follow the steps below:

Backup Existing Data

While the upgrade should normally preserve any existing data in your database, to be extra safe, you should first backup any
data that has been syncd to the server. Download each of the data files on the server to a csdb file. See Accessing Data for
instructions on how to download the data.

Update Project Files

Download and unzip the CSWeb source code and copy it to the csweb directory on your server. The csweb directory is where
you originally copied the project files to during doing the initial installation. For example, for wampserver it would likely be
C:\wamp64\www\csweb. The new files will overwrite the files from the original installation.

Start Apache and MySQL

Make sure Apache and MySQL are running.

Run Upgrade Script

When upgrading CSWeb, the database schema may change to support new features. In addition to updating the project
files, you need to run the upgrade script to migrate the database to the new structure. Open a browser and browse to
csweb/upgrade. For example, if you have installed on localhost then navigate to http://localhost/csweb/upgrade. The
upgrade script will check to see if the database needs to be migrated. If it does, it will display an Upgrade button. Click this
button to start the migration.

If everything is correct you will receive the "Upgrade Complete!" message. From here log in to CSWeb as usual.

Pa ge 10 of 14 Upgra ding
 Production
Running CSWeb in Production
Using CSWeb for a production data collection operation requires additional steps in order to make the server accessible to
devices in the field and to ensure proper data security.

Domain name
In order to connect to the server from devices outside your local network, such as tablets in the field, you will need to
register a domain name for your server. The instructions in this document describe using http://localhost to access your
CSWeb server. This will only work when accessing CSWeb from the server itself. In order to access the server from a tablet or
another computer you will need domain name such as http://census.gov. There are many companies online that can register
domain names. If you already have a website then you may be able to use that domain, or a subdomain, for your CSWeb
server.

Network security
If your server is connected to the internet, it is important to ensure that you have network security systems in place to
prevent unwanted intrusion and access to your data. Such systems will generally include a firewall. Your firewall must be
configured to allow HTTP and/or HTTPS traffic in order for devices to connect to CSWeb over the internet. If you plan to
store confidential survey data on your CSWeb server you should seek assistance from an expert in server security.

SSL certificate
TLS/SSL encrypts the communication between your server and devices in the field. TLS/SSL is also known as https. If you use
CSWeb without https, passwords and data are transferred as plain text and may be intercepted during transmission. For
confidential data it is important to use TLS/SSL to encrypt all data being transferred between devices in field and the server.
This can be done easily by configuring the web server (Apache or IIS) to use https instead of http. This requires an SSL
certificate for your domain. There are various companies and organizations that can provide SSL certificates.

Pa ge 11 of 14 Produc on
 How to ...
Accessing Data
Download CSPro DB File
1. Navigate to the Data tab of CSWeb.
2. Under the Download column click the file download icon for the dictionary you want to download.
3. This will download a PFF file. Double click the PFF file to launch the Data Viewer tool.
4. You will be asked to enter your CSWeb username and password.
5. The data will be downloaded as a single CSPro DB file.

Adding Users
Each user is composed of a username, first name, last name, role, email (optional), phone number (optional), and password.
The role can be either a standard user or an administator. The standard user can only synchronize from CSEntry. The
administrator can synchronize from CSEntry and log into the CSWeb website.

Adding a User
1. Navigate to the Users tab of CSWeb.
2. On the right-hand side click the Add User button.
3. Enter the username, first name, last name, role, email (optional), phone number (optional), and password.

Import Users
To import multiple users a CSV file is needed. Each row specifies a single user which has the following format: username, first
name, last name, user role, password, email (optional), phone number (optional). The CSV file can include a header row. If
your CSV file has a header row tick "CSV File has a header row." If an error is detected with any row, no users will be added.
Duplicate users are ignored.

1. Navigate to the Users tab of CSWeb.

2. On the right-hand side click the Import Users button.
3. Browse to the CSV file.

CSV Field Rules:

First and last name must only contain letters.
The role is either "Administator" or "Standard User."
The password must have least 8 characters.
The email and phone number can be blank.

CSV Example Rows:

user007, James, Bond, Administator, PasSwOrD7

Pa ge 12 of 14 How to ...
 user008, Bill, Timothy, Standard User, PasSwOrD8, b8@gmail.com, 123-4567

Troubleshooting
Troubleshooting Problems
CSWeb logs errors to a logs/api.log file located in the CSWeb sources folder in your web server's root directory. This log file
has more detailed information to help you troubleshoot problems.

If you need assistance setting up CSWeb or troubleshooting problems, please email cspro@lists.census.gov. Attach to the
email any server logs to help the CSPro development team diagnose the problem.

Reconfigure CSWeb
To reconfigure or reset your CSWeb installation:

1. Locate the CSWeb sources folder in your web server's root directory.
2. Delete the files src/api/app/config.php and src/ui/src/config.php.
3. To reconfigure CSWeb, open your web browser and launch the CSWeb setup page.

Common errors during CSWeb setup

Failed to connect to database. SQLSTATE[HY000] [1045] Access denied for user

The database username and database password are not correct. They should be set to the username and password for a
MySQL user that has permissions to access the MySQL database.

Failed to connect to database. SQLSTATE[HY000] [2002] php_network_getaddresses: getaddrinfo failed: No such host is
known.

The hostname is incorrect. This should be the hostname for the MySQL database, not the server hostname. In most cases
the hostname should be "localhost" unless your database and web server are running on different computers. The hostname
should NOT include "http://". If MySQL is running on a different port than the default, you should add the port to the
hostname. For example "localhost:3307".

Something went terribly wrong

This is a general error that could be caused by a number of different problems with the CSWeb configuration. For more
information check the CSWeb log files and also check the Apache/IIS/PHP error log.

Common errors syncing to CSWeb from a tablet/phone

Failed to connect to localhost

You are using a server URL that uses localhost. Localhost can only be used to access the server from a web browser running
on the server itself. To access the server from another computer or device you must use either a domain name or the IP
address of the server. If your server does not have a domain name or a static IP address you will need to obtain one. If you
are unsure how to do this you may want to consider using Dropbox synchronization instead of CSWeb.

Unable to resolve host

Either the server URL is incorrect or your device is not connected to the network.

Resource not found on server

Pa ge 13 of 14 How to ...
 The server URL is not correct. The host portion of the URL is probably correct but the part that follows is not. This often
happens when "ui" is used instead of "api" at the end of the URL. For example, http://example.org/csweb/ui instead of
http://example.org/csweb/api. Always use "api" when syncing with CSWeb from CSPro and use "ui" only when accessing
CSWeb from your web browser.

Get Help
To contact the CSPro development team with comments, questions, or to report problems, please contact:

International Programs
Population Division
U.S. Census Bureau
4600 Silver Hill Road
Washington, DC 20233
Phone: +1 301-763-1451
Support email: cspro@lists.census.gov
Official website: www.census.gov/data/software/cspro.html
CSPro Users forum: www.csprousers.org/forum

When you contact us, please mention that you are using CSPro 7.3.0.

Pa ge 14 of 14 How to ...