# Admin Actions

Administrative actions create, modify, or delete XINA data structures, perform user management, or other system functions.

## Schema Actions

### SCHEMA

Returns the complete environment schema as a JSON object.

| Property | Value | Required | Default |
|-|-|-|-|
| action | `"schema"` | yes |

*Example*

```json
{
  "action" : "schema"
}
```

The server will return a JSON object:


```json
{
  "groups" : [ ... ]
}
```

---

### CREATE

The CREATE action is used to create new groups, databases, teams, and users.

#### CREATE GROUP

Creates a new group.

| Property | Value | Required | Default |
|-|-|-|-|
| action | `"create"` | yes |
| create | `"group"` | yes |
| group | [group definition](schema-syntax#bkmrk-group) | yes |
| parent | [group specifier](specifier-syntax#bkmrk-group) | no |
| teams | group teams association (see below) | no |

If a `parent` group is provided, the created group will be a child of the parent; otherwise the group will be a root level group.

The `teams` property is used to associate the group with one or more teams on creation. This may either be a JSON array of team specifier(s), and the group will be added to those teams with the default group privileges as specified by each team, or may be a JSON object, with each key interpretted as a team specifier, and each value containing a JSON object of group privilege(s) to boolean values, overriding the default team privileges.


#### CREATE DATABASE

Creates a new database.

| Property | Value | Required | Default |
|-|-|-|-|
| action | `"create"` | yes |
| create | `"database"` | yes |
| database | [database definition](schema-syntax#bkmrk-database) | yes |
| parent | [group specifier](specifier-syntax#bkmrk-group) | yes |
| teams | database teams association (see below) | no |

The `teams` property is used to associate the database with one or more teams on creation. This may either be a JSON array of team specifier(s), and the database will be added to those teams with the default database privileges as specified by each team, or may be a JSON object, with each key interpretted as a team specifier, and each value containing a JSON object of database privilege(s) to boolean values, overriding the default team privileges.

#### CREATE TEAM

Creates a new team.

| Property | Value | Required | Default |
|-|-|-|-|
| action | `"create"` | yes |
| create | `"team"` | yes |
| team | [team definition](schema-syntax#bkmrk-team) | yes |

#### CREATE USER

Creates a new user.

| Property | Value | Required | Default |
|-|-|-|-|
| action | `"create"` | yes |
| create | `"user"` | yes |
| user | [user definition](schema-syntax#bkmrk-user) | yes |

---

### ALTER

The ALTER action is used to edit group, database, field, team, or user properties.

#### ALTER GROUP SET

Alters one or more group parameters. Requires the `alter` privilege on the specified group.

| Property | Value | Required | Default |
|-|-|-|-|
| action | `"alter"` | yes |
| alter | `"group"` | yes |
| op | `"set"` | yes |
| group | [group specifier](specifier-syntax#bkmrk-group) | yes |
| set | JSON object map of parameter(s) to value(s) | yes |

#### ALTER GROUP OBJECTS

Inserts, updates, or deletes group objects. Requires the `alter` privilege on the specified group.

| Property | Value | Required | Default |
|-|-|-|-|
| action | `"alter"` | yes |
| alter | `"group"` | yes |
| op | `"objects"` | yes |
| group | [group specifier](specifier-syntax#bkmrk-group) | yes |
| objects | JSON object map of key(s) to object value(s) | yes |

Any properties in the `objects` JSON object with a `null` value will be deleted, if they exist in the group objects.

#### ALTER GROUP FILES

Inserts, updates, or deletes group files. Requires the `alter` privilege on the specified group.

| Property | Value | Required | Default |
|-|-|-|-|
| action | `"alter"` | yes |
| alter | `"group"` | yes |
| op | `"files"` | yes |
| group | [group specifier](specifier-syntax#bkmrk-group) | yes |
| files | JSON object map of key(s) to object ID(s) | yes |

Any properties in the `files` JSON object with a `null` value will be deleted, if they exist in the group files.

#### ALTER DATABASE SET

Alters one or more database parameters. Requires the `alter` privilege on the specified database.

| Property | Value | Required | Default |
|-|-|-|-|
| action | `"alter"` | yes |
| alter | `"database"` | yes |
| op | `"set"` | yes |
| database | [database specifier](specifier-syntax#bkmrk-database) | yes |
| set | JSON object map of parameter(s) to value(s) | yes |

#### ALTER DATABASE OBJECTS

Inserts, updates, or deletes database objects.

| Property | Value | Required | Default |
|-|-|-|-|
| action | `"alter"` | yes |
| alter | `"database"` | yes |
| op | `"objects"` | yes |
| database | [database specifier](specifier-syntax#bkmrk-database) | yes |
| objects | JSON object map of key(s) to object value(s) | yes |

Any properties in the `objects` JSON object with a `null` value will be deleted, if they exist in the database objects.

#### ALTER DATABASE FILES

Inserts, updates, or deletes database files. Requires the `alter` privilege on the specified database.

| Property | Value | Required | Default |
|-|-|-|-|
| action | `"alter"` | yes |
| alter | `"database"` | yes |
| op | `"files"` | yes |
| database | [database specifier](specifier-syntax#bkmrk-database) | yes |
| files | JSON object map of key(s) to object ID(s) | yes |

Any properties in the `files` JSON object with a `null` value will be deleted, if they exist in the database files.

#### ALTER DATABASE ADD FIELDS

Adds one or more fields to an existing database. Requires the `alter` privilege on the specified database.

This operation modifies the database table(s) and may take several hours for very large databases.

| Property | Value | Required | Default |
|-|-|-|-|
| action | `"alter"` | yes |
| alter | `"database"` | yes |
| op | `"add_fields"` | yes |
| database | [database specifier](specifier-syntax#bkmrk-database) | yes |
| fields | JSON array of [field definitions](schema-syntax#bkmrk-field) | yes |
| first | `boolean` | no | `false`
| after | [field specifier](specifier-syntax#bkmrk-field) | no |

The action will fail if any of the new fields have the same name or label as eachother or any existing field in the database.

By default, new fields are added at the end of the existing fields. If `first` is true, new fields will be added at the front of the existing fields. If `after` is provided, new fields will be added immediately after the specified field, and before any following fields. If both `first` is `true` and `after` is provided, the action will fail.

#### ALTER DATABASE DROP FIELDS

Drops one or more fields from an existing database. Requires the `alter` privilege on the specified database.

This operation modifies the database table(s) and may take several hours for very large databases.

| Property | Value | Required | Default |
|-|-|-|-|
| action | `"alter"` | yes |
| alter | `"database"` | yes |
| op | `"drop_fields"` | yes |
| database | [database specifier](specifier-syntax#bkmrk-database) | yes |
| fields | [fields specifier](specifier-syntax#bkmrk-fields) | yes |

The action will fail if any of the specified fields is a key field, or if the action would drop all fields from a database.

#### ALTER DATABASE ORDER FIELDS

Specifies ordering of one or more fields in a database. Requires the `alter` privilege on the specified database.

This operation does not modify the database table(s), only the field order as indicated by the XINA schema.

| Property | Value | Required | Default |
|-|-|-|-|
| action | `"alter"` | yes |
| alter | `"database"` | yes |
| op | `"order_fields"` | yes |
| database | [database specifier](specifier-syntax#bkmrk-database) | yes |
| fields | JSON array of [field specifiers](specifier-syntax#bkmrk-field) | yes |
| after | [field specifier](specifier-syntax#bkmrk-field) | no |

Fields will be ordered based on the order provided in the `fields` property, with any fields not specified maintaining their original order after the specified set. If `after` is provided, the ordered block will start following that specified field, with any non-specified fields before the `after` field maintaining their original order. If the `after` field is included in the `fields` property, the action will fail.

*Example*

Given a database `db` with the fields order `f1`, `f2`, `f3`, `f4`, `f5`, `f6`, the action:

```json
{
  "action": "alter",
  "alter": "database",
  "database": "db",
  "op": "order_fields",
  "fields": ["f4", "f2"]
}
```

The resulting field order would be `f4`, `f2`, `f1`, `f3`, `f5`, `f6`.

Given the same intial setup and action but adding `"after": "f3"`, the resulting order would be: `f1`, `f3`, `f4`, `f2`, `f5`, `f6`

#### ALTER DATABASE RESET PARTITIONS

Resets one or more partitions of a database record table. Requires the `alter` privilege on the specified database.

*This action permanently deletes **all data in the specified partitions**.

Unlike the [DELETE](data-actions#bkmrk-delete) action, this action immediately frees storage space in the underlying database system.

| Property | Value | Required | Default |
|-|-|-|-|
| action | `"alter"` | yes |
| alter | `"database"` | yes |
| op | `"reset_partitions"` | yes |
| database | [database specifier](specifier-syntax#bkmrk-database) | yes |
| partitions | [partitions specifier](specifier-syntax#bkmrk-partitions) | yes |

#### ALTER FIELD SET

Alters one or more field parameters. Requires the `alter` privilege on the specified database.

| Property | Value | Required | Default |
|-|-|-|-|
| action | `"alter"` | yes |
| alter | `"field"` | yes |
| op | `"set"` | yes |
| database | [database specifier](specifier-syntax#bkmrk-database) | yes |
| field | [field specifier](specifier-syntax#bkmrk-field) | yes |
| set | JSON object map of parameter(s) to value(s) | yes |

#### ALTER FIELD OBJECTS

Inserts, updates, or deletes field objects. Requires the `alter` privilege on the specified database.

| Property | Value | Required | Default |
|-|-|-|-|
| action | `"alter"` | yes |
| alter | `"field"` | yes |
| op | `"objects"` | yes |
| database | [database specifier](specifier-syntax#bkmrk-database) | yes |
| field | [field specifier](specifier-syntax#bkmrk-field) | yes |
| objects | JSON object map of key(s) to object value(s) | yes |

Any properties in the `objects` JSON object with a `null` value will be deleted, if they exist in the field objects.

#### ALTER FIELD FILES

Inserts, updates, or deletes field files. Requires the `alter` privilege on the specified database.

| Property | Value | Required | Default |
|-|-|-|-|
| action | `"alter"` | yes |
| alter | `"field"` | yes |
| op | `"files"` | yes |
| database | [database specifier](specifier-syntax#bkmrk-database) | yes |
| field | [field specifier](specifier-syntax#bkmrk-field) | yes |
| files | JSON object map of key(s) to object ID(s) | yes |

Any properties in the `files` JSON object with a `null` value will be deleted, if they exist in the field files.

#### ALTER USER SET

Alters one or more user parameters. Requires the `super` privilege to alter any user other than the current user.

| Property | Value | Required | Default |
|-|-|-|-|
| action | `"alter"` | yes |
| alter | `"user"` | yes |
| op | `"set"` | yes |
| user | [user specifier](specifier-syntax#bkmrk-user) | yes |
| set | JSON object map of parameter(s) to value(s) | yes |

#### ALTER USER OBJECTS

Inserts, updates, or deletes user objects. Requires the `super` privilege to alter any user other than the current user.

| Property | Value | Required | Default |
|-|-|-|-|
| action | `"alter"` | yes |
| alter | `"user"` | yes |
| op | `"objects"` | yes |
| user | [user specifier](specifier-syntax#bkmrk-user) | yes |
| objects | JSON object map of key(s) to object value(s) | yes |

Any properties in the `objects` JSON object with a `null` value will be deleted, if they exist in the user objects.

#### ALTER USER FILES

Inserts, updates, or deletes user files. Requires the `super` privilege to alter any user other than the current user.

| Property | Value | Required | Default |
|-|-|-|-|
| action | `"alter"` | yes |
| alter | `"user"` | yes |
| op | `"files"` | yes |
| user | [user specifier](specifier-syntax#bkmrk-user) | yes |
| files | JSON object map of key(s) to object ID(s) | yes |

Any properties in the `files` JSON object with a `null` value will be deleted, if they exist in the user files.

---

### DROP

Permanently delete teams, groups, databases, or users.

#### DROP GROUP

Drops a group. This action requires the `super` privilege.
 
*This action permanently deletes **all data in the specified group**.*

| Property | Value | Required | Default |
|-|-|-|-|
| action | `"drop"` | yes |
| drop | `"group"` | yes |
| group | [group specifier](specifier-syntax#bkmrk-group) | yes |
| children | `boolean` | no | `false`

By default, if the specified group has any child groups or databases the action will fail. If `children` is `true`, all child groups and databases will also be dropped.

#### DROP DATABASE

Drops a database. This action requires the `super` privilege.

*This action permanently deletes **all data in the specified database**.*

| Property | Value | Required | Default |
|-|-|-|-|
| action | `"drop"` | yes |
| drop | `"database"` | yes |
| database | [database specifier](specifier-syntax#bkmrk-database) | yes |
| children | `boolean` | no | `false`

By default, if the specified database has any child databases the action will fail. If `children` is `true`, all child databases will also be dropped.

#### DROP TEAM

Drops a team. This action requires the `super` privilege.

*This action permanently deletes **all data in the specified team**.*

| Property | Value | Required | Default |
|-|-|-|-|
| action | `"drop"` | yes |
| drop | `"team"` | yes |
| team | [team specifier](specifier-syntax#bkmrk-team) | yes |

#### DROP USER

Drops a user. This action requires the `super` privilege.

*This action permanently deletes **all data associated with the specified user**.*

| Property | Value | Required | Default |
|-|-|-|-|
| action | `"drop"` | yes |
| drop | `"user"` | yes |
| user | [user specifier](specifier-syntax#bkmrk-user) | yes |

---

### JOIN

The JOIN action joins groups, databases, or users to one or more teams.

#### JOIN GROUPS

#### JOIN DATABASES

#### JOIN USERS

---

### LEAVE

The LEAVE action removes groups, databases, or users from one or more teams.

#### LEAVE GROUPS

#### LEAVE DATABASES

#### LEAVE USERS

---

## User Actions

### GRANT

---

### REVOKE

---

### REQUEST

Request an arbitrary action to be performed by a user with required permissions.

---

### RETRACT

Retract one or more user requests.

---

### APPROVE

---

### REJECT

---