TopBraid Enterprise Vocabulary Net User and Reference Guide: Administrator Guide

EVN Application Configuration

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 do this is to create a new RDF file, checking "File will export SPIN Functions or Templates (.spin extension)" on the "Create RDF/OWL/SPIN File" dialog box.

Once you've created this file, 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 your 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.

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 before proceeding with these steps.

FTP the EVN vocabulary project to a folder on the machine running TBC-ME.
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.
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.
(Optional) Test in localhost to make sure the changes are correct.

EVN Integration Points

TopBraid EVN's ability to import and export data gives you some batch-oriented options for using data from other systems as well as providing managed vocabulary data and metadata for use by other systems. For more dynamic integration with other systems, EVN offers two classes of options: web services and a SPARQL endpoint.

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 do 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):

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>}}

Instead of specifying the named graph to query with the SPARQL GRAPH keyword, a simpler option is to name it 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 Extension Points

This section illustrates some of the ways that EVN 4 can be extended to customize the user experience. The most basic and probably most powerful way of adjusting EVN to your specific needs is probably by defining your own ontology (classes and properties) through the EVN Class editor. The UI is flexible enough to handle any number of custom properties of any data type.

To create EVN customizations and extensions you will need to use TopBraid Composer. TopBraid Composer Maestro Edition is a development toolkit for TopBraid server products. Some experience with SPARQL Web Pages (SWP) is required to build EVN extensions. The general process of customizing and extending EVN system is as follows:

Create a project that will only contain your extension files. This project will need to be uploaded onto the server for deployment.
In that project, create a SPARQL Web Pages file (RDF/SWP) with TopBraid Composer. Make sure that file ends with .ui.* (for example, myextensions.ui.ttlx), so that EVN will use it as part of the global registry of SWP components. Unless you restart, you may need to click Model > Refresh global SWP graphs to make sure that TBC knows about your new .ui. file.
In the SWP file, create the extension by making the appropriate additions to your .ui.ttlx file, for example based on the examples mentioned below.
You can test your components incrementally by launching EVN from within TBC on localhost.
Once you want to use them on the server, use the TopBraid Live project upload feature to put the project containing the SWP file (and supporting files if needed) into production. A server restart may be advisable.
TopQuadrant will attempt to ensure compatibility of the extension points with each release. In practice this means that you will only need to redeploy your customization project to TopBraid EVN after you have done a fresh reinstall of a new version.

The file evn-plugins.ui.ttlx contains examples that you can use as a starting point to understand how to implement other extensions. You can download that file and save it into your workspace. Then use Model > Refresh global SWP graphs to activate the example extensions and launch EVN to play with them. The following sub-sections briefly describe how to change CSS styled and all examples from the evn-plugins.ui.ttlx file. In TBC, you can use Model > Find all locally defined resources to get a clickable list of these extensions.

Creating and Maintaining Constraint Libraries

In addition to EVN's form-based method for defining constraints on class instances, you can define more complex ones as SPARQL-based SPIN constraints in TopBraid Composer and then load them into your EVN installation.

To do this, use TopBraid Composer to create a model with ".spin." in its filename (for example, myConstraints.spin.ttl) that has spin:constraint values added to any classes whose definitions are visible in that model (skos:Concept for the taxonomy editor and any class you like for the ontology editor). Import the SPIN/spin.ttl library from the TopBraid SPIN project into the model with your class definitions to make the spin:constraint property available on the class editing form. The skosspin.spin.ttl model included in the SKOS folder of the TopBraid project imports spin.ttl and the skos-core.ttl W3C standard SKOS model in order to implement several of the constraints described in the W3C SKOS specification, and these constraints can serve as a model for new ones that you create. See the "Adding constraints" section of Getting Started with SPARQL Rules (SPIN) for additional information on using TopBraid Composer to create new constraints.

Deploying that model to your EVN installation's workspace will make that model appear on the Select Constraint Libraries list. Each model that you create like this will show up as a separate choice on the list, so splitting constraints across models will let you use specific subsets of your total constraint collection in different combinations as necessary for your application.

If you keep these models in a dedicated project in TopBraid Composer, that project can be redeployed to the TopBraid Live server running the EVN application to put those changes into effect as described in the TopBraid Composer online help under TopBraid Composer > TopBraid Live Integration > Overview of TopBraid Live Integration.

Changing CSS Styles

In order to customize the look of EVN, you should follow this process:

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 with a tool such as FireBug.
Create a folder ending with .www in the workspace—for example, my.www. Restart TBC to make sure that it knows about that folder.
In that folder create a CSS file, for example,my.css.
In that CSS file override the style that you want to modify by adding !important to the end of the declaration.
Create a .ui. file as described earlier, and add evn.topbraidlive.org/evn/evn.ui.ttlx to its imports.
In that file, select the evnui:ApplicationElements class and add an empty row to the ui:headIncludes property.
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

The icons depicting resources in tree components can be customized, 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="{= ui: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 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.

Custom Plugins for Creating Concepts and Vocabularies

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

Custom Plugins for Creating Concepts

EVN can be configured 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.

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.

Custom Plugins for Creating Vocabularies

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. The following image shows the custom dialog box from the example in evn-plugins.ui.ttlx. This dialog uses a UUID() generated namespace and does not allow the user to change that namespace. Defining static namespaces are also possible.

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 Text Properties will appear on the top of the Search form.

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

Create an empty SWP file whose name ends with ui.ttlx—for example, GeoSearchForm.ui.ttlx.
Import the SWA namespace (swa.ui.ttlx) and the ontology that defines the class whose search form will get the Search Text Properties field into your new file.
For each property to be searched by the Search Text Properties field, add a triple of the form ?class swa:fullTextSearchProperty ?property to your 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.
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.

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.

Administrator guide

Installing EVN

Configuring a relational database manager to store your EVN data

Using MySQL to store your EVN data

Controlling user access to EVN

Configuring EVN Explorer

Setting language choices

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