Add the geofence function

docs/central-submissions.rst

@@ -135,22 +135,18 @@ Once the :file:`.csv` or :file:`.zip` completes downloading, you will find one o
 Downloading submissions with Power BI or Excel
 ----------------------------------------------
 
-.. tip::
+Central provides an OData feed that Power BI or Excel can use to easily download submissions into a dashboard for visualization or into a spreadsheet for analysis.
+
+.. seealso::
 
   * See our :doc:`mapping households tutorial <tutorial-mapping-households>` for step-by-step guidance on using Power BI with ODK.
 
   * See `connecting Excel to ODK <https://forum.getodk.org/t/step-by-step-instructions-for-odata-use-with-excel-professional-2016/45118>`_ for instructions on using Excel with ODK.
 
-  Power BI and Excel uses the same underlying technology (Power Query) to connect to Central's OData feed. Try both of the above resources to maximize your learning.
-
-.. seealso::
-
-Central provides an OData feed that Power BI or Excel can use to easily download submissions into a dashboard for visualization or into a spreadsheet for analysis.
-
-.. tip::
+  Power BI and Excel uses the same underlying technology (Power Query) to connect to Central's OData feed. Try both of the above resources to maximize your learning. You can also follow along with this video:
 
-..  youtube:: CDycTI-8TOc
-   :width: 100%
+  ..  youtube:: CDycTI-8TOc
+     :width: 100%
 
 To download submissions with Power BI or Excel, follow these steps:
 
@@ -191,17 +187,17 @@ It can be tricky to access submission media files while using external tools lik
 
 In the OData feed, you will see media files given by their filename. If you want, you can construct a link within your analysis tool that will download any media file with your web browser. You can do this by gluing together pieces of text into a URL. Often this gluing operation is called ``concat`` or ``concatenate``. You'll need to make it look like this:
 
-  .. code-block:: bash
+.. code-block:: bash
 
-    https://DOMAIN/#/dl/projects/PROJECTID/forms/FORMID/submissions/INSTANCEID/attachments/FILENAME
+  https://DOMAIN/#/dl/projects/PROJECTID/forms/FORMID/submissions/INSTANCEID/attachments/FILENAME
 
 Where the uppercase words need to be replaced with the appropriate values. The easiest way to get the ``DOMAIN``, ``PROJECTID``, and ``FORMID`` is to open the Form in your web browser in the Central administration website and just copy the values you see there. The two web addresses are quite similar. Then you have to add the ``INSTANCEID`` and the ``FILENAME``, both of which you can find in the OData data itself.
 
 Here is an example of a completed address:
 
-  .. code-block:: bash
+.. code-block:: bash
 
-    https://my.odk.server/#/dl/projects/1/forms/forest_survey/submissions/uuid:20bcee82-4a22-4381-a6aa-f926fc85fb22/attachments/my.file.mp3
+  https://my.odk.server/#/dl/projects/1/forms/forest_survey/submissions/uuid:20bcee82-4a22-4381-a6aa-f926fc85fb22/attachments/my.file.mp3
 
 This location is a web page that causes a web browser to download a file. It cannot be used directly to embed images or video on any website or application.
 
@@ -237,7 +233,7 @@ Submission Details
 
 As of version 1.2, each submission has its own detail page which provides basic information about the submission, an activity history of action and discussion on that submission, and tools for updating the submission review state and data itself.
 
-   .. image:: /img/central-submissions/details.png
+.. image:: /img/central-submissions/details.png
 
 The title at the top is pulled from the ``instance_name`` if there is one, otherwise it will be the automatically assigned ``instanceID``. We recommend you :ref:`define an instance_name <instance-name>` based on the data in each submission. This is especially important if you plan on using this page a lot, because it makes navigation much easier to have friendly names at the top of the page and in the web browser title and tab.
 
