PPI Survey Conventions

Filename conventions

XML filename

An XML file, representing the survey, should be placed in the package"org.mifos.framework.util.resources.ppi"and should have a name of the form"PPISurveyINDIA.xml"Replace "INDIA" with the appropriate country name in uppercase. Linux based OS's are case-sensitive, so filename that doesn't follow this convention won't be found by the application on a Linux box.

Files to edit

A new PPI Survey must be registered in two places in the code:

PPIUIResources.properties

Package: "org.mifos.application.ppi.util.resources"This file stores translation keys for the UI. It must include one entry for each PPI survey of the form:PPI.Country.INDIA=IndiaReplace INDIA with the approriate country in UPPERCASE, and India (to the right of =) with a locale specific name of the country.

Country

Package: org.mifos.application.ppi.helpersThis is an enum type that has values for each country. The enum-name should be the same as the uppercase country name of the XML file; so in our example, "INDIA". The value for each name is a unique integer. This is referred to in code as the country id. However, it does not reference a table, so there is no real restriction on the order of, or relationship between the values. Still, it is probably best practice to use consecutive, increasing order. An iteration of this file might look like:::

public enum Country {

INDIA(1), BANGLDESH(2), KENYA(3), ... BOLIVIA(23);

XML file format

For a complete example of a well formed PPI Survey XML file, see PPISurveyINDIA.xml.All general XML format conventions apply, including header, characters, tags, etc'.

Components

>

There is only one of these tags in each document, and it must contain to the attributes country (the enum-name of the country this survey is for), and name (This is what will be displayed in the UI as the name of the generated survey).For example:::

<ppi country="INDIA" name="PPI Survey India"> ... </ppi>

>

There is one question tag for each question in the survey. The question tags are nested inside the base (<ppi>) tag. A question tag must have the attributes name, mandatory (=true or false), order (an integer representing the relative position of the question in the survey, zero-based). A question tag must also have exactly one child tag of type <text>, which contains within it the question text.For example:::

<question name="children" mandatory="true" order="0">

<text>How many children aged 0 to 17 are in the household?</text> ... choices go here, see below for details ...

</question>

>

There should be one choice tag for each choice in a question. Every choice tag is nested inside the question tag of the question to which it belongs. A choice tag must have the attribute points (a integer value representing the number of points the choice is worth). Nested inside the question tag is the text of the choiceFor example:::

<choice points="4">Electricity, coke, or coal</choice>

Updating PPI Surveys

It is possible to update a PPI survey that has already been registered into the system and, if certain rules are upheld, maintain data integrity.

Questions

Question order

At this point in time, changing the order of questions is not supported, and will likely jeopardize any data that has already been collected. So once a survey has be read into the application, the application expects the order attribute to remain the same.

Other question tag values

All other question tag values (text, name, mandatory) can be changed. Discretion should be taken when changing these values, however, keeping in mind that significant changes may alter the interpretation of data that has already been collected.

Choice tags

Similar to questions, the order of choices is not to be changed, as it will compromise collected data. Note, however, that in the case of choices order is denoted by location in the file rather than an order attribute.The points attribute can be changed, as well as the question text. However, like question, significant changes to either affect interpretation of already collected data.