Siembol-editor-ui: updating docs (#612)

G-Research · Apr 29, 2022 · f54b67c · f54b67c
1 parent eee1484
commit f54b67c
Show file tree

Hide file tree

Showing 21 changed files with 130 additions and 40 deletions.
diff --git a/README.md b/README.md
@@ -18,6 +18,8 @@ Siembol provides a scalable, advanced security analytics framework based on open
     - [Setting up OAUTH2 OIDC](/docs/siembol_ui/how-tos/how_to_setup_oauth2_oidc_in_siembol_ui.md)
     - [Modifying the layout](/docs/siembol_ui/how-tos/how_to_modify_ui_layout.md)
     - [Managing applications](/docs/siembol_ui/how-tos/how_to_manage_applications.md)
+    - [Use ui-bootstrap file](/docs/siembol_ui/how-tos/how_to_use_ui_bootstrap_file.md)
+    - [Filter configs and save searches](/docs/siembol_ui/how-tos/how_to_filter_configs_and_save_searches.md)
 - Siembol services    
     - [Setting up a service in the config editor rest](/docs/services/how-tos/how_to_set_up_service_in_config_editor_rest.md)
     - [Alerting service](/docs/services/siembol_alerting_services.md)

diff --git a/docs/introduction/how-tos/how_to_contribute.md b/docs/introduction/how-tos/how_to_contribute.md
@@ -7,7 +7,7 @@ How to contribute to the siembol Java project
 ### Environment
 
 - [Maven](https://maven.apache.org/guides/) - version `3.5+`
-- [Java Development Kit 13+](https://adoptopenjdk.net/)
+- [Java Development Kit 17+](https://adoptopenjdk.net/)
 
 ### How to compile and install
 
@@ -53,6 +53,9 @@ mvn versions:set -DnewVersion=your_new_version
 How to contribute to config editor UI project
 ---------------------------------------------
 
+### NodeJS version
+
+The current NodeJS version used can be found in the github actions pipeline [here](https://github.com/G-Research/siembol/blob/main/.github/workflows/ci.yml#L215).
 ### Angular version
 
 The current Angular version can be found in the [package.json](/config-editor/config-editor-ui/package.json) file.

diff --git a/docs/siembol_ui/how-tos/how_to_add_new_config_in_siembol_ui.md b/docs/siembol_ui/how-tos/how_to_add_new_config_in_siembol_ui.md
@@ -1,11 +1,13 @@
-# How to add new config in siembol ui
+# How to add new config in Siembol UI
 
-<img src="../screenshots/config_store_hover.png" alt="drawing"/>
+Adding a new config is done through the config manager view as seen below.
+
+<img src="../screenshots/config_manager.png" alt="drawing"/>
 
 ## Add/Clone/Paste new config
 There are three ways to create a new config:
 - by clicking on the `plus` icon on the right of the search bar
-- by cloning another config using the clone button that appears when hovering over it (as seen in screenshot above)
+- by cloning another config using the clone button in the `Store Actions` column
 - by pasting another config from your clipboard by clicking on the paste icon on the right of the search bar
 
 You will then be redirected to the Config Editor. The config name has to be unique and cannot contain any spaces. 
@@ -21,6 +23,6 @@ After clicking "clone config" you will be redirected to the new config.
 <img src="../screenshots/clone_dialog.png" alt="drawing" width="400px"/>
 
 ## Validate and Submit config to Store
-Once all required fields (indicated with a `*`) are filled in the `Submit` button at the buttom right becomes clickable. Clicking it will run a validation check on the config and if it is successfull a dialog will open where you can confirm the submission (see screenshot below). If the validation is not successfull an error dialog will pop up. 
+Once all required fields (indicated with a `*`) are filled in the `Submit` button at the bottom right becomes clickable. Clicking it will run a validation check on the config and if it is successful a dialog will open where you can confirm the submission (see screenshot below). If the validation is not successful an error dialog will pop up. 
 
 <img src="../screenshots/submit_dialog.png" alt="drawing" width="300px" />
diff --git a/docs/siembol_ui/how-tos/how_to_deploy_configurations_in_siembol_ui.md b/docs/siembol_ui/how-tos/how_to_deploy_configurations_in_siembol_ui.md
@@ -1,28 +1,29 @@
-# How to deploy configurations in siembol ui
-<img src="../screenshots/deployment_upgrade.png" alt="drawing" width='400px'/>
+# How to release configurations in Siembol IO
+<img src="../screenshots/config_manager.png" alt="drawing"/>
 
-## Editing Deployment
-To upgrade config click on the `Upgrade to x` button below the config, it appears whenever a config in release is not up to date with the store. You can also click on `View Diff` to see the changes made.
+## Editing Release
+To upgrade a config in release to the latest version in store click on the `Upgrade x to y` button in the `Release Actions` column. It is only visible when a config in release is not up-to-date with the store. You can also click on `View Diff` to see the changes made.
 
-To remove a config from deployment simply click on the bin icon that appears when hovering over it. 
+To remove a config from release simply click on the cross icon in the `Release Actions` column. 
 
-To change the order of the configs in deployment simply drag the deployment config to its desired location. 
+To change the order of the configs in release simply drag the release config to its desired location (it is only possible to reorder configs in release when no search or filter is applied).
 
-```
-Note: you cannot downgrade a config only upgrade.
-```
+> **_Note:_** A config can only be upgraded not downgraded.
 
-## Create Pull Request with new deployment in siembol ui
+## Release config not in current release
+To release a config that is not released, click the `Add to Release` button in the `Release Actions` column.
+
+## Create Pull Request with new release in Siembol UI
 <img src="../screenshots/submit_dialog_alert.png" alt="drawing" width='600px'/>
 
-Once configs have been added/deleted/upgraded/reorded use the `Deploy` button above. This will open up a dialog, for some services it will automatically run a validation in the background, for others (e.g: alert, correlationalert) additional metadata can be specified in the dialog before clicking the `Validate` button (see in screenshot above). Once validated the changes to the release are displayed in the dialog.  
+Once configs have been added/deleted/upgraded/reordered use the `Release PR` button above which is enabled after changes to release. This will open up a dialog, for some services it will automatically run a validation in the background, for others (e.g: alert, correlationalert) additional metadata can be specified in the dialog before clicking the `Validate` button (see in screenshot above). Once validated the changes to the release are displayed in the dialog.  
 
 For some services it will be possible to run tests on the all the configs in the service by clicking the `Test` button in the dialog. 
 
 To create a pull request in the release repo of the service being edited click on the `Deploy` button in the dialog.
 
-If the user trying to deploy does not have the latest version of the release, an error dialog will be shown and the latest release will be loaded from the backend. The user will have to redo its deployment changes to try again.
+If the user trying to release does not have the latest version of the release, an error dialog will be shown and the latest release will be loaded from the backend. The user will have to redo its release changes to try again.
 
-Once a pull request has been created in the repo it is not possible to create another one until it is either merged or closed. You can see when a pull request is opened in the UI, the `Deploy` button is replaced with `PR for release pending` and a `reload` icon. By clicking on the first a new tab is open to the pull request. The second should be clicked once the pull request is merged/close to reload the config from the backend and be able to deploy again.
+Once a pull request has been created in the repo it is not possible to create another one until it is either merged or closed. You can see when a pull request is opened in the UI, the `Release PR` button is replaced with `PR for release pending` and a `reload` icon (see screenshot below). By clicking on the first a new tab is open to the pull request. The second should be clicked once the pull request is merged/close to reload the config from the backend and be able to release again.
 
-<img src="../screenshots/pr_open.png" alt="drawing" width='500px'/>
+<img src="../screenshots/pr_open.png" alt="drawing"/>
diff --git a/docs/siembol_ui/how-tos/how_to_filter_configs_and_save_searches.md b/docs/siembol_ui/how-tos/how_to_filter_configs_and_save_searches.md
@@ -0,0 +1,20 @@
+# How to filter configs and save searches
+On the config manager page there are multiple ways to filter configs. Searches can also be saved by a user or shared among users through the URL.
+
+<img src="../screenshots/filtering_and_saving.png" alt="drawing"/>
+
+## Search bar
+The search bar can be used to filter for: author, name and labels of configs. The words in the search will all be checked against the configs.
+
+> **_Example:_** if the user searches for `TomH windows` only the configs with both `tomh` and `windows` in either author, name or labels will be displayed.
+
+To save a search click on the `save` icon to the right of the search bar. It will then be displayed in the saved search's panel below that can be expanded. Click on a saved search to apply it. 
+
+## Checkboxes
+On the left-hand side of the config manager page is a column for checkboxes. The standard checkboxes for each service are:
+- `my configs` - configs last modified by current user
+- `upgradable` - configs with unreleased changes in store
+- `unreleased` - unreleased configs
+
+To add more custom checkboxes to a service see [here](./how_to_use_ui_bootstrap_file.md).
+
diff --git a/docs/siembol_ui/how-tos/how_to_test_deployment_in_siembol_ui.md b/docs/siembol_ui/how-tos/how_to_test_deployment_in_siembol_ui.md
@@ -1,5 +1,5 @@
-# How to test a deployment in siembol ui
-For some services it is possible to test all the configs prior to submitting a new release from the deploy dialog by clicking on the `Test` button. This button will only be clickable once the deployment has been validated. 
+# How to test a release in Siembol UI
+For some services it is possible to test all the configs prior to submitting a new release from the release dialog by clicking on the `Test` button. This button will only be clickable once the release has been validated. 
 
 <img src="../screenshots/submit_dialog_alert.png" alt="drawing" width="500px"/>
 
@@ -9,4 +9,4 @@ The output will return two things:
 - the resulting JSON that would be outputted 
 - the raw output of the test (contains more details about the testing)
 
-<img src="../screenshots/deployment_testing_dialog.png" alt="drawing" width="600px"/>
+<img src="../screenshots/release_testing_dialog.png" alt="drawing" width="600px"/>
diff --git a/docs/siembol_ui/how-tos/how_to_use_editing_features.md b/docs/siembol_ui/how-tos/how_to_use_editing_features.md
@@ -14,10 +14,7 @@ Clicking on the copy icon during editing of a config will copy the JSON into you
 ## Paste in config editor
 When clicking the paste icon for the first time you should be presented with a dialog asking you to authorise this application to use your clipboard (in Chrome), you need to approve if you want to use the paste feature.
 
-After clicking the config is validated, if it is not valid an error dialog will pop up. If it valid the config will be pasted, however the name, author and version will not be pasted.
+After clicking the config is validated, if it is not valid an error dialog will pop up. If valid the config will be pasted, however the name, author and version will not.
 
 ## Paste in config manager
-It is also possible to paste when creating a new config by clicking on the paste icon right of the search bar (see screenshot below). If the config in your clipboard is not valid an error dialog will pop up. If it is valid you will be redirected to a new config.
-
-
-<img src="../screenshots/config_manager_paste.png" alt="drawing"/>
+See [here](./how_to_add_new_config_in_siembol_ui.md)
diff --git a/docs/siembol_ui/how-tos/how_to_use_ui_bootstrap_file.md b/docs/siembol_ui/how-tos/how_to_use_ui_bootstrap_file.md
@@ -0,0 +1,60 @@
+# How to use the ui-bootstrap file
+
+The `ui-bootstrap.json` file contains config about each service type. Click [here](/config/config-editor-ui/ui-bootstrap.json) to see the default file provided. Service types are defined [here](/docs/services/how-tos/how_to_set_up_service_in_config_editor_rest.md).
+
+## Schema paths
+This config file provides paths/keys of various variables in the schema of the service type provided by the backend. The possible keys are: 
+- `release.version` - release version key
+- `release.config_array` - release config_array key
+- `release.extras` - list of extra release keys
+- `perConfigSchemaPath` - path to configs
+- `name` - config name key
+- `version` - config version key
+- `author` - config author key
+- `description` - config description key
+
+## Labels function
+It also provides a key to define a JavaScript function that will return the labels for the service. This is done through the `labelsFunc` key. 
+
+## Testing
+Testing can be enabled or disable through these keys:
+- `testing.perConfigTestEnabled` - whether a single config can be tested
+- `testing.releaseTestEnabled` - whether the entire release can be tested
+- `testing.testCaseEnabled` - whether test cases can be created
+
+## Checkboxes
+Checkboxes for quick filtering can be added per service in the `checkboxes` key. Filters can be added based on different fields such as the author or the labels of the config. Below is example of the config of a checkbox. It defined one checkbox group called `Severity` with two checkboxes: `high` and `low`. The pattern defined for each checkbox is matched against the given field. The given field can be:
+- a `string` - the pattern is matched against it
+- a `list` - the pattern has to match one of the items
+```
+"checkboxes": {
+    "severity": {
+        "high": {
+            "field": "labels",
+            "pattern": "^severity:low$"
+        },
+        "low": {
+            "field": "labels",
+            "pattern": "^severity:high$"
+        }
+    }
+}
+```
+
+## Override default properties for service type
+The `override` key can be used to override any of the above properties for a specific service `name` (all the above is per service `type`). If there are two services of the same type different config can be applied to one using this key. 
+
+**_Example:_** Overriding the `testing.releaseTestEnabled` property for the `myalerts` service:
+```
+"override": {
+  "myalerts": {
+    "testing": {
+        "releaseTestEnabled": false
+    }
+  }
+}
+```
+
+
+
+
diff --git a/docs/siembol_ui/screenshots/config_manager.png b/docs/siembol_ui/screenshots/config_manager.png
diff --git a/docs/siembol_ui/screenshots/config_manager_paste.png b/docs/siembol_ui/screenshots/config_manager_paste.png
diff --git a/docs/siembol_ui/screenshots/config_manager_release.png b/docs/siembol_ui/screenshots/config_manager_release.png
diff --git a/docs/siembol_ui/screenshots/config_store.png b/docs/siembol_ui/screenshots/config_store.png
diff --git a/docs/siembol_ui/screenshots/config_store_history.png b/docs/siembol_ui/screenshots/config_store_history.png
diff --git a/docs/siembol_ui/screenshots/config_store_hover.png b/docs/siembol_ui/screenshots/config_store_hover.png
diff --git a/docs/siembol_ui/screenshots/deployment.png b/docs/siembol_ui/screenshots/deployment.png
diff --git a/docs/siembol_ui/screenshots/deployment_upgrade.png b/docs/siembol_ui/screenshots/deployment_upgrade.png
diff --git a/docs/siembol_ui/screenshots/filtering_and_saving.png b/docs/siembol_ui/screenshots/filtering_and_saving.png
diff --git a/docs/siembol_ui/screenshots/import_icon.png b/docs/siembol_ui/screenshots/import_icon.png
diff --git a/docs/siembol_ui/screenshots/pr_open.png b/docs/siembol_ui/screenshots/pr_open.png
diff --git a/...screenshots/deployment_testing_dialog.png → ...ui/screenshots/release_testing_dialog.png b/...screenshots/deployment_testing_dialog.png → ...ui/screenshots/release_testing_dialog.png
diff --git a/docs/siembol_ui/siembol_ui.md b/docs/siembol_ui/siembol_ui.md
@@ -14,7 +14,7 @@ On the home page all services are listed alphabetically by name on the left side
 Your recently visited pages are saved in your browser and can be accessed with only one click from the home page. The default number of pages shown is 5 but can be configured in the `ui-config.json` file using the "historyMaxSize" key.
 
 ### Explore Siembol
-The 'Explore Siembol' section of the home page is for quick access to useful resources such as documentation, ticket tracking systems etc... By default there is a link to the documentation and to the issues page on the git repo. This can be customised from the `ui-config.json` config file. 
+The 'Explore Siembol' section of the home page is for quick access to useful resources such as documentation, ticket tracking systems etc... By default, there is a link to the documentation and to the issues page on the git repo. This can be customised from the `ui-config.json` config file. 
 
 Below is the default config file provided. The two default links are in "homeLinks". To add a new one a url, an icon and a title are required like in the config below. 
 
@@ -47,28 +47,33 @@ After selecting a service to edit you will be redirected to the service configur
 
 <img src="screenshots/config_manager.png" alt="drawing"/>
 
-### Config Store
-The config store is shown on the left hand side of the config manager page. These are the configs in the store repo. The configurations are ordered according to the order in deployment and with the deployed configs before the non-deployed ones. 
-<img src="screenshots/config_store.png" alt="drawing"/>
+The table of configs is separated into the store (left) and release (right). To release an unreleased config or upgrade a config it first needs to be edited in the store, then it can be added to release and peer reviewed through git PRs.
 
-### Deployment
-<p align="center">
-    <img src="screenshots/deployment.png" alt="drawing" width="500px"/>
-</p>
-The deployments are shown on the right hand side of the config manager page. These are the configs that are in the release repo. To add a new config from the store to deployment, simply drag it into the deployment column. Click the `Upgrade to version x` button below a deployed config to upgrade it to the latest changes from the store. To delete a config from deployment click on the `bin` icon that appears when hovering over it. 
+Every config in the table is in the store, its release status is in the `Release Actions` column. There are three possible states:
+- `up-to-date` - store and release have the same version
+- `upgradable` - the version in release can be upgraded to the latest store version, click `Upgrade x to y` to upgrade
+- `unreleased` - the config in store has not been released at all yet, click `Add to Release` to add
+
+The configs are ordered according to the order in the release at first, followed by all the non-released ones. Reordering configs in release is done by clicking and dragging the icon to the left of the config name.
+
+To delete a config from the store it first needs to be deleted from release if it is released. To delete from release click the cross icon in the `Release Actions` column, then the bin icon should appear in the `Store Actions` column to delete from the store.
 
 ### Filtering
-There is a search bar and various checkboxes at the top of the config manager used to filter the configs shown. The search bar allows you to search for configs by name, author or labels. The checkbox "My Edits" filters all configs where the current user has made the latest changes, "Undeployed" filters configs not in the deployment column, "Upgradable" filters configs that are deployed but don't have the latest version from the store.
+There is a search bar and various checkboxes on the left of the config manager used to filter the configs shown. See [here](how-tos/how_to_filter_configs_and_save_searches.md) for more details.
 
 ### History
-By hovering over the version number of a store config its history becomes visible. It includes dates, authors and the count of lines changed. 
-Similarly the deployment history is visible by hovering over the history logo. 
+By hovering over the `Config Name` column of a config in store its history becomes visible, see screenshot below. It includes dates, authors and the count of lines changed. 
+Similarly, the release history is visible by hovering over the history logo next to the release column header. 
+
+The history is taken directly from git.
+
+<img src="screenshots/config_store_history.png" alt="drawing"/>
 
 ## Creating a service config
 See [here](how-tos/how_to_test_config_in_siembol_ui.md).
 
 ## Editing a service config
-To edit a config the edit button that appears when hovering over a config can be used. 
+Editing can be done through the edit icon in the `Store Actions` column.
 
 Once in edit mode the window is separated in two:
  - on the left is the json tree view of the config, useful for a quick view of the entire config