From 5bc5d049567131d8ef14d502c87ec9b807d11e21 Mon Sep 17 00:00:00 2001 From: Languages add-on Date: Fri, 12 Apr 2024 07:45:11 +0200 Subject: [PATCH 1/5] Added translation using Weblate (French) --- help/fr/docs/authorship.md | 52 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 help/fr/docs/authorship.md diff --git a/help/fr/docs/authorship.md b/help/fr/docs/authorship.md new file mode 100644 index 000000000..62c7768c4 --- /dev/null +++ b/help/fr/docs/authorship.md @@ -0,0 +1,52 @@ +Authorship columns +=================== + +Sometimes it is useful to have columns that record who created individual records, and +who last updated them. Grist lets you create such columns easily. It also automatically +tracks document changes in the Activity tab of Document History, but nevertheless it is +convenient to have that information in tabular form available to formulas and filters, +and authorship columns let you do that. + +## A "Created By" column + +Suppose we want to fill a column automatically with the name of the creator +of each record as they are added. As a first step, add a column called +(for example) `Created By`. In the column options in the side panel +(see [Columns](col-types.md) for a refresher), click +`Set trigger formula` action. + +![starting a Created-By column](images/formulas/formulas-created-by-convert.png) + +Set `user.Name`{: .formula} as the column's formula. There are other possibilities, +such as `user.Email`{: .formula}, a unique `user.UserID`{: .formula}, and so on. The +user information available is the same as that in [Access rule conditions](access-rules.md#access-rule-conditions). +Time information is available as well (see [Timestamp columns](timestamps.md)). +But let's stick with `user.Name`{: .formula} for now. + +![a Created-By column](images/formulas/formulas-created-by-final.png) + +Now, to set the column whenever a record is created, make sure that `Apply to new records` +option is checked. And that's it! Now whenever a record is created, the `Created At` +column will be set to the name of the user creating it: + +![a Created-By example](images/formulas/formulas-created-by-autofill.png) + + +## An "Updated By" column + +If we want a column that stores who last edited a record (as opposed to its creator), +the procedure is similar to that for [a "Created By" column](authorship.md#a-created-by-column), +but instead of `Apply to new records`, +select `Apply on record changes`. Then select `Any field` (assuming you want any +change in a record to count as an update) and press `OK`. You can alternatively +pick and choose which columns, when updated, will trigger the formula. + +![an Updated-By column](images/formulas/formulas-updated-by-setup.png) + +Here is an example the the new column at work - when `Cotton Candy v Candy Floss` +is updated,a user name appears for that record: + +![an Updated-By column](images/formulas/formulas-updated-by-autofill.png) + +!!! note "It is still possible for a user to manually edit cells in the `Created By` and `Updated By` columns. If you don't want that to be allowed, use [access rules](access-rules.md) to forbid it." + From c105939c44333a806fe6b4b8eeb6bb33fa825e11 Mon Sep 17 00:00:00 2001 From: Nicolas Imbert Date: Tue, 16 Apr 2024 13:17:38 +0000 Subject: [PATCH 2/5] Translated using Weblate (French) Currently translated at 100.0% (14 of 14 strings) Translation: grist-help/authorship Translate-URL: https://hosted.weblate.org/projects/grist-help/authorship/fr/ --- help/fr/docs/authorship.md | 82 ++++++++++++++++++++++---------------- 1 file changed, 47 insertions(+), 35 deletions(-) diff --git a/help/fr/docs/authorship.md b/help/fr/docs/authorship.md index 62c7768c4..687a9aa0d 100644 --- a/help/fr/docs/authorship.md +++ b/help/fr/docs/authorship.md @@ -1,52 +1,64 @@ -Authorship columns +Colonne de Paternité =================== -Sometimes it is useful to have columns that record who created individual records, and -who last updated them. Grist lets you create such columns easily. It also automatically -tracks document changes in the Activity tab of Document History, but nevertheless it is -convenient to have that information in tabular form available to formulas and filters, -and authorship columns let you do that. +Il est parfois utile d'avoir des colonnes qui enregistrent le nom de la personne +qui a créée une nouvelle ligne ou mis à jour de la donnée. Grist permet de créer +facilement ce type de colonnes. Grist va suivre automatiquement les +modifications apportées au document dans l'onglet "Historique du document", mais +il est parfois pratique de disposer de ces informations sous forme de tableau +pour les formules et les filtres, et les colonnes de Paternité vous permettent +de le faire. -## A "Created By" column +## Une colonne "Créé par" -Suppose we want to fill a column automatically with the name of the creator -of each record as they are added. As a first step, add a column called -(for example) `Created By`. In the column options in the side panel -(see [Columns](col-types.md) for a refresher), click -`Set trigger formula` action. +Supposons que nous voulions remplir automatiquement une colonne avec le nom du +créateur de chaque nouvelle ligne au fur et à mesure qu'elles sont ajoutées. +Pour commencer, ajouter une colonne appelée (par exemple) `Créé par`. Dans les +options de colonne du panneau latéral (voir [Colonnes](col-types.md) pour un +rappel), cliquez sur l'action `Définir une formule d'initialisation`. -![starting a Created-By column](images/formulas/formulas-created-by-convert.png) +![créer une colonne Créé Par](images/formulas/formulas-created-by-convert.png) -Set `user.Name`{: .formula} as the column's formula. There are other possibilities, -such as `user.Email`{: .formula}, a unique `user.UserID`{: .formula}, and so on. The -user information available is the same as that in [Access rule conditions](access-rules.md#access-rule-conditions). -Time information is available as well (see [Timestamp columns](timestamps.md)). -But let's stick with `user.Name`{: .formula} for now. +Définissez `user.Name`{ : .formula} comme formule de la colonne. Il existe +d'autres possibilités, comme `user.Email`{ : .formula}, ou `user.UserID`{ : +.formula}, etc. Les informations disponibles sur l'utilisateur sont les mêmes +que dans les [Permissions Avancées](access-rules.md#access-rule-conditions). +L'horodatage est également disponible (voir [Colonnes +d'horodatage](timestamps.md)). Mais restons-en à `user.Name`{ : .formula} pour +l'instant. -![a Created-By column](images/formulas/formulas-created-by-final.png) +![une colonne Créé par](images/formulas/formulas-created-by-final.png) -Now, to set the column whenever a record is created, make sure that `Apply to new records` -option is checked. And that's it! Now whenever a record is created, the `Created At` -column will be set to the name of the user creating it: +Maintenant, afin de paramétrer la colonne pour chaque nouvelle ligne créée, +assurez-vous que l'option `Appliquer sur les nouvelles lignes uniquement` est +cochée. Et c'est tout! Maintenant, à chaque fois qu'une nouvelle ligne est +créée, la colonne `Créé par` aura le nom de l'utilisateur qui a créé cette ligne -![a Created-By example](images/formulas/formulas-created-by-autofill.png) +![un exemple Créé par](images/formulas/formulas-created-by-autofill.png) -## An "Updated By" column +## Une colonne "Mis à jour par" -If we want a column that stores who last edited a record (as opposed to its creator), -the procedure is similar to that for [a "Created By" column](authorship.md#a-created-by-column), -but instead of `Apply to new records`, -select `Apply on record changes`. Then select `Any field` (assuming you want any -change in a record to count as an update) and press `OK`. You can alternatively -pick and choose which columns, when updated, will trigger the formula. +Si nous voulons une colonne qui enregistre le nom de la dernière personne qui a +modifié une ligne (par opposition à la personne qui a créé la ligne), la +procédure est similaire à [une colonne "Créé +par"](authorship.md#a-created-by-column), mais au lieu de "Appliquer sur les +nouvelles lignes uniquement", sélectionnez "Réappliquer en cas de modification +de la ligne". Sélectionnez ensuite `N'importe quel champ` (en supposant que vous +voulez que tout changement dans une ligne soit considéré comme une mise à jour) +et appuyez sur `OK`. Par ailleurs, vous pouvez également choisir que certaines +colonnes en particulier qui, lorsqu'elles seront mises à jour, déclencheront la +formule. -![an Updated-By column](images/formulas/formulas-updated-by-setup.png) +![une colonne Mise à jour par](images/formulas/formulas-updated-by-setup.png) -Here is an example the the new column at work - when `Cotton Candy v Candy Floss` -is updated,a user name appears for that record: +Voici un exemple de la nouvelle colonne à l'œuvre - lorsque `Cotton Candy v +Candy Floss` est mise à jour, un nom d'utilisateur apparaît pour cette ligne : -![an Updated-By column](images/formulas/formulas-updated-by-autofill.png) +![une colonne Mise à jour par](images/formulas/formulas-updated-by-autofill.png) -!!! note "It is still possible for a user to manually edit cells in the `Created By` and `Updated By` columns. If you don't want that to be allowed, use [access rules](access-rules.md) to forbid it." +!!! note "Il est toujours possible pour un utilisateur de modifier manuellement +les cellules dans les colonnes `Créé par` et `Mis à jour par`. Si vous ne voulez +pas que cela soit autorisé, utilisez les [Permissions Avancées](access-rules.md) +pour l'interdire." From fd2fbc1b53abe37c8827d4cad8110158d8b87415 Mon Sep 17 00:00:00 2001 From: Nicolas Imbert Date: Tue, 16 Apr 2024 15:43:15 +0000 Subject: [PATCH 3/5] Translated using Weblate (French) Currently translated at 100.0% (14 of 14 strings) Translation: grist-help/authorship Translate-URL: https://hosted.weblate.org/projects/grist-help/authorship/fr/ --- help/fr/docs/authorship.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/help/fr/docs/authorship.md b/help/fr/docs/authorship.md index 687a9aa0d..2ad1eb673 100644 --- a/help/fr/docs/authorship.md +++ b/help/fr/docs/authorship.md @@ -1,4 +1,4 @@ -Colonne de Paternité +Les Colonnes de Paternité =================== Il est parfois utile d'avoir des colonnes qui enregistrent le nom de la personne From 90b89ac227c45bd69dcbda3d6ce1cda607adab1d Mon Sep 17 00:00:00 2001 From: Florent Date: Fri, 3 May 2024 17:13:15 +0200 Subject: [PATCH 4/5] Added translation using Weblate (French) --- help/fr/docs/access-rules.md | 439 +++++++++++++++++++++++++++++++++++ 1 file changed, 439 insertions(+) create mode 100644 help/fr/docs/access-rules.md diff --git a/help/fr/docs/access-rules.md b/help/fr/docs/access-rules.md new file mode 100644 index 000000000..bd752b88c --- /dev/null +++ b/help/fr/docs/access-rules.md @@ -0,0 +1,439 @@ +Access rules +============== + +Every Grist document can be [shared with others](sharing.md) +using the `Manage Users` option in the sharing +menu (). +Users can be invited as Viewers, Editors, or Owners (see + [Sharing a document](sharing.md) for a refresher on those roles), or a document can be [shared publicly](sharing.md#public-access-and-link-sharing) with view or edit permissions. +Sometimes, you need more nuance about who can see or edit individual +parts of a document. Access rules give us that power. + +Only the owners of a document can edit its access rules. +When a document is loaded, owners see a tool called + Access Rules +in the left side bar. Click on that to view and edit +access rules. The rules are also accessible via the `Manage Users` option +of the sharing menu +with the `Open Access Rules` button (available only to document Owners). + +Suppose we run a small business sourcing and delivering unusual objects, +organized using a document with two tables, `Orders` and `Financials`. +Now we are taking on more employees, and want to share the document with them while +limiting their access to just what they need. + +![Access rules](images/access-rules/access-rules-example.png) + +## Default rules + +To see the access rules for a document, visit its access rules page by +clicking + Access Rules +in the left sidebar. When no custom rules have been created yet, +the access rules page contains the `Default Rules` for our document: + +![Access rules](images/access-rules/access-rules-page.png) + +These rules say, in summary, that Owners and Editors can do anything within +the document, that Viewers can only read the document, and everyone +else is forbidden all access. These rules cannot be modified, but they +can be overridden. To understand whether a group of rules allows a +certain permission ([Read, Update, Create, Delete, or Structure](access-rules.md#access-rule-permissions)), read +the rules from top to bottom, and find the first applicable rule +that allows (green) or denies (red) that permission. +We'll see plenty of examples as we go. + +## Lock down structure + +By default Owners and Editors are equally powerful within a document, with the ability to create +or delete tables or columns, write formulas, reorganize pages, and so on. + +Suppose we want only the original Owners of the document to be allowed to change +its structure, as we plan to invite other specialized collaborators as Editors. +To do this, uncheck the box for the first rule listed under 'Special Rules' to +disallow editors from editing structure. + +![Access rules](images/access-rules/access-rules-lock-structure.png) + +Once we've made changes, the `SAVE` button becomes an inviting green. We +click `SAVE` for the rule to take effect. + +**Important.** This is an important first step for any document where you intend to block any access to Editors. +Without denying them the structure permission (`S`), anyone with edit access will be able to +create or change formulas. Since formula calculations are not limited by access control rules, +a determined user could use them to retrieve any data from a document. To protect against +that, deny structure permission to users whose access should be limited. + +## Make a private table + +To ensure that only Owners can access a table, such as the `Financials` table in our example, +we click `Add Table Rules` and select the table name, `Financials`. This creates a new empty +group of rules called `Rules for table Financials`. +Then we add a condition for any user who is not an Owner (`user.Access != OWNER`), with all +permissions denied. Selecting `Deny All` from the drop-down beside `R` `U` `C` `D` is a fast +way to set all permissions to denied, or you can click each permission individually to turn +them red. `R` is Read, `U` is Update, `C` is Create, and `D` is Delete +(see [Access rule permissions](access-rules.md#access-rule-permissions)). +Structure (`S`) permissions are not available at the table level. +Once you are done, click `SAVE`. + +![Access rules](images/access-rules/access-rules-private-table.png) + +Now we could go ahead and share the document with a team member +specialized in deliveries, for example. We [share the +document](sharing.md) with them as an Editor so that the restrictions +we've set up apply to them. They won't see the `Financials` table in the +left side bar, and attempts to open it will be denied: + +![Access rules](images/access-rules/access-rules-private-table-is-hidden.png) + +## Seed Rules + +When writing access rules for specific tables, it is fairly common to repeat the same rule across many tables — +for example, always grant owners full read and write permissions. To automatically add a set of rules to all +new table rules, you can write "seed rules." There is a checkbox above default rules that makes the common +case easier with one click. Click it to write a seed rule that will automatically grant owners full access +whenever table rules are added. Click the `>` icon to uncollapse the seed rules table to modify seed rules. + +![access-rules-default-owner-access](images/access-rules/access-rules-default-owner-access.png) + +## Restrict access to columns + +We can restrict a collaborator's access to columns. In our eample, we might +wish to give a delivery specialist more limited access to +the `Orders` table. Perhaps they don't need to see an `Email` column, +or a `Piece` column with details of what is in the parcel. + +Click `Add Table Rules` and select `Orders` to create a rule group for the `Orders` table. +Now, in the `Rules for table Orders` group, click the three-dot icon (...), and +select `Add Column Rule`: + +![Access rules](images/access-rules/access-rules-limit-columns-rules.png) + +In the `Columns` area we have a new `[Add Column]` dropdown to add all the columns +to which we want the rule to apply (in our case `Email` and `Piece`). +For the condition, we could use `user.Email == 'kiwi@getgrist.com'`. This checks +for the email address of Kimberly, our fictional delivery specialist; we +could also check by name or a numeric ID. We turn all available permissions off for +this user on these columns: + +![Access rules](images/access-rules/access-rules-limit-columns-full-rules.png) + +Now that the rules are ready, click `Save`. + +If we have another employee who specializes in sourcing objects, and who needs to +see a different set of columns, we can do that. For example here we add a +rule to withhold `Address` and `Phone` columns from user `Charon`: + +![Access rules](images/access-rules/access-rules-sourcing-single.png) + +## View as another user + +A convenient way to check if access rules work as expected is with the `View As` feature, +available in the `View As` dropdown. This allows an Owner +to open the document as if they were one of the people it is shared +with, to see what their colleague would see. The Owner does not +"become" that colleague - any changes they make will be recorded as +coming from themselves and not the colleague - but they do see the +document from the colleague's perspective. + +![Access rules](images/access-rules/access-rules-view-as.png) + +In our example, we could select Kiwi, and the +document reopens, with a large banner stating that we are viewing it +as Kiwi. The `Piece` and `Email` columns are missing, +and the `Financials` table is surpressed: + +![Access rules](images/access-rules/access-rules-view-as-kiwi.png) + +You can also check in Raw Data to confirm only the expected tables, columns, and rows are exposed. + +![Access rules](images/access-rules/access-rules-view-as-kiwi-raw-data.png) + +When satisfied that everything looks as expected, we click the green `View as Yourself` +button to close this preview, and the document will reload. + +## User attribute tables + +If we are successful and hire many sourcing and delivery people, +then adding them one by one to rules would be tedious. One solution +is to use "user attribute tables." You can add a table to your document +that classifies users as you like, and then use those classes in your +access rules. For example, we can make a table called `Team`, and give it two +columns, `Email` and `Role`, where `Role` is a choice between +`Sourcing` and `Delivery`. + +![Access rules](images/access-rules/access-rules-team-table.png) + +Now we can tell Grist to make information from this table available +for access rules, by clicking on `Add User Attributes`. +Give the attribute any name you like (this will be how we refer to it +in formulas), such as `Team`. Pick the table to read (`Team` also in +this case). Give a user property to match against +rows in this table - in our case we'll use `user.Email`. And the +column to match against, `Email`. + +![Access rules](images/access-rules/access-rules-team-attribute.png) + +Save that. Now we can update our rules to be more general. We find with +autocomplete that we have a new `user.Team` variable available in +condtions. It makes columns from the `Team` available, such as `user.Team.Role`. +Now we can check if the user has a particular role, and apply the permissions +that go with that: + +![Access rules](images/access-rules/access-rules-team-rules.png) + +Great! Doing a spot check, Charon sees the expected columns for someone in +Sourcing. And if we recruit someone else to work with them, we can just add +them in the `Team` table, no rule changes needed. + +![Access rules](images/access-rules/access-rules-view-as-charon.png) + +## Row-level access control + +In our example, as orders are processed, they move from sourcing to delivery phases. +So there's really no need for the two groups to see all the orders at once. Let's add a +column called `Stage` that can be set to `Sourcing` or `Delivery`, so that we +can update access rules to show only the relevant orders. + +![Access rules](images/access-rules/access-rules-stage-column.png) + +In the `Rules for table Orders` group, click the three-dot icon (...), and +select `Add Default Rule` to add a rule that isn't limited to specific columns. +Let's deny access to all rows for non-Owners as a starting point, then add back in the +ones we want. We can do that with the condition `user.Access != OWNER` with +`Deny All` permissions. Then, we add another default rule by clicking `+`, and +add the condition `user.Team.Role == rec.Stage`. The `rec` variable allows +us to express rules that depend on the content within a particular record. +Here, we check if the `Stage` column of a record matches the user's role. +If it is, we allow `R` Read access: + +![Access rules](images/access-rules/access-rules-stage-rules.png) + +Here's how the table looks now as Kimberly (doing deliveries): + +![Access rules](images/access-rules/access-rules-stage-kiwi.png) + +And here's how the table looks as Charon (doing sourcing): + +![Access rules](images/access-rules/access-rules-stage-charon.png) + +Kimberly and Charon now have read-only access to the table. Owners still have full +write access to all rows and columns. + +!!! note "Understanding reference columns in access rules" + You can limit the data team members access to just those rows pertinent to their work. One way to do so is to relate all records in all tables to their respective team members. For example, leads and sales records can reference the sales rep responsible for those records. This quick video explains how. + + + +## Checking new values + +Access rules can be used to permit only certain changes to the document. +Suppose we want `Delivery` people +to be able to change `Stage` from `Delivery` to `Done`, without giving them the +arbitrary rights to edit that column. We can grant them that exceptional right +as follows. +In the `Rules for table Orders` group, click the three-dot icon (...), and +select `Add Column Rule`. Set `[Add Column]` to `Stage`, and mark the U/Update +permission to be granted. For the condition, use this: + +``` +(user.Team.Role == 'Delivery' and + rec.Stage == 'Delivery' and + newRec.Stage == 'Done') +``` + +This checks if the user has the Delivery role, and the record is in the Delivery stage, +and that the user is trying to change the Stage to `Done`. The `newRec` variable is a +variant of `rec` available when the user is proposing to change a record, with `rec` +containing its state before the change, and `newRec` its state after the proposed change. + +![Access rules](images/access-rules/access-rules-delivery-done-rule.png) + +Now, if we view the table as Kiwi, and try to change a `Stage` to `Sourcing`, we are +denied: + +![Access rules](images/access-rules/access-rules-delivery-done-forbid.png) + +If we change a `Stage` to `Done`, it works, and the record disappears from view since +it is no longer in the `Delivery` stage: + +![Access rules](images/access-rules/access-rules-delivery-done-allow.png) + +## Link keys + +Sometimes it is useful to give access to a specific small +slice of the document, for example a single row of a table. Grist offers +a feature called "link keys" that can help with that. Any parameters in +a Grist document URL that end in an underscore are made available to +access rules in a `user.LinkKey` variable. So for example if a document +URL ends in `....?Token_=xx-xx-xx-xx&Flavor_=vanilla`, then `user.LinkKey.Token` +will be set to `xx-xx-xx-xx` and `user.LinkKey.Flavor` to `vanilla`. +Let's work through an example to see how that can be helpful. + +Suppose we have a table of `Orders` and we'd like to occasionally +share information about a single order with someone. To do that with +link keys, we need some kind of hard-to-guess code for each order, +which can be used to access it. Grist has a [`UUID()`](functions.md#uuid) function that +gives a unique, random, and hard-to-guess identifier, so let's add a `UUID` column with +formula `=UUID()`: + +![Access rules](images/access-rules/access-rules-linkkey-uuid-formula.png) + +In fact we want `UUID()` to be called just once per order, when we create +it, and never recomputed (because then it would change). So in the right sidebar +we convert the formula column to a data column, freezing its values: + +![Access rules](images/access-rules/access-rules-linkkey-uuid-convert.png) + +This converts our formula to a trigger formula. We set the formula to apply to new records: + +![Access rules](images/access-rules/access-rules-linkkey-uuid-data.png) + +At this point we have a solid hard-to-guess code for each order in the +`UUID` column, that will be created as we add new orders. It can +be handy at this point to construct links to the document with that +code embedded in them. Grist has a helper for this called +[`SELF_HYPERLINK`](functions.md#self_hyperlink). To add a +link key called ``, just use this function with a +`LinkKey_` argument. In our case, we pass `LinkKey_UUID=$UUID` to +embed the value of the `UUID` column into the URL. We also set `label=$Ref` +to control the text label of the link in the spreadsheet. To show the link, +we set the column type to `Text` and set the `HyperLink` option: + +![Access rules](images/access-rules/access-rules-linkkey-link.png) + +Once we have these links, we can tidy up a little by hiding the +`UUID` and `Ref` columns (see [Column operations](widget-table.md#column-operations) for a refresher on how +to do this): + +![Access rules](images/access-rules/access-rules-linkkey-prune.png) + +The links don't do anything special yet, but we have everything we +need to make that happen now. Here is an example of access rules to +allow anyone with a UUID in their URL to read any order with a +matching UUID (otherwise only owners can read orders in this case): + +![Access rules](images/access-rules/access-rules-linkkey-rule.png) + +And here is what a non-owner now sees, with the UUID of the first order in their +URL: + +![Access rules](images/access-rules/access-rules-linkkey-use.png) + +This is just the beginning of the possibilities. Link keys can give access to +multiple rows across many tables. They can be used in +[User attribute tables](#user-attribute-tables). And the data they give access to +can be within tables, cards, card lists, charts, and custom widgets. + +Check out [another example](https://support.getgrist.com/examples/2021-04-link-keys/) to deepen your understanding of link keys even more. + +## Access rule conditions + +Accress rule conditions contain a formula expressing when the rule +should apply. A blank condition will always apply. When a condition +applies for an action, the permissions associated with the condition are +set to allowed or denied for that action if no earlier rule in the same +group has yet set them. When a condition does not apply, no +permissions are set by that rule, but other rules could set them. + +Formulas are written in a restricted subset of Python. +Variables that may be available in access rules are `user`, `rec`, and `newRec`. + +The `user` variable contains the following members: + + * `user.Access`: one of `owners`, `editors`, or `viewers`, giving how the + document was shared with the user (see [Sharing a document](sharing.md)). + * `user.Email`: the email address of the user (or `anon@getgrist.com` for users who are not logged in). + * `user.UserID`: a numeric ID that is associated with the user. + * `user.Name`: the user's name (or `Anonymous` if unavailable). + * `user.LinkKey`: an object with any access control URL parameters. Access control URL + parameters end in an underscore (which is then stripped). Only available in the + web client, not the API. + * `user.Origin`: The content of the Origin request header. Only available in the API, + not the web client. + * `user.SessionID`: a unique string assigned to anonymous users for the duration of that user's session. For logged in users, `user.SessionID` is always `"u"` + the user's numeric id. + +For an example of using the `user` variable, read [Default rules](access-rules.md#default-rules). + +The `rec` variable contains the state of an individual record/row, for +conditions that need to take that into account. When it is used, that +rule becomes row-specific. That allows, for example, to make certain +rows visible only to certain users, or to prohibit modification of +certain rows by certain users. +For an example of using the `rec` variable, read [Row-level access control](access-rules.md#row-level-access-control). + +The `newRec` variable is available for record/row creation and +updating, and contains the state of a row after a proposed change, +allowing you to selectively allow or deny certain changes. +For an example of using the `newRec` variable, read [Checking new values](access-rules.md#checking-new-values). + +Supported operations in condition formalas are currently: `and`, `or`, +`+`, `-`, `*`, `/`, `%`, `==`, `!=`, `<`, `<=`, `>`, `>=`, `is`, `is +not`, `in`, `not in`. Supported variables are: `user`, `rec`, +`newRec` with their members accessed with `.`. Strings, numbers, and +lists are also supported. If an operation you need is not available, +consider whether you can do part of the work in a formula in the table +itself (see [Access rule memos](access-rules.md#access-rule-memos) for an example). + +Comments are allowed, using `#` or `"""`. If there is a comment in a +rule, then the first comment in a rule that results in a denial of an +action will be reported to the user as a tip for why the action was not +permitted. See [Access rule memos](access-rules.md#access-rule-memos) for an example. + +## Access rule permissions + +A permission controls whether a user can perform a particalar kind of action. +Grist access rules currently deal with 5 kinds of action, which are given +single letter acronyms for convenience: + + * `R` - permission to read cells. + * `U` - permission to update cells. + * `C` - permission to create rows. + * `D` - permission to delete rows. + * `S` - permission to change table structure. + +The `S` structure permission is available in the default access rule +group. Column rules lack the `C` create and `D` delete permissions, +which should be handled in default table rules. + +**Note:** The `S` permission is very powerful. It allows writing formulas, which can access +any data in the document regardless of rules. Since the `S` permission is on by default for +Editors and Owners, any such user would be able to edit a formula and so retrieve any data. + +In other words, having the `S` permission makes it possible to circumvent other rules that prevent +access to data. For this reason, turning it off -- as described above in [Locking down +structure](#lock-down-structure) -- is an important first step in limiting data access. + + +## Access rule memos + +When a user receives an error message denying them access because of a +rule, it can be helpful to give specific details that will help them understand +the problem. You can do this by adding a memo for the condition. First, click +the memo icon to the right of your condition. + +![Comment Icon](images/access-rules/access-rules-comment-icon.png) + +Type the error message you wish to display into the entry box. Be sure to save your changes. + +![Comment Added](images/access-rules/access-rules-comment-added.png) + +When the rule blocks a user from performing an action, the memo will appear as a notification. + +![Duplicate error](images/access-rules/access-rules-dupe-forbidden.png) + +For an explanation of how this particular Access Rule works, see [Access Rules to Restrict Duplicate Records](examples/2023-01-acl-memo.md) + +## Access rule examples + +Along with the extended example of using access rules in this section, we will +collect complete examples of access rule templates and guides here. + + - [Lead lists](examples/2021-03-leads.md): A very simple list of leads, assigned to individuals to follow up, with control of assignments reserved for document owners. +- [Account-based Sales Team](https://templates.getgrist.com/38Dz6nMtzvwC/Account-based-Sales-Team): Sales CRM with deals and contacts assigned to sales reps. Reps can only see their own contacts and deals, but managers can see everything. +- [Public Giveaway](https://templates.getgrist.com/vP7WpQp89hLi/Public-Giveaway): A public giveaway organizer that uses access rules to enforce giveaway rules without requiring claimants to log into Grist. +- [Simple Poll](https://templates.getgrist.com/jd234iH1zDsL/Simple-Poll): A simple poll managed in Grist with access rules to limit one response per visitor. +- [Crowdsourced List](https://templates.getgrist.com/dKztiPYamcCp/Crowdsourced-List): Publicly crowdsourced list with access rules to empower moderators to edit almost anything, but limit visitors to only making and editing their own contributions. +- [Time Sheets](https://templates.getgrist.com/oGxD8EnzeVs6/Time-Sheets): Template to capture contractor timesheets. Access rules permit contractors to view only their historical time sheets, and edit only the active month. +- [Project Management](https://templates.getgrist.com/hifkng53AxyQ/Project-Management/): Track tasks by event and flag tasks at risk. Access rules limit permissions by department, and expand managers' permissions. From c30f412f8ef26271762207628e99c746cd6579da Mon Sep 17 00:00:00 2001 From: Nicolas Imbert Date: Fri, 3 May 2024 15:15:46 +0000 Subject: [PATCH 5/5] Translated using Weblate (French) Currently translated at 3.9% (4 of 101 strings) Translation: grist-help/access-rules Translate-URL: https://hosted.weblate.org/projects/grist-help/access-rules/fr/ --- help/fr/docs/access-rules.md | 562 +++++++++++++++++++---------------- 1 file changed, 300 insertions(+), 262 deletions(-) diff --git a/help/fr/docs/access-rules.md b/help/fr/docs/access-rules.md index bd752b88c..a40ed6378 100644 --- a/help/fr/docs/access-rules.md +++ b/help/fr/docs/access-rules.md @@ -1,212 +1,218 @@ -Access rules +Permissions avancées ============== -Every Grist document can be [shared with others](sharing.md) -using the `Manage Users` option in the sharing -menu (). -Users can be invited as Viewers, Editors, or Owners (see - [Sharing a document](sharing.md) for a refresher on those roles), or a document can be [shared publicly](sharing.md#public-access-and-link-sharing) with view or edit permissions. -Sometimes, you need more nuance about who can see or edit individual -parts of a document. Access rules give us that power. - -Only the owners of a document can edit its access rules. -When a document is loaded, owners see a tool called - Access Rules -in the left side bar. Click on that to view and edit -access rules. The rules are also accessible via the `Manage Users` option -of the sharing menu -with the `Open Access Rules` button (available only to document Owners). - -Suppose we run a small business sourcing and delivering unusual objects, -organized using a document with two tables, `Orders` and `Financials`. -Now we are taking on more employees, and want to share the document with them while -limiting their access to just what they need. +Chaque document Grist peut être [partagé avec d'autres](sharing.md) en utilisant +l'option « Gérer les utilisateurs » dans le menu Partager +(). Les +utilisateurs peuvent être invités en tant que spectateurs (lecture seule), +éditeurs ou propriétaires (voir [Partager un document](sharing.md) pour un +rappel sur ces rôles). Un document peut également être [partagé +publiquement](sharing.md#public-access-and-link-sharing) avec des permissions en +lecture ou écriture. Parfois, il est nécessaire d'aller plus loin et préciser +qui peut voir ou modifier certaines parties d'un document. Les permissions +avancées nous donnent ce pouvoir. + +Seuls les propriétaires d'un document peuvent modifier les permissions avancées. +A l'ouverture du document, les propriétaires voient un outil appelé + +Permissions Avancées dans la barre latérale gauche. Cliquez sur cet outil +pour visualiser et modifier les permissions avancées. Les règles sont également +accessibles via l'option `Gérer les utilisateurs` du menu de partage + avec le +bouton `Ouvrir les règles d'accès` (disponible uniquement pour les propriétaires +du document). + +Imaginons que nous dirigeons une petite entreprise, dont l'activité est la +distribution et la livraison d'objets peu insolites. L'entreprise est gérée à +l'aide d'un document avec deux tables, `Orders` (commandes) et `Financials` +(finances). Nous recrutons de nouveaux employés et souhaitons partager le +document avec eux tout en limitant leur accès à ce dont ils ont besoin. ![Access rules](images/access-rules/access-rules-example.png) ## Default rules -To see the access rules for a document, visit its access rules page by -clicking - Access Rules -in the left sidebar. When no custom rules have been created yet, -the access rules page contains the `Default Rules` for our document: +To see the access rules for a document, visit its access rules page by clicking + +Access Rules in the left sidebar. When no custom rules have been created +yet, the access rules page contains the `Default Rules` for our document: ![Access rules](images/access-rules/access-rules-page.png) -These rules say, in summary, that Owners and Editors can do anything within -the document, that Viewers can only read the document, and everyone -else is forbidden all access. These rules cannot be modified, but they -can be overridden. To understand whether a group of rules allows a -certain permission ([Read, Update, Create, Delete, or Structure](access-rules.md#access-rule-permissions)), read -the rules from top to bottom, and find the first applicable rule -that allows (green) or denies (red) that permission. -We'll see plenty of examples as we go. +These rules say, in summary, that Owners and Editors can do anything within the +document, that Viewers can only read the document, and everyone else is +forbidden all access. These rules cannot be modified, but they can be +overridden. To understand whether a group of rules allows a certain permission +([Read, Update, Create, Delete, or +Structure](access-rules.md#access-rule-permissions)), read the rules from top to +bottom, and find the first applicable rule that allows (green) or denies (red) +that permission. We'll see plenty of examples as we go. ## Lock down structure -By default Owners and Editors are equally powerful within a document, with the ability to create -or delete tables or columns, write formulas, reorganize pages, and so on. +By default Owners and Editors are equally powerful within a document, with the +ability to create or delete tables or columns, write formulas, reorganize pages, +and so on. Suppose we want only the original Owners of the document to be allowed to change its structure, as we plan to invite other specialized collaborators as Editors. -To do this, uncheck the box for the first rule listed under 'Special Rules' to -disallow editors from editing structure. +To do this, uncheck the box for the first rule listed under 'Special Rules' to +disallow editors from editing structure. ![Access rules](images/access-rules/access-rules-lock-structure.png) -Once we've made changes, the `SAVE` button becomes an inviting green. We -click `SAVE` for the rule to take effect. +Once we've made changes, the `SAVE` button becomes an inviting green. We click +`SAVE` for the rule to take effect. -**Important.** This is an important first step for any document where you intend to block any access to Editors. -Without denying them the structure permission (`S`), anyone with edit access will be able to -create or change formulas. Since formula calculations are not limited by access control rules, -a determined user could use them to retrieve any data from a document. To protect against -that, deny structure permission to users whose access should be limited. +**Important.** This is an important first step for any document where you intend +to block any access to Editors. Without denying them the structure permission +(`S`), anyone with edit access will be able to create or change formulas. Since +formula calculations are not limited by access control rules, a determined user +could use them to retrieve any data from a document. To protect against that, +deny structure permission to users whose access should be limited. ## Make a private table -To ensure that only Owners can access a table, such as the `Financials` table in our example, -we click `Add Table Rules` and select the table name, `Financials`. This creates a new empty -group of rules called `Rules for table Financials`. -Then we add a condition for any user who is not an Owner (`user.Access != OWNER`), with all -permissions denied. Selecting `Deny All` from the drop-down beside `R` `U` `C` `D` is a fast -way to set all permissions to denied, or you can click each permission individually to turn -them red. `R` is Read, `U` is Update, `C` is Create, and `D` is Delete -(see [Access rule permissions](access-rules.md#access-rule-permissions)). -Structure (`S`) permissions are not available at the table level. -Once you are done, click `SAVE`. +To ensure that only Owners can access a table, such as the `Financials` table in +our example, we click `Add Table Rules` and select the table name, `Financials`. +This creates a new empty group of rules called `Rules for table Financials`. +Then we add a condition for any user who is not an Owner (`user.Access != +OWNER`), with all permissions denied. Selecting `Deny All` from the drop-down +beside `R` `U` `C` `D` is a fast way to set all permissions to denied, or you +can click each permission individually to turn them red. `R` is Read, `U` is +Update, `C` is Create, and `D` is Delete (see [Access rule +permissions](access-rules.md#access-rule-permissions)). Structure (`S`) +permissions are not available at the table level. Once you are done, click +`SAVE`. ![Access rules](images/access-rules/access-rules-private-table.png) -Now we could go ahead and share the document with a team member -specialized in deliveries, for example. We [share the -document](sharing.md) with them as an Editor so that the restrictions -we've set up apply to them. They won't see the `Financials` table in the -left side bar, and attempts to open it will be denied: +Now we could go ahead and share the document with a team member specialized in +deliveries, for example. We [share the document](sharing.md) with them as an +Editor so that the restrictions we've set up apply to them. They won't see the +`Financials` table in the left side bar, and attempts to open it will be denied: ![Access rules](images/access-rules/access-rules-private-table-is-hidden.png) ## Seed Rules -When writing access rules for specific tables, it is fairly common to repeat the same rule across many tables — -for example, always grant owners full read and write permissions. To automatically add a set of rules to all -new table rules, you can write "seed rules." There is a checkbox above default rules that makes the common -case easier with one click. Click it to write a seed rule that will automatically grant owners full access -whenever table rules are added. Click the `>` icon to uncollapse the seed rules table to modify seed rules. +When writing access rules for specific tables, it is fairly common to repeat the +same rule across many tables — for example, always grant owners full read and +write permissions. To automatically add a set of rules to all new table rules, +you can write "seed rules." There is a checkbox above default rules that makes +the common case easier with one click. Click it to write a seed rule that will +automatically grant owners full access whenever table rules are added. Click the +`>` icon to uncollapse the seed rules table to modify seed rules. ![access-rules-default-owner-access](images/access-rules/access-rules-default-owner-access.png) ## Restrict access to columns -We can restrict a collaborator's access to columns. In our eample, we might -wish to give a delivery specialist more limited access to -the `Orders` table. Perhaps they don't need to see an `Email` column, -or a `Piece` column with details of what is in the parcel. +We can restrict a collaborator's access to columns. In our eample, we might wish +to give a delivery specialist more limited access to the `Orders` table. Perhaps +they don't need to see an `Email` column, or a `Piece` column with details of +what is in the parcel. -Click `Add Table Rules` and select `Orders` to create a rule group for the `Orders` table. -Now, in the `Rules for table Orders` group, click the three-dot icon (...), and -select `Add Column Rule`: +Click `Add Table Rules` and select `Orders` to create a rule group for the +`Orders` table. Now, in the `Rules for table Orders` group, click the three-dot +icon (...), and select `Add Column Rule`: ![Access rules](images/access-rules/access-rules-limit-columns-rules.png) -In the `Columns` area we have a new `[Add Column]` dropdown to add all the columns -to which we want the rule to apply (in our case `Email` and `Piece`). -For the condition, we could use `user.Email == 'kiwi@getgrist.com'`. This checks -for the email address of Kimberly, our fictional delivery specialist; we -could also check by name or a numeric ID. We turn all available permissions off for +In the `Columns` area we have a new `[Add Column]` dropdown to add all the +columns to which we want the rule to apply (in our case `Email` and `Piece`). +For the condition, we could use `user.Email == 'kiwi@getgrist.com'`. This checks +for the email address of Kimberly, our fictional delivery specialist; we could +also check by name or a numeric ID. We turn all available permissions off for this user on these columns: ![Access rules](images/access-rules/access-rules-limit-columns-full-rules.png) Now that the rules are ready, click `Save`. -If we have another employee who specializes in sourcing objects, and who needs to -see a different set of columns, we can do that. For example here we add a +If we have another employee who specializes in sourcing objects, and who needs +to see a different set of columns, we can do that. For example here we add a rule to withhold `Address` and `Phone` columns from user `Charon`: ![Access rules](images/access-rules/access-rules-sourcing-single.png) ## View as another user -A convenient way to check if access rules work as expected is with the `View As` feature, -available in the `View As` dropdown. This allows an Owner -to open the document as if they were one of the people it is shared -with, to see what their colleague would see. The Owner does not -"become" that colleague - any changes they make will be recorded as -coming from themselves and not the colleague - but they do see the -document from the colleague's perspective. +A convenient way to check if access rules work as expected is with the `View As` +feature, available in the `View As` dropdown. This allows an Owner to open the +document as if they were one of the people it is shared with, to see what their +colleague would see. The Owner does not "become" that colleague - any changes +they make will be recorded as coming from themselves and not the colleague - but +they do see the document from the colleague's perspective. ![Access rules](images/access-rules/access-rules-view-as.png) -In our example, we could select Kiwi, and the -document reopens, with a large banner stating that we are viewing it -as Kiwi. The `Piece` and `Email` columns are missing, -and the `Financials` table is surpressed: +In our example, we could select Kiwi, and the document reopens, with a large +banner stating that we are viewing it as Kiwi. The `Piece` and `Email` columns +are missing, and the `Financials` table is surpressed: ![Access rules](images/access-rules/access-rules-view-as-kiwi.png) -You can also check in Raw Data to confirm only the expected tables, columns, and rows are exposed. +You can also check in Raw Data to confirm only the expected tables, columns, and +rows are exposed. ![Access rules](images/access-rules/access-rules-view-as-kiwi-raw-data.png) -When satisfied that everything looks as expected, we click the green `View as Yourself` -button to close this preview, and the document will reload. +When satisfied that everything looks as expected, we click the green `View as +Yourself` button to close this preview, and the document will reload. ## User attribute tables -If we are successful and hire many sourcing and delivery people, -then adding them one by one to rules would be tedious. One solution -is to use "user attribute tables." You can add a table to your document -that classifies users as you like, and then use those classes in your -access rules. For example, we can make a table called `Team`, and give it two -columns, `Email` and `Role`, where `Role` is a choice between -`Sourcing` and `Delivery`. +If we are successful and hire many sourcing and delivery people, then adding +them one by one to rules would be tedious. One solution is to use "user +attribute tables." You can add a table to your document that classifies users as +you like, and then use those classes in your access rules. For example, we can +make a table called `Team`, and give it two columns, `Email` and `Role`, where +`Role` is a choice between `Sourcing` and `Delivery`. ![Access rules](images/access-rules/access-rules-team-table.png) -Now we can tell Grist to make information from this table available -for access rules, by clicking on `Add User Attributes`. -Give the attribute any name you like (this will be how we refer to it -in formulas), such as `Team`. Pick the table to read (`Team` also in -this case). Give a user property to match against -rows in this table - in our case we'll use `user.Email`. And the -column to match against, `Email`. +Now we can tell Grist to make information from this table available for access +rules, by clicking on `Add User Attributes`. Give the attribute any name you +like (this will be how we refer to it in formulas), such as `Team`. Pick the +table to read (`Team` also in this case). Give a user property to match against +rows in this table - in our case we'll use `user.Email`. And the column to match +against, `Email`. ![Access rules](images/access-rules/access-rules-team-attribute.png) -Save that. Now we can update our rules to be more general. We find with -autocomplete that we have a new `user.Team` variable available in -condtions. It makes columns from the `Team` available, such as `user.Team.Role`. -Now we can check if the user has a particular role, and apply the permissions -that go with that: +Save that. Now we can update our rules to be more general. We find with +autocomplete that we have a new `user.Team` variable available in condtions. It +makes columns from the `Team` available, such as `user.Team.Role`. Now we can +check if the user has a particular role, and apply the permissions that go with +that: ![Access rules](images/access-rules/access-rules-team-rules.png) -Great! Doing a spot check, Charon sees the expected columns for someone in -Sourcing. And if we recruit someone else to work with them, we can just add -them in the `Team` table, no rule changes needed. +Great! Doing a spot check, Charon sees the expected columns for someone in +Sourcing. And if we recruit someone else to work with them, we can just add them +in the `Team` table, no rule changes needed. ![Access rules](images/access-rules/access-rules-view-as-charon.png) ## Row-level access control -In our example, as orders are processed, they move from sourcing to delivery phases. -So there's really no need for the two groups to see all the orders at once. Let's add a -column called `Stage` that can be set to `Sourcing` or `Delivery`, so that we -can update access rules to show only the relevant orders. +In our example, as orders are processed, they move from sourcing to delivery +phases. So there's really no need for the two groups to see all the orders at +once. Let's add a column called `Stage` that can be set to `Sourcing` or +`Delivery`, so that we can update access rules to show only the relevant orders. ![Access rules](images/access-rules/access-rules-stage-column.png) In the `Rules for table Orders` group, click the three-dot icon (...), and select `Add Default Rule` to add a rule that isn't limited to specific columns. -Let's deny access to all rows for non-Owners as a starting point, then add back in the -ones we want. We can do that with the condition `user.Access != OWNER` with -`Deny All` permissions. Then, we add another default rule by clicking `+`, and -add the condition `user.Team.Role == rec.Stage`. The `rec` variable allows -us to express rules that depend on the content within a particular record. -Here, we check if the `Stage` column of a record matches the user's role. -If it is, we allow `R` Read access: +Let's deny access to all rows for non-Owners as a starting point, then add back +in the ones we want. We can do that with the condition `user.Access != OWNER` +with `Deny All` permissions. Then, we add another default rule by clicking `+`, +and add the condition `user.Team.Role == rec.Stage`. The `rec` variable allows +us to express rules that depend on the content within a particular record. Here, +we check if the `Stage` column of a record matches the user's role. If it is, we +allow `R` Read access: ![Access rules](images/access-rules/access-rules-stage-rules.png) @@ -218,24 +224,26 @@ And here's how the table looks as Charon (doing sourcing): ![Access rules](images/access-rules/access-rules-stage-charon.png) -Kimberly and Charon now have read-only access to the table. Owners still have full -write access to all rows and columns. +Kimberly and Charon now have read-only access to the table. Owners still have +full write access to all rows and columns. + +!!! note "Understanding reference columns in access rules" You can limit the +data team members access to just those rows pertinent to their work. One way to +do so is to relate all records in all tables to their respective team members. +For example, leads and sales records can reference the sales rep responsible for +those records. This quick video explains how. -!!! note "Understanding reference columns in access rules" - You can limit the data team members access to just those rows pertinent to their work. One way to do so is to relate all records in all tables to their respective team members. For example, leads and sales records can reference the sales rep responsible for those records. This quick video explains how. - ## Checking new values -Access rules can be used to permit only certain changes to the document. -Suppose we want `Delivery` people -to be able to change `Stage` from `Delivery` to `Done`, without giving them the -arbitrary rights to edit that column. We can grant them that exceptional right -as follows. -In the `Rules for table Orders` group, click the three-dot icon (...), and -select `Add Column Rule`. Set `[Add Column]` to `Stage`, and mark the U/Update -permission to be granted. For the condition, use this: +Access rules can be used to permit only certain changes to the document. Suppose +we want `Delivery` people to be able to change `Stage` from `Delivery` to +`Done`, without giving them the arbitrary rights to edit that column. We can +grant them that exceptional right as follows. In the `Rules for table Orders` +group, click the three-dot icon (...), and select `Add Column Rule`. Set `[Add +Column]` to `Stage`, and mark the U/Update permission to be granted. For the +condition, use this: ``` (user.Team.Role == 'Delivery' and @@ -243,76 +251,76 @@ permission to be granted. For the condition, use this: newRec.Stage == 'Done') ``` -This checks if the user has the Delivery role, and the record is in the Delivery stage, -and that the user is trying to change the Stage to `Done`. The `newRec` variable is a -variant of `rec` available when the user is proposing to change a record, with `rec` -containing its state before the change, and `newRec` its state after the proposed change. +This checks if the user has the Delivery role, and the record is in the Delivery +stage, and that the user is trying to change the Stage to `Done`. The `newRec` +variable is a variant of `rec` available when the user is proposing to change a +record, with `rec` containing its state before the change, and `newRec` its +state after the proposed change. ![Access rules](images/access-rules/access-rules-delivery-done-rule.png) -Now, if we view the table as Kiwi, and try to change a `Stage` to `Sourcing`, we are -denied: +Now, if we view the table as Kiwi, and try to change a `Stage` to `Sourcing`, we +are denied: ![Access rules](images/access-rules/access-rules-delivery-done-forbid.png) -If we change a `Stage` to `Done`, it works, and the record disappears from view since -it is no longer in the `Delivery` stage: +If we change a `Stage` to `Done`, it works, and the record disappears from view +since it is no longer in the `Delivery` stage: ![Access rules](images/access-rules/access-rules-delivery-done-allow.png) ## Link keys -Sometimes it is useful to give access to a specific small -slice of the document, for example a single row of a table. Grist offers -a feature called "link keys" that can help with that. Any parameters in -a Grist document URL that end in an underscore are made available to -access rules in a `user.LinkKey` variable. So for example if a document -URL ends in `....?Token_=xx-xx-xx-xx&Flavor_=vanilla`, then `user.LinkKey.Token` -will be set to `xx-xx-xx-xx` and `user.LinkKey.Flavor` to `vanilla`. -Let's work through an example to see how that can be helpful. - -Suppose we have a table of `Orders` and we'd like to occasionally -share information about a single order with someone. To do that with -link keys, we need some kind of hard-to-guess code for each order, -which can be used to access it. Grist has a [`UUID()`](functions.md#uuid) function that -gives a unique, random, and hard-to-guess identifier, so let's add a `UUID` column with -formula `=UUID()`: +Sometimes it is useful to give access to a specific small slice of the document, +for example a single row of a table. Grist offers a feature called "link keys" +that can help with that. Any parameters in a Grist document URL that end in an +underscore are made available to access rules in a `user.LinkKey` variable. So +for example if a document URL ends in `....?Token_=xx-xx-xx-xx&Flavor_=vanilla`, +then `user.LinkKey.Token` will be set to `xx-xx-xx-xx` and `user.LinkKey.Flavor` +to `vanilla`. Let's work through an example to see how that can be helpful. + +Suppose we have a table of `Orders` and we'd like to occasionally share +information about a single order with someone. To do that with link keys, we +need some kind of hard-to-guess code for each order, which can be used to access +it. Grist has a [`UUID()`](functions.md#uuid) function that gives a unique, +random, and hard-to-guess identifier, so let's add a `UUID` column with formula +`=UUID()`: ![Access rules](images/access-rules/access-rules-linkkey-uuid-formula.png) -In fact we want `UUID()` to be called just once per order, when we create -it, and never recomputed (because then it would change). So in the right sidebar -we convert the formula column to a data column, freezing its values: +In fact we want `UUID()` to be called just once per order, when we create it, +and never recomputed (because then it would change). So in the right sidebar we +convert the formula column to a data column, freezing its values: ![Access rules](images/access-rules/access-rules-linkkey-uuid-convert.png) -This converts our formula to a trigger formula. We set the formula to apply to new records: +This converts our formula to a trigger formula. We set the formula to apply to +new records: ![Access rules](images/access-rules/access-rules-linkkey-uuid-data.png) -At this point we have a solid hard-to-guess code for each order in the -`UUID` column, that will be created as we add new orders. It can -be handy at this point to construct links to the document with that -code embedded in them. Grist has a helper for this called -[`SELF_HYPERLINK`](functions.md#self_hyperlink). To add a -link key called ``, just use this function with a -`LinkKey_` argument. In our case, we pass `LinkKey_UUID=$UUID` to -embed the value of the `UUID` column into the URL. We also set `label=$Ref` -to control the text label of the link in the spreadsheet. To show the link, -we set the column type to `Text` and set the `HyperLink` option: +At this point we have a solid hard-to-guess code for each order in the `UUID` +column, that will be created as we add new orders. It can be handy at this point +to construct links to the document with that code embedded in them. Grist has a +helper for this called [`SELF_HYPERLINK`](functions.md#self_hyperlink). To add a +link key called ``, just use this function with a `LinkKey_` +argument. In our case, we pass `LinkKey_UUID=$UUID` to embed the value of the +`UUID` column into the URL. We also set `label=$Ref` to control the text label +of the link in the spreadsheet. To show the link, we set the column type to +`Text` and set the `HyperLink` option: ![Access rules](images/access-rules/access-rules-linkkey-link.png) -Once we have these links, we can tidy up a little by hiding the -`UUID` and `Ref` columns (see [Column operations](widget-table.md#column-operations) for a refresher on how -to do this): +Once we have these links, we can tidy up a little by hiding the `UUID` and `Ref` +columns (see [Column operations](widget-table.md#column-operations) for a +refresher on how to do this): ![Access rules](images/access-rules/access-rules-linkkey-prune.png) -The links don't do anything special yet, but we have everything we -need to make that happen now. Here is an example of access rules to -allow anyone with a UUID in their URL to read any order with a -matching UUID (otherwise only owners can read orders in this case): +The links don't do anything special yet, but we have everything we need to make +that happen now. Here is an example of access rules to allow anyone with a UUID +in their URL to read any order with a matching UUID (otherwise only owners can +read orders in this case): ![Access rules](images/access-rules/access-rules-linkkey-rule.png) @@ -321,119 +329,149 @@ URL: ![Access rules](images/access-rules/access-rules-linkkey-use.png) -This is just the beginning of the possibilities. Link keys can give access to -multiple rows across many tables. They can be used in -[User attribute tables](#user-attribute-tables). And the data they give access to -can be within tables, cards, card lists, charts, and custom widgets. +This is just the beginning of the possibilities. Link keys can give access to +multiple rows across many tables. They can be used in [User attribute +tables](#user-attribute-tables). And the data they give access to can be within +tables, cards, card lists, charts, and custom widgets. -Check out [another example](https://support.getgrist.com/examples/2021-04-link-keys/) to deepen your understanding of link keys even more. +Check out [another +example](https://support.getgrist.com/examples/2021-04-link-keys/) to deepen +your understanding of link keys even more. ## Access rule conditions -Accress rule conditions contain a formula expressing when the rule -should apply. A blank condition will always apply. When a condition -applies for an action, the permissions associated with the condition are -set to allowed or denied for that action if no earlier rule in the same -group has yet set them. When a condition does not apply, no -permissions are set by that rule, but other rules could set them. +Accress rule conditions contain a formula expressing when the rule should apply. +A blank condition will always apply. When a condition applies for an action, the +permissions associated with the condition are set to allowed or denied for that +action if no earlier rule in the same group has yet set them. When a condition +does not apply, no permissions are set by that rule, but other rules could set +them. -Formulas are written in a restricted subset of Python. -Variables that may be available in access rules are `user`, `rec`, and `newRec`. +Formulas are written in a restricted subset of Python. Variables that may be +available in access rules are `user`, `rec`, and `newRec`. The `user` variable contains the following members: - * `user.Access`: one of `owners`, `editors`, or `viewers`, giving how the - document was shared with the user (see [Sharing a document](sharing.md)). - * `user.Email`: the email address of the user (or `anon@getgrist.com` for users who are not logged in). - * `user.UserID`: a numeric ID that is associated with the user. - * `user.Name`: the user's name (or `Anonymous` if unavailable). - * `user.LinkKey`: an object with any access control URL parameters. Access control URL - parameters end in an underscore (which is then stripped). Only available in the - web client, not the API. - * `user.Origin`: The content of the Origin request header. Only available in the API, - not the web client. - * `user.SessionID`: a unique string assigned to anonymous users for the duration of that user's session. For logged in users, `user.SessionID` is always `"u"` + the user's numeric id. - -For an example of using the `user` variable, read [Default rules](access-rules.md#default-rules). +* `user.Access`: one of `owners`, `editors`, or `viewers`, giving how the + document was shared with the user (see [Sharing a document](sharing.md)). +* `user.Email`: the email address of the user (or `anon@getgrist.com` for users + who are not logged in). +* `user.UserID`: a numeric ID that is associated with the user. +* `user.Name`: the user's name (or `Anonymous` if unavailable). +* `user.LinkKey`: an object with any access control URL parameters. Access + control URL parameters end in an underscore (which is then stripped). Only + available in the web client, not the API. +* `user.Origin`: The content of the Origin request header. Only available in the + API, not the web client. +* `user.SessionID`: a unique string assigned to anonymous users for the duration + of that user's session. For logged in users, `user.SessionID` is always `"u"` + + the user's numeric id. + +For an example of using the `user` variable, read [Default +rules](access-rules.md#default-rules). The `rec` variable contains the state of an individual record/row, for -conditions that need to take that into account. When it is used, that -rule becomes row-specific. That allows, for example, to make certain -rows visible only to certain users, or to prohibit modification of -certain rows by certain users. -For an example of using the `rec` variable, read [Row-level access control](access-rules.md#row-level-access-control). - -The `newRec` variable is available for record/row creation and -updating, and contains the state of a row after a proposed change, -allowing you to selectively allow or deny certain changes. -For an example of using the `newRec` variable, read [Checking new values](access-rules.md#checking-new-values). - -Supported operations in condition formalas are currently: `and`, `or`, -`+`, `-`, `*`, `/`, `%`, `==`, `!=`, `<`, `<=`, `>`, `>=`, `is`, `is -not`, `in`, `not in`. Supported variables are: `user`, `rec`, -`newRec` with their members accessed with `.`. Strings, numbers, and -lists are also supported. If an operation you need is not available, -consider whether you can do part of the work in a formula in the table -itself (see [Access rule memos](access-rules.md#access-rule-memos) for an example). - -Comments are allowed, using `#` or `"""`. If there is a comment in a -rule, then the first comment in a rule that results in a denial of an -action will be reported to the user as a tip for why the action was not -permitted. See [Access rule memos](access-rules.md#access-rule-memos) for an example. +conditions that need to take that into account. When it is used, that rule +becomes row-specific. That allows, for example, to make certain rows visible +only to certain users, or to prohibit modification of certain rows by certain +users. For an example of using the `rec` variable, read [Row-level access +control](access-rules.md#row-level-access-control). + +The `newRec` variable is available for record/row creation and updating, and +contains the state of a row after a proposed change, allowing you to selectively +allow or deny certain changes. For an example of using the `newRec` variable, +read [Checking new values](access-rules.md#checking-new-values). + +Supported operations in condition formalas are currently: `and`, `or`, `+`, `-`, +`*`, `/`, `%`, `==`, `!=`, `<`, `<=`, `>`, `>=`, `is`, `is not`, `in`, `not in`. +Supported variables are: `user`, `rec`, `newRec` with their members accessed +with `.`. Strings, numbers, and lists are also supported. If an operation you +need is not available, consider whether you can do part of the work in a formula +in the table itself (see [Access rule memos](access-rules.md#access-rule-memos) +for an example). + +Comments are allowed, using `#` or `"""`. If there is a comment in a rule, then +the first comment in a rule that results in a denial of an action will be +reported to the user as a tip for why the action was not permitted. See [Access +rule memos](access-rules.md#access-rule-memos) for an example. ## Access rule permissions A permission controls whether a user can perform a particalar kind of action. -Grist access rules currently deal with 5 kinds of action, which are given -single letter acronyms for convenience: +Grist access rules currently deal with 5 kinds of action, which are given single +letter acronyms for convenience: - * `R` - permission to read cells. - * `U` - permission to update cells. - * `C` - permission to create rows. - * `D` - permission to delete rows. - * `S` - permission to change table structure. +* `R` - permission to read cells. +* `U` - permission to update cells. +* `C` - permission to create rows. +* `D` - permission to delete rows. +* `S` - permission to change table structure. -The `S` structure permission is available in the default access rule -group. Column rules lack the `C` create and `D` delete permissions, -which should be handled in default table rules. +The `S` structure permission is available in the default access rule group. +Column rules lack the `C` create and `D` delete permissions, which should be +handled in default table rules. -**Note:** The `S` permission is very powerful. It allows writing formulas, which can access -any data in the document regardless of rules. Since the `S` permission is on by default for -Editors and Owners, any such user would be able to edit a formula and so retrieve any data. +**Note:** The `S` permission is very powerful. It allows writing formulas, which +can access any data in the document regardless of rules. Since the `S` +permission is on by default for Editors and Owners, any such user would be able +to edit a formula and so retrieve any data. -In other words, having the `S` permission makes it possible to circumvent other rules that prevent -access to data. For this reason, turning it off -- as described above in [Locking down -structure](#lock-down-structure) -- is an important first step in limiting data access. +In other words, having the `S` permission makes it possible to circumvent other +rules that prevent access to data. For this reason, turning it off -- as +described above in [Locking down structure](#lock-down-structure) -- is an +important first step in limiting data access. ## Access rule memos -When a user receives an error message denying them access because of a -rule, it can be helpful to give specific details that will help them understand -the problem. You can do this by adding a memo for the condition. First, click -the memo icon to the right of your condition. +When a user receives an error message denying them access because of a rule, it +can be helpful to give specific details that will help them understand the +problem. You can do this by adding a memo for the condition. First, click the +memo icon to the right of your condition. ![Comment Icon](images/access-rules/access-rules-comment-icon.png) -Type the error message you wish to display into the entry box. Be sure to save your changes. +Type the error message you wish to display into the entry box. Be sure to save +your changes. ![Comment Added](images/access-rules/access-rules-comment-added.png) -When the rule blocks a user from performing an action, the memo will appear as a notification. +When the rule blocks a user from performing an action, the memo will appear as a +notification. ![Duplicate error](images/access-rules/access-rules-dupe-forbidden.png) -For an explanation of how this particular Access Rule works, see [Access Rules to Restrict Duplicate Records](examples/2023-01-acl-memo.md) +For an explanation of how this particular Access Rule works, see [Access Rules +to Restrict Duplicate Records](examples/2023-01-acl-memo.md) ## Access rule examples Along with the extended example of using access rules in this section, we will collect complete examples of access rule templates and guides here. - - [Lead lists](examples/2021-03-leads.md): A very simple list of leads, assigned to individuals to follow up, with control of assignments reserved for document owners. -- [Account-based Sales Team](https://templates.getgrist.com/38Dz6nMtzvwC/Account-based-Sales-Team): Sales CRM with deals and contacts assigned to sales reps. Reps can only see their own contacts and deals, but managers can see everything. -- [Public Giveaway](https://templates.getgrist.com/vP7WpQp89hLi/Public-Giveaway): A public giveaway organizer that uses access rules to enforce giveaway rules without requiring claimants to log into Grist. -- [Simple Poll](https://templates.getgrist.com/jd234iH1zDsL/Simple-Poll): A simple poll managed in Grist with access rules to limit one response per visitor. -- [Crowdsourced List](https://templates.getgrist.com/dKztiPYamcCp/Crowdsourced-List): Publicly crowdsourced list with access rules to empower moderators to edit almost anything, but limit visitors to only making and editing their own contributions. -- [Time Sheets](https://templates.getgrist.com/oGxD8EnzeVs6/Time-Sheets): Template to capture contractor timesheets. Access rules permit contractors to view only their historical time sheets, and edit only the active month. -- [Project Management](https://templates.getgrist.com/hifkng53AxyQ/Project-Management/): Track tasks by event and flag tasks at risk. Access rules limit permissions by department, and expand managers' permissions. +- [Lead lists](examples/2021-03-leads.md): A very simple list of leads, assigned + to individuals to follow up, with control of assignments reserved for document + owners. +- [Account-based Sales + Team](https://templates.getgrist.com/38Dz6nMtzvwC/Account-based-Sales-Team): + Sales CRM with deals and contacts assigned to sales reps. Reps can only see + their own contacts and deals, but managers can see everything. +- [Public + Giveaway](https://templates.getgrist.com/vP7WpQp89hLi/Public-Giveaway): A + public giveaway organizer that uses access rules to enforce giveaway rules + without requiring claimants to log into Grist. +- [Simple Poll](https://templates.getgrist.com/jd234iH1zDsL/Simple-Poll): A + simple poll managed in Grist with access rules to limit one response per + visitor. +- [Crowdsourced + List](https://templates.getgrist.com/dKztiPYamcCp/Crowdsourced-List): Publicly + crowdsourced list with access rules to empower moderators to edit almost + anything, but limit visitors to only making and editing their own + contributions. +- [Time Sheets](https://templates.getgrist.com/oGxD8EnzeVs6/Time-Sheets): + Template to capture contractor timesheets. Access rules permit contractors to + view only their historical time sheets, and edit only the active month. +- [Project + Management](https://templates.getgrist.com/hifkng53AxyQ/Project-Management/): + Track tasks by event and flag tasks at risk. Access rules limit permissions by + department, and expand managers' permissions.