Form XML Export

XML Data Format

When data is exported to the XML format from the FORM data collection platform, two XML files are produced: surveys.xml and responses.xml.

The surveys.xml file contains 4 tables that describe the structure of a form.

The responses.xml file contains the tables with the data about respondents and their answers to the questions.

Each of the files is accompanied by an .XSD file that describes the data format for the XML files.

Surveys.xml File Structure

Surveys.xml file contains the following description elements:

Survey

This table contains information for exported surveys:

• SurveyID – each form has a unique ID within the XML file. The field type is an integer, field length is 4 bytes, unsigned;

• KsID – internal ID of a form. This id is always unique to each form. The field type is a long integer, field length is 8 bytes, unsigned;

• Name – a text field that represents the name of the form that was assigned by the user who created it. The field type is a string, field size is 255;

• SurveyURL – Master URL at which the form is available. The field type is a string, field size is 1024;

• StartDate – the Start date when the form is available to collect data. The field type is dateTime, the date format is 2018-01-14 T 05:20:50.000;

• EndDate – the End date when the form stops collecting data. The field type is dateTime, the date format is 2018-01-14 T 05:20:50.000;

• CreateDate – date when the form has been created. The field type is dateTime, date format is 2018-01-14 T 05:20:50.000.

Question 

This table lists questions of all forms:

• QuestionID – a unique ID of a question within the XML file. The field type is an integer, the field length is 4 bytes, unsigned;

• KsID – unique ID of a question within the application. The field type is a long integer, the field length is 8 bytes, unsigned;

• Name – question text. The field type is string, the field size is 65536;

• SurveyID – links the question to the form, corresponds to the [SurveyID] field of the Survey table. The field type is an integer, the field length is 4 bytes, unsigned;

• isHidden – a field that indicates if the question is visible (Y or N) to the people who are filling out the form. The field type is a string, the field length is 1;

• AdID – additional reference ID. In most cases is set to the default value of 0. The field type is a string, the field length is 255;

• ArticleCode – internal parameter, not used. The field type is a string, the field length is 255;

• AnalysisCode – represents the analysis code set up for this question. The field type is a string, the field length is 50;

• CustomID – question identifier assigned to this question by the user. The value is always unique within the form. This field is only available if the question has a custom unique identifier. The field type is a string, the field length is 255;

• Type – represents the type of the question (please see question and answer types for more information). The field type is a string, the field length is 50;

• DataModelID – (only available for questions with types LOOKUP and MULTIPLE_LOOKUP) - a unique identifier of a Data Model where the values in the question may be selected from. The field type is a long integer, the field length is 8 bytes, unsigned;

• DataModelGroupID – (only available for questions with types LOOKUP and MULTIPLE_LOOKUP and only if the question allows to select values from a filtered list in the data model) - a  unique identifier of a filtered set of values from the Data Model where the values in the question may be selected from. The field type is a long integer, the field length is 8 bytes, unsigned.

Answer 

This table contains answer options for each question:

• AnswerID – a unique ID for the answer option within the XML file. The field type is an integer, the field length is 4 bytes, unsigned;

• KsID – unique internal ID for each of the answer options. The field type is long integer, the field length is 8 bytes, unsigned;

• QuestionID – ID of a question the answer option belongs to. Links to the [QuestionID] field of the Question table. The field type is integer, the field length is 4 bytes, unsigned;

• Weight – numeric value that corresponds to the answer options defined in the form definition. The field types are decimal, may contain up to 16 numbers in total and up to 5 decimal points;

• Value – text value of the answer option as it appears next to the radio button, checkbox, input field, within the dropdown or list-box in the form. The field type is a string, the field length is 65536;

• NumericValue – is the numeric value that corresponds to the answer option that has been defined in the report. The Field type is decimal, may contain up to 16 numbers in total and up to 5 decimal points;

• CustomID – answer option identifier that has been assigned to the answer option by the user. The value is always unique within the scope of the form. This field is only available if the answer option has a custom unique identifier. The field type is a string, the field length is 255;

• Type – the type of the answer option (please see question and answer types for more information). The field type is a string, the field length is 50.

Column 

Contains column definitions for matrix questions and Rank along scale questions:

• ColumnID – ID of a column, unique for the XML file. The field type is an integer, field length is 4 bytes, unsigned;

