Downloading, Refreshing, and Uploading
Description
Synchronizing form data and form type definitions with the server.
This app performs almost all of its operations using only the device's hardware and data resident on the device. It only communicates with the TransForm server using WiFi or cellular data when you direct it to. This section of Help addresses that communication.
There are four main situations when the app communicates with the server:
- Validating login credentials
- Downloading the definitions of the types of forms available to the logged in user
- Uploading new or modified forms with data
- Downloading existing forms with data
Errors may occur when uploading forms with data. For more information, see the section below titled:
- Errors during uploading
Validating login credentials
The app requires you to login with a valid user ID (usually an email address) and password to an existing account for which you are authorized. During the validation process the app communicates with the TransForm server to check the ID/password combination and to determine the valid accounts for that user. If you are authorized to use more than one account, you will be prompted to choose which one to use each time you login. You may only be logged in to one account at a time. You usually stay logged in to that account as that user until you logout, even if you exit and restart the app.
If the app needs to communicate with the server after too much time has elapsed since you last validated your login (for example, two days), then you will be prompted to confirm your login by providing your password before those operations that require the server are performed. Other operations (such as creating and adding data to forms) may be performed without requiring confirmation.
Confirming login is done using the Confirm login menu choice on the Main Control Bar shown above the List of Forms.
To discontinue being logged in as a particular user and account, use the Logout menu choice on the Main Control Bar. You will then need to do a full login to resume using the app for forms data capture or viewing.
Downloading or refreshing form type definitions
The definitions for each form type needs to be downloaded from the server. Each account has its own list of form types and they may be updated by the account administrator from time to time.
Definitions for the form types are automatically downloaded when a user logs in to an account. Those form types are listed on the Form Types List on the screen accessed with the Add a Blank Form button.
If you wish to refresh those definitions, downloading any new or changed form types, you may tap the Refresh from Server button above the Form Types list or the Refresh Definitions command on the Main Control Bar's menu. Refreshing is normally not needed unless form type definitions are changed or new ones added. This will probably depend upon the particular account and form types. (Refreshing or downloading is not automatically performed when you confirm login. Definitions are only automatically downloaded on a full login.)
Uploading forms
Forms must be uploaded to the server at some point to be used by the rest of the TransForm system. The user initiates the uploading either by tapping a button on the Forms List or a button on the form itself.
If there are any new, modified, or deleted forms, the Existing Forms list on the Forms List may include an Upload to Server button above the list (including the number of new and unsaved forms). (If the device is offline — for example, in Airplane Mode — the button will be replaced with an "Offline" indicator.) Tapping the button will initiate uploading of all new and modified forms to the server.
In addition, there is an Upload button as part of the Edit List operations to upload specific forms.
New, modified, or deleted forms are considered "unsaved" until uploaded to the server. (Uploading a deleted form causes the form to be deleted on the server as well as on the device.) There is usually a filter available to only show unsaved forms in the Forms List. See Search, Sort, Filter for more information about filtering.
A form may optionally include one or more buttons to initiate saving on the server. This is usually coupled with changing the status of the form. A form's status usually starts out with something like "Open" and may be changed to "Submitted", "Closed", or some other status determined by the form type designer.
A variety of conditions may cause one or more forms to encounter an error while uploading. A message will be displayed to alert you to this situation. See the Errors during uploading section below.
Downloading existing forms
If there are no unsaved forms, a Refresh button may appear above the Existing Forms list on the List of Forms. Tapping this will initiate downloading additions and changes to forms assigned to the logged in user for the logged in account. A display below the button will indicate how long it has been since checking was last done with the server for such changes.
This refresh capability is only needed in cases where new forms assigned to the user are added by others (such as a supervisor) or changes are made (such as returning a submitted form for more information, optionally with comments explaining what is needed).
Errors during uploading
A variety of conditions may cause one or more forms to encounter an error while uploading. A message will be displayed indicating the number of errors that were detected.
If an error is specific to a particular form, the form row will continue to indicate that it has changes that have not been uploaded. Tapping on the row to display the form will then let you use the List Problems item on the Form Details Menu to see a description of upload errors.
A common type of upload error is the "Write Conflict" error. It means that the server detected that the uploaded form was originally downloaded with data different than that currently on the server. This usually occurs when a user is logged in on two different devices and makes changes on each to the same form and then does an upload. The second upload will fail.
TransForm was designed for use by individuals, each with their own login ID, and each only logging in on one device at a time. It was not designed for simultaneous editing of the same form on two devices.
Once a write conflict is detected when uploading a form, that form will not be able to be uploaded as long as the other version is on the server. Each time an upload is done the error will be detected again.
If you logout, the changes to the form will be lost. When you then login again, the newer version will be downloaded from the server and editing may continue.
If there are changes to the form that you wish to preserve (such as to reenter them on the form after reloading), you may use the Duplicate Form command on the Form Details Menu to make a copy of the form with the error and then upload that before you logout. (In any case, do not erase the original before uploading the duplicate.)