EpiSurveyor Mobile User Guide

EpiSurveyor.org User Guide

EpiSurveyor Video Tutorials

Quick EpiSurveyor Demo

Creating Forms with EpiSurveyor

EpiSurveyor On the Phone

EpiSurveyor Advanced Features (Part 1)

EpiSurveyor Advanced Features (Part 2)

Developer API

 

This document describes client API for episurveyor.org.  By reading, using, or distributing this document, you accept the EpiSurveyor Terms & Conditions. www.datadyne.org/episurveyor/terms/

1.       Background

 

This document describes the API for transactions between the EpiSurveyor server (http://www.episurveyor.org) and client software. Client software can run on mobile devices (such as J2ME/iPhone/Android applications), or, software running on another server (such as a forms storage server, a document processing server).   In a transaction, the client sends a request to the server, waits for a response from the server, processes the response, and gives the necessary response to the user.

 

Before describing the interaction between the client and the server, it is important to note that the client-server transactions use a set of unique codes.  Depending on the success or failure of a transaction, certain codes that are returned by the server to signify the status of the request.  

 

Server requests do not always return codes. For example a request for a form will lead to either the form being returned if the request was successful or a code being returned if the request failed for some reason. The return code should signify to the client, the source, or the reason for the failure.

2.       Return Codes

 

Below are the return codes for different exceptions types occurring in the server. It is the responsibility of the client to check the return from a transaction for the possibility of being a code.

 

 

Code	Description
400	MOBILE_RESPONSE_ERROR_IN_DOWNLOAD. Signifies that there was an error in server downloading a form or any other item that was being downloaded.
401	MOBILE_RESPONSE_SURVEYNOTEXIST. This code is given when the client request for a survey or a form that is not existent on the server. This code may also be returned if the user attempts to perform an action on a survey that is non existent. Such activity may involve an activity like data upload for a non-existent survey.
402	MOBILE_RESPONSE_NODOWNLOAD_PERMISSION. This code is returned if the user the client is running as is not permitted to download a form for which he/she is making a request. Details on the access rules imposed on forms on the server are available in the EpiSurveyor user guide.
600	MOBILE_RESPONSE_SUCCESS_CODE. This is the most welcome code that signifies the success of any action or request to the server for which do data response is expected from the server. This code is returned for successful login, successful form data upload and many more other successful operations.
601	MOBILE_RESPONSE_TYPE_INVALIDUSER. This code is returned in any operation that involves the authentication of a user to signify that the username and password provided are not valid.
602	MOBILE_RESPONSE_TYPE_DBERROR. This code is retuned if there was a database related error in performing the requested operation.
603	MOBILE_RESPONSE_TYPE_SURVEYNOTEXIST. This code is given if a request is made for a non existent survey or form.
604	MOBILE_RESPONSE_TYPE_USER_NEW. This type of response is given if the user information passed to server about the current user signifies that the user is not registered with the server. This means that the username(email) specified for the username does not exists on the database. This might a sign of wrong entry of username(email) by the user.
605	MOBILE_RESPONSE_TYPE_NO_DOWNLOAD_PERMISSION. Signifies that the user has no permission to download the selected form or survey.
606	MOBILE_RESPONSE_TYPE_INVALID_FIELDS.  This code is returned to signify that the field structure for the fields sent on a request to the server is incorrect. An example is when for example you are making a login request and you pass a username field parameter with a non standard parameter. Standard here refers to the standards laid out by the EpiSurveyor.org web server and the EpiSurveyor client.
700	MOBILE_RESPONSE_TYPE_USER_VALID. This is the response that is given if a username specified is valid.
701	MOBILE_RESPONSE_TYPE_INVALIDUSER_FOR_FORMLIST.  This code is returned if a wrong username or password is provided in the request for list of available forms for download.
702	MOBILE_RESPONSE_TYPE_DBERROR_FOR_FORMLIST.  This code is retuned if a database error or exception occurs during the processing of the request for the list of formsa available for download.
703	MOBILE_RESPONSE_TYPE_SURVEYNOTEXIST_FOR_FORMLIST. This value is returned if there are no forms that exists on the server for the specific type of forms and the user. For example, this code is returned when a user requests for the list of public forms while none exists for that user

Most of the codes above have the capitalized, underscored name clearly describing their applicability and depends on the context. For example a return code of 600 would imply a successful login for a login request while the same return code would imply a successful data upload for a survey data upload request.

3.       Server Calls

 

This section describes the server calls and corresponding parameters passed in each call. There is also entry for the request method used. The only possible methods are GET and POST. This refers to the http form request methods. This is usually the attribute that is provided in an html form declaration. For example <form name='loginform' method='POST' action="/login">. The actions are identified in terms of different transactions that might take place between the client and the server.

 

In this specification there are some variables used which are listed below.

 

• $server_root=http://www.episurveyor.org

 

In the document,  parameters are reused. An example of a reuse is $server_root/login which will translate to http://www.episurveyor.org/login

 

Transaction	Description
Login Request	URL: $server_root/AuthenticateLogin
	Request Method: GET or POST
	Parameters: Name Value requestType login id The username of the user (email address used for registering with the server) pwd The password as specified during the same registration
	Response: One of the codes specified above
Forms List Request	URL: $server_root/GetFormList
	Request Method: GET or POST
	Parameters: Name Value requestType formlist userid The username of the user (email address used for registering with the server) pwd The password as specified during the same registration formtype The type of form. Can be one of the following constants (private,public) Formtag(not mandatory) The tag that has been specified for the form during form creation Formname(not mandatory) The name filter for the forms to be returned
	Response: The response is an xml like notation with the following format <formlist >      <form url="" formid="formid1">Survey name2</form>      <form url="" formid="formid2">Survey name2</form>      <form url="" formid="formidn-1">Survey n -1</form>      <form url="" formid="formidn">Survey n</form> < formlist/>
Get Survey Form	URL: $server_root/GetSurveyForm
	Request Method: GET or POST
	Parameters: Name Value requestType getSurveyForm id The username of the user (email address used for registering with the server) pwd The password for the user requesting the forms. name The name of the form to be downloaded which is one of the names provided in the forms list request described above
	Response: An xfrom representation of the form requested. The structure of xforms is described in details on javarosa.org
Upload Records to the server	URL: $server_root/UploadRecordsNew   Description: used to add a new record or update an already existing record.  In the case that the record already exists on the server and the client is making an update, the client makes a call the same way as it would call for a brand new record, except, server will discover that it is an update by realizing that the record of the same timestamp already exists in the server and accordingly updates the record.
	Request Method: POST
	Parameters: This is a unique case that has been modeled to deal with the restricted resources available in the mobile device. For this, you can only be able to upload one record at a time. The method does not use the http parameters as usual but instead the server acquires the connections input stream and processes the whole request stream data. Here the nature and order of the data being sent is specified as follows. The client uses the DataOutputStream to write the records to the server. As such there might be some differences in the way the record is sent due to the stream metadata info included in the stream. Her'es a sample code for sending the a record to the server.         out.writeUTF(userId);         out.writeUTF(password);         out.writeUTF(surveyName);         out.writeLong(dateModified);         out.writeLong(recordId.getMostSignificantBits());         out.writeLong(recordId.getLeastSignificantBits());         out.writeUTF(dataTree); out here is an object of type DataOutputStream The parameters are written out exactly in the order specified. Any other format is not accepted. These restrictions were put in place due to the large overhead that was being experienced in storing large xml trees in the limited phones memory especially for surveys with many questions. First you write out the user id which is the email address of the user submitting the record. Next you write out the password for the user Next you write out the name of the survey for which you are submitting the record. Next you write put the date modified for the record being submitted. Next you write out a long value that is a long value with the record id. Next you write the data tree which is a well formed xml structure with the following sample format for a sample survey <?xml version='1.0' ?>    <data>          <locat>Moscow's the mine' city ma'am</locat>          <attend>me!!</attend>          <this-is-a-label>~</this-is-a-label>          <a-multi-choice-question>Banana|Mango|Orange</ a-multi-choice-question>          <a-single-choice-question>Yes</ a-single-choice-question>    </data>   Label questions: create an element that has the identifier for the label as usual but set the value of the element with a tilde (~). This is also the format used for questions that require answers but which the user supplied no answers for. Multiple choice questions: separate the answers provided with a pipe (|).
	Response: One of the codes specified above. 600 if successful upload, and other codes otherwise
	Request Method: GET or POST
	Parameters: Name Value requestType login Id The username of the user (email address used for registering with the server) Pwd The password as specified during the same registration

4.       References

 

Please use this specification as is and give forward any questions or clarifications you might be having to datadynejava@googlegroups where you will be guaranteed to receive a response within at most 12hours. Please ask any questions and we will be there for clarification or rectification. 

 

Supported Phones

The EpiSurveyor mobile client (the part that runs on your mobile phone) should run on the majority of phones that can run Java (also called J2ME).  

You can find a list of phones that we have specifically tested here:

http://www.episurveyor.org/m

If your phone is not on the list, please contact us at support@datadyne.org and we can put it on our testing list.

Terms of Service

1 Your relationship with DataDyne
1.1 Your use of DataDyne's products, software, services and web sites (referred to collectively as the "Services" in this document and excluding any services provided to you by DataDyne under a separate written agreement) is subject to the terms of a legal agreement between you and DataDyne. "DataDyne" means DataDyne Group LLC, whose principal place of business is at 1804 Vernon St NW, 2nd floor, Washington, DC, United States.
1.2 Unless otherwise agreed in writing with DataDyne, your agreement with DataDyne will always include, at a minimum, the terms and conditions set out in this document. These are referred to below as the "Universal Terms".
1.3 Your agreement with DataDyne will also include the terms of any Legal Notices applicable to the Services, in addition to the Universal Terms. All of these are referred to below as the "Additional Terms". Where Additional Terms apply to a Service, these will be accessible for you to read either within, or through your use of, that Service.
1.4 The Universal Terms, together with the Additional Terms, form a legally binding agreement between you and DataDyne in relation to your use of the Services. It is important that you take the time to read them carefully. Collectively, this legal agreement is referred to below as the "Terms".
1.5 If there is any contradiction between what the Additional Terms say and what the Universal Terms say, then the Additional Terms shall take precedence in relation to that Service.
1.6 Where DataDyne has provided you with a translation of the English language version of the Terms, then you agree that the translation is provided for your convenience only and that the English language versions of the Terms will govern your relationship with DataDyne. If there is any contradiction between what the English language version of the Terms says and what a translation says, then the English language version shall take precedence.
2 Accepting the Terms
2.1 By using the Services, you agree to be bound by this Agreement, whether you are a "Visitor" (which means that you simply browsing the Services) or you are a "Member" (which means that you have registered an account with the Services). The term "you" or "User" refers to a Visitor or a Member.
2.2 You may not use the Service and you may not accept this Agreement if you are not of a legal age to form a binding contract with DataDyne.
2.3 If you accept this Agreement, you represent that you have the capacity to be bound by it or if you are acting on behalf of a company or entity that you have the authority to bind such entity. Before you continue, you should print or save a local copy of this Agreement for your records.
3 4. Provision of the Services by DataDyne
3.1 DataDyne has subsidiaries and affiliated legal entities around the world ("Subsidiaries and Affiliates"). Sometimes, these companies will be providing the Services to you on behalf of DataDyne itself. You acknowledge and agree that Subsidiaries and Affiliates will be entitled to provide the Services to you.
3.2 DataDyne is constantly innovating in order to provide the best possible experience for its users. You acknowledge and agree that the form and nature of the Services which DataDyne provides may change from time to time without prior notice to you.
3.3 You acknowledge and agree that if DataDyne disables access to your account, you may be prevented from accessing the Services, your account details or any files or other content which is contained in your account.
3.4 You acknowledge and agree that while DataDyne may not currently have set a fixed upper limit on the number of transmissions you may send or receive through the Services or on the amount of storage space used for the provision of any Service, such fixed upper limits may be set by DataDyne at any time, at DataDyne's discretion.
4 Use of the Services by you
4.1 In order to access certain Services, you may be required to provide information about yourself (such as identification or contact details) as part of the registration process for the Service, or as part of your continued use of the Services. You agree that any registration information you give to DataDyne will always be accurate, correct and up to date.
4.2 You agree to use the Services only for purposes that are permitted by (a) the Terms and (b) any applicable law, regulation or generally accepted practices or guidelines in the relevant jurisdictions (including any laws regarding the export of data or software to and from the United States or other relevant countries).
4.3 You agree not to access (or attempt to access) any of the Services by any means other than through the interface that is provided by DataDyne, unless otherwise specified by DataDyne.
4.4 You agree that you will not engage in any activity that interferes with or disrupts the Services (or the servers and networks which are connected to the Services).
4.5 Unless you have been specifically permitted to do so in a separate agreement with DataDyne, you agree that you will not reproduce, duplicate, copy, sell, trade or resell the Services for any purpose.
4.6 You agree that you are solely responsible for (and that DataDyne has no responsibility to you or to any third party for) any breach of your obligations under the Terms and for the consequences (including any loss or damage which DataDyne may suffer) of any such breach.
5 Your passwords and account security
5.1 You agree and understand that you are responsible for maintaining the confidentiality of passwords associated with any account you use to access the Services.
5.2 Accordingly, you agree that you will be solely responsible to DataDyne for all activities that occur under your account.
5.3 If you become aware of any unauthorized use of your password or of your account, you agree to notify DataDyne immediately at support@datadyne.org
6 Privacy and your personal information
6.1 For information about DataDyne's data protection practices, please read DataDyne's Privacy and Security Policy, which is hereby incorporated into this Agreement. This policy explains how Mint treats your personal information when you access DataDyne Services. The policy may be updated from time to time at our discretion. Changes will be effective upon posting to the site.
7 Content in the Services
7.1 You understand that all information (such as data files, written text, hardware, software, video, audio or other sounds, photographs, videos or other images) which you may have access to as part of, or through your use of, the Services are the sole responsibility of the person from which such content originated. All such information is referred to below as the "Content."
7.2 You should be aware that Content presented to you as part of the Services, including but not limited to advertisements in the Services and sponsored Content within the Services may be protected by intellectual property rights which are owned by the sponsors or advertisers who provide that Content to DataDyne (or by other persons or companies on their behalf). You may not modify, rent, lease, loan, sell, distribute or create derivative works based on this DataDyne (either in whole or in part) unless you have been specifically told that you may do so by DataDyne, in a separate agreement.
7.3 DataDyne reserves the right (but shall have no obligation) to pre-screen, review, flag, filter, modify, refuse or remove any or all Content from any Service. For some of the Services, DataDyne may provide tools to filter out explicit sexual content.
7.4 You understand that by using the Services you may be exposed to Content that you may find offensive, indecent or objectionable and that, in this respect, you use the Services at your own risk.
7.5 You agree that you are solely responsible for (and that DataDyne has no responsibility to you or to any third party for) any Content that you create, transmit or display while using the Services and for the consequences of your actions (including any loss or damage which DataDyne may suffer) by doing so.
8 Proprietary rights
8.1 You acknowledge and agree that DataDyne (or DataDyne's licensors) own all legal right, title and interest in and to the Services, including any intellectual property rights which subsist in the Services (whether those rights happen to be registered or not, and wherever in the world those rights may exist). You further acknowledge that the Services may contain information which is designated confidential by DataDyne and that you shall not disclose such information without DataDyne's prior written consent.
8.2 Unless you have agreed otherwise in writing with DataDyne, nothing in the Terms gives you a right to use any of DataDyne's trade names, trade marks, service marks, logos, domain names, and other distinctive brand features.
8.3 You agree that you shall not remove, obscure, or alter any proprietary rights notices (including copyright and trade mark notices) which may be affixed to or contained within the Services.
8.4 Unless you have been expressly authorized to do so in writing by DataDyne, you agree that in using the Services, you will not use any trade mark, service mark, trade name, logo of any company or organization in a way that is likely or intended to cause confusion about the owner or authorized user of such marks, names or logos.
9 License from DataDyne
9.1 DataDyne gives you a personal, worldwide, royalty-free, non-assignable and non-exclusive license to use the software provided to you by DataDyne as part of the Services as provided to you by DataDyne (referred to as the "Software" below). This license is for the sole purpose of enabling you to use and enjoy the benefit of the Services as provided by DataDyne, in the manner permitted by the Terms.
9.2 You may not (and you may not permit anyone else to) copy, modify, create a derivative work of, reverse engineer, decompile or otherwise attempt to extract the source code of the Software or any part thereof, unless this is expressly permitted or required by law, or unless you have been specifically told that you may do so by DataDyne, in writing.
9.3 Unless DataDyne has given you specific written permission to do so, you may not assign (or grant a sub-license of) your rights to use the Software, grant a security interest in or over your rights to use the Software, or otherwise transfer any part of your rights to use the Software.
10 Content license from you
10.1 You retain copyright and any other rights you already hold in Content which you submit, post or display on or through, the Service. By submitting, posting or displaying the Content you give DataDyne a worldwide, royalty-free, and non-exclusive license to reproduce, adapt, modify, translate, publish, publicly perform, publicly display and distribute any Content which you submit, post or display on or through the Service for the sole purpose of enabling DataDyne to provide you with the Service in accordance with its Privacy Policy.
10.2 You agree that this license includes a right for DataDyne to make such Content available to other companies, organizations or individuals with whom DataDyne has relationships for the provision of syndicated services, and to use such Content in connection with the provision of those services.
10.3 You understand that DataDyne, in performing the required technical steps to provide the Services to our users, may (a) transmit or distribute your Content over various public networks and in various media; and (b) make such changes to your Content as are necessary to conform and adapt that Content to the technical requirements of connecting networks, devices, services or media. You agree that this license shall permit DataDyne to take these actions.
10.4 You confirm and warrant to DataDyne that you have all the rights, power and authority necessary to grant the above license.
11 Ending your relationship with DataDyne
11.1 The Terms will continue to apply until terminated by either you or DataDyne as set out below.
11.2 If you want to terminate your legal agreement with DataDyne, you may do so by (a) notifying DataDyne at any time and (b) closing your accounts for all of the Services which you use, where DataDyne has made this option available to you. Your notice should be sent, in writing, to DataDyne's address which is set out at the beginning of these Terms.
11.3 DataDyne may at any time, terminate its legal agreement with you if:
A. you have breached any provision of the Terms (or have acted in manner which clearly shows that you do not intend to, or are unable to comply with the provisions of the Terms); or
B. DataDyne is required to do so by law (for example, where the provision of the Services to you is, or becomes, unlawful); or
C. the partner or sponsor with whom DataDyne offered the Services to you has terminated its relationship with DataDyne or ceased to offer the Services to you; or
D. DataDyne is transitioning to no longer providing the Services to users in the country in which you are resident or from which you use the service.
11.4 Nothing in this Section shall affect DataDyne's rights regarding provision of Services under Section 4 of the Terms.
11.5 When these Terms come to an end, all of the legal rights, obligations and liabilities that you and DataDyne have benefited from, been subject to (or which have accrued over time whilst the Terms have been in force) or which are expressed to continue indefinitely, shall be unaffected by this cessation, and the provisions of paragraph 20.7 shall continue to apply to such rights, obligations and liabilities indefinitely.
12 EXCLUSION OF WARRANTIES
12.1 NOTHING IN THESE TERMS, INCLUDING SECTIONS 14 AND 15, SHALL EXCLUDE OR LIMIT DATADYNE'S WARRANTY OR LIABILITY FOR LOSSES WHICH MAY NOT BE LAWFULLY EXCLUDED OR LIMITED BY APPLICABLE LAW. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF CERTAIN WARRANTIES OR CONDITIONS OR THE LIMITATION OR EXCLUSION OF LIABILITY FOR LOSS OR DAMAGE CAUSED BY NEGLIGENCE, BREACH OF CONTRACT OR BREACH OF IMPLIED TERMS, OR INCIDENTAL OR CONSEQUENTIAL DAMAGES. ACCORDINGLY, ONLY THE LIMITATIONS WHICH ARE LAWFUL IN YOUR JURISDICTION WILL APPLY TO YOU AND OUR LIABILITY WILL BE LIMITED TO THE MAXIMUM EXTENT PERMITTED BY LAW.
12.2 YOU EXPRESSLY UNDERSTAND AND AGREE THAT YOUR USE OF THE SERVICES IS AT YOUR SOLE RISK AND THAT THE SERVICES ARE PROVIDED "AS IS" AND "AS AVAILABLE."
12.3 IN PARTICULAR, DATADYNE, ITS SUBSIDIARIES AND AFFILIATES, AND ITS LICENSORS DO NOT REPRESENT OR WARRANT TO YOU THAT:
(A) YOUR USE OF THE SERVICES WILL MEET YOUR REQUIREMENTS,
(B) YOUR USE OF THE SERVICES WILL BE UNINTERRUPTED, TIMELY, SECURE OR FREE FROM ERROR,
(C) ANY INFORMATION OBTAINED BY YOU AS A RESULT OF YOUR USE OF THE SERVICES WILL BE ACCURATE OR RELIABLE, AND
(D) THAT DEFECTS IN THE OPERATION OR FUNCTIONALITY OF ANY SOFTWARE PROVIDED TO YOU AS PART OF THE SERVICES WILL BE CORRECTED.
14.4 ANY MATERIAL DOWNLOADED OR OTHERWISE OBTAINED THROUGH THE USE OF THE SERVICES IS DONE AT YOUR OWN DISCRETION AND RISK AND THAT YOU WILL BE SOLELY RESPONSIBLE FOR ANY DAMAGE TO YOUR COMPUTER SYSTEM OR OTHER DEVICE OR LOSS OF DATA THAT RESULTS FROM THE DOWNLOAD OF ANY SUCH MATERIAL.
14.5 NO ADVICE OR INFORMATION, WHETHER ORAL OR WRITTEN, OBTAINED BY YOU FROM DATADYNE OR THROUGH OR FROM THE SERVICES SHALL CREATE ANY WARRANTY NOT EXPRESSLY STATED IN THE TERMS.
14.6 DATADYNE FURTHER EXPRESSLY DISCLAIMS ALL WARRANTIES AND CONDITIONS OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO THE IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
15. LIMITATION OF LIABILITY
SUBJECT TO OVERALL PROVISION IN PARAGRAPH 14.1 ABOVE, YOU EXPRESSLY UNDERSTAND AND AGREE THAT DATADYNE, ITS SUBSIDIARIES AND AFFILIATES, AND ITS LICENSORS SHALL NOT BE LIABLE TO YOU FOR:
A. ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL CONSEQUENTIAL OR EXEMPLARY DAMAGES WHICH MAY BE INCURRED BY YOU, HOWEVER CAUSED AND UNDER ANY THEORY OF LIABILITY. THIS SHALL INCLUDE, BUT NOT BE LIMITED TO, ANY LOSS OF PROFIT (WHETHER INCURRED DIRECTLY OR INDIRECTLY), ANY LOSS OF GOODWILL OR BUSINESS REPUTATION, ANY LOSS OF DATA SUFFERED, COST OF PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, OR OTHER INTANGIBLE LOSS;
B. ANY LOSS OR DAMAGE WHICH MAY BE INCURRED BY YOU, INCLUDING BUT NOT LIMITED TO LOSS OR DAMAGE AS A RESULT OF:
a. ANY RELIANCE PLACED BY YOU ON THE COMPLETENESS, ACCURACY OR EXISTENCE OF ANY ADVERTISING, OR AS A RESULT OF ANY RELATIONSHIP OR TRANSACTION BETWEEN YOU AND ANY ADVERTISER OR SPONSOR WHOSE ADVERTISING APPEARS ON THE SERVICES;
b. ANY CHANGES WHICH DATADYNE MAY MAKE TO THE SERVICES, OR FOR ANY PERMANENT OR TEMPORARY CESSATION IN THE PROVISION OF THE SERVICES (OR ANY FEATURES WITHIN THE SERVICES);
c. THE DELETION OF, CORRUPTION OF, OR FAILURE TO STORE, ANY CONTENT AND OTHER COMMUNICATIONS DATA MAINTAINED OR TRANSMITTED BY OR THROUGH YOUR USE OF THE SERVICES;
d. YOUR FAILURE TO PROVIDE DATADYNE WITH ACCURATE ACCOUNT INFORMATION;
e. YOUR FAILURE TO KEEP YOUR PASSWORD OR ACCOUNT DETAILS SECURE AND CONFIDENTIAL;
12.4 THE LIMITATIONS ON DATADYNE'S LIABILITY TO YOU IN PARAGRAPH 15.1 ABOVE SHALL APPLY WHETHER OR NOT DATADYNE HAS BEEN ADVISED OF OR SHOULD HAVE BEEN AWARE OF THE POSSIBILITY OF ANY SUCH LOSSES ARISING.

FAQ

What's the big deal about EpiSurveyor?
EpiSurveyor is the first web 2.0 application for global health and international development. It's software that allows anyone to set up a worldwide, mobile-phone-based data collection system in minutes, for free. Our philosophy is that anyone who needs to collect critical data for public health or development should be able to do so quickly and efficiently, without consultants or meetings or grants or contracts. EpiSurveyor lets you do that. And that's one of the reasons our team has won so many awards: we're really building worldwide  capacity to collect, analyze, and use data worldwide -- for public health, for development, for anything!

How much does EpiSurveyor cost? And who pays?
For most users, EpiSurveyor doesn't cost anything at all. Yes, you read that right: for most users, EpiSurveyor is completely free. We do charge those users who want additional levels of service or support or training, and use that funding to pay for free access for everyone else.

EpiSurveyor has so far been funded by grants from the United Nations Foundation, the Vodafone Foundation, and the World Bank, and by DataDyne.org with funds we receive from providing extra services to a subset of users. The majority of EpiSurveyor users don't pay a single dollar, and never will, but we do charge those users who want additional levels of service or support or training. This is a very new way of funding and scaling technology, and we think it's the only way that will result in building capacity for everyone, not just the richest organizations.

You would need to pay if you wanted any of these things:

• a Pro account at episurveyor.org -- for $5000 per year, this removes the 500 record-per-form limit, the 20 form limit per userid, and the 100 question limit per form. A Pro account will also be needed to use our API, which will be released in 2010, and which will allow you to access your EpiSurveyor.org data from another piece of software. If you're planning to use the API, or to collect thousands and thousands of records from many, many users, then at least one of those users needs to have a Pro account. The Pro account also allows for priority 24-hour email tech support.

• custom reports -- please contact us if you would like any custom reports created. These custom reports will work with the data you collect in your forms, letting you run them at the press of a button on whatever data you've collected.

• custom support or training -- if your work with EpiSurveyor requires phone support, training, or other extra work on our part, we'll have to charge you for it (but don't worry: we'll plow the money right back into improvements for EpiSurveyor that will benefit you and everyone else).

What phones can I use?
Find the list of supported phones at www.episurveyor.org/m

How do I configure a Blackberry to use EpiSurveyor?
    Here are the steps on the Blackberry, after installing the EpiSurveyor app:

1. Click on Menu - > Options
2. Select and click Advanced Options
3. Scroll down to TCP and click enter
4. Change APN to the local GSM provider you are using (you can obtain the APN from the GSM provider support team)
5. Enter username and password
6. Press Menu and select and click on Save.
7. Go back and open EpiSurveyor and log in. It should work with the correct settings.

How do I create forms?
First, create a free account at www.episurveyor.org and follow onscreen directions. You can see a demonstration video at http://www.youtube.com/watch?v=5aS6R1fUCBU

Where do I download the application for my phone?
Go to www.episurveyor.org/m and click on the model of your phone to start downloading. System messages may pop up depending on your mobile phone and service.  Press "Yes" and "Accept" for prompts requesting access and/or downloading rights.

What's the best way to learn how to use the software?
Read the user guide, and watch the video tutorials! See the links at right for more info.

I don't have a phone, can I still try the software?
Yes, use the Online Phone Emulator, which is software in your browser that acts just like a phone (you can even enter real data). Go to www.episurveyor.org/emulator

I want to replace my paper data collection process with EpiSurveyor. Can somebody help me get started?
Absolutely! First, we recommend that you read the user guide, and watch the video tutorials. That will give you a good idea about the software. Then, email  support at datadyne dot org with a description of what you'd like to do.

I have some ideas for new features for EpiSurveyor. Who do I talk to?
Email your thoughts/questions/ideas to support at datadyne dot org

I am having problems connecting to the internet. What should I do?
Contact your cellular service provider to configure the internet settings on your mobile phone.

How reliable and secure is EpiSurveyor.org?
We have taken key precautions to make sure your data is secure, backed up, and always available online. Episurveyor.org is hosted by Rackspace.com, a leading provider of hosted online applications.

Where is my data stored?
Right now, your data is stored on DataDyne's servers.  In 2010 we'll release an API (Application Programming Interface) that will allow you to access your stored data via your own software (such as MS Access, MySQL, etc).

Who owns the data once it's stored on the EpiSurveyor website?
YOU do, of course! Your data belongs to you, and can be seen ONLY by you, unless you explicitly give someone else permission to look at it. DataDyne does not want to own your data, control your data, look at your data or EVER restrict your access to your data.  You are always free, at any time, to download your data to your own computer and delete your data from our site (or delete your whole account).

I don't want to store my data on your servers. What can I do?
No problem: we don't force you to upload the data via our servers. Once you've created a form and downloaded it to your mobile phone (or phones), and then collected data on the phone, you can always download the data from your phone to a memory card, and then transfer it to your laptop or desktop.

Can I host EpiSurveyor myself?
At this time, there is no way for you to host a copy of EpiSurveyor on your own servers. However, with our API, due out in 2010, you will be able to access your EpiSurveyor data from your own software systems.  We are also considering allowing paying customers to host their own version of EpiSurveyor completely on their own servers.  Ask at info at datadyne.org.

Is the source code for EpiSurveyor.org available?
Yes and no:

• episurveyor.org -- In 2010 we have released an API (Application Programming Interface) that allows other developers to connect their software with EpiSurveyor.org, but we have no plans to release the full source code. The API description is at http://datadyne.org/episurveyor/api

• the EpiSurveyor J2ME client -- yes, the full code for our J2ME mobile phone client, which is built on the framework of the JavaROSA open-source project, is available.

• the EpiSurveyor Android client -- yes, the code for our Android client (beta version released July 2010) is available, and is based on the excellent work done in the ODK project at the University of Washington

• the EpiSurveyor Windows program -- yes, the software for the older, Windows-based EpiSurveyor is available at sourceforge.net/projects/episurveyor/

• the EpiSurveyor Palm OS client -- yes, you can also find the source code for the Palm client at sourceforge.net/projects/episurveyor/ (note: the Palm OS client does not work on the Palm Pre or the Palm Pixi, both of which runs WebOS, not Palm OS).

But why won't you let me see the source code for the website?

Our target audience for EpiSurveyor are regular people, not programmers or technologists, and regular people don't read source code.  We are following the model of the web applications that we all know and love: Hotmail, Yahoo Mail, Google Maps, Gmail, Facebook, Flickr, etc, etc, etc. All of those programs are "closed" and provide great free functionality. We want to be the Gmail of data collection. :-)   If you happen to be a programmer, and like to read source code, please have a look at our API in the menu at right -- so you'll be able to connect your software with ours.

Who's using EpiSurveyor?
Wow: where do we start?  The PDA version of EpiSurveyor has been a standard of the WHO for years, and is in use in more than 10 sub-Saharan countries under WHO auspices. Since releasing a web- and mobile-phone-based version in July 2009, however, EpiSurveyor use has exploded: as of this writing we have more than 2200 users registered at the website (www.episurveyor.org), and those users have collected more than 50,000 forms on mobile phones (tip: the current numbers are always displayed on the login page at www.episurveyor.org). Hundreds of organizations and government agencies are now using EpiSurveyor for their mobile data collection including:

• Abt Associates
• American Red Cross
• CDC
• Government of Ontario (Ontario Ministry of Agriculture, Food and Rural Affairs) and the University of Guelph
• International Federation of the Red Cross
• John Snow, Inc.
• TulaSalud (watch their great EpiSurveyor video)
• The World Bank

How much memory do I need on my phone?
The EpiSurveyor Mobile client software is about 500k in size, so your phone must allow the installation of applications of that size. Beyond that, the answer really depends on how long your forms are. We've had no problem with forms of 50-75 questions using a Nokia 6300 and its internal memory, and with forms of 150 questions or more using a Nokia E71 GPS phone. Longer forms need more built-in phone memory (not external memory card memory, which doesn't help with this particular issue). When using the application, you might run into one of these memory-related errors (you can avoid these errors by creating shorter forms or getting a phone with more memory):

• OutOfMemory
• OutOfBound Error
• NullPointer Exception

We'll also be releasing an "EpiSurveyor Lite" version in late 2010 that will have only the core data collection functionality but will run on phones with less memory.


My phone has internet, but I am getting the error message “Could not connect to server. Please try again later.”

The may be two reason why this might happen:

1. You don’t have enough credit on your phone, thus you would need to top up the phone credit.
2. The APN setting (which EpiSurveyor uses) is not correctly set.  If so, you can contact your GSM provider to provide you with the settings or you can set up manually.

 
Steps to set APN setting for some common phones

For Nokia Series 40 phones (e.g. 6300)

1. Go into Settings.
2. Go into Configuration.
3. Go into Personal Configuration Settings.
4. Now, press Add New (visible if you don’t have a previous Personal Setting created) or press the Options button. When you have pressed the Options button, choose Add new.
5. When you have pressed Add New, you will get a new menu, which will give several options to choose from.
6. Now, scroll down and choose the Access Point and press Select. (Please note that this option is not available on the Nokia 3220 model and maybe on some more models, you can instead use the Services option instead of the Access Point option on the Nokia 3220.) Do not choose the Web option, since this will not work with EpiSurveyor.
7. Now go into Access Point Settings.
8. Go into Bearer Settings.
9. Go into Packet Data Access Point.
10. Now, enter you APN address corresponding to your provider. Click here to check settings
11. Then press OK.
12. Go back to the Personal Configurations Settings menu, where you now should be able to see an Access Point selected.
13. Now press the Options button, and then choose to activate this Access Point.

 For Series 60 phones  (e.g. n70, 6600, etc)

1. Go to Menu > Tools > Settings > Connection
2. Select Access Points > Options > New access point > Use default settings
3. Name the connection
4. Set Data bearer to Packet data
5. Fill in access point name (APN); click here to check your settings
6. Set Username – check on link above
7. Set Prompt password to No
8. Set Password – check on link above
9. Set Authentication to Normal
10. Set Homepage to whatever site you like
11. Back * 2
12. Select Packet data
13. Set Packet data conn. to When available
14. Leave Access point blank
15. Finished

For E Series phones (e.g. e63, e71 etc)

1. Go to Menu > Tools > Settings > Connection
2. Select Access Points > Options > New Access Point
3. Set Connection Name = GSM Network name
4. Data Bearer = Packet Data
5. Access Point = click here to check settings
6. User name = check on the link above
7. Password = check on the link above
8. Homepage = none
9. The rest of the fields are left to default
10. Click Back to Save
11. When you open EpiSurveyor to connect, Select the new APN you have just set up above

For Sony Ericsson Devices
Follow the steps on setting APN here
For access point, click here to check for your GSM provider settings

 
For Samsung devices

1. Go to Menu > Settings > Browser Settings > Profile Settings
2. Select unused profile
3. Set Profile Name = GSM Network Name
4. Home URL = blank
5. Bearer = GPRS
6. Proxy = Enable
7. Click on GPRS Settings
8. Proxy = leave as default
9. Proxy port = leave as default
10. APN = click here to check your GSM provider settings
11. Login ID = check on the link above
12. Password = check on the link above
13. Click Save

 

EpiSurveyor Photos

http://www.flickr.com/groups/1062396@N24/pool/show/

Translators Wanted for EpiSurveyor

We are preparing multiple language versions of EpiSurveyor and need volunteer translators, especially for:

- Spanish

- French

- Portuguese

- Arabic

- Mandarin Chinese

To help, download this file:

http://www.datadyne.org/files/episurveyortranslate.xls

For each item in Column B (in English), please enter the translation in Column C.  Then email the file to support @ episurveyor.org (without the spaces) and tell us which language you have provided.

Thanks!