• QuestionID – ID of a question this column belongs to, links this table to Question table. The field type is an integer, the field length is 4 bytes, unsigned;

• Index – Index of the column, its position in the form. The field type is integer, the field length is 4 bytes, unsigned;

• Weight – numeric value of a column as specified in the form. The field type is decimal, may contain up to 16 numbers in total and up to 5 decimal points;

• Name – a title of the column.Fieldtypeisstring, field length is 300;

• NumericValue – numeric value of a column as specified in the report definition. The field type is decimal, may contain up to 16 numbers in total and up to 5 decimal points;

• Type – a type of elements in the column. The field type is a string, field length is 50.

Option

Available for "Dropdown box" elements:

• OptionID – ID of an option, unique for the XML file. The field type is an integer, the field length is 4 bytes, unsigned;

• ColumnID – ID of a column this option belongs to. The field type is integer, the field length is unsigned;

• Value – a text value of an option. The field type is a string, the field length is 255;

• NumericValue – a numeric value of an option. The field type is decimal, may contain up to 16 numbers in total and up to 5 decimal points.

Responses.xml File Structure

Responses.xml file contains the following tables:

Respondent

• RespondentID – ID of a respondent, unique for the xml file. The field type is an integer, the field length is 4 bytes, unsigned;

• KsID – internal ID for the respondent. It is always unique for the respondent. The field type is long integer, the field length is 8 bytes, unsigned;

• Email – email of the respondent if it was present. The field type is a string, the field length is 320;

• ResponseLabel – text label for the response calculated based on values, entered in the form. The field type is a string, the field length is 1024;

• SurveyID – Id of a form that this respondent was taking. Links to the Survey table from the surveys.xml file. The field type is an integer, the field length is 4 bytes, unsigned;

• KsSurveyID – System wide Form ID, should match the KsID of the Survey object of the form this respondent is associated with. The field type is a long integer, field length is 8 bytes, unsigned;

• Completed – indicates whether the respondent has finished completing the form. 1 - the form has been completed, 0 - it is partially completed by this respondent. The field type is byte, the field length is 1 byte, unsigned;

• SubmitDateTime – date and time when the response was submitted. The field type is dateTime;

• InternalNote – internal notes for this respondent. The field type is a string, the field length is 65535;

• TotalScore – the total score calculated based on the responses. The field type is decimal, may contain up to 16 numbers in total and up to 5 decimal points.

Response

• InternalRespondentId – Internal respondent ID of the respondent the response belongs to. The value is identical to KsID of the corresponding Respondent object. The field type is long integer, the field length is 8 bytes, unsigned;

• ResponseID – ID of a response, unique within the XML file. The field type is integer, the field length is 4 bytes, unsigned; this parameter is not persistent;

• RespondentID – ID of a respondent whose response this one is. Links to the RespondentID of Respondent table. The field type is integer, the field length is 4 bytes, unsigned;

• QuestionID – ID of the corresponding question. Links to the QuestionID field of the Question table. The field type is integer, the field length is 4 bytes, unsigned;

• SurveyID – ID of the corresponding form. Links to the SurveyID field of the Survey table. The field type is integer, the field length is 4 bytes, unsigned;

• ColumnID – applies for Matrix questions and specifies the ID of a column in which the response was entered. Links to the ColumnID field of the Column table. The field type is integer, the field length is 4 bytes, unsigned;

• AnswerID – ID of the corresponding answer option. Links to AnswerID field of the Answer table. The field type is integer, the field length is 4 bytes, unsigned;

• Value – text value of a response.

• FileName - the original name of the uploaded file.

• FileSize - the size (in bytes) of the uploaded file.

• ContentType - the file type and extension.

• Weight – numeric value of the selected answer option as defined in the form definition. The field type is decimal, may contain up to 16 numbers in total and up to 5 decimal points;

• NumericValue – numeric value of the selected answer option as defined in the report definition. The field type is decimal, may contain up to 16 numbers in total and up to 5 decimal points;

• Objects (only available for questions with type MULTIPLE_LOOKUP) – a collection of <object> XML objects, where the selected data objects are listed;

• Object (only available for questions with type MULTIPLE_LOOKUP) – an object selected in the Multiple Object lookup question;

• UniqueKey (only available for questions with type MULTIPLE_LOOKUP) – a unique identifier of an object within the data model. The field type is a string, the field length is 65535;

