CSWeb Data Source

Overview

The CSWeb data source allows reading and writing data to a MySQL database hosted on a web server running CSWeb. This data source requires CSWeb 8.1+. Access to cases occurs using CSWeb's REST API. Because the server must be reachable at all times, this data source cannot be used in offline mode. Case modification occurs directly on the server, so there is no need to run synchronizations as the data is automatically synchronized.

Most people using CSWeb collect data using the CSPro DB data source and then use CSPro's synchronization functionality to transfer cases from the local device (the CSPro DB file) to the server (CSWeb). In environments where access to the server is guaranteed, using the CSWeb data source can simplify data collection as it eliminates the need to synchronize data and it ensures that all users have real-time access to the latest data.

Use the CSWeb data source with caution, as data collection operations will not succeed if the server is inaccessible.

Functionality

The CSWeb data source supports the following features:

Feature	Supported
Storage method	Server-based
Reading cases	✔
Writing cases	✔
Notes, case labels, and case statuses	✔
Storage of more than one kind of record	✔
Binary data items	✔
Deleting cases	✔
Undeleting cases	✔
Syncing data	—
Cases with duplicate keys	✔
Case identification via UUID	✔
Contains an embedded dictionary	✔
Allows record sorts	✘

User Permissions

When creating a connection, the data source attempts to log into CSWeb using credentials provided by the user, or specified in the connection string. The credentials for the CSWeb user are validated and then the role and its permissions are checked:

The role Administrator cannot use the CSWeb data source.
The role requires read permissions for Data and Dictionaries.
The role requires write permission for Data when opening the data source in read and write mode.
The role requires write permission for Dictionary when opening a data source using a dictionary that has not already been added to CSWeb.

Permissions can be defined on a per-dictionary basis and the role only requires permission to access the dictionaries and data that are used by the data source.

Dictionary Specification

Most CSPro functionality accesses data with a known dictionary. For example, a data entry application's main dictionary is the basis for the data collected using that application. However, some CSPro functionality can use an embedded dictionary. For example, when using Data Manager to open a CSPro DB data source, it can use the dictionary that is embedded in the CSPro DB file to determine how to describe the data. In contrast, when opening a Text data source, Data Manager will ask what dictionary describes the data.

A connection string to access CSWeb data may look like this:

https://example.org/csweb/api

If your data entry application uses a dictionary, MAIN_DICT, and an external dictionary, EXT_DICT, both could be set to use CSWeb. Based on the context of which dictionary this data source is associated with, CSPro knows whether to use CSWeb's MAIN_DICT databases or EXT_DICT databases. However, in circumstances where the dictionary is not explicitly known, such as when opening data using Data Manager, it can be specified using the property "dictionaryName":

https://example.org/csweb/api|dictionaryName=EXT_DICT

Binary Data

The CSWeb data source stores binary data metadata in a table named <dictionary name>_case_binary_data. The binary data itself is stored on the server in the directory files_csweb/binary-data/<dictionary name>. Each file in this directory is named after the binary data's MD5 signature. When reading case data, binary data is accessed using lazy loading, downloaded from CSWeb only when needed by the application.

Caching Data

To speed up access to CSWeb data, and to reduce server bandwidth, the default behavior is to cache responses from the server. Cached information is stored in an encrypted SQLite file located in CSPro's temporary storage directory. On Windows, this file is stored in a directory located at %AppData%/CSPro/csweb_cache/<dictionary name>.

This cache file is encrypted with a password that is stored in secure storage. The password is automatically generated by CSPro and is unique to each CSWeb user. This password is only used internally by CSPro and can be cleared using the Manage Credentials dialog.

Based on information from CSWeb, CSPro knows when the cached data is stale. In such cases, when newer data exists on the server, CSPro will request the data again rather than using the cache.

Even though cached data is encrypted, if you do not want to store any data locally, you can disable the cache using the "cacheLocally" property.

Customizable Behavior

The following behavior can be customized by specifying properties in the connection string. The default behavior is marked with ⁺⁺⁺.

Property Name and Values	Description

"cache"	Determines if cases are cached in memory. This may be useful to advanced users who want to optimize programs that do a lot of case lookups.
true	Cases are cached, meaning that a case is only read from the data source once.
false ⁺⁺⁺	Cases are not cached.

"cacheLocally"	Determines if CSWeb responses are cached locally in an encrypted file. This is different than the "cache" property, which applies to all data sources, which caches cases in memory during a single run of an application. The CSWeb local cache persists across application runs.
true ⁺⁺⁺	CSWeb responses are cached in an encrypted file.
false	CSWeb responses are not cached.

"dictionaryName"	A dictionary syncable name override. When defined, data is accessed using databases named after this override, not the name of the CSPro dictionary.

"password"	The CSWeb user's password. Hardcoding passwords in applications is not recommended. This is only used if a username is also provided.

"username"	The CSWeb user's username. This is only used if a password is also provided.

For example, the following connection string specifies that the local cache should not be used and that data should be accessed using databases based on a dictionary named SOIL_TEMPERATURE_DICT:

https://example.org/csweb/api|cacheLocally=false&dictionaryName=SOIL_TEMPERATURE_DICT