Custom Edit Rules

Knowledge Model Management (KMM) provides a mechanism to register routines that are triggered for every update operation. These routines are called Edit Rules (ERs). Some ERs are built-in. For example, there is a Global Unique Identifier (GUID) generation rule, which generates the “sem:guid” property for each added concept or concept scheme.

Additionally, there is a mechanism that allows to register custom ERs, allowing the update process to be customized. It might be used to generate a custom property or a resource URI in a custom URI format.

Warning

Implementing custom ERs is difficult, especially without an Integrated development environment (IDE). Also, registering custom ERs adds additional complexity to the deployment, maintenance and upgrade process. For example, there might be subtle interactions between standard and custom ERs. Also the syntax of ERs is not guaranteed not to change in future.

Implementing Custom ERs

Edit Rules are implemented with SWA Language developed by TopBraid, and documented here: http://uispin.org/ui.html?#introduction.

Here we only describe the key elements of defining an ER.

First, every ER has its type (specified under rdf:type property), supported types include:

• teamwork:EditRule - indicating this is a global (applied to all models) ER
• teamworkrulesx:ModelEditRule - indicating this is a model-specific ER
• teamwork:TCHEditRule - indicating this is a TCH graph rule (not discussed here)

Also, each ER should be defined as a subclass (specified under rdfs:subClassOf property). The corresponding super-classes are: teamwork:EditRules, teamworkrulesx:ModelEditRules, teamwork:TCHEditRules.

Second, every ER has its index (specified under ui:ruleIndex property) (0 by default). Registered ERs are fired according to increasing indexes. Negative indexes are supported.

Third, every ER has its body (specified under ui:prototype property), which defines the actual behaviur of the ER.

Registering Custom ERs

The Semaphore Workbench workspace in scanned on start-up for files with extension ui.ttlx. Each such file may provide implementation of multiple ERs. Also, each such file has its own URI, declared as the first line of the file. These URIs must be unique.

In order to register a new ER, place its implementation in “*.ui.ttlx” file into the workspace.

Enabling Model-Specific ERs

In order to enable a model-specific ER reference the ER base graph URI using the teamworkrulesx:imports predicate in TCH graph. This is done by adding the following triple to the TCH graph:

<TCH URI> teamworkrulesx:imports <ER Base Graph URI>

Here, <ER Base Graph URI> is the URI declared in the first line of the *.ui.ttlx file defining the ER.

Debugging ERs

The process of developing an ER might be complicated. In order to see debug messages, presenting details of applying consecutive ERs for an update operation, run the application with the “-Dtopbraid.debug=true” option.

Examples: Model-Specific ERs

Here we present how to use custom Model-Specific ERs. Note that Model-Specific rules are preferred over Global Rules as their impact is limited to the selected models.

We start from showing how to enable sample Model-Specific ERs, then we show to write and register a new ER.

Experimenting with provided Model-Specific ERs

A good starting point to experiment with the mechanism of ERs is to have a look at ERs delivered with the application. After running the application a set of example model-specific ERs is deployed to the workspace directory:

${SEMAPHORE_WORKSPACE_HOME}/com.smartlogic.workbench.customer/rules/

those include:

• customer-guid-rule.ui.ttlx - defines example:CR201_CustomIdGenerator which generates example:customGuid property as GUID for every concept and concept scheme
• customer-id-rule.ui.ttlx - defines example:CR200_CustomGuidGenerator which generates example:intId property (as consecutive integers) for every concept and concept scheme
• customer-uri-based-on-guid-rule.ui.ttlx - defines example:CR20_GenerateCustomUriBasedOnGuid which generates URIs for every created resource

Note that, none of the above ERs are enabled by default to any of the models.

The custom properties used by the ERs are defined in a separate workspace file:

${SEMAPHORE_WORKSPACE_HOME}/com.smartlogic.workbench.customer/rules/core/customer-core.ttl

This file is referenced from the ERs by using owl:imports predicate. Also, references to this file need to be added to the tch graph of the model for which the a custom ER is going to be enabled.

Alternatively, definitions of the properties might be embedded in the TCH graph.

Enabling sample example:CR201_CustomIdGenerator

