diff --git a/docs/explore-and-author/bke-module/bke-canvas.png b/docs/explore-and-author/bke-module/bke-canvas.png new file mode 100644 index 000000000..dbd2da682 Binary files /dev/null and b/docs/explore-and-author/bke-module/bke-canvas.png differ diff --git a/docs/explore-and-author/bke-module/bke-config-modules.png b/docs/explore-and-author/bke-module/bke-config-modules.png new file mode 100644 index 000000000..a3dbc0580 Binary files /dev/null and b/docs/explore-and-author/bke-module/bke-config-modules.png differ diff --git a/docs/explore-and-author/bke-module/bke-config-override.png b/docs/explore-and-author/bke-module/bke-config-override.png new file mode 100644 index 000000000..7445cb4fc Binary files /dev/null and b/docs/explore-and-author/bke-module/bke-config-override.png differ diff --git a/docs/explore-and-author/bke-module/bke-config-section.png b/docs/explore-and-author/bke-module/bke-config-section.png new file mode 100644 index 000000000..a39e37bbe Binary files /dev/null and b/docs/explore-and-author/bke-module/bke-config-section.png differ diff --git a/docs/explore-and-author/bke-module/bke-linked-resources.png b/docs/explore-and-author/bke-module/bke-linked-resources.png new file mode 100644 index 000000000..2a771157a Binary files /dev/null and b/docs/explore-and-author/bke-module/bke-linked-resources.png differ diff --git a/docs/explore-and-author/bke-module/bke-navigation.png b/docs/explore-and-author/bke-module/bke-navigation.png new file mode 100644 index 000000000..dc0ab759b Binary files /dev/null and b/docs/explore-and-author/bke-module/bke-navigation.png differ diff --git a/docs/explore-and-author/bke-module/bke-node-details.png b/docs/explore-and-author/bke-module/bke-node-details.png new file mode 100644 index 000000000..19c938e4f Binary files /dev/null and b/docs/explore-and-author/bke-module/bke-node-details.png differ diff --git a/docs/explore-and-author/bke-module/bke-save-changes.png b/docs/explore-and-author/bke-module/bke-save-changes.png new file mode 100644 index 000000000..97d617931 Binary files /dev/null and b/docs/explore-and-author/bke-module/bke-save-changes.png differ diff --git a/docs/explore-and-author/bke-module/bke-search-results.png b/docs/explore-and-author/bke-module/bke-search-results.png new file mode 100644 index 000000000..14fc0a0b9 Binary files /dev/null and b/docs/explore-and-author/bke-module/bke-search-results.png differ diff --git a/docs/explore-and-author/bke-module/bke-used-properties.png b/docs/explore-and-author/bke-module/bke-used-properties.png new file mode 100644 index 000000000..dac2388e3 Binary files /dev/null and b/docs/explore-and-author/bke-module/bke-used-properties.png differ diff --git a/docs/explore-and-author/bke-module/bke-visualization-catalog.png b/docs/explore-and-author/bke-module/bke-visualization-catalog.png new file mode 100644 index 000000000..bf01b6459 Binary files /dev/null and b/docs/explore-and-author/bke-module/bke-visualization-catalog.png differ diff --git a/docs/explore-and-author/bke-module/bke-visualization.png b/docs/explore-and-author/bke-module/bke-visualization.png new file mode 100644 index 000000000..f97554e36 Binary files /dev/null and b/docs/explore-and-author/bke-module/bke-visualization.png differ diff --git a/docs/explore-and-author/bke-module/bke-welcome.png b/docs/explore-and-author/bke-module/bke-welcome.png new file mode 100644 index 000000000..5917c6afd Binary files /dev/null and b/docs/explore-and-author/bke-module/bke-welcome.png differ diff --git a/docs/explore-and-author/bke-module/easynav-canvas.png b/docs/explore-and-author/bke-module/easynav-canvas.png deleted file mode 100644 index 9e49884e9..000000000 Binary files a/docs/explore-and-author/bke-module/easynav-canvas.png and /dev/null differ diff --git a/docs/explore-and-author/bke-module/easynav-config-EasyNavModule.png b/docs/explore-and-author/bke-module/easynav-config-EasyNavModule.png deleted file mode 100644 index 3e81eafc4..000000000 Binary files a/docs/explore-and-author/bke-module/easynav-config-EasyNavModule.png and /dev/null differ diff --git a/docs/explore-and-author/bke-module/easynav-config-newEasyNavModule-dialog.png b/docs/explore-and-author/bke-module/easynav-config-newEasyNavModule-dialog.png deleted file mode 100644 index 4f4e60bd7..000000000 Binary files a/docs/explore-and-author/bke-module/easynav-config-newEasyNavModule-dialog.png and /dev/null differ diff --git a/docs/explore-and-author/bke-module/easynav-config-search-config-dialog.png b/docs/explore-and-author/bke-module/easynav-config-search-config-dialog.png deleted file mode 100644 index f750d736a..000000000 Binary files a/docs/explore-and-author/bke-module/easynav-config-search-config-dialog.png and /dev/null differ diff --git a/docs/explore-and-author/bke-module/easynav-config-select-in-workspace.png b/docs/explore-and-author/bke-module/easynav-config-select-in-workspace.png deleted file mode 100644 index 515861440..000000000 Binary files a/docs/explore-and-author/bke-module/easynav-config-select-in-workspace.png and /dev/null differ diff --git a/docs/explore-and-author/bke-module/easynav-exploration-expand.png b/docs/explore-and-author/bke-module/easynav-exploration-expand.png deleted file mode 100644 index bc45f56b7..000000000 Binary files a/docs/explore-and-author/bke-module/easynav-exploration-expand.png and /dev/null differ diff --git a/docs/explore-and-author/bke-module/easynav-literal-inline.png b/docs/explore-and-author/bke-module/easynav-literal-inline.png deleted file mode 100644 index 1a9273fde..000000000 Binary files a/docs/explore-and-author/bke-module/easynav-literal-inline.png and /dev/null differ diff --git a/docs/explore-and-author/bke-module/easynav-start.png b/docs/explore-and-author/bke-module/easynav-start.png deleted file mode 100644 index 9d5f0aa28..000000000 Binary files a/docs/explore-and-author/bke-module/easynav-start.png and /dev/null differ diff --git a/docs/explore-and-author/bke-module/easynav-visualization-catalog.png b/docs/explore-and-author/bke-module/easynav-visualization-catalog.png deleted file mode 100644 index 183d0a41d..000000000 Binary files a/docs/explore-and-author/bke-module/easynav-visualization-catalog.png and /dev/null differ diff --git a/docs/explore-and-author/bke-module/easynav-welcome-search.png b/docs/explore-and-author/bke-module/easynav-welcome-search.png deleted file mode 100644 index a02ce81a2..000000000 Binary files a/docs/explore-and-author/bke-module/easynav-welcome-search.png and /dev/null differ diff --git a/docs/explore-and-author/bke-module/index.md b/docs/explore-and-author/bke-module/index.md index 641fed893..769ddafe8 100644 --- a/docs/explore-and-author/bke-module/index.md +++ b/docs/explore-and-author/bke-module/index.md @@ -4,87 +4,162 @@ tags: - KnowledgeGraph - Video --- - - # Business Knowledge Editor ## Introduction -This module allows the visual exploration of Knowledge Graphs. -It allows to save and share explorations. -Furthermore, sophisticated individual search settings (filter presets) can be created and configured per Application view. +The Business Knowledge Editor (BKE) allows the visual exploration and authoring of Knowledge Graphs. +Resources are rendered as nodes on a canvas and can be expanded along the relationships that connect them to other resources. +Explorations can be saved as named visualizations, shared and re-opened later. + +Which resources can be found, how edges are labeled and which graph is explored by default is controlled by the +:eccenca-module-workspace-configuration: [Application view configuration](../workspace-configuration/index.md) module, +see [Configuration](#configuration) below. ## Usage -If enabled, content of Knowledge Graphs can be explored in a visual way, rendering nodes and edges and allowing the user to expand along the relationships between the nodes. +Start the module by selecting :eccenca-module-bke: **Business knowledge editor** in the main navigation. + +![Business knowledge editor in the main navigation](bke-navigation.png){ class="bordered" } + +### Starting a visualization + +The module welcome screen offers three ways to begin: + +- **Search and select a resource** to start a new visualization from that resource. +- **Create empty visualization** to start with an empty canvas, e.g. to [author an ontology](visually-authoring-ontologies/index.md). +- **Load existing visualization** (upper right) to re-open a saved visualization. + +![The welcome screen of the Business knowledge editor](bke-welcome.png){ class="bordered" } -Start using `Business Knowledge Editor` by selecting the respective module entry in the main navigation. +!!! Note + + The **Select a graph to explore** drop-down is only shown if no `contextGraph` is configured for the module in the + current Application view. If a `contextGraph` is configured, that graph is used and the drop-down is omitted. -![](easynav-start.png) +Enter at least three characters to populate the result list, then click a result to open the exploration canvas. -At the module welcome screen the user can either load a saved visualization of start searching for an initial node / resource by providing a search term. +![Search results on the welcome screen](bke-search-results.png){ class="bordered" } !!! Note - The graph selection drop-down might or might not be visible depending the existence of an (optional) `Business Knowledge Editor Module` configuration. - In case no specific module configuration exists or non has not has been set for the current Application view the graph selection will be shown. - A `Business Knowledge Editor Module` configuration pre-configures a graph. - Thus, the dropdown will not be shown if such has been configured for the current Application view. + The result list is produced by the `searchListQueries` configuration of the module. + By default it contains two presets, one for instances and one for classes, which is why the example above returns the class `Encoder` as well as the hardware instances labeled with it. + See [Configuration](#configuration) on how to tailor these presets. + +### The canvas + +![The exploration canvas](bke-canvas.png){ class="bordered" } + +The canvas is framed by: + +- **Search Instances** (upper left) — search for further resources to add to the canvas. + The tabs (`All`, plus one per configured search preset) let you restrict the search to a single preset. +- **Classes** (lower left) — the classes of the explored graph. Drag an entry onto the canvas to create a new resource + of that class. +- **Canvas toolbar** (upper right) — *Start new visualization from selected nodes*, *Arrange* (auto-layout), + *Undo*, *Redo* and *Save*. +- **Zoom controls and minimap** — zoom in/out, *Fit View* and an overview of the whole visualization. -![Initial search on the welcome screen.](easynav-welcome-search.png) +### Expanding a resource -Enter a search term to populate the result list. -Click a result to start the visual graph exploration. +Hover a node and click the connector dot on its right edge to open the **Used properties** panel. +It lists every property used by this resource together with the number of related resources. +A :material-arrow-left: in front of the property name marks an incoming (inverse) relation. -![The exploration canvas](easynav-canvas.png) +![Expanding a node shows its used properties](bke-used-properties.png){ class="bordered" } -The exploration starts with the selected node (or a saved exploration). -The nodes can further be expanded along the relationships that exist to other resources. -Therefore, click the node expansion button on the right side of a node (the point where the arrows originate in the screenshot below). +Select a property to open the **Linked Resources** panel with the resources reachable via that property. -![Expanding the exploration](easynav-exploration-expand.png) +![Linked resources of the selected property](bke-linked-resources.png){ class="bordered" } -Any expanded resource / node can be added to the current exploration by double-clicking the node. -Clicking anywhere on the empty canvas will close the relationship dialog and retain the added nodes and their relationships only. +From here you can: -![Literal view](easynav-literal-inline.png) +- **click a single resource** to add it to the canvas, +- **drag `Add N entries`** onto the canvas to add all listed resources at once, +- **drag `New `** onto the canvas to create a new resource of the property's target class and link it directly. + If the property has no target class or shape defined, this button is disabled and labeled `Undefined target class or shape`. -Click :material-chevron-down: on a node to see literal values related to this resource :material-chevron-up: closes the details again. +Repeat the expansion on any node to grow the visualization. +Use *Arrange* in the canvas toolbar to re-layout the result. -`Save` allows to save an exploration, :octicons-plus-circle-24: will start a new exploration while :fontawesome-regular-folder: allows to open any previously saved exploration. +![A visualization built from several expansions](bke-visualization.png){ class="bordered" } -![Load saved exploration from `Visualization catalog`](easynav-visualization-catalog.png) +### Inspecting and editing a resource -The `Visualization catalog` dialog shows the saved exploration and allows to :octicons-eye-24: open, :octicons-trash-24: delete or to :material-file-link-outline: copy the link to the exploration. +Double-click a node to open the details panel on the right side. +It shows the literal values of the resource and highlights its relations on the canvas. -## Setup +![Details of the selected node](bke-node-details.png){ class="bordered" } -This feature is enabled by default. -It can be customized or disabled in the respective Application view configuration section. +The buttons in the panel header are: -Without further (Application view) specific configuration the feature can be used asking for the graph that shall be explored every time a new exploration is started. +| Button | Description | +| --- | --- | +| :material-eraser: Remove from visualization | Removes the node from the canvas, the resource stays in the graph. | +| :material-delete-outline: Remove from graph | Marks the resource for deletion from the graph. | +| :material-pencil-outline: Edit mode | Switches the panel into a form to change the resource's values. | -Optionally a `Business Knowledge Editor` configuration can be created to provide a fixed graph selection and search filter settings. +The :material-dots-vertical: menu of a node offers *View in Knowledge Graph*, *New query using this resource* and +*Copy resource identifier*. -### Create a Business Knowledge Editor Configuration +### Saving -![Create a `Business Knowledge Editor` Configuration](easynav-config-EasyNavModule.png) +Click **Save** in the canvas toolbar. -In the `Knowledge Graphs` module navigate to the `CMEM Configuration` graph. +![The save dialog](bke-save-changes.png){ class="bordered" } -Select the class `Business Knowledge Editor` module and `Create a new "Business Knowledge Editor"`. +The dialog covers both aspects of a BKE session: -![New `Business Knowledge Editor` dialog](easynav-config-newEasyNavModule-dialog.png) +- **SAVE VISUALISATION** — stores the canvas itself as a named visualization. + Select the **Graph** it is stored in (`CMEM Query Catalog` by default) and provide **Name** and **Description**. + Switch the toggle off to only write the graph changes without storing a visualization. +- **GRAPH CHANGES** — lists the resources you deleted, added or changed during the session, together with the + **RESOURCE VIOLATIONS** reported for them. -Provide a `Name` for your configuration and select the `Default Graph` which contains the nodes you want to explore visually. -This graph can of course be an integration graph. +### Re-opening a saved visualization -`Search Configuration` is optional but a powerful feature to create predefined search filter/facets. -If want to use this capability select existing `Search Configuration`s in the drop down or create stubs for the configurations you want to setup. +Click :material-folder-outline: **Load existing visualization** in the application header to open the +**Visualization catalog**. -### Set the Business Knowledge Editor module in the Application view configuration +![The visualization catalog](bke-visualization-catalog.png){ class="bordered" } -![Select `Business Knowledge Editor` module in `Application view` configuration](easynav-config-select-in-workspace.png) +The catalog is a faceted list of all saved visualizations. Click an entry to open it, or use +:material-trash-can-outline: to delete it. -After creating the `Business Knowledge Editor` module configuration it need to be selected in Application view configuration(s) that shall be using it. +## Configuration + +The module is enabled by default. +All of its settings are part of the :eccenca-module-workspace-configuration: +[Application view configuration](../workspace-configuration/index.md) module, in the **Business knowledge editor** +section of the **Modules** list. + +![The module list of the Application view configuration](bke-config-modules.png){ class="bordered" } + +Expand the section to see the parameters. +The **System Default Application View** column shows the platform-wide default, the column named after the current +Application view (`default` in the screenshot) holds the value used by that Application view. + +![The Business knowledge editor configuration section](bke-config-section.png){ class="bordered" } + +### Parameters + +| Parameter | Description | +| --- | --- | +| `order` | Position of the module within the *Explore* section of the navigation bar. | +| `contextGraph` | The graph explored by default. If set, the graph drop-down on the welcome screen is not shown. | +| `searchListQueries` | Search result filter / query presets used by the module. Each entry is a [`GraphResourcePattern`](../../deploy-and-configure/configuration/explore/graph-resource-pattern/index.md) together with a label; the label becomes a tab in the **Search Instances** panel. Defaults to one preset for `Instances` (everything that is not a class) and one for `Classes`. | +| `shapePropertyView` | Determines how edges are presented. If `true`, property shape information is used (`sh:name`, `sh:path`, …), if `false` the label of the property is used. | + +### Overriding a parameter for an Application view + +Click **Override** next to a parameter to set an Application view specific value. +The value becomes editable and a :material-trash-can-outline: appears to drop the override again and fall back to the +system default. Confirm your changes with **Save** in the application header. + +![Overriding the contextGraph parameter](bke-config-override.png){ class="bordered" } + +!!! Note + Toggling the module itself off in the section header removes :eccenca-module-bke: **Business knowledge editor** + from the navigation of that Application view.