• FomattedName (only available for questions with type MULTIPLE_LOOKUP) – a formatted name for the selected object. The field type is a string, the field length is 65535.

• If you are exporting responses to XML format usingRemote Data Retrieval feature and use the parameter RbrLink=true, the exported file will also contain the RbrLink description element with the link to Report by Respondent, and the RbrPdfLink description element, which allows to download a response in PDF format. Both links are located in the Respondent table under the Submit date time description element.

• If you are exporting responses to XML format using Remote Data Retrieval feature and use the parameter ignoreHtmlTags=true, the exported file will also include information about HTML tags that were used to customize text of questions and answer options.

Question and Answer Types with Possible Response Values

For RANK_GRID_DEPENDENT and RANK_GRID_INDEPENDENT questions, the minimum and maximum values for ranking can be obtained from the Column table. For each of these questions, a set of columns is created that has rankings in the Index field. The lowest rank will be the lowest index for the QuestionID and the highest index will be the highest possible rank. Titles are also given to some of these columns in the Name field.

For MULTIPLE_LOOKUP questions the responses are provided differently than for other questions types. Each response contains a list of internal <Object>elements ,instead of response values. When the responses for such question are imported into the relational database, it is expected that the import procedure will generate a link between the <Object> elements and the <Response> elements. 

A Form Attached to the Task Definition

If a Form is attached to the Task Definition and such form or its report is exported to XML format, the surveys.xml and responses.xml files will include some additional description elements.

 Click here for more details:

Additional Task description elements in the Surveys.xml file

• TaskDefinitionID – internal identifier of a task definition this form has been published with, field type is a long integer, the field length is 8 bytes, unsigned;

• TaskDefinitionName – a name of the task definition this form has been published with, the field type is a string, the field size is 1024 bytes.

These description elements will appear after CreateDate and before QuestionID.

Additional Task description elements in the Responses.xml file

• TaskDefinitionID – internal identifier of a task definition this form has been published with. The field type is a long integer, the field length is 8 bytes, unsigned;

• TaskID – internal identifier of a task this response is linked to. The field type is a long integer, the field length is 8 bytes, unsigned;

• TaskSummary – summary of the task instance this response is linked to. The field type is a string, the field length is 1024 bytes;

• TaskDescription – description of the task instance this response is linked to.The field type is a string, the field length is 65536 bytes;

• TaskDueDate – Task due date. The field type is DateTime, date format is 2018-01-18 T 05:20:50.000;

  This field is present only if the due date has been enabled for the task definition. If the due date is enabled for the task definition but has not been set for the task instance the field will be present but the value in the field will be empty.

• TaskResponsiblePartyID – unique identifier of the responsible party as specified in the application's Contact Manager. The field type is a string, field length is 1024 bytes;

• TaskResponsiblePartyName – formatted name of the responsible party as specified in the application's Contact Manager. The field type is a string, field length is 1024 bytes;

• TaskCreatedByID – unique identifier of the person who created the task as specified in the application's Contact Manager. The field type is a string, field length is 1024 bytes;

  If the person who created the task cannot be determined the value in this field will be empty;

• TaskCreatedByName – formatted name of the person who created the task as specified in the application's Contact Manager. Field type is a string, field length is 1024 bytes;

  If the person who created the task cannot be determined the value in this field will be empty;

• TaskStatus – current status of the task. The field type is a string, field length is 255 bytes;

  • StatusID – unique identifier of the status. The field format is a long integer, the field length is 8 bytes, unsigned;

  • StatusName – the name of the custom status; the field value is a string, the field length is 1024 bytes;

  • Closed – indicator if the task is considered closed (true, false).

• TaskProperties – an array of elements containing the custom properties of a task with the following values:

  • InternalRespondentID – internal ID of the Respondent object the task instance was linked to; the field format is a long integer, the field length is 8 bytes, unsigned; this parameter can be used as persistent, instead of the ResponseID parameter;

  • PropertyID – internal ID of the custom property. The field format is a long integer, the field length is 8 bytes, unsigned;

  • PropertyName – a name of the custom property. The field value is a string, field length is 1024 bytes;

  • PropertyValue – a value of the custom property, corresponds to the text value of the response in the form field linked to the custom property (same is in the corresponding Response->Value field). The field type is a string, field length is 65536 bytes.