Feature Upgrade: Starting with CSPro 7.0, you should no longer use synchronization scripts, as they will soon be removed from CSPro. To replicate the behavior of the scripts, you must use the syncconnect, syncfile, and syncdisconnect functions.
CSPro synchronization scripts, with the file extension .pnc, allow for the transfer of data and programs back and forth between Android devices and remote machines. You can transfer data by using an FTP server, via a Dropbox account, or to another Android device by using Bluetooth. Multiple synchronization scripts can exist on a device, and you will have to determine the paradigm under which you would like to have your interviewers synchronize data and programs. For example, one synchronization script could update all survey instruments on the Android device and another script could send collected data to the server. Alternatively, one script could be used for both tasks.
Synchronization scripts can be executed in two ways:
- A script can be run by calling the sync function in logic. This allows advanced programmers to setup dynamic synchronization scripts and to control when they are executed.
- Synchronization scripts can be retrieved and executed manually. Once retrieved from a server, synchronization files are stored in the CSEntry "sandbox," meaning that they are safe from other applications and are unable to be viewed by your interviewers (with the rare exception of interviewers using rooted devices). If you make changes to the synchronization script, you must have your interviewers retrieve the synchronization file again. Although synchronization makes updating applications and data easy, it is important to ensure that your synchronization script is comprehensive and complete before distributing it.
There is no tool that comes with CSPro that you can use to edit your scripts, but you can create and edit them in a text editor such as Notepad.
AppName=optional application name
Description=optional description of the synchronization script
RootFolder=optional path on the Android device from which CSEntry bases the sync
DeviceName=optional name for the device in a Bluetooth server sync
<parameters described below>
CreateClientPath=directory to be created on the Android device
ClientPath=directory on the Android device to move to
Put=file to upload from the Android device to the server
CreateServerPath=directory to be created on the server
ServerPath=directory on the server to move to
Get=file to download from the server to the Android device
When processing a synchronization file, CSEntry first attempts to create a successful connection. If successful, the steps of the synchronization script are executed sequentially, in a similar fashion to a batch file or shell script.
The CreateClientPath and CreateServerPath statements are similar to a mkdir (make directory) command. If the folder already exists, then no folder will be created.
The ClientPath and ServerPath statements are similar to a cd (change directory) statement. Synchronization will fail if a folder does not exist, so if you are not sure that a folder exists, be sure to create it before moving to that directory.
In the Get and Put statements, you can use the ? and * wildcards. The Get and Put statements will always download or upload files, regardless of whether the files have been updated on the server or on the device.
In any statement, you can use a few replacement parameters:
- %AppName%: the application name optionally defined in the synchronization header
- %Date%: the date, in "year-month-day" (without hyphens) format, that the synchronization script occurred, using the Android device's clock
- %DateTime%: the date and time, in "year-month-day-hour-minute-second" (without hyphens) format, that the synchronization script occurred, using the Android device's clock
- %DeviceID%: the device ID, which corresponds to the value that is returned by the getdeviceid function
- %UID%: the user ID, which corresponds to the value that is returned by the getusername function
By default, the synchronization script starts processing from the <external storage>/csentry/ folder on your device. Executing a statement such as "ClientPath=/Data" will attempt to move to the <external storage>/csentry/Data folder, as all paths are based off of the csentry folder. If you would like to override this behavior, you can specify a different root folder using the RootFolder attribute. The following four examples execute in the same manner:
When connecting with an FTP server, the Connection section must contain the following attributes:
Username=FTP user name
If the FTP server that you are connecting to has Transport Layer Security or Secure Sockets Layer protections, then you can specify the protocol with one of the following statements:
SSLTLS=Implicit (for FTPS)
SSLTLS=Explicit (for FTPES)
When connecting with Dropbox, the Connection section must contain the following attributes:
When CSEntry attempts to connect to Dropbox, you will get a prompt where you can enter your Dropbox username and password.
A Bluetooth synchronization occurs between two Android devices. One device acts as a "server" and the other acts as a "client." The server has no intelligence, and it is the client's responsibility to get and put the appropriate files. A device could be a server during one synchronization and the client during the next. The Connection section for the Bluetooth server must contain the following attributes:
As mentioned in the File Format section above, it is also possible to set a Bluetooth name that the server will use while broadcasting as it waits for connections. If no name is specified, then the synchronization will broadcast using the Android device's Bluetooth name.
The Connection section for the Bluetooth client must contain the following attributes:
DeviceName=optional name of the Bluetooth server that the client is connecting to
If the DeviceName is left off of a Bluetooth client sync, then CSEntry will display a list of nearby Bluetooth devices that are broadcasting and allow the interviewer to select the device to which they want to connect.
When a Bluetooth synchronization begins, the user of the device acting as a server will have to respond to a warning indicating that their Bluetooth credentials will be broadcast. After accepting this, the Bluetooth client will be able to connect to the server.
To download a synchronization file to an Android device, select the Synchronize option on the menu while in the Entry Applications screen
. If any synchronization scripts have already been downloaded, they will be displayed here. Clicking on a script will launch the synchronization process. Alternatively, you can select "Add new" to add a new script. In this case, you will be presented with a list of three places where scripts can be found: on Dropbox, on an FTP server, or on the Android device storage.
- If selecting Dropbox, you will be asked to validate your Dropbox credentials and authorize CSEntry to access your files.
- When entering FTP credentials, you must enter a host, username, and password.
Once a connection has been made, CSEntry will display a list of files and folders on the Dropbox account, FTP server, or device storage. You can navigate into subfolders by clicking on a folder icon. You can visit a parent folder by selecting the up arrow icon that appears to the right of path that is currently displayed. In addition to folders, two kinds of files will be displayed:
- .pff file: If you click on a .pff file, CSEntry will automatically create a synchronization script based on the parameters described in the .pff file. This only works for basic data entry applications. If you use features such as lookup files, then this approach will generally not work as expected.
- .pnc file: If you click on a .pnc file, CSEntry will download the custom synchronization script.
Selecting either a .pff or a .pnc file will create or retrieve the synchronization script and place it in the CSEntry sandbox. It does not execute the script described in the file. After the download, you will have the option to select the script if you want to execute the synchronization.
To delete a synchronization script, hard-press on the name after clicking on Synchronize. You will have the option to delete the script. Alternatively, if you select "Add new" and download a file with the same name as a previously downloaded file, it will overwrite the previous synchronization script.