From b1937fac976b9477616cdb6a8f1bc31d7dad41ae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=C3=A9l=C3=A8ne=20Martin?= Date: Thu, 10 Sep 2026 16:01:08 -0700 Subject: [PATCH 1/3] Update docs for v2026.3 --- docs/central-entities.rst | 45 +++++++++---------- docs/central-projects.rst | 12 ----- docs/central-submissions.rst | 2 +- docs/central-users.rst | 4 +- docs/entities-intro.rst | 4 +- docs/img/central-entities/entity-upload.png | 4 +- .../central-submissions/public-link-new.png | 4 +- 7 files changed, 28 insertions(+), 47 deletions(-) diff --git a/docs/central-entities.rst b/docs/central-entities.rst index daaa78085..9f9d55c18 100644 --- a/docs/central-entities.rst +++ b/docs/central-entities.rst @@ -131,7 +131,7 @@ Creating an Entity List in the Central Interface To create an Entity List directly in the Central web interface, first navigate to the Project which should contain this Entity List. Open the :guilabel:`Entity Lists` tab. At the top of this page, you will see a :guilabel:`New` button you can click to create a new Entity List. You will only be asked for its name. Because Entity List names are used as identifiers throughout ODK, there are some restrictions on what you can choose as the name. If Central keeps rejecting your name, it is best to stick with basic letters and numbers. -Once your Entity List is created, you can define the properties it should have so that you can :ref:`upload Entities from CSV ` to populate your new list. To add a new property, click on the :guilabel:`New` button on the :guilabel:`Properties` tab. +Once your Entity List is created, you can manually define new properties from the :guilabel:`Properties` tab, create a form that writes Entities to it, or :ref:`upload Entities from CSV `. .. _central_entities_creating-definition: @@ -169,38 +169,28 @@ You can also try a follow-up Form Draft by manually creating a CSV of sample Ent Importing CSVs into Entity Lists --------------------------------- -.. versionadded:: v2024.1 +In a lot of cases you already have data that you would like to load into your Entity List. To do so, navigate to the Entity List you'd like to load your data into, and select the :guilabel:`Entities` tab. At the top of that screen, click on the :guilabel:`Upload Entities` button. -In a lot of cases you already have data sitting around that you would like to load into your Entity List. Starting with Central v2024.1, you can do this directly in Central. - -To get started, navigate to the Entity List you'd like to load your data into, and select the :guilabel:`Data` tab. At the top of that screen, click on the :guilabel:`Upload` button. - -.. image:: /img/central-entities/entity-upload.png - -You should see a screen that looks similar to the above. You can see data tables with column headings matching the properties in your Entity List. If you have any Entities in this Entity List already, you will see a preview of them in the table above. +You will see a data table with column headings matching the properties in your Entity List. If you have any Entities in this Entity List already, you will see a preview of a few of them. To add your new data to this Entity List, you will first need to convert it into a ``.csv`` file if it is not already. You can use common spreadsheet applications like Excel, Google Sheets, or OpenOffice Calc to do this. There are some additional requirements on this data file: -1. The first row (and *only* the first row) is a header row labeling each of your columns. -2. Your header row must exactly match your Entity List properties. -3. In addition to your Entity List properties, you must also include a ``label`` column, where you can provide the name for each Entity that is used when displaying the Entity in Central and Collect. +1. The first row (and *only* the first row) is a header row that corresponds to your Entity properties. +2. The first row must include a ``label`` column, where you can provide the name for each Entity that is used when displaying the Entity in Central and Collect. If you're not sure what this should look like, you can download a sample template ``.csv`` file by clicking the :guilabel:`Download a Data Template` button. -.. note:: - *What if my Entity List doesn't have any properties yet? Can't you just read them from my file?* +Once you have a ``.csv`` file, you can select it for upload either by dragging it over the box, or by clicking on the :guilabel:`choose a file` button. If there is anything Central is worried about, you will see errors and warnings above your import data. Errors must be fixed before the file can be uploaded, while warnings can be reviewed and bypassed when appropriate. - Not yet. Please `let us know `_ if this is something you would like to see! For now, you will need to add the properties manually. The quickest way to do this is :ref:`in the Entity Properties section ` in Central. - -Once you have a ``.csv`` file that meets these requirements, you can select it for upload either by dragging it over the box, or by clicking on the ``choose one`` button. If your file doesn't meet the above requirements, or if Central can't understand how to read the file, you will see an error message appear. Otherwise, you will see a preview of the data that Central found in the file and how it will load into the Entity List. +.. image:: /img/central-entities/entity-upload.png -.. image:: /img/central-entities/entity-upload-preview.png +Once errors are resloved, you will see a preview of the data that Central found in the file and how it will load into the Entity List. -Looking at this view, you can match up the columns and ensure your data is loading into the correct places. You can also verify that the number of records in your file matches the number of Entities Central found to import. It is also often a good idea to check at least the last few rows of your import data in the preview table in addition to the beginning. If there is anything Central is worried about, you will see warnings above your import data. Warnings at this point mean that Central is able to import your file, but is not completely sure it has interpreted your file correctly. If you don't see any problems looking over the preview, you can feel safe to ignore the warnings. +Looking at this view, you can match up the columns and ensure your data is loading into the correct places. You can also verify that the number of records in your file matches the number of Entities Central found to import. It is also often a good idea to check at least the last few rows of your import data in the preview table in addition to the beginning. If you don't see any problems looking over the preview, you can feel safe to ignore any warnings. You can continue uploading new versions of your file until you are satisfied with the preview. -Click on the :guilabel:`Append data` button to import your data into your Entity List. Be sure you are ready to proceed: there isn't currently an easy way to undo an import. +Click on the :guilabel:`Append Entities` button to import your data into your Entity List. Be sure you are ready to proceed: there isn't currently an easy way to undo an import. .. _central-entities-create-manually: @@ -434,7 +424,7 @@ By default, every Web User, App User and Public Access Link receives every Entit You have two options for filtering Entities on the server side: * Ownership filtering, which limits users to Entities they own. -* Property filtering, which compares Entity properties with Custom Properties assigned to the requesting App User or Public Access Link. +* Property filtering, which compares Entity properties with Properties assigned to the requesting App User or Public Access Link. Web Users with the Administrator, Project Manager, or Project Viewer roles are unaffected by either filter type and continue to receive every Entity. @@ -448,14 +438,14 @@ This access type applies to App Users, Web Users with the Data Collector role, a Filter by property """""""""""""""""" -Property filters compare the value of an Entity property (such as ``region`` or ``role``) with the value of the corresponding :ref:`Custom Property ` on the App User or Public Access Link requesting the Entity List. +Property filters compare an Entity property with a property on the App User or Public Access Link accessing the Entity List. For example, if an App User has a ``region`` property with the value ``North``, you can configure an Entity List to provide that user only with Entities whose ``region`` property is also ``North``. .. warning:: Property filters currently apply only to App Users and Public Access Links. If a property filter is configured, Web Users with the Data Collector role will not receive any Entities. Currently, you can only filter on user-defined Entity properties, not on system properties like ``label`` or creation date. -By defining Custom Properties and creating filter rules, you can ensure users only receive the Entities relevant to their work. Like :ref:`choice filters ` in forms, property filters compare values to determine which Entities are available. +By defining user Properties and creating filter rules, you can ensure users only receive the Entities relevant to their work. Like :ref:`choice filters ` in forms, property filters compare values to determine which Entities are available. Common use cases include: @@ -467,9 +457,14 @@ For example, this rule ensures that users only receive Entities whose region pro .. image:: /img/central-entities/filter-by-property.* -To define a property filter, you need to first create a :ref:`Custom Property ` for the project and make sure the Entity List has an Entity property to compare against. Then, select the Entity property and the Custom Property that you want to compare. Currently, only exact equality is supported. +To define a property filter, you need to first add a user Property to your App Users and Public Access Links. Do this by creating a new user or link or by editing an existing one. You also need to make sure that the Entity List has an Entity property to compare against. Then, select the Entity property and the user Property that you want to compare. Currently, only exact equality is supported. + +When filtering by Property, every App User and Public Link that can access the Entity List through a Form should have a value for the Property. A blank value for that Property will not match any Entities so the user will receive an empty list. + +View as App User +"""""""""""""""" -When filtering by property, every App User and Public Link that can access the Entity List through a Form should have a value for the Custom Property. A blank value for that property will not match any Entities so the user will receive an empty list. +Use the :guilabel:`View as` filter to see which Entities are available to a specific App User. Select an App User to preview the Entity List using that user's access. This is useful for testing property-based access filters and verifying that users can access the expected Entities. .. _deleting-entity-lists: diff --git a/docs/central-projects.rst b/docs/central-projects.rst index 2602cc937..ec1e29670 100644 --- a/docs/central-projects.rst +++ b/docs/central-projects.rst @@ -123,18 +123,6 @@ As you make changes to Form States and App User access, they will be highlighted .. tip:: When you first create an App User, it will not have access to any Forms. When you first create a Form, no App Users will be allowed to access it. -.. Linked from Central -.. _central-custom-properties: - -Managing Custom Properties -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Custom Properties let you control which Entities each App User or Public Link receives. For example, if your organization works across multiple regions, you can create a ``region`` Custom Property, assign each App User a region, and configure an :ref:`Entity List access filter ` so each user receives only Entities from their region. - -Go to the :guilabel:`Custom Properties` tab for a project to see the available Custom Properties and add new ones. Custom Property names follow the same rules as form field names or Entity property names: they can't have spaces in them, must start with a letter or underscore, and can only contain letters, numbers, and a limited set of symbols (``_``, ``-``, and ``.``). - -Once a Custom Property is defined, assign values to App Users or Public Links. You can then create :ref:`Entity List access filters ` that compare Entity properties with those Custom Properties to determine which Entities each user receives. - .. _central-project-archive: Archiving a Project diff --git a/docs/central-submissions.rst b/docs/central-submissions.rst index 5c3023084..44cede7d0 100644 --- a/docs/central-submissions.rst +++ b/docs/central-submissions.rst @@ -57,7 +57,7 @@ To create a Public Access Link, go to the Form's :guilabel:`Public Access` tab. In the window that appears, you'll need to name the Link. This name is for your own identification purposes in the administration website, and is not displayed to respondents. -If the project has :ref:`Custom Properties `, they can be set here or by editing a Public Access Link later. This allows :ref:`Entity filter rules ` to control which Entities are delivered when forms are opened through a Public Access Link. +You can assign properties to a Public Access Link. These properties can be used by Entity List access filters to :ref:`control which Entities are delivered ` when a form is opened through the link. You'll also need to decide whether to allow multiple submissions per respondent. Normally, respondents filling a Form through a Public Link will be redirected to a thank you page after sending a Submission. Pressing the back button will not bring them back to the Form but they could send in another Submission by visiting the Link again. Checking the :guilabel:`Single Submission` checkbox enables basic protection against more than one Submission being made from the same browser. diff --git a/docs/central-users.rst b/docs/central-users.rst index d58fdb55b..c0dadd221 100644 --- a/docs/central-users.rst +++ b/docs/central-users.rst @@ -237,9 +237,9 @@ Alternatively, App Users can represent devices (device1, device2) or roles (Hosp You'll also need to design a way to distribute settings QR codes such that they remain private. See :doc:`settings QR code ` documentation for ideas. -If the project has :ref:`Custom Properties `, you can set their values when creating or editing an App User. +App User Properties let you associate information such as a region, team, or supervisor with an App User. These Properties can be used to :ref:`control which Entities the App User can access `. You can add Properties when creating an App User and edit them later. -Once you provide a Display Name and optional Custom Properties for the user, click :guilabel:`Create`. The user will be created, and you will see a screen that looks like this: +Once you provide a Display Name and optional Properties for the user, click :guilabel:`Create`. The user will be created, and you will see a screen that looks like this: .. image:: /img/central-users/app-users-created.png :width: 400px diff --git a/docs/entities-intro.rst b/docs/entities-intro.rst index a2631c107..031a51ef8 100644 --- a/docs/entities-intro.rst +++ b/docs/entities-intro.rst @@ -187,9 +187,7 @@ If you usually have Internet connectivity, this is unlikely to be very important I need to assign specific Entities to specific data collectors, how can I represent this? ----------------------------------------------------------------------------------------- -:ref:`Entity filtering ` allows administrators to control which Entities are delivered to App Users and Public Access Links. - -Using :ref:`Custom Properties ` and filter rules, users can receive only the Entities relevant to their work. For example, a field worker assigned to a district can receive only Entities from that district. +:ref:`Entity filtering ` allows administrators to control which Entities are delivered to App Users and Public Access Links. For example, a field worker assigned to a district can receive only Entities from that district. You can also filter what a user sees within a Form by using a :ref:`select_one_from_file ` with a :ref:`choice_filter `. This doesn't limit the amount of data sent to each device but it can significantly reduce the amount of options shown to each user and can help speed up :ref:`lookup expressions `. diff --git a/docs/img/central-entities/entity-upload.png b/docs/img/central-entities/entity-upload.png index f33880eff..d41f4d916 100644 --- a/docs/img/central-entities/entity-upload.png +++ b/docs/img/central-entities/entity-upload.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:c3a5c9133c91914d298c23a467982d0b5bfbfa82b1b097db1b8c3d6a6eea4e30 -size 93758 +oid sha256:8f8f4bc49f44e9c869c658e12ca10048ed45847fa40825940dd08f12e2db58f6 +size 128683 diff --git a/docs/img/central-submissions/public-link-new.png b/docs/img/central-submissions/public-link-new.png index 19ddceed6..f46256c68 100644 --- a/docs/img/central-submissions/public-link-new.png +++ b/docs/img/central-submissions/public-link-new.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:eed4c318f7923767c979162584b9373a0afbbcab9f3c8d03486da53781988306 -size 228335 +oid sha256:a224b3b1b05daa378939700e39ce2c7e48591d9a52828ee256dc7df24358911d +size 276337 From 80a5422c41b3a3d9e242d902cb007a5b57e5d738 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=C3=A9l=C3=A8ne=20Martin?= Date: Thu, 10 Sep 2026 16:05:38 -0700 Subject: [PATCH 2/3] No special upgrade instructions --- docs/central-upgrade.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/central-upgrade.rst b/docs/central-upgrade.rst index 049527313..b115f4054 100644 --- a/docs/central-upgrade.rst +++ b/docs/central-upgrade.rst @@ -15,6 +15,7 @@ To upgrade, start by reviewing upgrade notes for all versions between your curre Upgrade notes ------------- +* Central v2026.3: no upgrade notes * :ref:`Central v2026.2 `: special instructions if you use direct backups via API or build frontend from source * :ref:`Central v2026.1 `: plan for longer than usual downtime, update ``.env`` if you need to configure custom database SSL * :ref:`Central v2025.4 `: perform database maintenance From d802a060e4d4c29b4cfa72253fb8b591922dc923 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=C3=A9l=C3=A8ne=20Martin?= Date: Thu, 10 Sep 2026 16:06:32 -0700 Subject: [PATCH 3/3] Fix typo --- docs/central-entities.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/central-entities.rst b/docs/central-entities.rst index 9f9d55c18..e30307d45 100644 --- a/docs/central-entities.rst +++ b/docs/central-entities.rst @@ -186,7 +186,7 @@ Once you have a ``.csv`` file, you can select it for upload either by dragging i .. image:: /img/central-entities/entity-upload.png -Once errors are resloved, you will see a preview of the data that Central found in the file and how it will load into the Entity List. +Once errors are resolved, you will see a preview of the data that Central found in the file and how it will load into the Entity List. Looking at this view, you can match up the columns and ensure your data is loading into the correct places. You can also verify that the number of records in your file matches the number of Entities Central found to import. It is also often a good idea to check at least the last few rows of your import data in the preview table in addition to the beginning. If you don't see any problems looking over the preview, you can feel safe to ignore any warnings. You can continue uploading new versions of your file until you are satisfied with the preview.