> ## Documentation Index
> Fetch the complete documentation index at: https://docs.activeviam.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Managing bookmarks with the bookmark tool
The bookmark tool is a utility pre-configured in Atoti CVA Risk Capital for
exporting and importing bookmarks to and from a directory structure.
## What it's for
The standard exporting/importing functionality available in the core
Atoti Server API exports the `bookmarks/` endpoint in the Content Server
as a `.json` file. However, as the number of bookmarks delivered with
Atoti CVA Risk Capital increases, this option presents a number of issues:
* The `.json` file becomes cumbersome to track in git.
* Customizations are increasingly difficult to perform.
* Merging custom bookmarks with any Atoti CVA Risk Capital changes is awkward.
To address these problems, the bookmark tool enables exporting bookmarks as
a directory structure that follows the hierarchy visible in the UI. By
having separate files for every bookmark:
* Incorporating changes becomes easier.
* Git is able to track changes to individual files.
* Merging separate sets of bookmarks becomes as simple as copying custom
files or directories to the appropriate location.
### Exporting
To export Atoti CVA Risk Capital bookmarks:
1. Run Atoti CVA Risk Capital as usual.
2. Configure the export [behavior](#behavior).
3. Run the `main` method of the `ExportReferenceContentServer` class
(`com.activeviam.cvarc.starter.server.ExportReferenceContentServer`)
in the `cvarc-application-tests` module.
4. (Optional) To export to a different folder, modify the
`cvarc-content-server` parameter of the `exportBookmarks()` call.
The tool connects to the content server at the default URL:
```
http://localhost:9090/cvarc-application/activeviam/content
```
The export class loads its properties from
`cvarc-application-tests/src/main/resources/cvarc.export.properties`.
| Property | Description |
| ------------------------------------------ | ---------------------------------------------------------------------------------- |
| `contentServer.bookmarks.export-to-file` | Determines whether the content server will be exported into a single `.json` file. |
| `contentServer.bookmarks.export-to-folder` | Determines whether the content server will be exported into a folder structure. |
| `contentServer.bookmarks.default-owners` | The list of user roles to be used as the default owners for a bookmark. |
| `contentServer.bookmarks.default-readers` | The list of user roles to be used as the default readers for a bookmark. |
| `contentServer.url` | The content server URL. |
When folder export is enabled, the tool also writes the Content Server's
`ui/organization_settings` content to `cvarc-content-server/organization_settings.json`
alongside the bookmarks directory.
### Importing
Atoti CVA Risk Capital ships with a default set of bookmarks in the
`cvarc-content-server` folder and `cvarc-content-server.json` file bundled
in the release deliverables. For full details on configuring the import
behavior, see
[Project configuration](../dev-getting-started/configuration-project#bookmarks).
The import behavior of the content service is configurable in `cvarc.properties`
within the `cvarc-application` module:
| Property | Description |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `contentServer.factory-reset` | Determines whether or not a reset will be performed.
- `false` disables the reset — no bookmarks will be loaded over the ones already in the content server.
- `true` and `file` performs a reset from the core `.json` file format.
- `folder` performs a reset from the bookmark tool directory structure. |
| `contentServer.factory-reset.filename` | Defines the file to use for the `true` and `file` options. Defaults to `cvarc-content-server.json`. |
| `contentServer.factory-reset.folder-name` | Defines the folder to use for the `folder` option. Defaults to `cvarc-content-server`. |
| `contentServer.bookmarks.default-owners` | The list of user roles to be used as the default owners for a bookmark. |
| `contentServer.bookmarks.default-readers` | The list of user roles to be used as the default readers for a bookmark. |
The file and folder names are resolved using a Spring
`PathMatchingResourcePatternResolver`, and the properties conform to its
required format.
For an application built as a SpringBoot JAR, the properties must be
replaced with properly formatted absolute paths, as it is impossible to
load folders directly from a JAR file.
### Format
#### Export format
The bookmarks directory exported by this tool contains the folders and files
in the following structure:
| Directory level | Contents |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Root | `bookmarks-listing` directory — contains the full set of bookmarks as displayed in the UI. |
| | `i18n.json` and `settings.json` files. |
| `bookmarks-listing` directory | Any nested folders (as visible in the UI), together with a `folder-name_metadata.json` file that determines the description, owners, and readers of the bookmark folder. |
| | Any bookmarks at that level in the bookmark tree as a `bookmark-name.json` file, together with a `bookmark-name_metadata.json` file that determines the description, owners, and readers of the bookmark. For more information, see [Permissions](#permissions). |
#### Bookmarks
Individual bookmarks (within `bookmark-name.json` files) conform to the
Atoti UI/Content Server format. The bookmark tool offers no additional
features or configuration options for bookmark content.
#### Metadata
`bookmark-name_metadata.json` files are configuration files for
Atoti UI/Content Server auxiliary features.
The files support the following format:
```json theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
{
"key": "d08",
"description": "Description of folder or bookmark",
"owners": ["ROLE_USER"],
"readers": ["ROLE_USER"]
}
```
| Property | Usage | Optionality |
| ----------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| key | Unique identifier for the bookmark or folder. This key is used in the bookmark sharing feature in Atoti UI. | Optional. If no key is persisted, a hash of the name and the Content Server object definition will be used. |
| description | A description of the bookmark or folder. It is used as a tooltip within Atoti UI. | Optional. If no description is defined, the tooltip will not display a description field. |
| owners | An array of user roles with permissions to modify the bookmark or folder. | Optional. For more information, see [Permissions](#permissions). |
| readers | An array of user roles with permissions to view the bookmark or folder. | Optional. For more information, see [Permissions](#permissions). |
Due to all supported properties being optional, metadata files can be omitted
altogether for new bookmarks. Once imported into the Content Server, the
generated internal metadata must be exported (see [Exporting](#exporting)) to
guarantee key persistence.
### Permissions
#### Behavior
* If a folder or file does not have any permissions defined in the relevant
metadata file, it uses the permissions of its parent. This inheritance
policy is applied right through to the top of the bookmark tree.
* If none of the files or folders have custom permissions, the default
permissions passed into the library call will be used.
#### Impact on export and import
Which permissions get exported or imported depends on whether permissions are
defined in the metadata file for the given folder or file, in addition to its
location in the bookmarks structure.
| Position in bookmark structure | Export | Import |
| ------------------------------ | ----------------------------------------------------- | ----------------------------------------------------------------------------------- |
| Top level | Only export permissions if different from the default | If there is no permission defined in the `name_metadata.json` file, use the default |
| Any other level | Only export permissions if different from parent | If there is no permission defined in the `name_metadata.json` file, use the default |
#### Example
In this example, the default permission is set as `USER/USER` and the bookmark
structure is as follows:
```
Root
└── Bookmark1
└── Bookmark2
└── Folder1 ...............................[ROOT/USER]
├── Folder4
├── Bookmark4
├── Bookmark5
├── Bookmark3......................[USER/USER]
└── Folder2
├── Bookmark6
└── Folder3
├── Bookmark7
├── Bookmark8
```
* Custom permissions have been set for `Folder1` and `Bookmark3`.
So they have their respective permissions files `Folder1_metadata.json`
and `Bookmark3_metadata.json`.
* All children of `Folder1` inherit its permissions `[ROOT/USER]`, except
for `Bookmark3` which has its own permissions `[USER/USER]`.
* All other folders and files will use the default permissions as they have
no permissions files set.
## Merging or modifying bookmarks
* To merge bookmarks, copy the relevant folders and bookmark files to the
appropriate location within the `bookmarks-listing` directory, together
with the `name_metadata.json` file where appropriate.
* To edit a bookmark, modify its `.json` file.
* To edit the description and permissions of files and folders in the UI,
modify the relevant `name_metadata.json` file.
If the file does not exist, create it with the following format:
```json theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
{ "owners": ["ROLE_USER"], "readers": ["ROLE_USER"] }
```
Or with a description:
```json theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
{ "description": "Description of folder or bookmark", "owners": ["ROLE_USER"], "readers": ["ROLE_USER"] }
```