> ## 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 Market Risk 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 Solutions 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 Solution changes is
  awkward

To address these problems, this bookmark tool enables you to
export the 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 the Atoti Market Risk bookmarks:

1. Run the solution as usual.
2. Configure the export behavior.
3. Run the `main` method of the
   `ExportReferenceContentServer`
   class.
4. (Optional) To export to a different folder, you can modify the
   `mr-content-server` parameter of the exportBookmarks() call.

Atoti Solutions come with a set of properties loaded in the export
class, that can be found in the `src/test/resources` folder of the
respective starter module. You can find the properties in the
`mr.bookmark.properties` file

<table><thead><tr><th>Property</th><th>Description</th></tr></thead><tbody><tr><td><code>contentServer.bookmarks.export-to-file</code></td><td>Determines whether the content server will be exported into a single <code>.json</code> file.</td></tr><tr><td><code>contentServer.bookmarks.export-to-folder</code></td><td>Determines whether the content server will be exported into a folder structure.</td></tr><tr><td><code>contentServer.bookmarks.default-owners</code></td><td>The list of user roles to be used as the default owners for a bookmark.</td></tr><tr><td><code>contentServer.bookmarks.default-readers</code></td><td>The list of user roles to be used as the default readers for a bookmark.</td></tr><tr><td><code>contentServer.url</code></td><td>The content server URL.</td></tr></tbody></table>

## Importing

Atoti Solutions provide a default set of bookmarks in the
`accelerator-ui` standalone module included in the release deliverables.
The import behavior of the content service is configurable within the
`src/main/resources/${accelerator-name}.properties` file in the
`starter` project:

<table><thead><tr><th>Property</th><th>Description</th></tr></thead><tbody><tr><td>mr.application.content-server.reset</td><td>Determines whether or not a reset will be performed. false disables the reset - no bookmarks will be loaded over the ones already contained in your content server. true and file performs a reset from the core .json file format. folder performs a reset from the bookmark tool directory structure.</td></tr><tr><td>mr.application.content-server.factory-reset.filename</td><td>Defines the file to use for the true and file options.</td></tr><tr><td>mr.application.content-server.factory-reset.folder-name</td><td>Defines the folder to use for the folder option.</td></tr><tr><td>mr.application.content-server.bookmark.default-owners</td><td>The list of user roles to be used as the default owners for a bookmark.</td></tr><tr><td>mr.application.content-server.bookmark.default-readers</td><td>The list of user roles to be used as the default readers for a bookmark.</td></tr></tbody></table>

The file and folder names will be resolved using a Spring
`PathMatchingResourcePatternResolver`, and the properties conform to its
required format.

For an application built as a SpringBoot JAR, the properties have to be
replaced with properly formatted absolute paths, as it is impossible to
load folders directly from a JAR file.

## Format

The bookmarks directory exported by
this tool will contain the folders and files in the following
structure:

<table><thead><tr><th>Directory Level</th><th>Contents</th></tr></thead><tbody><tr><td>Root</td><td>bookmarks-listing directory - Contains the full set of bookmarks as displayed in the UI.</td></tr><tr><td /><td>i18n.json, and settings.jsonfiles.</td></tr><tr><td>bookmarks-listing directory</td><td>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.</td></tr><tr><td /><td>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.</td></tr></tbody></table>

#### 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:

```
{
    "key": "d08",
    "description": "Description of folder or bookmark",
    "owners" : [ "ROLE_USER" ],
    "readers" : [ "ROLE_USER" ]
}
```

<table><thead><tr><th>Property</th><th>Usage</th><th>Optionality</th></tr></thead><tbody><tr><td>key</td><td>Unique identifier for the bookmark or folder. This key is used in the bookmark sharing feature in Atoti UI.</td><td>Optional. If no key is persisted, a hash of the name and the Content Server object definition will be used.</td></tr><tr><td>description</td><td>A description of the bookmark or folder. It is used as a tooltip within Atoti UI.</td><td>Optional. If no description is defined, the tooltip will not display a description field.</td></tr><tr><td>owners</td><td>An array of user roles with permissions to modify the bookmark or folder.</td><td>Optional. For more information, see <a href="#Permissi">Permissions</a>.</td></tr><tr><td>readers</td><td>An array of user roles with permissions to view the bookmark or folder.</td><td>Optional. For more information, see <a href="#Permissi">Permissions</a>.</td></tr></tbody></table>

Due to all supported properties being optional, the metadata files can
be omitted altogether for new bookmarks. Once imported into the Content
Server, the generated internal metadata must be exported (see
[Exporting](#Exportin)), 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.

<table><thead><tr><th>Position in bookmark structure</th><th>Export</th><th>Import</th></tr></thead><tbody><tr><td>Top level</td><td>Only export permissions if different from default.</td><td>If no permission is defined in the <code>name\_metadata.json</code> file, use the default</td></tr><tr><td>Any other level</td><td>Only export permissions if different from parent.</td><td>If no permission is defined in the <code>name\_metadata.json</code> file, use the default.</td></tr></tbody></table>

#### 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 `Bookmark`3.
  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, create or modify the relevant `name_metadata.json` file.