Form Submission Formats: Standard vs. Labels as Node Names

Available on all tiers:

Essentials

Advanced

Enterprise

About
Standard XML Format

Form Information
Pages and Answers

Labels as Node Names XML Format

About

The Data Node Format can be selected for programmatic-type documents -- XML and JSON. There are two different structures available; the difference lies in the naming of nodes containing question/answer information. "Labels as Node Names" may be more suitable if less generic node names are needed.

The full Standard structure is listed below, with differences between this format and the "Labels as Node Names" format noted afterwards.

Standard Data Format

Changes to the Data Record Format:

For TrueContext REST APIs and JSON/XML document formats, we maintain a practice of not deleting existing properties or objects. A mechanism for versioning is used to facilitate deletions to our JSON/XML formats when necessary. Customers will be contacted in advance if they will be affected.

However, we will occasionally add new properties to existing APIs to support new features in the TrueContext Platform. We do not create a new version of our APIs for new properties and we advise that clients of our APIs are resilient to additions by ignoring unknown properties. Client applications should ignore any properties that are not relevant to their use case.

General Structure

The dataRecord root element has a number of child elements. For the sake of simplicity, this article will group all children of dataRecord into two groups: form-level information (sibling elements that contain general information about the data record), and "pages" (an element with children organizing page and answer data).

dataRecord

The dataRecord node is the root element.

Attributes:

identifier (used in referenceNumber)
version (v2)
zone (device time zone)

<dataRecord xmlns="https:/..." xmlns:xsi="http:/..." xsi:schemaLocation="https://..." identifier="18489010" version="v2" zone="America/Toronto">
...
</dataRecord>

Form Information

About

These nodes are: children of "dataRecord"
Siblings to "pages"
Elements do not repeat

Reference Number

The data record reference number. Formatted as "Date Submitted-datarecord identifier" (see above).

<referenceNumber>
	20140613-1813302612
</referenceNumber>

State

The data record state.

<state>
	Dispatched
</state>

Submit Date

There are three to four elements containing information on when the data record was submitted.

deviceSubmitDate: Date/time submitted in device time zone.

shifted:

The shifted time depends on the Document Time Zone Source, as described in the following table. The examples show the UTC offset for each time zone.

Note:The device time zone refers to the device setting, not the user profile locale settings in the TrueContext Mobile App account details.

If the Document Time Zone Source is set to…	Then the `shifted` time is in the…	Examples
Form Submission	Device time zone, which is the `provided` time. In this case, the `provided` time and the `shifted` time are the same.	Date Time of Incident - provided time: 2024-06-04T22:07:00+01:00 Date Time of Incident - shifted: 2024-06-04T22:07:00+01:00
Team Preference Setting	Team time zone	Date Time of Incident - provided time: 2024-06-04T22:07:00+01:00 Date Time of Incident - shifted: 2024-06-04T14:07:00-07:00
Custom	The custom time zone that you specify	Date Time of Incident - provided time: 2024-06-04T22:07:00+01:00 Date Time of Incident - shifted: 2024-06-04T23:07:00+02:00

serverReceiveDate: Date/time the TrueContext server received the data record.
dispatchDate: Included if state (see above) = dispatched. Date/time the data record was dispatched from the TrueContext server.

<deviceSubmitDate>
	<provided>
		<time>2014-06-13T13:28:05-04:00</time>
		<zone>America/Toronto</zone>
	</provided>
	<shifted>2014-06-13T13:28:05-04:00</shifted>
</deviceSubmitDate>
<serverReceiveDate>2014-06-13T13:28:07-04:00</serverReceiveDate>
<dispatchDate>2014-06-11T13:28:07-04:00</dispatchDate>

Form

Contains information abut the form/form version the data record was submitted against.

Attributes: "identifier"
Elements:

versionIdentifier: The identifier for the version of the form the data record was submitted against.
name: The name of the form the data record was submitted against.
version: The version number of the form.
formSpaceidentifier: The identifier of the FormSpace FormSpaces are where forms are stored and organized in the TrueContext Web Portal. A TrueContext Team may have multiple FormSpaces, depending on their needs. Admins can set FormSpace permissions to control which users have access to the forms in that FormSpace. the form is in.
formSpacename: The name of the FormSpace the form is in.

<form identifier="141413001">															
	<versionIdentifier>152110416</versionIdentifier>									
	<name>Demo Questions</name>															
	<version>20</version>																
	<formSpaceIdentifier>191162042</formSpaceIdentifier>								
	<formSpaceName>1- Demo FormSpace</formSpaceName>									
</form>

User