In order to enable the sample ID generating ER, proceed with the following steps:

• Create a new test model “SampleIDTest”
• Open SPARQL Editor for the model and execute the following SPARQL insert:

PREFIX owl: <http://www.w3.org/2002/07/owl#>
PREFIX teamworkrulesx: <http://www.smartlogic.com/2016/05/semaphore-teamworkrulesx#>
INSERT {
  GRAPH <urn:x-evn-master:SampleIDTest.tch> {
    <urn:x-evn-master:SampleIDTest.tch> teamworkrulesx:imports <http://www.smartlogic.com/2016/05/customer-id-rule> .
  }
  GRAPH <urn:x-evn-master:SampleIDTest> {
    <urn:x-evn-master:SampleIDTest> owl:imports <http://www.smartlogic.com/2016/05/customer-core>
  }
} WHERE {} 

• Navigate to model and add concept scheme “MyScheme” with concept “MyConcept” underneath
• Open concept details and click on “Concept URI and GUID” next to its label, you will notice that, a custom identifier “Example integer ID” is generated and displayed.

Disabling sample example:CR201_CustomIdGenerator

This a continuation of the previous scenario.

• Open SPARQL Editor for the “SampleIDTest” model and execute the following SPARQL delete:

PREFIX owl: <http://www.w3.org/2002/07/owl#>
PREFIX teamworkrulesx: <http://www.smartlogic.com/2016/05/semaphore-teamworkrulesx#>
DELETE {
  GRAPH <urn:x-evn-master:SampleIDTest.tch> {
    <urn:x-evn-master:SampleIDTest.tch> teamworkrulesx:imports <http://www.smartlogic.com/2016/05/customer-id-rule> .
  }
} WHERE {} 

• Navigate to “MyScheme” and create concept “MyStandardConcept” underneath
• Open “Concept URI and GUID” for the concept. Notice that “Example integer ID” is not generated

Enabling sample example:CR20_GenerateCustomUriBasedOnGuid

In order to enable the sample URI based on GUID generating ER, proceed with the following steps:

• Create a new test model “SampleURIBasedOnGUIDTest”
• Open SPARQL Editor for the model and execute the following SPARQL update

PREFIX owl: <http://www.w3.org/2002/07/owl#>
PREFIX teamworkrulesx: <http://www.smartlogic.com/2016/05/semaphore-teamworkrulesx#>
INSERT {
  GRAPH <urn:x-evn-master:SampleURIBasedOnGUIDTest.tch> {
    <urn:x-evn-master:SampleURIBasedOnGUIDTest.tch> teamworkrulesx:imports <http://www.smartlogic.com/2016/05/customer-uri-based-on-guid-rule> .
  }
} WHERE {}

• Navigate to model and add concept scheme “MyScheme” with concept “MyConcept” underneath
• Open “MyScheme” details and click on “ConceptScheme URI and GUID”, you will notice the URI is in the form: <xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx>, where the last part corresponds to the sem:guid property.
• Open “MyConcept” details and click on “Concept URI and GUID” next to its label, you will notice the URI is in the form: <SampleURIBasedOnGUIDTest#xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx>, where the last part corresponds to the sem:guid property.

Note that this rule does not require to reference the <customer-core> graph, as this rule does not add new triples for custom properties. It “only” generates the URIs.

Example - writting and registering custom Model-Specific ERs

Here we describe how to develop and register your own ERs. TIn particular, we show how to modify one of workspace examples. This includes, where to put the modified files, and how to enable the ER once ready.

In this example we want to add a custom GUID property (called mycompany:guid) for every concept and concept scheme added to a given model, perform the following steps:

• Ensure the application is not running
• Create a new workspace directory:

${SEMAPHORE_WORKBENCH_HOME}/workspace/com.smartlogic.workbench.customer/customized

• Create, in the `customized` directory, a new file `mycompany-core.ttl`, which will only define the mycompany:guid property, with the following content:

# baseURI: http://www.smartlogic.com/mycompany-core

@prefix mycompany: <http://proto.smartlogic.com/mycompany#> .
@prefix owl: <http://www.w3.org/2002/07/owl#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

