====== PDF eSurvey Developer Guide ======

The Pacific EMIS makes use of what we call "PDF eSurveys" or "eSurveys" for short. Essentially, the eSurveys are PDF form documents used to submit the surveys obsoleting the old paper based process. The eSurveys are built using a proprietary tool called [[http://www.lystech.com/|CenoPDF]], so a relatively not expensive license must be bought to create the surveys (or edit them in the future). CenoPDF is a Microsoft Word plugin that adds the ability to edit, convert and create fillable PDF form files with text box, check box, button, annotations, actions, javascript, etc. directly in Microsoft® Word, Microsoft® Publisher and Microsoft® Excel.


<note important>Only still used in Kiribati.</note>
===== Creating/Editing the PDF eSurvey =====

The first thing to do for anybody creating/editing the eSurveys is to read the CenoPDF [[http://www.lystech.com/webhelp/default.htm|User Guide]]. Once familiar with CenoPDF one can startting creating a new eSurvey or editing an existing one to a new revision. When starting from scratch it is a good idea to get the source word document of Karibati which at the time of this writing is the most comprehensive eSurvey using this technology in the Pacific.

These word documents currently could be given from one of the Pacific EMIS team members but ideally eventually it should be included in the software repository and version control there as well. Due to the very large number of data cells to process it is not recomended to try and creating the whole survey into a single big word document, but one should break it down into several documents and then re-attached together into a single PDF once complete.

The process for creating new eSurveys for a given country is something like this:

  - Go through a given eSurvey (i.e. Primary School Annual Survey) from  Kiribati and decide what part of the eSurvey applies to you.
  - Collect all the Kiribati broken down word documents for a given  eSurvey (i.e. Primary School Annual Survey) and download them  somewhere on your workstation
  - Pick the relevant part that you need for your eSurvey.
  - Edit what needs to be edited (e.g. some countries call education  levels Class 1, Class 2, etc. others refer to them as Grade 1,  Grade 2, etc.) Other plain text labels will need to be edited as well such  as names of provinces
  - Save your word document as another name (e.g. SIEMIS_PRI_TRIN.docx  for SIEMIS primary schools survey part recording transfers in data)
  - Generate the PDF for this word document using the CenoPDF export to  PDF feature (not the MS Word export to PDF).
  - Do this for all the word documents to get all the data grid needed  in the survey effectively constructing the whole survey piece by  piece.
  - Combine all the generated PDF documents into the final PDF eSurvey  and call it something like "SIEMIS_2016_PRI_v1.pdf" with the "_v1" as a  simple means to make it clear what version of the eSurvey this is  in case it changes in the future. The combine step is done using a  command line tool by executing the following two commands:

<code>
> "C:\the-path\cenoPostProcess.exe" -d C:\the-path\Pineapples.eSurvey\siemis\PRI\out -c "SIEMIS_2016_PRI.pdf" -f "SIEMIS_PRI*.pdf" --nopause

> "C:\the-path\cenoPostProcess.exe" -d C:\the-path\Pineapples.eSurvey\siemis\PRI\out -f "SIEMIS_2016_PRI.pdf" --title "Solomon Islands Primary Survey 2016"  -j "C:\the-path\Pineapples.eSurvey\js"
</code>

<note important>
There is a small issue making the final generated eSurvey missing, or more specifically hiding some labels. There is an easy work around. Open every CenoPDF generated document into Adobe Acrobat and save the document without making any changes. Accept to override the file. Run the final step 8. above after doing this only.
</note>

The process for editing would be much simpler.

  - Locate the word document that needs to be edited or if you need to    create a new document create one.
  - Generated the PDF for the one you changed.
  - Attach all the PDF document together into the new PDF eSurvey and  increase its revision number  (e.g. "SIEMIS_2016_PRI_v2.pdf").

===== PDF eSurvey Manager =====

Currently the PDF eSurvey Manager is a standalone desktop application that must be installed on a machine to "manage" eSurveys, in other words, it aims at doing the following:

  * Read existing school surveys from a database (production or a test database)
  * Pre-populate surveys with some data before sending them to schools
  * Upload completed surveys into the database (again, production or a test database)

The PDF eSurvey Manager repository is available at FIXME INCLUDE LINK TO REPO. But you only need to download the executable unless you are a developer wanting to fix or improve the tool. Detailed step by step instructions on how to install, configure and use the PDF eSurvey Manager belong in the User Guide since they are the target audience.

===== PDF eSurvey Process =====

The PDF eSurvey compliments the new online web user interface. For schools with a more reliable Internet connection they can directly access the survey form online and submit directly in the web Pacific EMIS application. Other schools without access to a reliable Internet connection but with access to a laptop or large tablet running the freely available [[https://get.adobe.com/reader/|Adobe Acrobat Reader]] can use the PDF eSurvey. There is no need for a good Internet connection, the PDF eSurvey can be sent to the school just like the old paper based survey, on a USB disk for example, and returned to the data entry officers just as before.

A more detailed user-oriented process is documented in the User Guide, but in essence it goes like this:

  - Start the eSurvey Manager
  - Create a pre-populated survey for one or more  schools. Pre-populated eSurveys contains some important information  such as the school name and ID and some data for previous years as a guide for example.
  - Distribute those pre-populated eSurveys to their respective schools on a USB stick or email if that have it.
  - School fill up their surveys as before but directly on a computer instead of paper.
  - Schools return the filled eSurveys on the same USB stick or email
  - Data Entry Officers look through the eSurveys for any issues and make sure it is all correctly completed
  - Start the eSurvey Manager and load the data from the PDF eSurvey into the database
  - Verify all data was uploaded successfully by browsing to the survey on the Pacific EMIS online web application