@@ -259,5 +255,5 @@ Any time a user edits a submission, they will see a note when they are returned
 
 Finally, when edits are submitted, the submission :ref:`review state <central-submissions-review-states>` will automatically be set to :guilabel:`Edited`, and (as of version 1.3) you will see the changes between versions in the Submission Detail activity feed. Please note that Central will show you the differences between versions, but it doesn't know the exact actions you took to cause those changes. Sometimes the differences shown are not the same as the actions taken, but the resulting data will appear exactly as edited.
 
-   .. image:: /img/central-submissions/diff.png
+.. image:: /img/central-submissions/diff.png
 

docs/central-upgrade.rst

@@ -420,7 +420,7 @@ This is *critical infrastructure upgrade*. In particular, it upgrades the includ
 
              $ sudo ./files/postgres14/upgrade/check-available-space
 
-          *If you don't have enough space,* **stop here** and resume when you have increased the disk space available. You may achieve this by clearing out data you don't need (e.g., logs) or by    increasing the total disk space available (e.g., by :ref:`adding external storage <central-install-digital-ocean-external-storage>`).
+          *If you don't have enough space,* **stop here** and resume when you have increased the disk space available. You may achieve this by clearing out data you don't need (e.g., logs) or by    increasing the total disk space available.
 
        #. **Create a file to prove that you're carefully reading these instructions.** This is required to continue.
 

docs/collect-import-export.rst

@@ -10,7 +10,7 @@ Managing and distributing settings QR codes
 
 .. warning::
 
-  Settings QR codes generally include confidential information and should be kept private. Make sure to follow :doc:`Android security best practices <collect-security>`.
+  Settings QR codes generally include confidential information and should be kept private. Make sure to follow :ref:`Android security best practices <device-recommendations>`.
 
 When using :ref:`Central App Users <central-users-app-overview>`, settings QR codes are used as `passwordless authentication <https://www.cyberark.com/what-is/passwordless-authentication/>`_. When using other servers, settings QR codes may contain plaintext passwords. Settings QR codes should be treated with the same care as passwords would be. We recommend scanning them directly from the Central user interface if possible.
 

docs/collect-intro.rst

@@ -24,7 +24,7 @@ Collect supports location, audio, images, video, barcodes, signatures, multiple-
 Supported devices
 -------------------
 
-You can use Collect with a wide range of Android devices and the only requirement is that they must run Android 5 or above. That said, we generally recommend using Android 10 or higher for the best :doc:`security <collect-security>` and performance.
+You can use Collect with a wide range of Android devices and the only requirement is that they must run Android 5 or above. That said, we generally recommend using Android 10 or higher for the best :ref:`security <device-recommendations>` and performance.
 
 The device specification that will make the biggest difference for Collect performance is RAM. For forms with a lot of complex :doc:`logic <form-logic>`, many :ref:`repeat instances <repeats>`, or 60k+ elements in a choice list, Entity List or attached data file, we recommend aiming for devices with at least 4 GB of RAM. Devices with less RAM will likely work even for complex forms but may feel slow and even occasionally crash.
 

docs/form-operators-functions.rst

@@ -514,7 +514,7 @@ Encoding and decoding strings
 
 .. function:: extract-signed(string, public-key)
 
-  Given a base64-encoded, signed string and public key as inputs, verifies that the first 64 bytes are a valid `Ed25519 <https://en.wikipedia.org/wiki/EdDSA> signature`_. If the signature is valid, returns the message (non-signature) portion of the contents as a UTF-8 string. If the signature is not valid, returns an empty string.
+  Given a base64-encoded, signed string and public key as inputs, verifies that the first 64 bytes are a valid `Ed25519 signature <https://en.wikipedia.org/wiki/EdDSA>`_. If the signature is valid, returns the message (non-signature) portion of the contents as a UTF-8 string. If the signature is not valid, returns an empty string.
 
 .. _math-functions:
 
@@ -725,7 +725,7 @@ Geography
 
   It takes into account the circumference of the Earth around the Equator but does not take altitude into account.
 
-.. function:: distance(nodeset | geoshape | geotrace)
+.. function:: distance(nodeset | geoshape | geotrace | geopoint, geopoint [, geopoint [...]])
 
   Returns the distance, in meters, of either:
 
