TopBraid EVN Developer Guide

Adding SPARQL Query Templates

To add new taxonomy template query choices to the selections described in Running template queries, use TopBraid Composer Maestro Edition to create some that follow the pattern of the existing ones and then upload the project containing your new template queries to the EVN server.

The easiest way to accomplish this is by creating a new RDF file, checking "File will export SPIN Functions or Templates (.spin extension)" on the "Create RDF/OWL/SPIN File" dialog box.

Once the file has been created, import evn.topbraidlive.org/spin/skostemplates.spin.ttl into it, and then create a new subclass of skostemplate:IntegratedTemplates, using the existing subclasses that you see as a model. You will see that the rdfs:label property of each stores the text displayed as the template's name on the EVN Template drop-down list, its rdfs:comment value provides the tooltip, and the spin:body property stores the query to execute. Define run-time parameters by adding spl:Argument values to the spin:constraint property.

After saving the file, upload the project containing it to the EVN server, and the new menu template will be available to your users on the Template menu.

For tips on testing your query against data stored on EVN before uploading its project to make it one of the query template selections, see EVN as a SPARQL Endpoint.

Adding SPARQL Endpoints to the "Copy Concept from SPARQL Endpoint" list

The EVN user guide chapter's section on Copying data from remote sources and other vocabularies describes how to copy concepts from SPARQL endpoints. SPARQL endpoints listed in the Copy Concept from SPARQL Endpoint dialog box are stored in a model that uses the SPARQL Service Description schema.

Working with these models requires TopBraid Composer, the administrative interface to EVN. To create one, create a SPARQL Web Pages file (that is, one with .ui. in its name, such as evn-endpoints.ui.ttlx) that imports sd.ttl from the Common folder of TopBraid Composer's TopBraid project in the Navigator view.

To add a choice to the Copy Concept from SPARQL Endpoint list of endpoints, define an instance of sd:Service in your SPARQL Web Pages model. For each, specify the URI of the endpoint as an sd:endpoint value and the name of the endpoint that you want to appear on the dialog box as an rdfs:label value.

This model must be made available to the EVN server; the simplest way to do so would be to create it in its own project and to then upload that project to the EVN server.

Advanced EVN debugging

