# Space Mapping

This mechanism allows us to configure spaces that Advanced Identity Management will maintain.

## Configuration

We define each space giving it a name (which will be displayed in Element),
a unique ID (which allows Advanced Identity Management to track the Space even if it gets renamed),
and a list of groups whose users will become the members of the Space.
Users needs to be a member of *any* configured group, not all of them.

You can pick any ID you want,
but if you change it later Advanced Identity Management will create a brand new space and abandon the old ones, likely confusing the users.

In order to limit space membership to a specific Group, we include its Group ID.

Each group may optionally include a powerLevel setting, allowing specific groups to have elevated permissions in the space.

A special group ID of `''` (an empty string) indicates that all users from the server, regardless of their group membership,
should become the members of the Space.

In addition to regular groups, you may also make a space federated by specifying `federatedGroups` and a remote Advanced Identity Management server.
See [Federation](https://ems-docs.element.io/books/element-server-suite-pro/page/federation) for more details.

An optional list of subspaces may also be configured, each using the same configuration format and behaviour (recursively).

If a space has subspaces configured, its members list will be composed of the members of the space itself
**any any of its subspaces, recursively** -- so a subspace's member list is always a subset of its parent space's member list.
This may change in the future, so it's advised not to rely on this when configuring your spaces.


```
spaces:
  id: root
  name: 'Company'
  groups:
    - externalId: 'element-users'
```

With `powerLevel` option allows us to give users extra permissions. This is equivalent to the `group_power_level` setting[^note].

```
spaces:
  id: root
  name: 'Company'
  groups:
    # regular users
    - externalId: 'element-users'
    # moderators
    - externalId: 'element-moderators'
      powerLevel: 50
```

In case of Power Level conflicts, the highest power level will be used. With the following configuration:

```
spaces:
  id: root
  name: 'Company'
  groups:
    - externalId: 'moderators'
      powerLevel: 50
    - externalId: 'admins'
      powerLevel: 100
```

A user who's a member of both `moderators` and `admins` will end up with Power Level of 100.

Subspaces can be configured analogically:

```
spaces:
  id: shared
  name: "Element Corp"
  groups:
  - externalId: 'matrix-mods'
    powerLevel: 50
  - externalId: ''
  subspaces:
  - id: london
    name: "London Office"
    groups:
    - externalId: 'london-matrix-mods'
      powerLevel: 50
    - externalId: 'london-employees'
```