# Scopes

{% hint style="warning" %}
Please be sure of your agent type and version and pick the right documentation accordingly.
{% endhint %}

{% tabs %}
{% tab title="Node.js" %}
{% hint style="danger" %}
This is the documentation of the `forest-express-sequelize` and `forest-express-mongoose` Node.js agents that will soon reach end-of-support.

`forest-express-sequelize` v9 and `forest-express-mongoose` v9 are replaced by [`@forestadmin/agent`](https://docs.forestadmin.com/developer-guide-agents-nodejs/) v1.

Please check your agent type and version and read on or switch to the right documentation.
{% endhint %}
{% endtab %}

{% tab title="Ruby on Rails" %}
{% hint style="success" %}
This is still the latest Ruby on Rails documentation of the `forest_liana` agent, you’re at the right place, please read on.
{% endhint %}
{% endtab %}

{% tab title="Python" %}
{% hint style="danger" %}
This is the documentation of the `django-forestadmin` Django agent that will soon reach end-of-support.

If you’re using a Django agent, notice that `django-forestadmin` v1 is replaced by [`forestadmin-agent-django`](https://docs.forestadmin.com/developer-guide-agents-python) v1.

If you’re using a Flask agent, go to the [`forestadmin-agent-flask`](https://docs.forestadmin.com/developer-guide-agents-python) v1 documentation.

Please check your agent type and version and read on or switch to the right documentation.
{% endhint %}
{% endtab %}

{% tab title="PHP" %}
{% hint style="danger" %}
This is the documentation of the `forestadmin/laravel-forestadmin` Laravel agent that will soon reach end-of-support.

If you’re using a Laravel agent, notice that `forestadmin/laravel-forestadmin` v1 is replaced by [`forestadmin/laravel-forestadmin`](https://docs.forestadmin.com/developer-guide-agents-php) v3.

If you’re using a Symfony agent, go to the [`forestadmin/symfony-forestadmin`](https://docs.forestadmin.com/developer-guide-agents-php) v1 documentation.

Please check your agent type and version and read on or switch to the right documentation.
{% endhint %}
{% endtab %}
{% endtabs %}

## Scopes

#### What is a scope?

A scope is a filter which applies to a collection and all its segments.

It is useful in that it can be used to control what data is available to users. More specifically, scopes can be set up to filter data dynamically on the current user.

{% hint style="warning" %}
**Scopes** are applied to the entire application excluding global smart actions, API & SQL charts and Collaboration & Activities.
{% endhint %}

#### How to set up a scope

To access the scope management page for a given collection, you'll need to [go to that collection's settings page](https://docs.forestadmin.com/user-guide/collections/scopes) using the Layout editor mode.

![](https://2014605362-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LR7SWfEwsNtj_ZiSkSA%2F-Lm9OHicjzIFkE7CpGK0%2F-Lm9PaPgbypvtVde9HFf%2FCapture%20d%E2%80%99e%CC%81cran%202019-08-13%20a%CC%80%2011.54.36.png?alt=media\&token=c2db42a6-7165-44c0-b40f-5edc3b2ae84f)

Once on the Scopes tab **(1)**, you can set up your filter **(2)** and save **(3)**. In the above screenshot, only customers with an email ending with *@forestadmin.com* will be displayed in the collection **and** all of its segments. All other customers won't be accessible.

#### Using a dynamic scope

Imagine a situation where you have several Operations teams each specialized in a specific country's operations:

* *France* team handles customers from France
* *Germany* team handles customers from Germany
* ...

![](https://2014605362-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LR7SWfEwsNtj_ZiSkSA%2F-LmnIBGjIZbAX_PAo12y%2F-LmnKTjEEPdDKmkbrg2V%2FCapture%20d%E2%80%99e%CC%81cran%202019-08-21%20a%CC%80%2010.34.44.png?alt=media\&token=dae42dc2-cb84-405b-9b38-1e7d8d8c73d1)

If you set up the following scope...

![](https://2014605362-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LR7SWfEwsNtj_ZiSkSA%2F-LmnIBGjIZbAX_PAo12y%2F-LmnJrnUO5kG8rjvFWgN%2Fimage.png?alt=media\&token=5e124f20-f12f-4306-b0a0-452d085a5a94)

...then Marc who belongs to the *France* team will only see customers from France.\
However, Louis who belongs to the *Germany* team will only see customers from Germany.

![After the scope has been set up](https://2014605362-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LR7SWfEwsNtj_ZiSkSA%2F-LmnIBGjIZbAX_PAo12y%2F-LmnKN8v6GMuqvsymJm6%2Fimage.png?alt=media\&token=253d6630-ad65-435a-81f6-28786d3e996f)

**Dynamic variables**

In the example above, we used the team name to filter out what the user sees: `$currentUser.team.name`

Here the exhaustive list of available dynamic variables:

| Syntax                       | Result                                                                 |
| ---------------------------- | ---------------------------------------------------------------------- |
| `$currentUser.id`            | The id of the current user                                             |
| `$currentUser.firstName`     | The first name of the current user                                     |
| `$currentUser.lastName`      | The last name of the current user                                      |
| `$currentUser.fullName`      | The full name of the current user                                      |
| `$currentUser.email`         | The email of the current user                                          |
| `$currentUser.team.id`       | The id of the team of the current user                                 |
| `$currentUser.team.name`     | The name of the team of the current user                               |
| `$currentUser.tags.your-tag` | The value associated with key `your-tag` for the current user, if any. |

**Using user tags**

The above example is only possible if your data matches your users' details (email, team, etc). It's likely that it won't always be the case. This is why we've introduced user tags:

![](https://2014605362-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LR7SWfEwsNtj_ZiSkSA%2F-M4yeD8Rzr-amah88UTG%2F-M4z9hyeSxdj4iSKwahY%2Fimage.png?alt=media\&token=48959b32-dd5a-48c7-b88c-26fa37fa8d08)

User tags are [set from each user's details page](https://docs.forestadmin.com/user-guide/project-settings/teams-and-users/add-and-manage-users) and allow you to freely associate your users to a value which will match against your data using the `$currentUser.tags.your-tag` dynamic variable:

![](https://2014605362-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LR7SWfEwsNtj_ZiSkSA%2F-M4yeD8Rzr-amah88UTG%2F-M4z9xH4NPipfEuJZEzl%2Fimage.png?alt=media\&token=2a256121-1c85-4523-a686-11023cf92f3d)

Using the above scope, the above user would see **1**, **2** but not **3**:

![](https://2014605362-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LR7SWfEwsNtj_ZiSkSA%2F-M4yeD8Rzr-amah88UTG%2F-M4z8tQmEHzhjqyMXuBt%2FCapture%20d%E2%80%99e%CC%81cran%202020-04-15%20a%CC%80%2018.58.32%20copie.png?alt=media\&token=40f18020-4119-45a8-9861-02944bf5c18d)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.forestadmin.com/documentation/reference-guide/scopes.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.