Debugging of complex relationships within your data may require more sophisticated investigations than the EVN query form allows. You can send the data any SPARQL query you like via the SPARQL endpoint, which has a web-based form at /evn/tbl/sparql where you can enter queries. (For example, for an EVN installation at http://mycompany.com/evn, the endpoint would be at http://mycompany.com/evn/tbl/sparql.)

Even more advanced investigations can be done by FTPing models to a local copy of TopBraid Composer (TBC-ME). The following is a series of general steps that can be used in this scenario.

When in doubt, check with TopQuadrant EVN support (evnsupport@topquadrant.com) before proceeding with these steps.

1. FTP the EVN vocabulary project to a folder on the machine running TBC-ME.

2. Use Import Existing Projects into Workspace to place the project into TBC-ME's workspace. This give you access to the data through the SDB back-end.

3. Modification can be made directly to the data graph as needed, because save operations will save to the SDB data back end.

   

   If you use TopBraid Composer and not EVN to make these changes, they will not be recorded using EVN's change tracking features, and may conflict with activity taking place using the web-based interface, so should be avoided.

4. (Optional) Test in localhost to make sure the changes are correct.

Web Services

Systems can call a set of built-in web services with an HTTP GET or POST. For example, the following URL (split onto two lines for this page, but to be executed as a single URL) calls the RelatedConcepts service, asking for a list of concepts related to the Geography vocabulary's concept of Asia:

http://localhost:8080/evn/tbl/template?_template=http://topbraid.org/spin/skostemplates%23RelatedConcepts
&_base=urn:x-evn-master:geo&concept=http://topquadrant.com/ns/examples/geography%23Asia

The following web form will perform a POST version of the same request:

<html>
  <body>
<form action="http://localhost:8080/evn/tbl/template" method="post">
  <p>sample form</p>
  <input type="hidden" name="_template" value="http://topbraid.org/spin/skostemplates#RelatedConcepts" />
  <input type="hidden" name="_base" value="urn:x-evn-master:geo" />
  <input type="hidden" name="concept" value="http://topquadrant.com/ns/examples/geography#Asia" />
  <input type="submit" value="Submit" />
</form>
  </body>
</html>

Select "Available EVN-related Web Services" on the EVN home page to see a list of the web services and documentation for each.

EVN as a SPARQL Endpoint

Add /evn/tbl/sparql to your EVN server's domain name and port number to get the URL of its SPARQL endpoint. Each vocabulary is stored as a separate named graph on the server; to find a given vocabulary's graph name, mouse over its name on the EVN home screen and note the projectGraph parameter in the URL that the name links to.

For example, if you have EVN installed at the domain name ourevnserver.com on port 8080, entering the following query into the TopBraid Composer SPARQL view would send a query to that endpoint requesting a list of Continent resources in the Geography vocabulary:

SELECT ?continent WHERE
{ SERVICE <http://ourevnserver.com:8080/evn/tbl/sparql> 
   {GRAPH <urn:x-evn-master:geo> 
 {?continent a <http://topquadrant.com/ns/examples/geography#Continent>} 
  } 
}

Instead of using a SPARQL client such as the TBC-ME SPARQL view to send the query to the endpoint with the SERVICE keyword, you (or, more likely, an application you are building) can run the query by embedding an escaped version of it in a URL built on the endpoint URL. For example, let's say you wanted to send the following query to the endpoint http://ourevnserver.com:8080/evn/tbl/sparql:

SELECT ?continent WHERE
   {GRAPH <urn:x-evn-master:geo> 
 { ?continent a <http://topquadrant.com/ns/examples/geography#Continent>} 
}

You can add an escaped version as a query parameter value to the endpoint URL shown above, resulting in the following URL (split here for display, but to be treated as a single line). The best practice is to use a URL encoding function to properly format the query for HTTP:

http://ourevnserver.com:8080/evn/tbl/sparql?query=SELECT+?continent+WHERE+{GRAPH+<urn:x-evn-master:geo>+
{?continent+a+<http://topquadrant.com/ns/examples/geography%23Continent>}}

An option to specifying the named graph with the GRAPH keyword, is to name the graph in a default-graph-uri parameter added to the URL. For example, let's look at this simpler query that does not mention the graph to query:

SELECT ?continent WHERE  
{?continent a <http://topquadrant.com/ns/examples/geography#Continent>}

Escaping this and adding it to the SPARQL endpoint URL with the named graph specified using the default-graph-uri parameter gives us the following URL (split here for display, but to be treated as one line):

http://localhost:8080/evn/tbl/sparql?default-graph-uri=urn:x-evn-master:geo&query=SELECT+?continent+WHERE+{?continent+a+<http://topquadrant.com/ns/examples/geography%23Continent>}

For further information on these options and on ways to specify the result set format, see the TBC-ME online help at TopBraid Composer > TopBraid Live Integration > TopBraid Live SPARQL Endpoint.

EVN SPARQL Endpoint Update

SPARQL Update statements can be executed on EVN project graphs. By default, SPARQL Endpoint Updates are disabled. To enable updates set the "Enable SPARQL updates" to true in in the Server Configuration Parameters page. Access controls are also available for SPARQL Endpoint Updates. For more information on setup for SPARQL Endpoint update, see SPARQL Endpoint Update.

SPARQL Update statements use the sparql servlet with the update parameter for specifying the SPARQL Update query. Note that the query must therefore explicitly specify a graph context to execute the update in using the GRAPH <...> syntax. An example update call is shown in the following URL:

Note this assumes a user is logged in, either via a browser or a basic authentication request. SPARQL Updates can be included in the change history by appending the user name to the end of the graph name as in the following example. The change will be added to the change graph with the currently logged in user as the creator of the change.

Access controls can also be defined for SPARQL Update using the Permission Group Management page and the SPARQLUpdateAllowGrp and SPARQLUpdateDenyGrp groups. For more information see the TopBraid Permission Group Management document.

Creating and Maintaining Constraint Libraries

In addition to TopBraid EVN's form-based method for defining constraints on class instances, SPARQL-based SPIN constraints can be defined in TopBraid Composer and then uploaded to an EVN server installation.

To do this, use TopBraid Composer to create a RDF/OWL/SPIN File. SPIN constraints defined in this file will define a constraint library for EVN. It is also useful to give the library a title that will appear in the Includes list in EVN. Go to the Ontology Home (form sub-tab) and add an rdfs:label such as "My data constraints".

Import (owl:imports) the schema of the data constraints will be executed against. For example, if constraints were being defined for the example geography model, then import the sample geo.tdb file (the schema can be un-imported after the constraints have been tested). Define constraints on the spin:constraints property. Keeping with the geography model example, if the following constraint is added to the g:Province class, then a constraint violation is raised if a member of g:Province does not have a broader relationship with one of the entities listed in the query.

# All provinces must be in Canada, Philippines, Netherlands, Belgium, Spain, Italy, South Africa, Congo, or Argentina
ASK WHERE {
?this skos:broader ?broader .
FILTER (?broader NOT IN (g:Canada, g:Philippines, g:Netherlands, g:Belgium, g:Spain, g:South_Africa, g:Congo, g:Argentina)) .
}

Note that the comment of the ASK query will be displayed when a constraint violation is found. Constraint violations can be displayed in the Constraint Violations link in the Reports tab and will also appear when editing individual concepts/instances. See the "Adding constraints" section of Getting Started with SPARQL Rules (SPIN) for additional information on using TopBraid Composer to create new constraints.

For SKOS-based vocabularies, the skosspin.spin.ttl model included in the SKOS folder of the TopBraid project implements several of the constraints described in the W3C SKOS specification, and these constraints can serve as a model for developing new constraint libraries.

Once defined and tested in TBC-ME, the file can be deployed to any project on a TopBraid EVN server. Use the Includes link in the EVN vocabulary's General tab to choose the constraint library for a specific vocabulary. Constraint libraries can be used in any vocabulary, as chosen in Include, allowing the creation a collection of constraints that can be used in different combinations as necessary for your application.

For deploying projects, which may include Constraint Violations from TopBraid Composer, to a TopBraid Live server running the EVN application, see the TopBraid Composer online help under TopBraid Composer > TopBraid Live Integration > Overview of TopBraid Live Integration.

Creating and Maintaining Constraint Templates

Constraint Templates are used to define templates for adding constraints to a class. See the EVN User Guide section named "Adding constraints to a class." A default set of constraint templates are defined in TopBraid/SPIN/spl.spin.ttl. This file can be unlocked in TopBraid Composer to view some examples of Constraint Templates, which are defined as subclasses of spl:ConstraintTemplates.

The constraint templates can be extended by following these steps:

1. In TopBraid Composer, create a New > RDF/OWL/SPIN file. Make sure the .spin extension is not selected.
2. For selection in the Include (see steps below), it is useful to provide a label for the file. Go to the Ontology Home (house icon in top icon bar of TBC), select the Form sub-tab and add an rdfs:label that gives the constraint a name, such as "Constraint Templates for Geography models".
3. Create a subclass of spl:ConstraintTemplates.
4. Edit the spin:body with a SPARQL query that construct an instance of spin:ConstraintViolation. An exmple is found below. Make sure the spin:labelTemplate property is populated with a string so that the system can display the template.
5. Deploy the project the new SPIN file is in to the server. If using TBC-ME, this step is not necessary.
6. In TopBraid EVN, open the vocabulary you want to add the constraints to.
7. Open the General tab and click on Includes. Choose the SPIN file just created.
8. Edit the Production Model or a Working Copy. Select a class and edit it.
9. Click the '+' next to Constraint. A "Add Constraint" pop-up will appear that includes the constraint template(s) included in the spin file.

An example constraint template follows. The constraint is named "Property Value of type and exact cardinality" by placing that string in the rdfs:label of a subclass of spl:ConstraintTemplates. Three arguments are defined as shown here - note the type of each argument.

The body of the example constraint template is as follows:

CONSTRUCT {
    _:b0 a spin:ConstraintViolation .
    _:b0 spin:violationRoot ?this .
    _:b0 spin:violationPath ?property .
    _:b0 rdfs:label ?message .
}
WHERE {
    ?this ?property ?value .
    ?value a ?type .
    BIND ((?type != ?class) AS ?typeCompare) .
    BIND ((spl:objectCount(?this, ?property) != ?propCount) AS ?countCompare) .
    FILTER (?typeCompare || ?countCompare) .
    BIND (IF(?typeCompare, ui:concat("The value of ", ui:label(?property), " must be of type ", ui:label(?class)), 
		ui:concat("The value of ", ui:label(?property), " can only have ", ?propCount, " values")) AS ?message) .
}

The WHERE clause of the SPARQL query checks that two constraints are valid: the type of the property value and the number of properties allowed. A different message is created depending on which constraint is violated. The CONSTRUCT clause creates an instance of ConstraintViolation. The root of the violation will be the resource being checked for violations and the property is the property passed by the filling out the template.

The constraint template will appear as shown here witht the title "Property Value of type and exact cardinality".

This constraint can be used to ensure that a country has only one capital and that its type is City. In the Geography taxonnomy edit the class Country, click the '+' for constraint and fill in as follows:

Running the Constraint Violations Report from the Report tab reveals that there are some constraint violations in the Geography model:

Changing CSS Styles

In order to customize the TopBraid EVN user interface styling, follow this process:

1. Identify the CSS style that you want to change. This is usually done by looking at the source code or the DOM tree of the HTML by performing a left-click and choosing Inspect Element (available on most browsers) or with a tool such as FireBug.
2. Create a folder ending with .www in the workspace—for example, my.www. Restart TBC to make sure that it knows about that folder.
3. In that folder create a CSS file, for example,my.css.
4. In that CSS file override the style that you want to modify by adding !important to the end of the declaration.
5. Create a .ui. file as described earlier, and add evn.topbraidlive.org/evn/evn.ui.ttlx to its imports.
6. In that file, select the evnui:ApplicationElements class and add an empty row to the ui:headIncludes property.
7. In that row, enter a line such as <link href="lib/my/my.css" rel="stylesheet" type="text/css"/>.

Here is an example CSS snippet to override the default logo:

.evn-logo {
background-image: url(images/CustomizedLogo.png) !important;
}

To verify that this worked, you should see the link to your CSS file in the generated source of EVN. The !important; directive in the styles will make sure they get higher priority than the original ones, allowing you to change colors etc. The !important is not needed if you are simply adding new styles to an existing style name.

Note that the /lib/... folder is a redirect to any folder ending with .www in your workspace. This way you can also add images and other resources such as JavaScript files.

Customizing Icons

TopBraid EVN allows the icons of resources in the tree components to be changed, even assigning different icons to representing different classes for easier visual identification by end users.

To do this, first define a CSS style using the steps described above, pointing that style to a background image of your choice and setting its background-position to 0 0. Then, store the name of that style at the class that you want to change the icon of, using the property swa:typeIcon. Point the evnui:Editor SWA application at your CSS file, and the tree will use that icon for all instances of the associated class.

For example, to reset the concept hierarchy icon for instances of the Country class in the Geography vocabulary with a myCountryIcon.jpg file stored in the same directory as your CSS file, you could add the following lines to it:

.CountryStyle { background-image:url('myCountryIcon.jpg') !important;
background-position: 0 0 !important;
}

(The !important directives are necessary to override default settings.) Then, import the Geography schema file geo.tdb into your custom ui.ttlx file and assign the g:Country class a swa:typeIcon value of "CountryStyle". Finally, import evn.topbraidlive.org/taxonomy/evn.ui.ttlx into your custom .ui.ttlx file and add a ui:headIncludes value of the following to the evnui:Editor class, adjusting the name and path to point at your own CSS file:

<link href="lib/my/my.css" rel="stylesheet" type="text/css"/>

On the concept hierarchy, you will see your new icon in place of the default one for the specified class:

If no direct type icon exists, it will walk up the superclass tree. In the case of the EVN Concept Hierarchy, it will eventually reach the icon defined for the class skos:Concept.

Adding new menu choices to TopBraid EVN

In the evn-plugins.ui.ttlx example file described at the beginning of this section, navigate to evn-plugins:ExampleGlobalAction to see how to contribute items to the global context menu in the header area of EVN. This example adds the "Example global action" menu choice shown here. When selected, it counts the number of concepts in the model:

These global menu items can be used for a large variety of tasks, and the example illustrates how to make an Ajax call-back to the server along the way.

The context menu at the bottom of the EVN screen lists menu choices that act on the currently selected resource. See evn-plugins:ExampleResourceAction in the example file for an example of how to add an item to this menu. Those action items are often used to perform edits on the selected resource, and the example shows how such edits are implemented using ui:update. Below we can see the "Example resource action" item that this example adds to the menu; selecting it displays a dialog box that queries the user for "related" and "date" values that it then adds to the resource:

Further details are provided in the rdfs:comment values of the examples.

Form Widgets

The SWP library used by EVN, the TopBraid SWP Application Components Library SWA, provides a flexible plugin mechanism that allows developers to add custom widgets to forms. Those widgets can insert arbitrary HTML, replacing the default widgets that render values as simple labels or hyperlinks. The SWA documentation (available from the Help > SWA Help/Examples) provides some background. In the example file, navigate to evn-plugins:ExampleMapObjectViewer for an example Google Maps component. You can use this with the Geography example ontology that is shipping with TopBraid.

Form Layouts

TopBraid EVN 4.5 introduces a graphical form layout editor, allowing end users to define which properties show up for a given class and in what order.

For advanced use cases please take a look at the SWA documentation (Help > SWA Help/Examples) for details on how to define custom form layouts via SWP.

Custom Plugins for Creating Concepts and Vocabularies

Custom plugins are used to modify behavior when concepts and vocabularies are created.

You may want EVN to perform additional initialization whenever a new concept is created—for example, to assign a new unique ID for each new concept. EVN provides a plugin mechanism that allows developers to add such initializations. See evn-plugins:ExampleCreateConceptPlugins for an example of such a plugin.

Similarly, EVN can be configured to perform additional initializations whenever a new vocabulary has been created through the user interface. Among others, this can be used to automatically pre-populate the user permissions (in the .tch. graph) with certain user groups. See evn-plugins:ExampleCreateProjectPlugin for an example of such a plugin.

You can use a similar plugin to adjust the dialog box that appears when new resources are created. For example, URIs of newly created resources of certain classes could be auto-generated. See evn-plugins:UUIDCreateResourceDialogPlugin for an example of such a plugin.

Activating Search Text Properties

The EVN search form by default includes a global text field that searches across all string properties of the matching instances. For large models with a lot of strings, this may be quite slow. It is therefore possible to limit the properties on a class-by-class basis, for example by searching both skos:prefLabel and skos:altLabel only. EVN provides infrastructure to do that, but it is off by default. If activated, a widget labeled Search Any Text will appear on the top of the Search form.

To turn on this behavior and specify the properties to be searched by this field by executing the following steps in TopBraid Composer:

1. Create an empty SWP file with a name ending with ui.ttlx —for example, GeoSearchForm.ui.ttlx
2. Import the SWA namespace (swa.ui.ttlx) and the ontology defining the class that Search Text Properties will search field into the file.
3. For each property to be searched by the Search Text Properties field, add a triple of the form {?class swa:fullTextSearchProperty ?property} to the file, where ?class is a class such as skos:Concept or the appropriate subclass and ?property is the property to add to the list of properties to search.
4. Upload the file to the EVN server when done.

Status Change Rules

It is possible to define SWP-based rules that are triggered whenever the status of a working copy changes, e.g. from Uncommitted to Frozen. The evn-plugins.ui.ttlx file contains an example of such a rule, which will send an email to all editors or managers of a given working copy whenever its status changes. Take a look at evn-plugins:SendEmailsOnTagStatusChangeRule. In a nutshell, the rule's prototype will be executed and side effects can be performed there. The prototype of the rule can find out what has changed via the special named graphs ui:addedGraph and ui:deletedGraph. Most SPARQLMotion modules such as sml:SendEMails can be used within SWP.

Custom Plugins for Concept Dialog Boxes

The dialog box that appears when new concepts (resources) are created can be customized. For example, URIs of newly created resources of certain classes could be auto-generated. See evn-plugins:UUIDCreateResourceDialogPlugin for an example of such a plugin.

Event-Condition-Actions Rules

TopBraid EVN includes a simple Event-Condition-Action (ECA) rule engine that can be used to trigger rules whenever a change was performed on an EVN project. Example use cases of this feature include anything that needs to happen as a side effect of edit operations:

• updating an external index (such as Solr)
• creating automatically generated triples
• aligning inverse properties
• sending automated notifications to co-workers
• ...

The following screenshot defines a rule that inserts an rdfs:comment whenever a new owl:DatatypeProperty has been created by someone.

As shown above, these ECA rules are essentially SWP elements that define their behavior in their ui:prototype. To create your own rule, simply create a globally registered .ui.* file that imports the teamworkrules system ontology, and then create a subclass of teamwork:EditRules. The rule engine of EVN will execute the ui:prototype of any globally registered edit rule after each edit. During the execution of those prototypes, there are two dedicated named graphs with a special meaning: The graph ui:addedGraph will contain the newly added triples, and ui:deletedGraph will contain those triples that have just been deleted. For example, if someone has pressed Save Changes on an EVN form, replacing one skos:altLabel with another, then the ui:addedGraph will contain the new value, and ui:deletedGraph will contain the old value. You can use SPARQL to query those change triples and perform side effects with ui:update or SPARQLMotion modules.

Note that the default graph of the WHERE clause is the active EVN graph but without its imports. To operate on the imports closure, use a WHERE clause such as:

WHERE {
{
BIND (ui:graphWithImports(ui:currentQueryGraph()) AS ?graph) .
}
GRAPH ?graph {
...
}
}

EVN uses this rule engine out of the box to update a Solr index after each edit (if Solr has been activated for the current project). For more information and examples, see the Blog entry that introduced the feature.

At your own risk...

There are a multitude of other ways in which EVN can be customized and changed, but TopQuadrant does not officially support or recommend them. For example, you can define and include your own JavaScript file in which you override some of the JavaScript functions defined in the swa.js and evn.js libraries. Another option is to declare subclasses of the existing SWP elements and use ui:overrides to substitute the ui:prototype of the existing elements. Note that we really cannot guarantee the stability of those undocumented internal JavaScript calls or SWP elements, so if you really want to change those then you need to do this on your own risk. If you feel you definitely need some other official extension point, you should contact us and let us know which parts of the system you need to modify and we may be able to accommodate this for a future release.

Further EVN customization options and capabilities

TopBraid EVN was designed to offer, out-of-the-box, most of the core capabilities needed for enterprise vocabulary management functions identified by our market research and interactions with a wide variety of organizations.

Recognizing that some organizations and users may require a certain degree of modifications and additions—ranging from simple tailoring (for example, adding a logo, changing some color scheme choices) to customization of operations (for example, modifying or adding a use case)— TopBraid EVN includes several levels and capabilities for customization. Built on the TopBraid Suite platform, designed for creating and modifying flexible applications, EVN's features as well as its look and feel can be customized through:

• Adding or modifying business actions through SPARQLMotion scripts. SPARQLMotion is a visual scripting language for data processing and orchestration. Many new operations can be added by developing new scripts.

• Changing the look and feel or content of EVN on entry pages such as the EVN home page, vocabulary management, and working copy management pages using SPARQL Web Pages (UISPIN), a SPARQL-based framework for describing user interfaces.

If you are interested in the possibilities for tailoring TopBraid EVN to better suit your needs, please contact TopQuadrant to explore the following options:

• Having TopQuadrant quickly configure a customized EVN solution to meet your detailed requirements. We will be pleased to quote and provide affordable customization and tailoring services.

• Enabling your organization to develop and maintain customizations for EVN by guiding and training your selected personnel to perform the variety of customization capabilities outlined above.

TopBraid EVN customers with product support and maintenance in effect will be able to upgrade to new EVN releases at no charge.