From edc55a9de4b36e7f023dac31059d1cc6c679cdd5 Mon Sep 17 00:00:00 2001 From: spatialash Date: Fri, 26 Jun 2026 17:11:43 +0530 Subject: [PATCH] new example document for feature update location --- .../feature-created-duration.md | 65 ++++++ .../feature-created-location-properties.md | 193 ++++++++++++++++++ .../feature-duration-properties.md | 120 +++++++++++ .../feature-updated-location-properties.md | 167 +++++++++++++++ 4 files changed, 545 insertions(+) create mode 100644 docs/CALCULATIONS/calculations-reference/feature-created-duration.md create mode 100644 docs/CALCULATIONS/calculations-reference/feature-created-location-properties.md create mode 100644 docs/CALCULATIONS/calculations-reference/feature-duration-properties.md create mode 100644 docs/CALCULATIONS/calculations-reference/feature-updated-location-properties.md diff --git a/docs/CALCULATIONS/calculations-reference/feature-created-duration.md b/docs/CALCULATIONS/calculations-reference/feature-created-duration.md new file mode 100644 index 0000000..0ae9db6 --- /dev/null +++ b/docs/CALCULATIONS/calculations-reference/feature-created-duration.md @@ -0,0 +1,65 @@ +--- +title: Feature Created Duration +excerpt: Access the total time in seconds spent creating a feature on the mobile device. +deprecated: false +hidden: false +metadata: + title: '' + description: Access the total time in seconds spent creating a feature on the mobile device. + robots: noindex +next: + description: '' +--- +The record's `this` object includes the total elapsed time the user spent creating the feature (record or repeatable item) on the mobile device before saving it for the first time. This is measured in seconds and reflects the active editing session from the moment the new record was opened until it was first saved. + +This property is available in both calculation fields and data events. + +# this.featureCreatedDuration + +Returns the total number of seconds spent creating the feature before it was first saved. + +## Syntax + +```js +this.featureCreatedDuration +``` + +## Returns + +Number — Seconds. Returns `null` if the duration was not recorded, or if the feature was created from the web. + +## Examples + +```js +// Return the creation duration in seconds +this.featureCreatedDuration +// returns 142 +``` + +```js +// Display duration as minutes and seconds +var secs = this.featureCreatedDuration; +if (secs !== null) { + var mins = Math.floor(secs / 60); + var remainder = secs % 60; + SETRESULT(mins + 'm ' + remainder + 's'); +} else { + SETRESULT('Duration unavailable'); +} +// returns "2m 22s" +``` + +```js +// Flag records created very quickly (possible data quality concern) +var duration = this.featureCreatedDuration; +if (duration !== null && duration < 10) { + ALERT('This record was created in under 10 seconds. Please verify the data is complete.'); +} +``` + +## Notes + +- Measures the wall-clock time between when the new record was opened and when it was first saved. It does not exclude time when the app was backgrounded. +- Returns `null` for records created on the Fulcrum web app. +- Returns `null` if the mobile app did not capture duration data (for example, records created with older versions of the app). +- This value is fixed after first save. It does not update on subsequent edits. To measure time spent on updates, use `this.featureUpdatedDuration` or `this.featureEditedDuration`. diff --git a/docs/CALCULATIONS/calculations-reference/feature-created-location-properties.md b/docs/CALCULATIONS/calculations-reference/feature-created-location-properties.md new file mode 100644 index 0000000..f6827f6 --- /dev/null +++ b/docs/CALCULATIONS/calculations-reference/feature-created-location-properties.md @@ -0,0 +1,193 @@ +--- +title: Feature Created Location Properties +excerpt: Access the GPS coordinates, altitude, and accuracy recorded at the moment a feature was first created on the mobile device. +deprecated: false +hidden: false +metadata: + title: '' + description: Access the GPS coordinates, altitude, and accuracy recorded at the moment a feature was first created on the mobile device. + robots: noindex +next: + description: '' +--- +The record's `this` object exposes the GPS location captured at the moment the feature (record or repeatable item) was first created on the mobile device. These four properties give you access to that creation-time snapshot: latitude, longitude, altitude, and horizontal accuracy. All four values are captured together at the same instant and reflect the device's GPS state when the feature was first saved. + +These properties are available in both calculation fields and data events. + +# this.featureCreatedLatitude + +Returns the latitude recorded at the time the feature was first created. + +## Syntax + +```js +this.featureCreatedLatitude +``` + +## Returns + +Number — Decimal degrees (WGS84). Returns `null` if no GPS fix was available at the time of creation, or if the feature was created from the web. + +## Examples + +```js +// Return the creation latitude as a number +this.featureCreatedLatitude +// returns 27.770756908186286 +``` + +```js +// Display creation coordinates as a formatted string +'Created at: ' + this.featureCreatedLatitude + ', ' + this.featureCreatedLongitude +// returns "Created at: 27.770756908186286, -82.638039" +``` + +```js +// Guard against null before using in a calculation +var lat = this.featureCreatedLatitude; +if (lat !== null) { + SETRESULT(ROUND(lat, 6)); +} else { + SETRESULT('No GPS at creation'); +} +``` + +## Notes + +- Returns `null` for records created on the Fulcrum web app, since no GPS is captured in the browser. +- Returns `null` if the device did not have a GPS fix when the feature was created. +- For repeatable items, returns the GPS location of the repeatable at the time it was first saved, not the parent record's location. +- This value does not change after the feature is first saved. To access the most recent location, use `this.featureUpdatedLatitude`. + +--- + +# this.featureCreatedLongitude + +Returns the longitude recorded at the time the feature was first created. + +## Syntax + +```js +this.featureCreatedLongitude +``` + +## Returns + +Number — Decimal degrees (WGS84). Returns `null` if no GPS fix was available at the time of creation, or if the feature was created from the web. + +## Examples + +```js +// Return the creation longitude as a number +this.featureCreatedLongitude +// returns -82.638039 +``` + +```js +// Calculate displacement between creation and current longitude +var drift = Math.abs(LONGITUDE() - this.featureCreatedLongitude); +SETRESULT(ROUND(drift, 8)); +// returns the absolute difference in decimal degrees +``` + +## Notes + +- Returns `null` for records created on the Fulcrum web app. +- Returns `null` if the device did not have a GPS fix when the feature was created. +- For repeatable items, returns the longitude of the repeatable at the time it was first saved. +- This value does not change after the feature is first saved. + +--- + +# this.featureCreatedAltitude + +Returns the altitude (in meters above sea level) recorded at the time the feature was first created. + +## Syntax + +```js +this.featureCreatedAltitude +``` + +## Returns + +Number — Meters above sea level (WGS84 ellipsoid). Returns `null` if altitude data was unavailable at the time of creation, or if the feature was created from the web. + +## Examples + +```js +// Return the creation altitude +this.featureCreatedAltitude +// returns 27.770756908186286 +``` + +```js +// Display altitude in feet +var altMeters = this.featureCreatedAltitude; +if (altMeters !== null) { + SETRESULT(ROUND(altMeters * 3.28084, 1) + ' ft'); +} else { + SETRESULT('Altitude unavailable'); +} +// returns "91.1 ft" +``` + +## Notes + +- Returns `null` if the device hardware does not support altitude or no GPS fix was available at creation. +- Altitude accuracy varies significantly by device and GPS conditions. It is generally less precise than latitude and longitude. +- Returns `null` for records created on the Fulcrum web app. + +--- + +# this.featureCreatedAccuracy + +Returns the horizontal GPS accuracy (in meters) recorded at the time the feature was first created. + +## Syntax + +```js +this.featureCreatedAccuracy +``` + +## Returns + +Number — Meters. A lower value indicates a more precise GPS fix. Returns `null` if accuracy data was unavailable at the time of creation, or if the feature was created from the web. + +## Examples + +```js +// Return the creation GPS accuracy +this.featureCreatedAccuracy +// returns 5.2 +``` + +```js +// Warn if the GPS accuracy at creation was poor +var accuracy = this.featureCreatedAccuracy; +if (accuracy !== null && accuracy > 10) { + ALERT('Warning: This record was created with low GPS accuracy (' + accuracy + 'm).'); +} +``` + +```js +// Display a quality label based on creation accuracy +var acc = this.featureCreatedAccuracy; +var label; +if (acc === null) { + label = 'Unknown'; +} else if (acc <= 5) { + label = 'High'; +} else if (acc <= 15) { + label = 'Medium'; +} else { + label = 'Low'; +} +SETRESULT(label); +``` + +## Notes + +- Represents horizontal accuracy only. Vertical (altitude) accuracy is not separately exposed. +- Returns `null` for records created on the Fulcrum web app. +- GPS accuracy is influenced by sky visibility, atmospheric conditions, and device hardware. Values under 5 meters are typically considered high accuracy for field data collection. diff --git a/docs/CALCULATIONS/calculations-reference/feature-duration-properties.md b/docs/CALCULATIONS/calculations-reference/feature-duration-properties.md new file mode 100644 index 0000000..0bbe1ff --- /dev/null +++ b/docs/CALCULATIONS/calculations-reference/feature-duration-properties.md @@ -0,0 +1,120 @@ +--- +title: Feature Duration Properties +excerpt: Access the total time spent on the most recent update session and the cumulative editing time for a feature on the mobile device. +deprecated: false +hidden: false +metadata: + title: '' + description: Access the total time spent on the most recent update session and the cumulative editing time for a feature on the mobile device. + robots: noindex +next: + description: '' +--- +The record's `this` object exposes two duration properties that measure time spent editing a feature (record or repeatable item) on the mobile device. `featureUpdatedDuration` measures the time spent in the most recent editing session. `featureEditedDuration` measures the total cumulative time spent editing the feature across all sessions. + +These properties complement `this.featureCreatedDuration` and are useful for auditing field workflows, flagging unusually short or long edits, and measuring field productivity. + +These properties are available in both calculation fields and data events. + +# this.featureUpdatedDuration + +Returns the number of seconds spent in the most recent editing session before the feature was last saved. + +## Syntax + +```js +this.featureUpdatedDuration +``` + +## Returns + +Number — Seconds. Returns `null` if the duration was not recorded, or if the feature was updated from the web. Returns `0` if the feature has not been edited since creation. + +## Examples + +```js +// Return the most recent edit duration in seconds +this.featureUpdatedDuration +// returns 87 +``` + +```js +// Display as a readable time string +var secs = this.featureUpdatedDuration; +if (secs !== null) { + var mins = Math.floor(secs / 60); + var remainder = secs % 60; + SETRESULT(mins + 'm ' + remainder + 's'); +} else { + SETRESULT('Not available'); +} +// returns "1m 27s" +``` + +```js +// Flag if the most recent edit was unusually brief +ON('edit-record', function(event) { + var duration = this.featureUpdatedDuration; + if (duration !== null && duration < 5) { + ALERT('The last edit of this record lasted less than 5 seconds. Please review the data.'); + } +}); +``` + +## Notes + +- Measures the wall-clock time of the most recent editing session only. It does not accumulate across edits. To measure total time across all edits, use `this.featureEditedDuration`. +- Returns `null` for records updated on the Fulcrum web app. +- Returns `null` if the mobile app did not capture duration data (for example, records updated with older versions of the app). +- Does not exclude time when the app was backgrounded during the edit session. + +--- + +# this.featureEditedDuration + +Returns the total cumulative number of seconds spent editing the feature across all editing sessions. + +## Syntax + +```js +this.featureEditedDuration +``` + +## Returns + +Number — Seconds. Returns `null` if duration data was not captured. Returns `0` if the feature has never been edited after creation. + +## Examples + +```js +// Return total editing time across all sessions +this.featureEditedDuration +// returns 430 +``` + +```js +// Display total editing time in minutes +var total = this.featureEditedDuration; +if (total !== null) { + SETRESULT(ROUND(total / 60, 1) + ' minutes total editing time'); +} else { + SETRESULT('Not available'); +} +// returns "7.2 minutes total editing time" +``` + +```js +// Compare total editing time against creation time +var created = this.featureCreatedDuration || 0; +var edited = this.featureEditedDuration || 0; +var totalTime = created + edited; +SETRESULT(ROUND(totalTime / 60, 1) + ' minutes total field time'); +``` + +## Notes + +- Accumulates the duration of all editing sessions, including `featureUpdatedDuration` from the most recent save. It does not include the original creation time — to include that, add `this.featureCreatedDuration`. +- Returns `0` for features that have never been edited after their initial creation. +- Returns `null` if the mobile app did not capture duration data (for example, records created and never edited with older versions of the app that did not support duration tracking). +- Returns `null` for records edited exclusively on the Fulcrum web app. +- Does not exclude time when the app was backgrounded during editing sessions. diff --git a/docs/CALCULATIONS/calculations-reference/feature-updated-location-properties.md b/docs/CALCULATIONS/calculations-reference/feature-updated-location-properties.md new file mode 100644 index 0000000..1a1070b --- /dev/null +++ b/docs/CALCULATIONS/calculations-reference/feature-updated-location-properties.md @@ -0,0 +1,167 @@ +--- +title: Feature Updated Location Properties +excerpt: Access the GPS coordinates, altitude, and accuracy recorded at the time a feature was most recently updated on the mobile device. +deprecated: false +hidden: false +metadata: + title: '' + description: Access the GPS coordinates, altitude, and accuracy recorded at the time a feature was most recently updated on the mobile device. + robots: noindex +next: + description: '' +--- +The record's `this` object exposes the GPS location captured at the moment the feature (record or repeatable item) was most recently updated on the mobile device. These four properties give you access to that update-time snapshot: latitude, longitude, altitude, and horizontal accuracy. + +For a feature that has never been edited after creation, these values will match the corresponding `featureCreated*` properties. + +These properties are available in both calculation fields and data events. + +# this.featureUpdatedLatitude + +Returns the latitude recorded at the time the feature was most recently updated. + +## Syntax + +```js +this.featureUpdatedLatitude +``` + +## Returns + +Number — Decimal degrees (WGS84). Returns `null` if no GPS fix was available at the time of the update, or if the feature was updated from the web. + +## Examples + +```js +// Return the update latitude +this.featureUpdatedLatitude +// returns 27.771203451892 +``` + +```js +// Calculate distance moved between creation and last update (approximate, flat-earth) +var latDiff = this.featureUpdatedLatitude - this.featureCreatedLatitude; +var lonDiff = this.featureUpdatedLongitude - this.featureCreatedLongitude; +var approxMeters = Math.sqrt(latDiff * latDiff + lonDiff * lonDiff) * 111320; +SETRESULT(ROUND(approxMeters, 1) + 'm'); +``` + +## Notes + +- Returns `null` for records updated on the Fulcrum web app. +- Returns `null` if the device did not have a GPS fix at the time of the update. +- For a newly created feature that has not yet been edited, this value matches `this.featureCreatedLatitude`. +- For repeatable items, reflects the GPS location of the repeatable at the time of the most recent save. + +--- + +# this.featureUpdatedLongitude + +Returns the longitude recorded at the time the feature was most recently updated. + +## Syntax + +```js +this.featureUpdatedLongitude +``` + +## Returns + +Number — Decimal degrees (WGS84). Returns `null` if no GPS fix was available at the time of the update, or if the feature was updated from the web. + +## Examples + +```js +// Return the update longitude +this.featureUpdatedLongitude +// returns -82.637204 +``` + +```js +// Display updated coordinates as a formatted string +'Last updated at: ' + this.featureUpdatedLatitude + ', ' + this.featureUpdatedLongitude +// returns "Last updated at: 27.771203451892, -82.637204" +``` + +## Notes + +- Returns `null` for records updated on the Fulcrum web app. +- Returns `null` if the device did not have a GPS fix at the time of the update. +- For a newly created feature that has not yet been edited, this value matches `this.featureCreatedLongitude`. + +--- + +# this.featureUpdatedAltitude + +Returns the altitude (in meters above sea level) recorded at the time the feature was most recently updated. + +## Syntax + +```js +this.featureUpdatedAltitude +``` + +## Returns + +Number — Meters above sea level (WGS84 ellipsoid). Returns `null` if altitude data was unavailable at the time of the update, or if the feature was updated from the web. + +## Examples + +```js +// Return the update altitude +this.featureUpdatedAltitude +// returns 29.112456 +``` + +```js +// Show elevation change between creation and last update +var gain = this.featureUpdatedAltitude - this.featureCreatedAltitude; +SETRESULT(ROUND(gain, 2) + 'm elevation change'); +// returns "1.34m elevation change" +``` + +## Notes + +- Returns `null` if the device hardware does not support altitude or no GPS fix was available at the time of update. +- Returns `null` for records updated on the Fulcrum web app. +- For a newly created feature that has not yet been edited, this value matches `this.featureCreatedAltitude`. + +--- + +# this.featureUpdatedAccuracy + +Returns the horizontal GPS accuracy (in meters) recorded at the time the feature was most recently updated. + +## Syntax + +```js +this.featureUpdatedAccuracy +``` + +## Returns + +Number — Meters. A lower value indicates a more precise GPS fix. Returns `null` if accuracy data was unavailable at the time of the update, or if the feature was updated from the web. + +## Examples + +```js +// Return the update GPS accuracy +this.featureUpdatedAccuracy +// returns 4.8 +``` + +```js +// Prevent saving if GPS accuracy at update is too low +ON('save-record', function(event) { + var accuracy = this.featureUpdatedAccuracy; + if (accuracy !== null && accuracy > 20) { + INVALID('GPS accuracy is too low (' + accuracy + 'm). Move to an open area and try again.'); + } +}); +``` + +## Notes + +- Returns `null` for records updated on the Fulcrum web app. +- Returns `null` if accuracy data was not available at the time of the update. +- For a newly created feature that has not yet been edited, this value matches `this.featureCreatedAccuracy`.