@@ -758,18 +758,37 @@ Geography
     calculate, calculated_distance, , distance(${trace})
     note, display_distance, Calculated distance: ${calculated_distance}
 
-  - concatenated geopoints
+  - a list of geopoints either specified as strings or references to other fields
 
   .. csv-table:: survey
     :header: type, name, label, calculation
 
     geopoint, point1, Record a Geopoint
     geopoint, point2, Record a Geopoint
-    calculate, concatenated_points, , "concat(${point1},' ; ', ${point2})"
-    calculate, calculated_distance, , distance(${concatenated_points})
-    note, display_distance, Calculated distance: ${calculated_distance}
+    calculate, dist, , "distance(${point1}, ${point2})"
+    note, dist_note, Calculated distance: ${dist}
+
+  The ``distance`` function takes into account the circumference of the Earth around the equator but does not take altitude into account. The longer the line segments are, the less accurate the computed distance will be. Additionally, distance calculations closer to the equator are more accurate than ones close to the poles.
+
+  You can use the ``distance`` function for things like basic reverse geocoding and basic geofencing. See `this sample form <https://docs.google.com/spreadsheets/d/1gMOeQdq-DhXz4C1WvgPZ3hsdXDF2mDMYOKTbsRco4Hg>`_ for multiple examples.
+
+.. function:: geofence(geopoint, geoshape)
+
+  Returns ``True`` if the specified point is inside the specified geoshape, ``False`` otherwise.
+
+  .. csv-table:: survey
+    :header: type, name, label, relevant, appearance
+
+    geoshape, shape, Specify a shape to use as a fence
+    geopoint, point, Select a point to see whether it is in the fence,,placement-map
+    note, in_note, Point is inside the fence, "geofence(${point}, ${shape})"
+    note, out_note, Point is outside the fence, "${point} != '' and not(geofence(${point}, ${shape}))"
+
+  You can also find this example `in Google Sheets <https://docs.google.com/spreadsheets/d/1UKLC9ZBT5CdquUqmyMvf2Ofspl5IC2YRPBhV8ruo5bQ>`_
+
+  The ``geofence`` function is helpful for things like validating that a data collector is the expected location when filling out a form. If you don't need to define precise boundaries, you can instead use the :func:`distance` function to validate that a data collector is within a certain distance of the center of the target location. 
 
-  It takes into account the circumference of the Earth around the Equator and does not take altitude into account.
+  If you need to validate that data collectors are at an indoor location, keep in mind that location capture is generally inaccurate indoors unless there are cellular and WiFi signals available. You can address this by asking data collector to capture the location of the building front door before entering or by defining a fence that is, for example, 5 to 10 meters outside the real boundaries of the building.
 
 .. _utility-functions:
 

docs/security.rst

@@ -92,9 +92,11 @@ The software is the same either way you choose, but there are important security
   SSL Certificates (HTTPS),✅,✅,The ODK server requires HTTPS and uses Let's Encrypt certs with TLS 1.3 and an `A+ rating from SSL Labs <https://www.ssllabs.com/ssltest/analyze.html?d=production.getodk.cloud>`_.
   Uptime Management,✅,❓,"ODK Cloud has had `99.9999% uptime <https://status.getodk.org/>`_ since April 2023."
 
+
+.. _device-recommendations:
+
 Device recommendations
 ----------------------
-.. _device-recommendations:
 
 It is important that you secure devices running Collect. We strongly recommend:
 
@@ -106,9 +108,10 @@ It is important that you secure devices running Collect. We strongly recommend:
 
 Collect's :ref:`protected settings <admin-settings>` can set and hide options that may further increase your data security.
 
+.. _security-audits:
+
 Security audits
 ---------------
-.. _security-audits:
 
 In addition to internal security reviews of every change to ODK, we commission independent white-box penetration tests, source code audits, and reviews of our architecture and processes. After mitigating issues, we publish the results.
 

docs/spelling_wordlist.txt

@@ -168,6 +168,8 @@ Gejibo
 geo
 geocoding
 geodata
+geofence
+geofencing
 geojson
 GeoJSON
 Geolocation