Contains information on the user who was logged into the device that submitted the data record (the data record submitter).

Attributes: "identifier"
Elements:

username: TrueContext username
displayName: First Name, Last Name (username)

<user identifier="13548142">															
	<username>johndoe@abc.com</username>
	<displayName>John Doe (johndoe@abc.com)</displayName>								
</user>

Dispatcher

This element is included when the data record state = dispatched. It contains information on the TrueContext user who dispatched the form.

Attributes: "identifier"
Elements:

username: TrueContext username
displayName: First Name, Last Name (username)

<dispatcher identifier="13548142">														
	<username>johndoe@abc.com</username>
	<displayName>John Doe (johndoe@abc.com)</displayName>							
</dispatcher>

GeoStamp

This element is included when the form the data record is submitted against is configured with a form-level geostamp.

Elements:

success: Tells if a geostamp was successfully acquired (Options: true | false)

captureTimestamp

provided: Date/Time geolocation was acquired in device time zone
- time
- zone

shifted:

The shifted time depends on the Document Time Zone Source, as described in the following table. The examples show the UTC offset for each time zone.

Note:The device time zone refers to the device setting, not the user profile locale settings in the TrueContext Mobile App account details.

If the Document Time Zone Source is set to…	Then the `shifted` time is in the…	Examples
Form Submission	Device time zone, which is the `provided` time. In this case, the `provided` time and the `shifted` time are the same.	Date Time of Incident - provided time: 2024-06-04T22:07:00+01:00 Date Time of Incident - shifted: 2024-06-04T22:07:00+01:00
Team Preference Setting	Team time zone	Date Time of Incident - provided time: 2024-06-04T22:07:00+01:00 Date Time of Incident - shifted: 2024-06-04T14:07:00-07:00
Custom	The custom time zone that you specify	Date Time of Incident - provided time: 2024-06-04T22:07:00+01:00 Date Time of Incident - shifted: 2024-06-04T23:07:00+02:00

source: what tool/service on the device was used to acquire the location (Options: GPS | Network)
coordinates
- latitude
- longitude
- altitude
address

<geoStamp>																				
	<success>true</success>																
	<captureTimestamp>
		<provided>																		
			<time>2014-06-13T13:27:56-04:00</time>
			<zone>America/Toronto</zone>
		</provided>
		<shifted>2014-06-13T13:27:56-04:00</shifted>									
	</captureTimestamp>
	<source>GPS</source>																
	<coordinates>
		<latitude>45.348002905586</latitude>
		<longitude>-75.9196980421965</longitude>
		<altitude>91.3237</altitude>
	</coordinates>
	<address>523 Legget Drive, Ottawa, ON, CA</address>
</geoStamp>

Pages and Answers

The "pages" element appears after all the data record-level information elements and is a sibling to them. Values are contained within answers; answers are contained within pages. The structure is as follows.

<pages>
	<page label="Page 1" name="Page 1">
		<sections>
			<section label="Section1" name="Section1" type="Flow">
				<answers>
					<answer label="New Question 1" dataType="FreeText" controlType="SmallTextbox">
						<question>New Question 1
						</NewQuestion1>
						<values>
							<value>Testing</value>
						</values>
					</answer>
					<answer label="New Question 2" dataType="FreeText" controlType="SmallTextbox">
						<question>New Question</question>
						<values>
							<value>Testing Again</value>
						</values>
					</answer>
				</answers>
			</section>
		</sections>
	</page>
</pages>

Standard Format vs. All Labels as Node Names Format

The Standard Format is listed above.

The "All Labels as Node Names" format differs only in the Pages/Sections/Answers section of the data record (the "Form Information" section is identical). In "All Labels as Node Names" format the node containing each page, section, or question and the corresponding value is named with the page, section, or question label. As labels are unique in a form, each "answer" node will be uniquely named. Each "answer" node still has a label, as well. Question labels are assigned in the form builder.

<pages>
	<Page1 label="Page 1" name="Page 1">
		<sections>
			<Section1 label="Section1" name="Section1" type="Flow">
				<answers>
					<NewQuestion1 label="New Question 1" dataType="FreeText" controlType="SmallTextbox">
						<question>New Question 1
						</NewQuestion1>
						<values>
							<value>Testing</value>
						</values>
					</NewQuestion1>
					<NewQuestion2 label="New Question 2" dataType="FreeText" controlType="SmallTextbox">
						<question>New Question</question>
						<values>
							<value>Testing Again</value>
						</values>
					</NewQuestion2>
				</answers>
			</Section1>
		</sections>
	</Page1>
</pages>