mycompany:guid
  rdf:type owl:DatatypeProperty ;
  rdfs:label "My Company GUID" ;
  rdfs:subPropertyOf skos:notation ;
.
<http://www.smartlogic.com/mycompany-core>
  rdf:type owl:Ontology ;
.

• Copy the customer-guid-rule.ui.ttlx file and put it into ${SEMAPHORE_WORKBENCH_HOME}/workspace/com.smartlogic.workbench.customer/customized/ as mycompany-guid-rule.ui.ttlx.
• Modify the file by applying the the following string replacements:

 http://www.smartlogic.com/2016/05/customer-guid-rule -> http://www.smartlogic.com/mycompany-guid-rule
 http://www.smartlogic.com/2016/05/customer-core -> http://www.smartlogic.com/mycompany-core
 http://proto.smartlogic.com/example# -> http://proto.smartlogic.com/mycompany#
 example: -> mycompany:
 "Custom GUID generator" -> "My Company GUID generator"

• Restart the application (the new ER in “*.ul.ttlx” file will be registered on start-up)
• Create a new model, named “MyCompanyGuidTest”
• Open SPARQL Editor for the model and execute the following SPARQL update

PREFIX owl: <http://www.w3.org/2002/07/owl#>
PREFIX teamworkrulesx: <http://www.smartlogic.com/2016/05/semaphore-teamworkrulesx#>
INSERT {
  GRAPH <urn:x-evn-master:MyCompanyGuidTest.tch> {
    <urn:x-evn-master:MyCompanyGuidTest.tch> teamworkrulesx:imports <http://www.smartlogic.com/mycompany-guid-rule> .
  }
  GRAPH <urn:x-evn-master:MyCompanyGuidTest> {
    <urn:x-evn-master:MyCompanyGuidTest> owl:imports <http://www.smartlogic.com/mycompany-core>
  }
} WHERE {}

• navigate to model and add concept scheme “MyScheme” with concept “MyConcept” underneath
• Open concept details and click on “Concept URI and GUID” next to its label, you will notice that, a custom identifier “My Company GUID” is generated and displayed.

Examples - Global ERs

Here we present how to use Global ERs. In particular we show how to write and register a new ER for URI generation.

Provided Global ERs

A set of default ERs used by Semaphore Workbench is provided in the workspace directory:

${SEMAPHORE_WORKSPACE_HOME}/com.smartlogic.topbraid.teamwork/rules/

Generate URIs based on sem:guid property in all models

• Ensure the application is not running
• Create (if doesn’t exist yet) a new workspace directory:

${SEMAPHORE_WORKBENCH_HOME}/workspace/com.smartlogic.workbench.customer/customized

• Copy the customer-uri-based-on-guid-rule.ui.ttlx file and put it into ${SEMAPHORE_WORKBENCH_HOME}/workspace/com.smartlogic.workbench.customer/customized/ as mycompany-global-uri-based-on-guid-rule.ui.ttlx.
• Modify the file by applying the the following string replacements:

http://www.smartlogic.com/2016/05/customer-uri-based-on-guid-rule -> http://www.smartlogic.com/mycompany-global-uri-based-on-guid-rule
http://proto.smartlogic.com/example# -> http://proto.smartlogic.com/mycompany#
example:CR20_GenerateCustomUriBasedOnGuid -> mycompany:CR20_GenerateCustomUriBasedOnGuid
teamworkrulesx:ModelEditRule -> teamwork:EditRule      
teamworkrulesx:ModelEditRules -> teamwork:EditRules
"Generate custom URI based on GUID" -> "Generate My company URI based on GUID"

• After the changes are applied, the file should have the following content
• Restart the application (the new ER file will be registered on start-up)
• Create a new model, named “GlobalUriBasedOnGuidTest1”
• Navigate to model and add concept scheme “MyScheme” with concept “MyConcept” underneath
• Open “MyConcept” details and click on “Concept URI and GUID” next to its label, you will notice the URI is generated based on sem:guid property.

• You may want to repeat the last three steps for a new different model “GlobalUriBasedOnGuidTest2”. You will notice the ER is applied as well.