Components of an ODK Survey form

Looks like each survey needs three files in a folder in
\ODK\js\forms\formName\

  1. formDef.json
  2. xforms.xml
  3. formname.xlsx

Once you have made the form in Excel or GoogSpreadsheets, (following this
Documentation http://code.google.com/p/opendatakit/wiki/XLSForm2Docs) you
can convert it using the converter
here:http://ec2-50-16-84-43.compute-1.amazonaws.com/xlsform/2/

The output is the formDef.json file.
Now you place this in with the formname.xlsx file in the
\ODK\js\forms\formName\ folder and you

So now my question is, where does the xforms.xml file come from? Is it
being generated by the regular XLSForm at
http://opendatakit.org/use/xlsform/?

If so, having some trouble with that. Not only can I not make an XML using
my own survey (created using the above guidelines), I can't get a working
XML export from XLSForms using the provided sample excel file
'sample_xlsform.xls'. I get the error below:
[image: Inline image 1]

I'd love to see a little more information on the construction of forms for
ODK Survey, particularly addressing the above issue with XLSForm.
thanks for the help,

☞§※☼:airplane::open_umbrella::slight_smile:
~Neil

image

Not quite.

The only file needed for ODK Survey javascript on the phone is the
formDef.json. The xlsx does not need to be on the phone (we just ship it
along with the formDef.json, as it is a simple way to know which
formDef.json file matches which XLS source file).

The xml file is used for the backwards-compatibility interaction with ODK
Aggregate -- both (1) so that ODK Aggregate knows how to store data
collected using the formDef.json, and (2) as a 'form' that ODK Aggregate
can interpret and report as downloadable by an ODK Survey client using the
legacy ODK Collect APIs. When such an XML 'form' is uploaded to ODK
Aggregate, it is used by aggregate to create the data tables to store the
submissions, but ODK Survey is expecting that a formDef.json file is
present as a media file associated with the form. From ODK Survey's
perspective, the xml form definition file is just boilerplate needed to
gain access to the formDef.json. Once the new interfaces to ODK Aggregate
become available (the ones that allow bidirectional updates), there won't
be any need for the xml file.

If you copy any valid formDef.json file into a directory underneath the
forms directory on the phone, ODK Survey will pick up that form definition
and present it as an option for the user. That is the intended behavior --
i.e., no xml or xls is required once the formDef.json gets onto the phone.
If you see a different behavior, please open an issue.

To generate the XML, use the Windows-based HTA script, as described here:
http://code.google.com/p/opendatakit/wiki/SurveyReleaseNotes#Backward-compatible_operations_with_ODK_Aggregate

Mitch

image

··· On Thu, Feb 21, 2013 at 11:07 AM, Neil Hendrick wrote:

Looks like each survey needs three files in a folder in
\ODK\js\forms\formName\

  1. formDef.json
  2. xforms.xml
  3. formname.xlsx

Once you have made the form in Excel or GoogSpreadsheets, (following this
Documentation http://code.google.com/p/opendatakit/wiki/XLSForm2Docs)
you can convert it using the converter here:http://ec2-50-16-84-43.compute-1.amazonaws.com/xlsform/2/

The output is the formDef.json file.
Now you place this in with the formname.xlsx file in the
\ODK\js\forms\formName\ folder and you

So now my question is, where does the xforms.xml file come from? Is it
being generated by the regular XLSForm at
http://opendatakit.org/use/xlsform/?

If so, having some trouble with that. Not only can I not make an XML using
my own survey (created using the above guidelines), I can't get a working
XML export from XLSForms using the provided sample excel file
'sample_xlsform.xls'. I get the error below:
[image: Inline image 1]

I'd love to see a little more information on the construction of forms for
ODK Survey, particularly addressing the above issue with XLSForm.
thanks for the help,

☞§※☼:airplane::open_umbrella::slight_smile:
~Neil

--
You received this message because you are subscribed to the Google Groups
"ODK Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an
email to opendatakit-developers+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

--
Mitch Sundt
Software Engineer
University of Washington
mitchellsundt@gmail.com

Mitch,
Thanks for the very complete and detailed answer. I had been a little
boggled by the hodge-podge of files, but i can see it is a lot more simple
and self-contained than it appeared at first.

To take this thing to the next level, it would be interesting to see a
breakdown of the anatomy of a json survey.

From what I can see from a forensic analysis of the example survey provided
with the ODK Survey alpha

The file is divide into 5 major sections:

model
{21}
settings
[3]
survey
[39]
calculates
[1]
choices
{3}

The *Model *is where you place what we previously called the Instance and
its Nodes. That is, a placeholder for each datapoint. This also indicates
the type of data (integer, string, geopoint, etc. )
"coffee_today": {
"type": "integer"

The *Settings *contains the Form ID, Form Version, and Form Title:
{
"setting": "form_title",
"_rowNum": 4,
"value": "Example Form"
}

The *Survey *contains an entry for each question, in the order that they
are presented to the user. Each one refers to a node name from the Model.
It also contains a type indicator which will determine what kind of widget
will pop up. For example, in the model, the barcode node is type=string,
because the data will be stored as a string. But, here in the Survey
section, the type is 'barcode' so that it will launch the correct intent,
(barcode reader, camera, etc.) to generate the string that gets stored in
the barcode node.

    {
        "name": "barcode",
        "_rowNum": 8,
        "type": "barcode",
        "param": null,
        "label": "Scan a barcode"
    },

The *Label *is also declared here, and I assume if you had more than one
language, it would be in here like

"label.Spanish": "Escanear un código de barras"

There are also the *params *and *conditions *for skip logic and
constraints.
"param": "intents_end",
"condition": "not(selected(data('examples'), 'intents'))"

Params may refer to a selection of options, like Yes, and No, whose
details are kept in the later section for choices.

                "param": "yesno",
                "label": "Have you visited Seattle?",
                "type": "select_one",

There may be *calculates *for a question in the survey section

"condition": "calculates.ask_about_seattle()"

Which refer to the next section;

Calculates where special calculation type skip logic is stored.
{
"calculation": "selected(data('visited_continents'),
'NorthAmerica')",
"_rowNum": 2,
"name": "ask_about_seattle"
}

Finally, the *Choices *section contains options and values which are
referred to in the questions in the Survey section.
"yesno": [
{
"_rowNum": 2,
"name": "yes",
"label": "yes"
},
{
"_rowNum": 3,
"name": "no",
"label": "no"
}

Thats' the overview I can glean from a reading of it. I am sure that there
is somewhere an exhaustive description of the use of each of these. Some
more details for those who will likely write some of this without XLSForm,
would be greatly appreciated.

thanks,

☞§※☼:airplane::open_umbrella::slight_smile:
~Neil

Documentation???!!!

Surely, you jest :wink:

Here's an internal design/motivation document that I just moved out to the
wiki:

http://code.google.com/p/opendatakit/wiki/SurveyJSON

But I can't stress enough that the format of this file is highly likely to
change dramatically, especially the 'survey' section.

Please consider this an initial position statement, and by no means a
definition of a standardized file format structure.
It won't be standardized until we have Release Candidates for ODK Tables
and ODK Survey (alpha -> ... -> beta -> ... -> RC1 (release candidate #1)).

Mitch

··· On Fri, Feb 22, 2013 at 10:29 AM, Neil Hendrick wrote:

Mitch,
Thanks for the very complete and detailed answer. I had been a little
boggled by the hodge-podge of files, but i can see it is a lot more simple
and self-contained than it appeared at first.

To take this thing to the next level, it would be interesting to see a
breakdown of the anatomy of a json survey.

From what I can see from a forensic analysis of the example survey
provided with the ODK Survey alpha

The file is divide into 5 major sections:

model
{21}
settings
[3]
survey
[39]
calculates
[1]
choices
{3}

The *Model *is where you place what we previously called the Instance and
its Nodes. That is, a placeholder for each datapoint. This also indicates
the type of data (integer, string, geopoint, etc. )
"coffee_today": {
"type": "integer"

The *Settings *contains the Form ID, Form Version, and Form Title:
{
"setting": "form_title",
"_rowNum": 4,
"value": "Example Form"
}

The *Survey *contains an entry for each question, in the order that they
are presented to the user. Each one refers to a node name from the Model.
It also contains a type indicator which will determine what kind of widget
will pop up. For example, in the model, the barcode node is type=string,
because the data will be stored as a string. But, here in the Survey
section, the type is 'barcode' so that it will launch the correct intent,
(barcode reader, camera, etc.) to generate the string that gets stored in
the barcode node.

    {
        "name": "barcode",
        "_rowNum": 8,
        "type": "barcode",
        "param": null,
        "label": "Scan a barcode"
    },

The *Label *is also declared here, and I assume if you had more than one
language, it would be in here like

"label.Spanish": "Escanear un código de barras"

There are also the *params *and *conditions *for skip logic and
constraints.
"param": "intents_end",
"condition": "not(selected(data('examples'), 'intents'))"

Params may refer to a selection of options, like Yes, and No, whose
details are kept in the later section for choices.

                "param": "yesno",
                "label": "Have you visited Seattle?",
                "type": "select_one",

There may be *calculates *for a question in the survey section

"condition": "calculates.ask_about_seattle()"

Which refer to the next section;

Calculates where special calculation type skip logic is stored.
{
"calculation": "selected(data('visited_continents'),
'NorthAmerica')",
"_rowNum": 2,
"name": "ask_about_seattle"
}

Finally, the *Choices *section contains options and values which are
referred to in the questions in the Survey section.
"yesno": [
{
"_rowNum": 2,
"name": "yes",
"label": "yes"
},
{
"_rowNum": 3,
"name": "no",
"label": "no"
}

Thats' the overview I can glean from a reading of it. I am sure that there
is somewhere an exhaustive description of the use of each of these. Some
more details for those who will likely write some of this without XLSForm,
would be greatly appreciated.

thanks,

☞§※☼:airplane::open_umbrella::slight_smile:
~Neil

--
You received this message because you are subscribed to the Google Groups
"ODK Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an
email to opendatakit-developers+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

--
Mitch Sundt
Software Engineer
University of Washington
mitchellsundt@gmail.com

All,

I want to echo what Mitch said that the file is highly likely to change.

One of the reasons we released the alpha was to get suggestions from people
before we worked on finalizing things. There are some items the ODK team
plans to further refine but before we refine too far we wanted to show
developers a rough sketch of some of the directions we are heading to allow
developers to provide feedback to the ODK core team.

Waylon

··· On Fri, Feb 22, 2013 at 11:35 AM, Mitch S wrote:

Documentation???!!!

Surely, you jest :wink:

Here's an internal design/motivation document that I just moved out to the
wiki:

http://code.google.com/p/opendatakit/wiki/SurveyJSON

But I can't stress enough that the format of this file is highly likely to
change dramatically, especially the 'survey' section.

Please consider this an initial position statement, and by no means a
definition of a standardized file format structure.
It won't be standardized until we have Release Candidates for ODK Tables
and ODK Survey (alpha -> ... -> beta -> ... -> RC1 (release candidate #1)).

Mitch

On Fri, Feb 22, 2013 at 10:29 AM, Neil Hendrick mojotexas@gmail.comwrote:

Mitch,
Thanks for the very complete and detailed answer. I had been a little
boggled by the hodge-podge of files, but i can see it is a lot more simple
and self-contained than it appeared at first.

To take this thing to the next level, it would be interesting to see a
breakdown of the anatomy of a json survey.

From what I can see from a forensic analysis of the example survey
provided with the ODK Survey alpha

The file is divide into 5 major sections:

model
{21}
settings
[3]
survey
[39]
calculates
[1]
choices
{3}

The *Model *is where you place what we previously called the Instance
and its Nodes. That is, a placeholder for each datapoint. This also
indicates the type of data (integer, string, geopoint, etc. )
"coffee_today": {
"type": "integer"

The *Settings *contains the Form ID, Form Version, and Form Title:
{
"setting": "form_title",
"_rowNum": 4,
"value": "Example Form"
}

The *Survey *contains an entry for each question, in the order that they
are presented to the user. Each one refers to a node name from the Model.
It also contains a type indicator which will determine what kind of widget
will pop up. For example, in the model, the barcode node is type=string,
because the data will be stored as a string. But, here in the Survey
section, the type is 'barcode' so that it will launch the correct intent,
(barcode reader, camera, etc.) to generate the string that gets stored in
the barcode node.

    {
        "name": "barcode",
        "_rowNum": 8,
        "type": "barcode",
        "param": null,
        "label": "Scan a barcode"
    },

The *Label *is also declared here, and I assume if you had more than one
language, it would be in here like

"label.Spanish": "Escanear un código de barras"

There are also the *params *and *conditions *for skip logic and
constraints.
"param": "intents_end",
"condition": "not(selected(data('examples'), 'intents'))"

Params may refer to a selection of options, like Yes, and No, whose
details are kept in the later section for choices.

                "param": "yesno",
                "label": "Have you visited Seattle?",
                "type": "select_one",

There may be *calculates *for a question in the survey section

"condition": "calculates.ask_about_seattle()"

Which refer to the next section;

Calculates where special calculation type skip logic is stored.
{
"calculation": "selected(data('visited_continents'),
'NorthAmerica')",
"_rowNum": 2,
"name": "ask_about_seattle"
}

Finally, the *Choices *section contains options and values which are
referred to in the questions in the Survey section.
"yesno": [
{
"_rowNum": 2,
"name": "yes",
"label": "yes"
},
{
"_rowNum": 3,
"name": "no",
"label": "no"
}

Thats' the overview I can glean from a reading of it. I am sure that
there is somewhere an exhaustive description of the use of each of these.
Some more details for those who will likely write some of this without
XLSForm, would be greatly appreciated.

thanks,

☞§※☼:airplane::open_umbrella::slight_smile:
~Neil

--
You received this message because you are subscribed to the Google Groups
"ODK Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an
email to opendatakit-developers+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

--
Mitch Sundt
Software Engineer
University of Washington
mitchellsundt@gmail.com

--
You received this message because you are subscribed to the Google Groups
"ODK Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an
email to opendatakit-developers+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

Thanks Guys, I will take it all with a grain of salt, as is appropriate for
Alpha testing.
Thanks for the details, if I have anything to suggest or add, I will bring
it up.

☞§※☼:airplane::open_umbrella::slight_smile:
~Neil