|
| 1 | +--- |
| 2 | +icon: eccenca/application-queries |
| 3 | +tags: |
| 4 | + - LinkRules |
| 5 | + - KnowledgeGraph |
| 6 | +--- |
| 7 | +# Link Rules Module |
| 8 | + |
| 9 | +## Introduction |
| 10 | + |
| 11 | +The Link Rules module provides mechanisms to simplify creating data linking and to imposes role specific workflows over the whole process. |
| 12 | + |
| 13 | +Linking tasks allow the creation of links between resources based on rules in the Corporate Memory Build component. Such a linking task demands the configuration of source and target input resource selections (dataset, resource type or additional restrictions), the link type and an output dataset. These configurations demand a thorough understanding of your knowlege graph internals and may become a repetitive task. The Link rules module allows to streamline this process in a way that also users with limited understanding of the knowledge graph can create link rules based on pre-defined templates. |
| 14 | + |
| 15 | +## Usage |
| 16 | + |
| 17 | +This guide explains how to navigate, search, create, and manage Link Rules in the interface. |
| 18 | + |
| 19 | +{ class="borderer"} |
| 20 | + |
| 21 | +### Open the Link Rules Section |
| 22 | + |
| 23 | +In the main navigation menu, under *BUILD* section, click *Link rules* (①). |
| 24 | +This opens the list of existing link rules. |
| 25 | + |
| 26 | +### Manage Templates (Optional) |
| 27 | + |
| 28 | +If you want to work with predefined templates for link rules, click *Manage Templates* in the top right corner (②). |
| 29 | + |
| 30 | +### Search for Link Rules |
| 31 | + |
| 32 | +Use the Search field (③) to quickly locate an existing link rule by name or keyword in the description. |
| 33 | + |
| 34 | +### Expand or Collapse Rule Details |
| 35 | + |
| 36 | +Click the arrow icon (④) next to a rule to expand or collapse its details. |
| 37 | + |
| 38 | +In the Details tab (⑦), you’ll find: |
| 39 | +- General Information (operators, paths) |
| 40 | +- Result Statistics |
| 41 | +- Rule Status |
| 42 | +- Publication Information |
| 43 | +- Activities |
| 44 | +- The Custom tab contains any additional user-defined properties. |
| 45 | + |
| 46 | +In the rule execution panel (⑥), you can *Execute* the rule (▶ icon), *Delete* the rule (🗑 icon) and *Clone* (⿻ icon) it or modify its configuration (✏ icon). |
| 47 | + |
| 48 | +### Open the Link Rule editor |
| 49 | + |
| 50 | +Click on the rule name in the *Linking* column (⑤) to open the link rule editor. |
| 51 | + |
| 52 | +### Create a New Link Rule |
| 53 | + |
| 54 | +To create a new rule, click the blue plus button (⑧) in the bottom-right corner. |
| 55 | +Follow the prompts to define the template, connecting predicate, etc. |
| 56 | + |
| 57 | + |
| 58 | +## Setup |
| 59 | + |
| 60 | +### Template Catalog |
| 61 | + |
| 62 | +Create a new graph that holds templates for Link Rules. The graph IRI will be needed for configuration later on. |
| 63 | + |
| 64 | +!!! info |
| 65 | + |
| 66 | + Suggestion for Template Catalog Graph IRI: ´https://ns.eccenca.com/data/linkruletemplates/´. You may use [this file](./CMEM_Link_Rule_Template_Catalog.ttl) as the graphs content. |
| 67 | + |
| 68 | +!!! info |
| 69 | + |
| 70 | + This graph could be prepared even it is not used in many setups. |
| 71 | + |
| 72 | +!!! info |
| 73 | + |
| 74 | + If there is no Shape for Link Rule Template load this file as a `New Shape Catalog` (Graph label: Link Rules Shape Catalog, Graph IRI: ´https://vocab.eccenca.com/shacl/link_rules/´). |
| 75 | + |
| 76 | + |
| 77 | +### Link Rules Build project |
| 78 | + |
| 79 | +Create a new project in Build that holds all linking tasks created in the Link Rules module. |
| 80 | + |
| 81 | +{ class="bordered" } |
| 82 | + |
| 83 | +In the *Advanced Options* section set a *Project Identifier* as this needs to be configured in the next steps. |
| 84 | + |
| 85 | +Inside this project create a new workflow that will be used to register all published rules, so that all these rules can be executed at once. Again it is recommended to set a *Item Identifier* as this needs to be configured in the next steps. |
| 86 | + |
| 87 | +{ class="bordered" } |
| 88 | + |
| 89 | +Inside this project create *Knowledge Graph datasets* for these graphs you want to use for linking. |
| 90 | + |
| 91 | +!!! info |
| 92 | + |
| 93 | + This project is managed by the *Link Rules module*. You should not alter elements inside the project unless you know what you are doing. |
| 94 | + |
| 95 | +### Access condition |
| 96 | + |
| 97 | +Create a dedicated access condition that allows users to execute link rules and write results to the output graphs of created link rules. |
| 98 | + |
| 99 | +This access conditions is used by the Link Rules module to grant write access to the output graph whenever a new rule is created. |
| 100 | + |
| 101 | +!!! info |
| 102 | + |
| 103 | + It is currently not possible to set a *Access Condition Identifier* nor to simply retrieve the IRI of an existing access condition. Hence the admin needs to retrieve the IRI of this access condition from the CMEM Access Conditions graph. |
| 104 | + |
| 105 | +### Workspace configuration |
| 106 | + |
| 107 | +Enable the *Link Rules* module. |
| 108 | + |
| 109 | +In the following let us walk through the configuration options. |
| 110 | + |
| 111 | +- **Order**: The position of the Link Rules module in the menu. |
| 112 | +- **Template Catalog IRI**: The IRI of the template catalog we just created. As the name implies, the Template Catalog holds all templates for usage in the Link Rules module. Templates allow preselecting patterns for easier rule creation. |
| 113 | +- **Project ID**: The *Project Identifier* of the Link Rules Build project we just created. Link Rules will be managing this project and add the rules to it. To get the id of a project, open the project in the build component, select the project and choose 'Show identifier' in the context menu, in the top right. The project needs to have a workflow, which is used to execute the rules and has to be configured in this section. Furthermore, the projects needs one or more Datasets, which can be selected in the templates. |
| 114 | + |
| 115 | + |
| 116 | +- **Published Rules Workflow ID**: The *Item Identifier* of the workflow in the Link Rules Build project we just created. |
| 117 | +- **Access Condition IRI**: The IRI of the Access Condition we just created. |
| 118 | +- **Output Graph Template**: A template for graph IRIs which will hold the results of a linking rule. It needs to include the placeholder `{name}`, for example `http://eccenca.com/user_rules/result_{name}`. |
| 119 | +- **Publication Graph Template**: A template for graph IRIs which will import the result graph once the results are published. This can be a simple graph IRI, for example `http://eccenca.com/user_rules/results_published`. |
| 120 | +- **Result Download Query**: A query that will be used to download the results of a linking rule. By default all resource IRIs will be listed as `resource1` and `resource2`. Whenever you want to provide other data via the *Download results* function, such as a specific identifier or a label instead of the IRI, this query can be adopted here. |
| 121 | +- **Annotation Class IRI** (optional): Rule results can be enriched with annotations. Instances of this class can be selected in the link rules interface. Instances have both a connection to the rule and the result. The connection is defined by the *Annotation Link Property IRI*. The values of the annotation are defined by the *Annotation Value Property IRI*. This relation is materialized as `rdf:value` in the output graph upon execution. |
| 122 | +- **Annotation Value Property IRI** (optional): Values of sub-properties of this property are actually connected as `rdf:values` to the generated links of a rule. |
| 123 | +- **Annotation Link Property IRI** (optional): The connection between a rule and an annotation resource (i.e. instance of *Annotation Class IRI*) is defined by this property. |
| 124 | +- **Annotation Graph IRI** (optional): The IRI of the graph, from which instances of the *Annotation Class IRI* are selected. |
| 125 | + |
| 126 | +When the configuration is saved the *Link Rules module* should appear in the *Build* section of the menu. |
| 127 | + |
| 128 | + |
| 129 | +### Create a Link Rule Template |
| 130 | + |
| 131 | +Templates can be managed at *Link Rules module* -> *Manage Templates*. |
| 132 | + |
| 133 | +Create a new Link Rule Template. Such a template describes an abstract link rule with pre-defined settings. |
| 134 | + |
| 135 | +- **Label**: A mandatory label for the template. |
| 136 | +- **Target Property**: The (default) connecting property for the derived link rules. The property can be individually set for each link rule later on. |
| 137 | +- **Input** group: The datasets which hold the subjects (source) and objects (target) to link. |
| 138 | + - **Source/Target Dataset**: The dataset holding the resources to link. |
| 139 | + - **Source/Target Resource Pattern**: A filter description template for the resources to link. This is a JSON object as described in [Graph Resource Pattern](#graph-resource-pattern). When creating a Link Rule based on this template these resource patterns can be altered. So this template may remain simple, but should provide sufficient help for the end user to define a proper resource selection. |
| 140 | +- **Output** group: The dataset which will hold the Link Rule results. |
| 141 | + - **Output Graph**: The graph IRI where to write the Link Rule results. Available placeholders: `{name}` for the Link Rules name. |
| 142 | + |
| 143 | +##### <a name="graph-resource-pattern"></a> Graph Resource Pattern |
| 144 | + |
| 145 | +This section specifies the JSON object used to provide a search filter configuration for source and target resources used for the Link Rule. |
| 146 | + |
| 147 | +The source / target resources are always referred as variable `a`. |
| 148 | + |
| 149 | +In the example below, resources are selected which are of type variable `class` and are referenced another resource named `subResource` by the property `http://example.com/vocab/hasParent`. The `class` variable is restricted to be one of `http://example.com/vocab/Company` or `http://example.com/vocab/Department`. |
| 150 | + |
| 151 | +```json |
| 152 | +{ |
| 153 | + "paths": [ |
| 154 | + { |
| 155 | + "subjectVarName": "a", |
| 156 | + "predicate": "http://www.w3.org/1999/02/22-rdf-syntax-ns#type", |
| 157 | + "objectVarName": "class" |
| 158 | + }, |
| 159 | + { |
| 160 | + "subjectVarName": "subResource", |
| 161 | + "predicate": "http://example.com/vocab/hasParent", |
| 162 | + "objectVarName": "a" |
| 163 | + } |
| 164 | + ], |
| 165 | + "pathFilters": [ |
| 166 | + { |
| 167 | + "varname": "class", |
| 168 | + "varIsAnyOneOfResource": [ |
| 169 | + "http://example.com/vocab/Company", |
| 170 | + "http://example.com/vocab/Department" |
| 171 | + ] |
| 172 | + } |
| 173 | + ] |
| 174 | +} |
| 175 | +``` |
| 176 | + |
| 177 | +In the `paths` section triple patterns are defined using `subjectVarName`, `predicate`, `objectVarName`. |
| 178 | + |
| 179 | +The `pathFilters` section defines restrictions on the variables defined above. |
| 180 | +The following path filter properties can be used: |
| 181 | + |
| 182 | +- `isNoneOfLiteral` |
| 183 | +- `isNoneOfResource` |
| 184 | +- `varIsAnyOneOfLiteral` |
| 185 | +- `varIsAnyOneOfResource` |
| 186 | +- `literalFilters` |
| 187 | + - `GreaterThan` |
| 188 | + - `LessThan` |
| 189 | + - `GreaterEqualsThan` |
| 190 | + - `LessEqualThan` |
| 191 | + - `NotEquals` |
| 192 | + - `Contains` |
| 193 | + - `Regex` |
0 commit comments