Managing Bookmarks with the Bookmark Tool
The Bookmark Tool is a utility pre-configured in the Accelerators for exporting and importing bookmarks to and from a directory structure.
What it’s for
The standard exporting/importing functionality available in the core
ActivePivot API exports the bookmarks/
endpoint in the Content Server
as a .json
file. However, as the number of bookmarks delivered with
Accelerators increases, this option presents a number of issues:
-
The
.json
file becomes cumbersome to track in git -
Customisations are increasingly difficult to perform
-
Merging custom bookmarks with any Accelerator changes is awkward
To address these problems, this bookmark tool enables you to export the bookmarks as a directory structure that follows the hierarchyper 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 Accelerator bookmarks:
-
Run the Accelerator as usual.
-
Configure the export behaviour.
-
Run the
main
method of theExportReferenceContentServer
class. -
(Optional) To export to a different folder, you can modify the frtb-content-server parameter of the exportBookmarks() call.
The Accelerators 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
${accelerator-name}.test.properties
file
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. |
Importing
The Accelerators 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:
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 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. |
contentServer.factory-reset.filename |
Defines the file to use for the true and file options. |
contentServer.factory-reset.folder-name |
Defines the folder to use for the folder option. |
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 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
Export format
The bookmarks directory exported by this tool will contain 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. |
Bookmarks
Individual bookmarks (within bookmark-name.json
files) conform to the
ActiveUI/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
ActiveUI/Content Server auxiliary features.
The files support the following format:
{ "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 ActiveUI. | 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 ActiveUI. | 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. |
readers | An array of user roles with permissions to view the bookmark or folder. | Optional. For more information, see Permissions. |
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), 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
andBookmark
3.
So they have their respective permissions filesFolder1_metadata.json
andBookmark3_metadata.json
- All children of
Folder1
inherit its permissions[ROOT/USER]
except forBookmark3
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 thename_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:
-- Without Description --{ "owners" : [ "ROLE_USER" ], "readers" : [ "ROLE_USER" ]}-- With Description --{ "description": "Description of folder or bookmark", "owners" : [ "ROLE_USER" ], "readers" : [ "ROLE_USER" ]}