TQ logo

Complete TopQuadrant Documentation

TopBraid Enterprise Vocabulary Net User and Reference Guide

User guide

This chapter shows you how you can use EVN to perform the basic tasks associated with the editing and maintenance of multi-user vocabularies.

The EVN home screen

The top of the EVN home screen has a banner with a log out link and a Help link that leads to the EVN documentation.


Internet Explorer 9 has been known to unnecessarily switch to Windows Compatibility View at times, sometimes causing problems with the EVN interface. See Internet Explorer and Compatibility Mode for information on resetting this.

Right under the banner, the EVN home screen lists up to two categories of taxonomies, depending on what role the logged-in user has for each taxonomy: Taxonomies that you can edit and Taxonomies that you can view.

If you have heard about vocabularies on your system that do not appear there, you may not have the appropriate viewing or editing privileges for that vocabulary. To grant you access, a user with manager privileges for that vocabulary needs to assign you a Viewer (or higher) role. See Changing the role of a production or working copy vocabulary user in the User Guide chapter for details about the necessary steps.

The menu below the listed taxonomies offers these options:

The next section of the EVN home screen lists up to three categories of ontologies, depending on what role the logged-in user has for each: Ontologies that you manage, Ontologies that you can view, and Ontologies that you have no access to.

For the purposes of EVN, taxonomies are defined as models that are based on SKOS. Ontologies are defined as models that do not include SKOS. (While you can edit a SKOS-based model in the ontology editor, the taxonomy editor offers additional features that make it a better tool for this.)

User interfaces for managing SKOS and non-SKOS models differ slightly. For example, with non-SKOS models, EVN does not display a Concept Hierarchy (a hierarchy of items connected by SKOS "broader" statements). Similarly, imports and exports of hierarchically structured spreadsheets are not supported for these models.

Since most of the editing features in the two interfaces are identical, the EVN user guide does not offer separate documentation for working with ontologies. We recommend that users follow the documentation that describes how to work with SKOS taxonomies with an understanding that when working with non-SKOS models, they will see the term "ontology" in the interface instead of "taxonomy." When describing features available for managing both taxonomies and ontologies, we will use the term "vocabularies."

Features supported only for SKOS models but not available for other models are identified in this guide with the following:

This feature is available only for taxonomies.

Below the listed ontologies, the Create New Ontology link lets you create a ontology as described in Creating a new taxonomy. (As mentioned above, in this tool you will see the term "ontology" and not "taxonomy" used for these models).

The Content Tag Sets section of the EVN home page lists any tag sets created using EVN Tagger. This includes menu choices to Create New Content Tag Set and to see the Guide to Tagger, which describes all of the necessary steps for setting up and using EVN Tagger.

The Administration section of the EVN home page has options for your EVN system administrator and developers using EVN as a vocabulary server. The Server Administration menu choice leads to setup and configuration options described in the in the Administrator guide, and Available EVN-related Web Services describes the details of how to use the web services made available as part of the TopBraid Search Enrichment Server.

Managing windows

Several features of TopBraid EVN will open up a new window to display information. For example, mousing over one of the arrows on a display form, as shown below, displays a tool tip that indicates that it can open a separate window with information about that resource—in this case, the label "USA":


Clicking "USA" will display information about that label in the same window. Clicking the arrow, however, will open a new window with the information about that label resource:


Note the white X in the upper-right of the new window. Clicking this white X on any window that has one will close that window.

Editing and searching concepts

This section describes the tasks involved in navigating and editing taxonomies. There are no special browsing or editing tasks that can only be performed with production or working copy taxonomies, so everything described in this section can be used with either.

When you edit the production copy of a taxonomy and save your edits, those changes will be visible by everyone using the production copy. They will also appear in any working copies. When you edit a working copy, though, those changes will only be visible in that working copy.

Selecting a production or working copy to edit

On the EVN home screen, all vocabularies for which you have access will appear as a hypertext link. Clicking one sends you to that vocabulary's production copy management screen. From this screen, if you have edit privileges, the Edit Production Taxonomy link will appear, and you can click it to go to edit screen.

Instead of editing a production copy directly, it is a best practice to make edits to a working copy and to then commit the working copy to production after a review cycle. See Vocabulary change management: working with working copies for further information.

If this vocabulary has any uncommitted working copies, their names will also appear on the production copy management screen, with those that you have access to appearing as hypertext links. Clicking one of these links will take you to the working copy management screen, which is very similar to a production copy management screen. If you have edit privileges for this working copy, you can click the Edit Working Copy link to go to the edit screen for that working copy.

Browsing information about concepts

This feature is available only for taxonomies.

When editing a taxonomy, the Concepts screen shows you the concept hierarchy tree, property values of the selected concept, and links to navigate away from the main editing screen. Clicking the dark bar on the separator between the concept hierarchy and the property values form collapses the hierarchy to the left to make more room for the form.



When the concept hierarchy is collapsed, clicking the dark bar on the left will restore it.

In the upper-left, you can link directly to the EVN Home page, or to the management page for the taxonomy you are editing or, if you are editing a working copy, the management page for the working copy ("November edits" in the illustration below). Links in the upper-right let you find out more about the logged-in user and also let you log out.

The Concept Hierarchy lets you navigate through the concepts. Click the plus or minus sign to the left of a concept label on the hierarchy to expand or contract that level of the hierarchy.



Selecting a concept name in the hierarchy displays the attribute and relationship values for that concept in the form on the right. This includes the preferred label of the concept and the property values for that concept. In the illustration above, with Ukraine chosen on the hierarchy on the left, we see details about it on the right.

The black bar across the top of the form shows the concept's preferred label, class, and on the right its Uniform Resource Identifier, or URI. This globally unique ID for the concept is used as an internal identifier and also makes it possible for the concept to link to related data outside of this taxonomy using Semantic Web standards.

Data about a concept can be one of two kinds of properties:

If the concept's data was imported from another source using one of the choices from the gear menu at the top of the screen, selecting Refresh resource from the gear menu at the bottom of the screen will update the local copy of that data from the source that it was copied from.

Displaying edit history

Clicking the Show History checkbox near the top of the taxonomy editing screen (or the lower-right of the ontology editor) toggles the display of a list of saved changes made to this resource within the working or production copy being edited since it was first created.


Editing concepts

To edit a concept in the EVN Editing application, browse to it as described in Browsing information about concepts and their history and click the concept you wish to edit on the concept hierarchy tree. This displays its preferred label and metadata in the tab on the right.

When displaying a concept, this form will only show properties that have values assigned:


When you click the Edit button at the bottom, though, the edit form lets you edit any property that may be associated with this class:


The scroll bar on the right shows that the displayed portion of the form is not even one fourth of it.

After making any edits, additions, and deletions, the Save Changes button at the bottom of the edit screen will save your changes to this concept. Click the Cancel button next to it if you decide to abort your changes.

You can undo the changes made with a given save operation by clicking the "Undo must recent edit" button in the upper-right of the EVN screen. Clicking this button again will undo your undo operation, reverting the data to its state before the first time you clicked it.

To change a concept's place on the Concept Hierarchy, you can edit its has broader value on the edit form, or you can just drag it on the hierarchy to its new location. Below, we see that Christmas Island is being dragged to Maldives; the green checkmark shows that Maldives is a valid place to put the Christmas Island concept. (For inappropriate destinations, EVN displays a red X instead of a green checkmark.)


Editing, adding, and deleting relationships and other property values

To edit an existing value, click its field and edit it like you would edit a value on any form. If a property has no values assigned, the editing form will have a single blank where you can add text as if you were editing an existing value.

After you begin entering a value for a relationship property, a drop-down list will display the names of valid concepts beginning with those letters, letting you scroll down and pick one instead of typing its whole name. The following shows the list after entering "Ta" in the "has related" property while editing the Geography taxonomy; the cursor has scrolled down to select Taiwan from the list:


EVN lets you add additional values for a given property by clicking the plus sign next to the property name. For example, if the preferred label property only has the value "Ukraine", clicking its plus sign adds a new blank field underneath the existing value:


Often, the reason to have multiple values for the same property in a given concept is to show the same information in multiple languages. The drop-down list to the right of each value lets you assign a specific language code. The following shows the second preferred label for "Ukraine" being assigned the ISO 639 language code for the Spanish language:


Your EVN administrator can customize the list of language code choices offered on this list to be as long or as short as you like as described in the Setting language choices section of the Administrator guide chapter. The languge selection can also include country-specific language codes such as "es-MX" and "en-US" as well as two-letter language codes such as "es".

When you import one vocabulary into another (or, as is very common, multiple vocabularies into an empty one to provide a "view" on that combination of vocabularies), as described in Importing one vocabulary into another, the techniques described above will let you define relationships between any two concepts in any of the these vocabularies. This is a nice way to build crosswalks and other sets of relationships between independently-developed vocabularies.

To delete a property value, click the X to the right of the value.

Polyhierarchies

When a particular concept can appear more than one place in a taxonomy's hierarchy, that hierarchy is known as a polyhierarchy. This is useful, for example, if you want a certain class of products for sale to appear as the child of multiple other categories, such as putting "Outdoor lamps" under both "Lighting" and "Patio furniture." Below, we see that the British Virgin Islands concept is a child of both United Kingdom and West Indies:


This isn't two different concepts with the same preferred label (which is perfectly OK in EVN); it's the same concept appearing in two different places. Because British Virgin Islands is selected on the tree, we can see on the right that its metadata includes two values for "has broader": the United Kingdom and West Indies concepts. Adding a value to make it show up in additional places on the tree, or removing it from one of these two places, is as simple as clicking the Edit button and adding or removing "has broader" values.

Rich text editing

Properties such as definition and history note, where you may have one or more paragraphs of text, include a toolbar of drop-down lists and buttons that let you customize the appearance of your text. Each of these widgets modifies the currently selected text or, if none is selected, any text that you type while the button is selected. Buttons that do not apply to your current task will be displayed in a lighter color and won't do anything—for example, if you haven't performed any editing actions yet, the Undo button will be unavailable.


Words not in EVN's spellcheck dictionary, like "Helvetica" in the illustration above, are displayed with a squiggly red line underneath them.

The three drop-down lists on the rich text toolbar let you set the Format of a paragraph (for example, to "Paragraph" or "Heading 1"), the Font Family (for example, to Arial or Courier New) and the Font Size.

The buttons do the following:

Mousing over each button tells you its name and its shortcut key, if it has one.

Bold: Bolds the text. Keyboard shortcut: Ctrl+B.
Italic: Sets the text in italics. Keyboard shortcut: Ctrl+I
Underline: Underlines the text. Keyboard shortcut: Ctrl+U
Align Left: Justifies a paragraph of text along the left edge of the display. This is the default setting.
Align Center: Centers the paragraph of text within the display.
Align Right: Justifies the text against the right edge of the display.
Align Full: Justifies the text against the left and right edges of the display by adding spaces between the words.
Select Text Color: Sets the text to the color that you select from the palette displayed with the little black triangle.
Select Background Color: Sets the text's background to the color that you select from the palette displayed with the little black triangle.
Insert/Remove Bulleted List: Makes the current paragraph a bulleted list item, converts multiple paragraphs into a bulleted list, or removes existing bullets.
Insert/Remove Numbered List: Makes the current paragraph a numbered list item, converts multiple paragraphs into a numbered list, or removes existing numbers.
Decrease Indent: Undoes the indenting done by the "Increase Indent" button by one level.
Increase Indent: Indents the current or selected text one level.
Insert Horizontal Line: Inserts a single line across the width of the display.
Undo: Undoes the most recent edit action. Keyboard shortcut: Ctrl+Z
Redo: Redoes the most recent "undo" action. Keyboard shortcut: Ctrl+Y
Insert/Edit Link: Displays a dialog box that lets you turn the selected text into a hypertext link, or, if it is already one, lets you configure it. The dialog box has several tabs of options to set the link's behavior and appearance.
Link to Concept: Converts the selected text into a link to another concept in this taxonomy (as opposed to converting it to a traditional hypertext link to a web resource, like "Insert/Edit Link" does). A dialog box will let you enter the destination concept's name; as you type, its typeahead feature will display a drop-down list of terms from the current taxonomy that begin with the letters you've typed.
Unlink: Convert the selected link anchor text back to regular text.
Insert/Edit Image: Lets you set the URL and formatting parameters for an image to embed in the text.

Linking a concept to DBpedia

This feature is available only for taxonomies.

The DBpedia project makes data from Wikipedia infoboxes available as Linked Data. When you have a concept selected in EVN, selecting Link to DBpedia resource from the gear menu at the bottom of the screen adds a "has related" property to that concept; its value points to the same concept in DBpedia. If EVN cannot find a corresponding concept in DBpedia, it assigns a "has related" value of false.

When this property is set, applications using your taxonomy's data can use this value to retrieve additional data about the concept from the DBpedia SPARQL endpoint.

Adding comments

When viewing or editing a concept, the Comments button in the lower-left shows how many comments have been added to the selected concept for this production or working copy. Clicking the button displays a dialog box where you can see previous comments and add your own under the "Add Comment" title; Click the OK button when you are finished.

The following shows the second comment being added for the West Indies concept:


Comments have a status such as "open", "declined" and "resolved". The status of those can be changed using a drop down list at the bottom of each comment entry.

The Comments dialog may also display comments submitted by users of the EVN Viewer application. Those are marked with (via Browser).

In order to get an overview of recently added comments, click on View Comments on the main page of the selected vocabulary or working copy. This link will not show up if no comments have been entered yet. The resulting page lists the most recent 100 comments with hyperlinks that take users to the relevant screen to edit the concepts. The comments can be filtered by status, e.g. to only display the "open" comments.

Working with the concept hierarchy: adding, deleting, and moving concepts and schemes

This feature is available only for taxonomies.

Creating one or multiple concepts

To create a new concept, select the new concept's parent on the Concept Hierarchy and click the the "Create Concept" button underneath the Concept Hierarchy. This displays the Create Concept dialog box. Below, we see the dialog box displayed after clicking this button with "American Samoa" selected:


The dialog box has three fields:

  • The Label is the preferred label for the new concept. You can always edit this value later, the same way you would edit any other preferred label.

  • The Identifier is the internal ID used by EVN to track the concept. (Because SKOS is based on the W3C RDF standard, this ID is a URI.) Advanced users sometimes have reasons to edit this, but you in most cases you'll be safe just leaving the default value that appears.

  • The Type identifies whether the new Concept is a regular concept or a specialized class of concept. EVN lets you create these classes so that specialized properties can be stored for some concepts but not others—for example, so that forms for editing countries include the calling code, but forms for editing continents do not. Click the downward-pointing arrow on this field to see what your choices are for this vocabulary. (To create new classes, see Working with classes.)

After you click the Create Concept dialog box's OK button, EVN will select your new concept on the Concept Hierarchy and display its edit form, where you can edit it the same way you'd edit any other concept.

To create multiple concepts at once, select the parent of the new concepts on the Concept Hierarchy and pick Create multiple concepts from the gear menu at the bottom of the screen. A dialog box will ask you to enter label values for each one on a separate line, and a field under that lets you specify the type to enter. The following shows three labels entered with a class of Island selected:


After you click OK on the dialog box, you will see the three new concepts added as child of the selected one on the concept hierarchy. You can then edit them the same way you would edit any other concepts.

Cloning concepts

If you want to create a new concept that is similar to an existing one so that you don't have to re-enter all the property values for the new concept, you can create a clone of the existing one. You can also clone a concept and the subtree of descendant concepts underneath it in the concept hierarchy.

To clone a single concept, select it the concept hierarchy, then pick Clone concept from the gear menu at the bottom of the screen. EVN will create a sibling of the existing concept with the same name but the word "Copy" added to the end of its preferred label. You can then rename it to whatever you like.

All the other data will be copied to the new one, and any concepts that had the original concept as a property value will have the new one as well. Before the Belize concept was cloned in the following, the concept for the city of Belmopan had only one "has broader" value: Belize.


Now, it has both Belize and Belize Copy as has broader values.

The value of a relationship property (for example, the "has broader" value for Belmopan) is another concept, but the preferred label of that value is what EVN displays as the value. If you update that concept's preferred label, the update will be reflected in the data for concepts that have that concept as a value. For example, if you clicked "Belize Copy", renamed it to "New Belize", and then clicked Belmopan, you would see the update to the Belize Copy concept shown in Belmopan's "has broader" value.

To clone multiple concepts at once, select a concept on the concept hierarchy and pick Clone concept and descendants from the gear menu at the bottom of the screen, EVN creates a sibling of the existing concept with the same name but the word "Copy" added to the end of its preferred label. It also makes copies of all of the selected concept's descendants, and all of the data associated with the selected concept and its descendants.

Below, we can see the result of cloning the United Kingdom concept with its descendants:


In addition to creating the "Copy" version of United Kingdom, EVN created "Copy" versions of all of its descendants. With "Scotland Copy" selected, you can see that all the property values for Scotland have been added to its copy—for example, the calling code of 44 and the language of "Scottish English". Note, however, that its "has broader" and capital values refer to the relevant copies, not the original versions of the Great Britain and Edinburgh concepts.

Deleting a concept

To delete a concept, select it on the concept hierarchy panel and select Delete from the at the bottom of the screen. A message box will ask you if you're sure that you want to delete it, and then you can click OK or Cancel on that message box.

Deleting a concept deletes any descendant concepts that it has as well. For example, deleting the North America concept from the Geography taxonomy will also delete Canada, United States, Mexico, Ontario, Texas, Toronto, Dallas, and so forth, so be careful.

Creating and deleting concept schemes

A concept scheme is a set of concepts grouped together into a list or hierarchy. It might represent a taxonomy, a thesaurus, a code list, or any other controlled vocabulary. A taxonomy may be a single scheme, but because of EVN's ability to group several taxonomies together, some may appear as multiple schemes. For example, you might have a taxonomy of apparel products and another of colors in which the clothing was available, with both schemes displayed at the same time. Or, you might want to show several code lists together, especially if they provide values for certain properties of another taxonomy being displayed.

To create a new hierarchy, click the New Scheme button This displays a dialog box that prompts you for the name of your new scheme and lets you change the generated identifier for it if you wish. Below, the name "My New Scheme" has been entered and the default identifier value has been left alone.


After you click the dialog box's OK button, you'll see your new scheme as a sibling of any existing schemes (or, if you just created a brand new taxonomy, as the first one there) with the Edit form open for your new scheme:


Use the has top concept property to identify one more more concepts that will be at the top of this hierarchy, the way that Asia, Africa, Atlantic Ocean, and the other top concepts are shown with the Geography scheme. (You can always set these values later by editing the scheme.) Click Save Changes when you are finished.

You can edit a concept scheme's name and top concept values again by selecting that scheme on the Concept Hierarchy panel and clicking the Edit button at the bottom of the form.

Add a concept to a scheme the same you would add concept as a child to another concept: by selecting the new concept's parent (in this case, the concept scheme) and clicking the Create concept... button. When a concept scheme is selected, you can also use the Create multiple concepts choice of the gear menu at the bottom of the screen. See Creating one or multiple concepts for more information.

To delete a concept scheme, select it on the Concept Hierarchy panel and select Delete from the gear menu.

Deleting a concept scheme will delete all the concepts in that scheme that don't appear anywhere else. If you want to save any of a concept scheme's nodes before deleting that concept scheme, drag them to a different concept scheme on the Concept Hierarchy before deleting the concept scheme.

Copying data from remote sources and other taxonomies

Menu choices on the gear menu in the upper-right of the EVN screen let you copy concepts from SPARQL endpoints, from RDF available at remote URLs, and from other taxonomies on your system.

When you select Copy Concept from SPARQL Endpoint from the upper-right gear menu, EVN displays a dialog box where you select the endpoint, enter an optional named graph from which to retrieve the data, and indicate the URI of the resource to retrieve. (See the Administrator Guide for information on adding choices to the SPARQL endpoint selection on this dialog box.) In the following, DBpedia has been selected, the named graph field has been left blank, and the DBpedia URI for the Albanian city of Tirana has been entered as the Concept URI:


After you click this dialog box's OK button, EVN copies the triples that have that URI as a subject from the specified endpoint and adds triples to make that resource a concept with a preferred label of the copied resource's rdfs:label value. The new concept will appear in an "Imported Scheme" concept scheme in the Concept Hierarchy, but you can drag it somewhere else if you prefer.


Because an EVN server can function as a SPARQL endpoint, Copy Concept from SPARQL Endpoint is a good way to create connections between taxonomies on different EVN servers. (See EVN Integration Points for further information on using EVN's own SPARQL Endpoint.)

Copy Concept from URL lets you establish relationships between local and external concepts. When you select it, EVN prompts you for a URL and then copies statements about a resource defined at that URL, adding triples to make that resource a concept with a preferred label of the copied resource's rdfs:label value. For example, because DBpedia lets you dereference the URIs representing its resources directly, you could enter the same Tirana URI used to demonstrate Copy Concept from SPARQL Endpoint above to copy the same data using Copy Concept from URL with no need to enter a SPARQL endpoint URL.

Copy Concept from Vocabulary displays a dialog box that prompts you for a vocabulary on the same EVN server (for which you have read access) and a concept in that vocabulary. In the following, someone editing a Working Copy of the sample Geography vocabulary is copying the Africa concept from the sample IPTC News Codes vocabulary:


After you click this dialog box's OK button, EVN copies the data for that concept and any ancestor concepts into the vocabulary that you're editing. Below we see how, after filling out the dialog box as shown above, EVN copied Africa, its parent concept World, and its grandparent concept World Region into the November edit working copy of the Geography vocabulary:


If you are viewing a resource that you've copied from a remote location with one of the upper-right gear menu's three Copy commands, and the remote version of the data has changed, select Refresh resource from the concept gear menu under the editing form to update the version that you are viewing.

SKOS-XL taxonomies

SKOS-XL (SKOS eXtension for Labels) is a part of the W3C SKOS standard that lets you treat labels as resources in their own right, with their own metadata. This is useful for adding provenance data or information for text mining tools about how to use specific labels. TopBraid EVN lets you use SKOS-XL to add any metadata you like to alternative and hidden labels.

To activate the SKOS-XL support for a particular taxonomy, select Edit Includes on that taxonomy's management screen and check "SKOS XL Vocabulary" to include it. Then, when you edit concepts in that vocabulary, the edit forms will let you add XL versions of alternative and hidden labels along with metadata about them. Below, in an edit form for Belgium, we see that along with a regular field for an alternative label, there is a nested form for "alternative label (object)" with four additional metadata fields available to describe the label along with the field for the label text.


To associate a new property with a SKOS-XL label so that it appears on one of these nested forms, give it a domain of Label.

Once a label's data has been entered, it will appear like any other relationship property value on the relevant form: as a hypertext link. For example, below we see that the concept with an English preferred label of "United States" has four alternative label objects, including "USA," and four hidden label objects. Clicking one of those will display all the data about that label object in the window where the United States information is currently displayed, and clicking the arrow to the right of any of these label objects will display its information in a new window. Below, someone has clicked the arrow to the right of "USA," which opened the new window on the right.


Clicking the white arrow in the upper-right of the new window will close it, as described in Managing windows.

Working with classes

Because EVN's taxonomy editor builds around the W3C SKOS standard, everything is organized as concepts. The most basic class of organization is known as the Concept class, and you can define specialized versions of this class to make it easier to organize custom properties. For example, in the sample Geography taxonomy, the Country class has calling code, capital, and language properties, but the other classes do not. The custom properties will automatically appear on the forms used to edit or search for instances of these classes.

Editing of classes works the same whether you are editing a production copy or a working copy. As with edits to a working copy's concepts, edits to classes in a working copy will not affect the production copy until someone with manager privileges commits that working copy's changes to production.

Browsing information about classes, their associated properties and their history

Classes, like the concepts themselves, are shown in a hierarchical tree. The Switch to Classes Hierarchy icon at the top of Concept Hierarchy will display the Class editing screen.


To switch back to the Concept Hierarchy editing screen, click the Switch to Concept Hierarchy icon at the top of the Classes Hierarchy:


The Class editing screen shows a hierarchy of Concept subclasses. As with the Concept Hierarchy, you can expand the Classes hierarchy by clicking the plus signs next to each class name. Light brown circles represent classes, green rectangles represent attribute properties, and blue rectangles represent relationship properties.


Mousing over any of this screen's buttons displays a tooltip telling you what it does.

Clicking a node on the Classes Hierarchy displays information about the selected node on the right. If you have a Manager or Editor role for this taxonomy copy, it also displays an Edit button at the bottom, which lets you customize the selected class or property.

Colored icons on the tree show you what they represent:

A class. Other than the Concept one at the top of the Class Hierarchy, each of these is a subclass of its parent node on the hierarchy. See Creating a new class and Editing class, attribute, or relationship definitions for more information.
An attribute property of the class represented by the shape's parent node on the hierarchy. See Adding a new attribute or relationship property to a class for additional information.
A relationship property of the class represented by the shape's parent node on the hierarchy. Adding a new attribute or relationship property to a class for more about these.

Yellow squares represent individual concepts, which is why they appear on the Concept Hierarchy but not the Class Hierarchy. (Note how the Switch to Concept Hierarchy icon has yellow squares on it.) Although instances do not appear on the Class Hierarchy, the "Create Concept/Instance" button at the bottom of the Class Hierarchy screen lets you create a new instance of the selected class.

Creating a new class

A class is a a subset of a taxonomy's concepts grouped together for easier management. The concepts within a given class may themselves be grouped into subclasses of that class.

By default, a new taxonomy's only defined class will be Concept. Your first new class will be a subclass of that, and all others will be descendants of this first one or its siblings.

To create a new class, select the new one's parent class on the Class Hierarchy and click the Create Class button underneath the Class Hierarchy. This displays a dialog box where you enter the name of your new Class and optionally edit the URI generated by EVN as an internal ID for the class. After you click the OK button, EVN adds it to the Class Hierarchy and displays details about the class in the form on the right where you can edit these details as described in Editing class, attribute, or relationship definitions.

After doing this, whenever you see a choice of classes while working with your data (for example, above the search form, or when assigning a class to a new concept) you will see your new class as one of the choices.

Editing class, attribute, or relationship definitions

On the Classes Hierarchy, clicking any node displays available data about the node (whether it's a class, an attribute, or a relationship) in the form on the right. If you have a manager or editor role, an edit button will appear below that form; clicking it lets you edit the data with a form similar to the one used to edit concepts. When you are finished, click the Save Changes or Cancel button below the form.

When editing attributes and relationships, their domain property identifies the class that they are associated with (for example, which forms they will appear on) , and the range property identifies the potential values that can be assigned.

Editing the calling code attribute below, we see that it has a domain of Country, and will therefore appear as a custom property on the edit form when you edit a Country concept, and a range of integer, which will limit entered values to integers:


When editing the capital property below, we see that it also has a domain of Country, but because it's a relationship (that is, it specifies a concept's relationship to another concept) it has a range of another class: City.


With these settings for the capital relationship property, in addition to a capital field appearing on the edit form for Country concepts, the field will only allow the user to enter a city stored in the taxonomy as a capital value—in fact, only city names will appear in the autocomplete list, making it easier for the user to enter an appropriate value. For example, if someone is editing data for Nepal on the Concept Hierarchy screen and they enter "Ka" as the first two letters of the capital, the typeahead list lists cities (and only cities—note that the state of Kansas and country of Kazakhstan, which are part of the Geography taxonomy, are not on the list) that begin with those two letters:


Adding a new attribute or relationship property to a class

After selecting a class on the Class Hierarchy, clicking the Create Attribute or Create Relationship buttons adds one of those properties to the selected class. EVN first displays a dialog box where you enter the name of your new property and optionally edit the URI generated by EVN as an internal ID for the property. After you click the OK button, EVN adds your new property to the Class Hierarchy and displays details about the property in an edit form on the right where you can edit these details as described in Editing class, attribute, or relationship definitions.

After you define a new attribute or relationship property for a given class, you will see it as a custom property on edit and search forms for that class.

Adding constraints to a class

EVN lets you attach rules to classes about valid values for its properties. For example, you could define a constraint saying that a certain numeric property's values had to be in a certain range, and then if someone entered a value outside of that range, a popup message box would tell them that they entered an invalid value. Running a Constraint Violation Report would also flag such violations.

To enable the rules feature, make sure that your taxonomy includes the SPIN Standard Library.

When you edit a class, under Class Characteristics, clicking the plus sign next to constraint displays a list of constraint templates:


Selecting one and clicking OK displays a dialog box where you configure the details of your constraint; the terms in square brackets in the illustration above show which parameters you need to configure for each type of constraint.

Available constraint choices include the following:

Deleting classes and attribute and relationship properties

To delete a class or an attribute or relationship property for a given class, select it on the Class Hierarchy and select Delete from the gear menu at the bottom of the screen.

Deleting a property will also delete all values assigned to that property for any concepts in the taxonomy. Deleting a class will delete all concepts of that class and all properties defined for that class.

Working with concepts from the Class Hierarchy

When viewing the Class Hierarchy, several shortcuts are available to help you work with concepts of the class selected on the concept tree:

Capabilities and assignment of user roles: Viewer, Editor, and Manager

An EVN user's access to a production vocabulary or to a specific working copy of a particular production vocabulary depends on the role assigned to that user. To summarize, someone in a Viewer role can view and browse a vocabulary without making any changes, an Editor can edit concepts and their metadata, and a Manager can control others' access privileges and control large-scale changes such as deleting of a vocabulary. A specific user might be the Manager of one production vocabulary, have only Editor privileges for one working copy of another production vocabulary, and not even have Viewer privileges for a third one.

The specific details of each role's capabilities depend on whether the role describes access to a production vocabulary or to a particular working copy of a vocabulary.

User roles and access to a production vocabulary

User roles and access to a working copy

Whoever creates a given working copy becomes the Manager of that working copy, even if that user only had Viewer privileges of the vocabulary itself.

Changing the role of a production or working copy vocabulary user

To identify which authenticated user has which role in the maintenance of a given vocabulary, you'll find a grid near the bottom of each vocabulary and working copy management screen. This grid lists the roles of each registered user for that vocabulary or working copy. A user like KurtMakuch below has no access to the vocabulary:



The production and working copy user role grids look similar, but the same user may have different roles for a particular production copy and one of its associated working copies, or for two different working copies. While the production vocabulary user lets the vocabulary manager assign roles to anyone on the system, the working copy vocabulary list only lets its manager assign role to people with access to that working copy. For example, the following working copy user list does not include KurtMakuch, because as shown above he has no access to this working copy's vocabulary.



You must have Working Copy manager status to change anyone's roles for that particular working copy, and the Vocabulary Manager for that vocabulary can change them as well.

For a manager, each role is a drop-down list that lets you reassign someone's role. Note that the third choice is blank; assigning a blank role prevents the user from having any access.


For someone who has a viewer or editor role, the list will appear as a plain list that they cannot edit:


In addition to assigning roles to individual users, EVN allows vocabulary managers to assign roles to security roles from directory services such as LDAP. These security roles show up in the same table as the other (potential) members, but represent a whole group of people.

Vocabulary change management: working with working copies

This section describes how to manage working copies: how to create them, how to change their status as they move through a workflow, and how to use the tools that help you review them.

Working copies, roles and governance

In TopBraid EVN, working copies are temporary copies of a production copy that users with the appropriate roles can edit without affecting the production copy. The same user can be assigned different roles for a production copy and for a working copy associated with that production copy, letting you implement governance policies for proposed edits to the production copy.

For example, if Jane manages a vocabulary, she can give John viewer privileges of the vocabulary but editor privileges of a particular working copy for that vocabulary. John can make all the changes he wants to the working copy, and (based on the privileges allocated by Jane, or anyone else with a manager role for that working copy) others can see and maybe participate in those changes, but because he only has viewer privileges for the production copy, he cannot commit those changes. Only a production copy manager or editor such as Jane can, after determining that the appropriate review procedures have been followed. The appropriate steps are something for their organization to decide on, and may include freezing a working copy several for several days, requesting comments, and the running of specific TopBraid EVN reports as part of the review process.

Creating a working copy of a production vocabulary

From the management screen for a given vocabulary, click the Create Working Copy link. EVN will prompt you to enter a name and a description for the working copy; a typical name would be a summary of the changes that will be made in this working copy.

Once you click the Submit button after entering the new working copy's name and description, you will see your new working copy listed under "Uncommitted Working Copies" on the vocabulary's management screen. For anyone with access to that working copy, its name there will be a hypertext link that takes them to the working copy's management screen, where they can select from links that let them edit it, browse it, change its status, and view reports on it.

This screen also has a list of user roles that let you manage which users have what kind of privileges with this working copy, as described in Changing the role of a production or working copy vocabulary user. As the creator of this working copy, you are its manager, with all possible privileges over the working copy itself, although publishing it to the production copy of the vocabulary requires you to have Vocabulary Editor privileges.

Collaborative editing of working copies

If multiple people are working on the same working copy, then the changes by one person are sometimes not immediately visible to another person. Use Update Working Copy from Server from the working copy's start page to refresh your working copy, updating it to include any changes made by other people working on the same working copy.

Freezing a working copy for review

A Working Copy Manager has the ability to freeze a working copy so that users with access to it can only browse it without the ability to make any changes, regardless of the level of their access. This can be useful as part of a workflow plan—for example, that a working copy gets frozen for review three days before publishing its changes to the production copy.

To freeze a working copy, click Freeze for Review on the working copy's management screen.

Rejecting all changes in a working copy

The Reject All Changes link appears to someone with Vocabulary Editor privileges on a working copy's management screen. After you click it, a status message screen will indicate the working copy's new status. The working copy's management screen will then display the Allow Further Changes and Delete this Working Copy links.

Allowing further changes to a working copy

Along with the ability to freeze a working copy, a Working Copy Manager has the ability to unfreeze a working copy so that users with the appropriate privileges can make further changes to it. To do so, click Allow Further Changes on the working copy management screen. This will only appear (on the management screen of a working copy that has been frozen) to someone with Working Copy Manager privileges.

Deleting a working copy

Before you can delete a working copy, you must have Vocabulary Manager status, and the working copy must have "Rejected Working Copy" status. (See Rejecting all changes in a working copy for more information on this.) Once it does, Delete this Working Copy will appear as one of the choices on the management screen for that working copy. Once you select it, a message box will ask you to confirm that you want to delete it. This action cannot be undone.

Viewing a vocabulary change history report

Click the View Change History link on either a production vocabulary or a working copy's management screen to display a report on all the changes on the Change History screen. For a production vocabulary, this will show all the published changes made since the vocabulary has been created. For the working copy, this will show only changes made within the working copy.

Clicking the Search button on the Change History screen displays a time-stamped list of the saves made to that working copy in the Matching Changes panel, and clicking one of those lines displays details about what changes were made as part of that save operation in the Details of Selected Change panel. Below, the change made on July 30th has just been clicked, showing that three values were added and one was deleted as part of the change made with a particular save operation.


If you are logged in as a user who is editor or manager of the vocabulary or working copy associated with the change, then a link Revert this Change will appear in the bottom panel. Click on this link to undo this operation. This will in fact create a new "forward" edit in the change history, with yourself as author. Note that this feature should be used with care, because reverting some steps from the middle of the change history may lead to orphan resources in your model.

If you are logged in as a user who is editor or manager of the production vocabulary and look at a change performed on a working copy, then a link Commit this Change to production will appear in the bottom panel. Click on this link to move the change history entry (in the example above, the three additions and the deletion) out of the working copy and into the production copy, essentially cherry-picking which change from a working copy you want to accept. As with the Revert feature mentioned above, this feature should be used with care, because committing some steps from the middle of the change history may lead to information that is disconnected from the rest of the vocabulary. For example, when you commit a change that has modified the label of a newly created resource, then you should also make sure that the change that created the resource in the first place has also been committed.

Before you click the Search button, you can narrow the scope of the search by filling out any or all of the fields at the top of the form:

Viewing comparison of working copy to production vocabulary

Click Comparison Report on a working copy's management screen to display a report on the differences between that working copy and the current production copy. The report will list, by concept, the affected property, its value in the production version, and its value in the working copy.

For example, the following shows what happens after the "South Korea" concept's preferred label is edited, an alternative label is added, and a "Seoul" concept is added as a narrower value of the "South Korea" (renamed to "Republic of Korea") concept.



The right hand side of each change contains a link View Change that displays a dialog box with details of the change log entry that caused that particular change. Depending on your permissions, you can revert or commit the change in that dialog box. See Viewing a vocabulary change history report for further information on reverting and committing individual changes.

Show affected working copies

If you're editing (or about to edit) a concept on the Concept Hierarchy screen and wondering what other working copies may be affected, you can select that concept on the Concept Hierarchy tab and pick Show affected working copies from the gear menu . This displays a dialog box with a report on what other working copies of the same vocabulary may be affected. For example, while editing the "South Korea" concept in one working copy, picking this menu choice displays the following short report about changes made by user JaneSmith in another working copy:



Publishing all changes in a working copy

The Commit Changes to Production link appears to someone with Vocabulary Editor privileges on a working copy's management screen. After you click it, a message box requests confirmation that you want to commit all of the working copy's changes to the production vocabulary, and then a status message screen will indicate that the working copy has been committed. This working copy will no longer be listed on the vocabulary's management screen, because once its changes have been made to the production vocabulary, they are no longer proposed changes.

Creating a new vocabulary

Before a new vocabulary can be created with the web-based interface, the administrator must configure EVN's vocabulary storage as described in the Configuring a relational database manager to store your EVN data section of the the Administrator Guide chapter.

The EVN home page includes a Create new taxonomy link, which displays the following page:



The values entered in the "Label" and "Description" fields will appear on vocabulary management screens to describe this vocabulary. The "Default Namespace" URI will be used to create identifiers for the concepts, classes, and custom properties in your new vocabulary. If you do not have a specific one in mind, you can use the generated one that appears when this form displays.

After you click Submit, a message box will tell you whether it was created successfully and return you to the EVN home screen.

To go back and change any of this information, click Edit to the right of the vocabulary's name on the management screen for that vocabulary. This leads to a form that lets you change the name, description, and default namespace. For taxonomies, an additional "Start Classes Hierarchy at owl:Thing" checkbox lets you set the taxonomy's class hierarchy to display with owl:Thing as the root of the tree instead of skos:Concept. (If you set it to display owl:Thing as the root, skos:Concept will appear as one of its subclasses.)

Deleting and clearing a vocabulary

The manager of a particular vocabulary will find a Delete this vocabulary link at the bottom of the the vocabulary management screen for that vocabulary. When you click it, a message box checks that you are sure you want to delete the vocabulary. After you click OK on this message box, the vocabulary and any working copies and data will be deleted.

A deleted vocabulary is not recoverable.

Another management feature is the Clear this taxonomy (or Clear this ontology) link, which deletes all content, working copies and history for the vocabulary. The vocabulary itself and its user roles will be preserved. This feature can be used prior to file imports, to replace the whole content with an externally generated version.

Cloning and versioning a vocabulary

EVN allows managers of a vocabulary to create one or more clones of a vocabulary. A newly created clone will have the same content as the production copy of the original vocabulary and the same user roles will be used. However, neither the change history nor the working copies will be cloned.

Creating a clone is often used to "branch off" a version of a vocabulary, so that it can be referenced and imported separately from the current version. For example you could start off with a vocabulary called "People". Then, once you have reached a milestone you could create a clone and call it "People 1.0". Now, any other vocabulary that explicitly shall only use terms from version 1.0 can change its includes to that version only, while the ongoing work towards version 2.0 will continue on the main "People" vocabulary.

In order to create a clone, managers can use the Create a Clone/Version link in the Life Cycle section at the bottom of the the vocabulary management screen. The following screen will ask for the name of the clone.

Selecting constraint libraries

Near the top of a vocabulary's main screen you will find the "Select Constraint Libraries" link that lets you configure which constraint libraries are in use for that vocabulary.

After selecting it, the Constraint Libraries screen lists the available constraint libraries, with those currently in use shown in bold. In the following, the "SKOS constraints" library is currently in use for the Geography taxonomy, and its rules will be applied for the Constraint Violation Report (see Displaying a constraint violation report) for more on this and for interactive validation of data editing with EVN. Clicking the Remove link will remove that constraint library from use with this particular vocabulary.

The evnconstraints library shown in the illustration is not currently in use, but can be added by clicking the Add link shown next to it.

There is no limit to the number of constraint libraries that you can have active at one time. For bigger vocabularies, having a large number of rules active at once can slow down interactive editing; one approach to consider in these situations is to turn off all constraint libraries during editing and to then turn on those that are appropriate to your application before running the Constraint Violation Report.

Importing external data

On each vocabulary's management screen, you can import data from spreadsheets, from RDF files, and from XML files that have been exported from the MultiTes thesaurus management package. You can also import one or more taxonomies on your system into another one.

Including one vocabulary into another

The Edit Includes link on each vocabulary's management screen lets you pick other vocabularies on the system (as long as you have read access to them) and include them into the existing one. Includes work by reference only — in other words, it adds the other vocabulary's data to the current one as part of the display, but does not actually copy it. This also means that you can't actually edit the included data.

This feature is useful for creating views of multiple taxonomies at once. It's also useful for mapping between taxonomies; if you include two taxonomies and then define relationships between concepts in one with concepts in the other (for example, to say that "proteins" in one has a close match relationship to "Protein" in another) the defined relationship will be saved as part of the including vocabulary.

Importing spreadsheet data

This feature is available only for vocabularies.

The Import Concepts from Spreadsheet link is available both on a taxonomy's main management screen and on the management screen for each working copy. Select it, and EVN will display the following screen:



Your spreadsheet may be stored as either an Excel file (Excel 95, 97, 2000, XP, or 2003), a tab-separated value file, or a comma-separated value file. As the screen above shows, the importer will assume the file type based on its extension. Because an Excel file may have more than one sheet of data, this screen lets you specify a sheet index value to identify which sheet to read in. The default is 1, for the first sheet.

The sheet index counts all sheets in an Excel workbook, including hidden ones. For example, if you enter a 3 here and EVN seems to import the second sheet, there may be a hidden one between the first and second sheet that made the third one look like it was the second one when Excel was displaying the workbook. The Excel online help explains how to check for the existence of hidden sheets.

The Target type field lets you select from the Classes defined for the target taxonomy so that imported terms can be assigned to those types. For the sample Geography taxonomy, these Classes include Continent, Country, and Island; for all taxonomies, the default Class is skos:Concept.

Click Choose File and pick the file you want to import, and then click Next. This leads to the Select Spreadsheet Type screen, which shows six sample layouts for typical taxonomy arrangements on a spreadsheet, and under them, the first six lines of the spreadsheet that you're importing. The following shows this screen while importing a spreadsheet with the names of regions in Antarctica:



Lighter text on the spreadsheet layout samples is optional, so the Column-based Tree choice is the closest match to the spreadsheet about regions of Antarctica.

Note that all sample layouts include a header row with labels for the columns, and the spreadsheet that you import should as well. In the Antarctica spreadsheet, these labels are "Continent," "Country," and "Region."

After you click the title of the pattern that most closely resembles the spreadsheet you're importing, EVN displays a form that lets you configure details about how EVN should import your spreadsheet. To make this easier, it includes the sample of your spreadsheet from the previous screen. The following shows the Import Spreadsheet screen for the Column-based Tree pattern.



The Import Spreadsheet screen for all of the spreadsheet patterns have the first two of the following three sections, and most have some variation on the Hierarchy section as well:

When you select the No Hierarchy pattern, EVN will import the indicated terms as separate concepts without generating a hierarchy to connect them, and then on EVN Concept Hierarchy you can drag nodes around on the tree to arrange them into a hierarchy if you wish.

A Preview button on the Import Spreadsheet form lets you see the RDF triples that would be generated with the currently configured settings. Your browser's Back button will then return you to the form. When you are satisfied with the sample data shown on the preview screen, click the Finish button. EVN will display a message about successful importing of the data along with a set of data that you can use as a mapping file for imports of spreadsheets with a similar structure in the future.

In many cases, setting the Hierarchy section and leaving everything else at the default settings will work. When configuring input for a given spreadsheet, start by trying this and then checking Preview to see what else needs to be configured.

Importing RDF

Click Import RDF File on the vocabulary's main screen. On the next screen, the Browse button will open a dialog box that lets you pick a file to import.


When importing RDF into a Working Copy, the addition of each triple will be added as an entry in the change history, where it will be available to all the relevant reports. When importing into a production copy, the Record each new triple in change history checkbox gives you the option of not adding these to the change history, as the illustration above shows.

Once you've done this and identified the format of your RDF file, click the Finish button, and a message will you tell you whether you've successfully imported the file.

Importing RDF into the Taxonomy Editor

If you are importing data into the taxonomy editor, EVN uses the W3C SKOS (Simple Knowledge Organization System) standard to model taxonomy data and metadata. SKOS is an OWL ontology that defines properties for most of the information that taxonomy managers want to store. If you want to import data into the taxonomy editor that follows the RDF model but does not use properties from the SKOS ontology, you can convert it using the SPARQL RDF query language in TopBraid Composer. If that data is not stored using the RDF data model, but is in a spreadsheet, a tab-delimited file, a relational database, or an XML file, TopBraid Composer can automate the conversion of these and other formats into RDF. Then, you can can use SPARQL CONSTRUCT queries to convert the data to SKOS so that you can manage it with EVN. For more information on running SPARQL queries in TopBraid Composer, see TopBraid Composer > User Interface Overview > SPARQL in the TopBraid Composer online help.

After importing data into the taxonomy editor, if the imported data did not contain an instance of skos:ConceptScheme, the the Concept Hierarchy screen will show new terms under a hierarchy with the default label "CONCEPT SCHEME UNDEFINED." You can rename that, or if you have an existing hierarchy, drag the new hierarchy's descendant nodes wherever you like in the existing hierarchy and then delete the CONCEPT SCHEME UNDEFINED node.

To ensure successful importing of SKOS data, make sure that:

  • The RDF/XML file includes at least one skos:ConceptScheme instance with one or more skos:hasTopConcept properties.

  • The taxonomy uses skos:broader values to identify parent-child relationships for the concept hierarchy. For example, if there is a skos:ConceptScheme of Animals that has a skos:hasTopConcept value pointing to a Mammal concept, and a Dog concept has a skos:broader value of the Mammal concept, Dog will appear as a child node of Mammal on the tree. A Collie concept with a skos:broader value of the Dog concept will appear as its child on the concept hierarchy, and so on.

    This combination of skos:hasTopConcept and skos:broader nodes lets the system identify which concepts are in which concept scheme, so there is no need to use the skos:inScheme property. Similarly, skos:narrower values can be inferred from the existing skos:broader values, so there is no need to include them explicitly.

  • Imported data about concepts that already exist in the taxonomy must use the same URIs for that data to appear with the existing data for those concepts.

If the RDF that you are importing does not have the necessary structure, TopBraid Composer includes many features to transform the data according to your needs. Cleanup tasks include the following:

  • Delete broader transitive, narrower transitive, and semantic relation properties.

  • Delete rdfs:label values where an identical skos:prefLabel exists.

  • Ensure that each named class has at least one named superclass.

  • Remove redundant rdf:type values, leaving the most specific one.

  • Replace skos:narrower values with skos:broader values pointing in the other direction.

  • Replace untyped literals with xsd:string literals.

  • Removal of line break characters.

Importing MultiTes XML

This feature is available only for taxonomies.

To import an XML file exported from the MultiTes thesaurus management package, click Import MultiTes File on a taxonomy's main screen. On the next screen, the Browse button opens a dialog box that lets you pick a file. Once you've done this, click the Finish button, and a message will you tell you whether you've successfully imported the file.

EVN will create a concept scheme for the imported MultiTes data based on the name of the host taxonomy. You can rename or rearrange its contents using all the standard EVN features for editing data.

Importing RDF into the Ontology Editor

RDF files can only be imported into a production ontology. (Note that this is for non-SKOS models; see Importing RDF for information on importing SKOS Models.)

Click Import RDF File under Import External Data on the ontology's main screen. On the next screen, the Browse button will open a dialog box that lets you pick a file to import.

After you select a Turtle, N-Triples, or RDF/XML file and click the Finish button, EVN will add any defined classes to the ontology's class tree and any instances corresponding to defined classes (whether imported classes or pre-existing classes) to the model so that they will be accessible in the Instances window when their class is selected in the Class Hierarchy tree.

Creating reports and exporting data

Creation of reports and exporting of data is available when working with both production and working copies of taxonomies to anyone with read access to those taxonomies. The management screen for a given vocabulary has links to perform all these actions with a production vocabulary, and a working copy management screen has links to perform these actions with that working copy.

To retrieve subsets of vocabulary data according to criteria that you specify, sorted however you like, remember that EVN's Search screen gives you fine-grained control over the data to display on the Search Results area. That form's gear menu offers several choices to export the results into formats that can be easily imported into spreadsheet programs such as Excel, where you can then format or otherwise manipulate the data any way you like. See Using the search form and Saving search results for more information.

Publishing a vocabulary to the EVN Explorer

EVN includes an optional component that lets users in a manager role publish vocabularies using the EVN Explorer add-on that allows an unlimited number of viewers to have read-only access to a vocabulary.

To publish a version of your vocabulary for display with this tool, select Publish from the Export section of a taxonomy's main page. The next screen asks for you to enter a short id for the published version, a display name, and a description.


The display name and description will already be filled out with values from the vocabulary itself, but you can edit them on this screen if you like. As the screen tells you, the short id is a system-internal name that is used to generate URLs, and must consist of characters and digits only. The short id is not the display name for the end users.

If you publish the same vocabulary twice with two different short id values, both will appear in the list of published vocabularies, which you may want to do to provide access to different versions. If you publish a vocabulary using the same short id that you used for an earlier publish operation, the new one will replace the old one.

EVN will ask you to provide a short name to track the published vocabulary; to replace an existing one, give it the same name you gave it before. After entering the name and clicking the Publish button, it will appear on a list of published vocabularies.

If your EVN installation has been configured to publish to a separate read-only Explorer version of EVN, this will publish your vocabulary to that one instead of to the server where you are doing your editing. See EVN Configuration Parameters for further details.

When you select a vocabulary from this list, EVN displays it using what is essentially the same interface as the regular EVN editing screen, for taxonomies without the buttons at the bottom or top or access to the class hierarchies. All search and navigation features are still available.


Displaying a constraint violation report

Under the Reports heading on a production vocabulary or working copy management screen, select Constraint Violations Report to display a report of all constraints violated by that vocabulary. Constraints are defined with the vocabulary; EVN includes a set of constraints defined as part of the W3C SKOS standard that can be added in with any vocabulary.

After you select Constraint Violations Report, a message box will show you the progress of the constraint checking, and then you'll see the report. For example, the following report shows that the "South Korea updates" working copy violates two SKOS constraints: New York City has two different preferred label values and the Republic of Korea has the same value in both its preferred label and its alternative label.


Displaying graph statistics report

This feature is available only for taxonomies.

Select Graph Statistics under the Reports heading on a taxonomy or working copy management screen to display two bar graphs about node distribution in the taxonomy's concept hierarchy. The following shows these graphs for the Geography taxonomy included with EVN:



The "Number of nodes per level" graph shows that there are 18 top level nodes in this taxonomy, 226 nodes one level below the top level, 323 at the level below that, and so forth. The second graph shows that above 60 concept nodes in the taxonomy have only one child, 25 have two children, 17 have three children, and so forth.

Graphs like this can be very helpful to a taxonomy designer who wants to reorganize a taxonomy hierarchy. For example, if an online store's website designers have determined that product category menus should each have between four and seven choices, and those menus are generated from a managed taxonomy, these graphs can help the editor of that taxonomy evaluate the need for taxonomy reorganization.

Spell checking your taxonomy's data

Select Spell check on a production or working copy management screen to generate a report on words that EVN does not recognize. The following shows the beginning of a spell checking report for the sample Geography taxonomy:


As the scrollbar on the right shows, there are many more entries in this report because of all the foreign place names. The displayed part of the report shows three words that the spell checker didn't recognize (actually two, because it found one in two different places). For each, it shows the word it didn't recognize, the phrase around it (with the word bolded) for context, the name of the property and concept where the word was found, and suggested replacements for it. Knowing the concept, property, and context will let you find it with the EVN editor and fix it if it is a mistake.

Exporting your vocabulary as RDF

Select Turtle, N-Triple, or RDF/XML under the Export header on a production or working copy management screen to generate an RDF file representation of the vocabulary using one of these formats. Different browsers may display this different ways, or perhaps not display anything at all in the standard browse window; selecting your browser's equivalent of the View Source command will display the actual RDF data. When viewing the source, you can also pick Save As or Save Page As from your browser's File menu to save the RDF file as a disk file.

Instead of clicking one of these three links, an alternative is to right-click it and then pick "Save Target As" or "Save Link As", depending on your browser, to save the RDF representation of the data to a local file. A dialog box will then prompt you for the name and location of the file.

Exporting the taxonomy hierarchy to spreadsheet format

This feature is available only for taxonomies.

Select Hierarchy Spreadsheet under the Export header on a production taxonomy or working copy management screen to generate a tab-delimited text file version of the concept hierarchy. If you save this as a disk file, spreadsheet programs such as Excel import it into their native format. (See Exporting your vocabulary as RDF for techniques for saving the generated data while viewing it or saving the information after right-clicking the Hierarchy Spreadsheet link.)

The following shows the hierarchy from the Geography taxonomy imported into Microsoft Excel:



When the Internet Explorer browser displays tab-separated exported data, it may not show carriage returns, displaying the output instead as one giant paragraph. Select Source from the View menu to see the exported data with carriage returns preserved.

To export a subtree of the Concept Hierarchy to a tab-separated value spreadsheet file, select Export hierarchy to spreadsheet from the gear menu under the edit form with a node selected on the Concept Hierarchy. For example, the following will create a spreadsheet similar to the one shown above but with North American at the top of the hierarchy and the countries, states, provinces, and cities of North America listed under it.


Exporting a taxonomy concept overview to spreadsheet format

This feature is available only for taxonomies.

Select Concept Overview Spreadsheet under the Export header on a production taxonomy or a working copy management screen to generate a tab-delimited text file version of the concept hierarchy. If you save this as a disk file, popular spreadsheet programs can import it into their native spreadsheet format. (See Exporting your vocabulary as RDF for techniques for saving the generated data while viewing it or saving the information after right-clicking the Concept Overview link.)

The following shows the concept overview from the Geography taxonomy imported into Microsoft Excel:


When the Internet Explorer browser displays tab-separated exported data, it may not show carriage returns, displaying the output instead as one giant paragraph. Select Source from the View menu to see the exported data with carriage returns preserved.

Editing Ontologies

Editing an ontology is similar to customizing a taxonomy's classes, as described in Working with classes, except that in that case you're creating a customized version of the W3C SKOS ontology, while with the EVN Ontology Editor you can create or work with any ontology or schema that you like.

TopQuadrant's TopBraid Composer is the most advanced, professional standards-based ontology editor available. The EVN Ontology Editor provides additional features, in particular to allow collaboration and change tracking by a team of ontologists, but TopBraid Composer gives the greatest control over how you configure your ontologies. Because they're both built around the same W3C standards, each can be used with resources created by the other.

Create a new ontology by picking Create New Ontology from the EVN home screen. Once you've done so, the ontology's home screen offers you many of the same options that you find on an EVN taxonomy home screen, such as the ability to edit it, to view change histories, to run several of the same reports, to import and export most of the same formats, and to delete the ontology or taxonomy. The creation and management of working copies also works the same way and provides the same benefits.

The Ontology Editor Screen

The Ontology Editor lets you edit both an ontology (that is, the definitions of classes, properties, and relationships between them) and instances of an ontology on the same screen. The upper-left of the Ontology Editor screen shows the class hierarchy, with classes, attribute properties, and relationship properties shown as nodes on the tree the same way they are shown on the EVN Concept Hierarchy as described in Browsing information about classes, their associated properties and their history. Clicking a class or property on the hierarchy tree displays information about it in the form on the right. Below, we can see that the diagram property of the "Medical entity" class has been selected, displaying information about that property on the form.


The colored buttons at the bottom of the class hierarchy, next to the quick search field, let you add a new class , attribute property , or relationship property to the selected class in the hierarchy.

Below the Class Hierarchy is the Instances window, which shows instances of the most recently selected class in the Class Hierarchy. Below, we can see a list of "Medical entities" instances in that window, as above, except that the Anesthesia instance has been selected, displaying information about it in the form on the right:


Next to the quick search window at the bottom of the Instances window is the Create instance button , which lets you create a new instance of selected class.

Whether you're creating a new class, property, or instance, or editing an existing one by clicking the Edit button below the form, the edit controls all work the same way that they work in the EVN taxonomy editor.

Searching in the Ontology Editor

The Ontology Editor's search features are similar to those found in the taxonomy editor, as described in Searching. The Class Hierarchy and Instance window each have their own quick search field.

The search form that displays when you click the gray strip on the right-hand side of the Ontology Editor lets you search instances of the currently selected class in the Class Hierarchy. The search form will display any properties associated with the selected class; this lets you use them as search criteria and specify which ones you want retrieved with the search results. In the following, the form is filled out to retrieve all instances of the Person class that have "law" in their family name property, and the gender and birth date properties have been checked so that those values get retrieved with the results, which are shown below the Search button.


Faceted search

Select Open faceted search dialog... on the search results gear menu to display a dialog box that lets you do a faceted search for instances in the selected class.

After opening this dialog box, the Add Property field lets you select properties from that class to use for your faceted search. Below, this field's drop-down list is being used to select the family name field.


In the next screen shot, the family name and gender properties have been added and the main form is showing information about the instances of the class. The > symbol to the right of the gender property has been selected, pointing it down and displaying all possible values stored with that property along with the number of instances that have those values. (Clicking the > to the right of the family name property would do the same for its values.)


Clicking "female" on the previous screen adds that as a faceted search criterion, so that the panel on the right only displays instances with a gender value of female:


Clicking the x next to "female" removes it as a search criterion, showing all the instances of the class that were shown before it was added.

You can also narrow down the list of displayed names by entering a search string in the upper-right and clicking the magnifying class icon.

This example only scratched the surface of what you can do with faceted search. Using different combinations of properties and property values lets you do much more sophisticated searches of your instance data.

Displaying Custom Instance Trees

By default, the EVN Ontology editor displays a tree hierarchy of the classes in your ontology and, when a given class is selected, a list of that class's instances in a flat list below that. You can also display the instances in new window in a hierarchical tree that represents parent-child relationships using the class property of your choice by selecting Open hierarchy of instances from the gear menu at the bottom of your screen when a particular class has been selected.

In the following, with the Person class selected, we see that a user is selecting "parent [Inverse]" as the relationship to use in displaying node relationships on the tree.


This adds a tree to that window in which a node's child will be determined by the inverse of the "parent" property, so that, for example, Joseph Kennedy has a child of Edward Kennedy in the Person Hierarchy below, and Edward Kennedy has the three children shown.


Note also how selecting a node on the tree, such as Edward Kennedy in the example, displays the information about that resource on the main form.

Editing Form Layouts

By default, the EVN Ontology editor displays instances on forms with a default layout that includes sections for Annotations, Properties and Incoming References. Within those sections, the properties are sorted alphabetically. EVN's web-based form layout editor lets you create custom forms where you can select which properties appear where, as well as what labels display with them.

Each form is associated with a particular class. To get started with this editor, choose a class on the Class Hierarchy and open its context menu at the bottom of the form. If the class already has a customized form layout, you will see the menu items Edit form layout... to open the editor and Reset form layout to delete the configured form. If the class does not have a customized form layout yet, you will see the menu item Create form layout... to open the form editor in a new browser tab as shown in the screenshot below. (If none of these appear, a form may be defined for this class elsewhere.)


The default form created via Create form layout... consists of a single section called Properties that holds a widget for each property that is relevant for the selected class. (A property is relevant if it has a matching rdfs:domain or corresponding owl:Restriction). The editor can be used to modify which properties appear where on the different form types.

The left hand side of the form editor, called Element Hierarchy displays a tree structure with user interface elements. Selecting an element in the hierarchy will display details on the right hand side. You can drag and drop elements within the tree to change the order of properties or move elements under a new parent.

Because of a bug in the code used to render the tree component, sometimes dragging a node between two other nodes does not work and may need to be retried several times. This bug is outside of our control.

Depending on the selected element, different buttons will appear underneath the tree, allowing the user to create new elements of the given class.

There are four types of form elements that you can add to your form:

Property widgets can be configured with the following settings:

Note that the form layouts will not update automatically if properties are added or deleted. If a new property is added to a class and the class has a customized form, then you may want to double-check that the property is either explicitly enumerated or that an Objects Placeholder (see above) exists to catch all implicit properties.

Because all form definitions are stored in the same place (in a file called server.topbraidlive.org/dynamic/uiconfig.ui.ttl), form layouts for the same class (determined by the URI of the class) will be used globally, across all projects. For security reasons there is no global mechanism for end users to see all customized forms, but the main screen of an Ontology has a link to See Customized Forms that is visible for the managers of the Ontology. This opens up a page enumerating all classes from the Ontology that have customized forms, with options to navigate to those definitions and possibly to delete the forms.

To administrators: If you copy projects from one server to another, using the Send Projects to Another Server feature, there is an option to also copy the form definitions. For regular system back-ups or other maintenance tasks you may want to preserve and copy the uiconfig.ui.ttl file as well.

The Form Editor and SWA

The layout of the forms used by TopBraid EVN is determined by form definitions represented in SPARQL Web Pages (SWP), in particular SWA Forms. Users familiar with SWP can take full control of form layouts by editing customized forms with TopBraid Composer and then uploading the form definitions as .ui.ttlx files to the EVN server. However, this process requires some detailed knowledge of how the system works as well as admin access to upload the files.

Solr Integration

Apache Solr is an open-source enterprise search platform that can be used in conjunction with TopBraid EVN. In a nutshell, EVN can be configured to automatically update a Solr search index whenever changes to a vocabulary are made. The resulting Solr index can then be queried either from external applications or via TopBraid's own SWA Faceted Search components. In addition to powering faceted search, Solr can also improve string and text searches, speeding searches over large taxonomies and ontologies.

Setting up a Solr Integration

This section assumes that an administrator has installed Solr 4.4 somewhere in your network. Other versions after 4.1 may also work.

With a default installation, the URL of Solr would be http://localhost:8983/solr/collection1 but obviously you would need to get this information from your administrator.

Once the Solr server is up and running, vocabulary managers can use the link Configure Solr on a Vocabulary's main page to set up automatic synchronization. On that page, enter the URL of the Solr server, and (if necessary) user credentials. After making any changes to those settings, you may want to (re-) initialize the Solr index by clicking on Rebuild Solr Index in the Export section of the vocabulary page.

If Solr has been activated as above, any regular edit to the production (master) vocabulary will be automatically sent to the Solr index. For example, if a user adds a new description to a vocabulary concept, the Solr index will contain a Solr document with the URI of the concept as its id and Solr fields for each of the relevant properties of the concept.

Manual Re-indexing of a Solr Index

After certain batch operations, the automatic indexing may not be triggered, and the Solr index needs to be recreated by hand. In particular, the index should be rebuilt if the imports of a vocabulary have been changed, because the Solr index will cover both the main vocabulary and its imports. Use Rebuild Solr Index from the Export section of the vocabulary page to trigger a rebuild. Note that this will completely wipe out the associated index.

Using a Solr Index

The Solr index can be accessed by any Solr-compliant third party application. In addition, the SWA Faceted Search interface will automatically make use of the Solr index if one has been configured for the vocabulary being queried.

At the time of writing, the faceted search component is not used by the EVN Taxonomy editor. However, the EVN Ontology editor does have a menu item in the drop down menu under the search form to Open Faceted Search Dialog... for the currently selected class, as described in Searching in the Ontology Editor. Furthermore, you can define a custom teamwork project type that uses an editor that includes the faceted search. Check out Help > TopBraid Teamwork Platform Help in TopBraid Composer to learn more.

SharePoint Integration

Microsoft's SharePoint CMS includes a simple taxonomy manager for managing tags that can be assigned to content within the CMS. The EVN Taxonomy editor is a sophisticated editor for taxonomies that can be used in conjunction with SharePoint.

Exporting a taxonomy to SharePoint import format

This feature is available only for taxonomies.

A taxonomy from outside of SharePoint and its metadata can be imported into SharePoint 2010 for use in this taxonomy manager if it conforms to a CSV format specified as part of the SharePoint documentation.

Selecting SharePoint Import File under the Export header on an EVN production or working copy management screen exports the taxonomy in this CSV format. Right-click the link to save it as a disk file for import into SharePoint.

Because taxonomy hierarchies in SharePoint can be no deeper than seven levels, this feature of EVN only exports the top seven levels of a taxonomy hierarchy.

Configuring SharePoint for EVN

In order to use the more seamless SharePoint integration (see section below), a taxonomy manager needs to link a taxonomy with a given SharePoint instance. Click Configure SharePoint in the head of a taxonomy's main page to enter the server URL, user name and password. The URL of a SharePoint server must of the form http://sharepoint.example.org/sites/mysite/ and EVN will add _api/search/query etc. automatically to call the corresponding web service.

Browsing matching SharePoint documents

If an EVN Taxonomy has been configured to point to a SharePoint server, EVN will display a Matching SharePoint documents section under the heading Data Views at the bottom of a concept's form. You can click on the Table view hyperlink to open a tabular view of documents that use the current concept as a tag. The resulting table contains columns with the document's title, path, file extension (such as docx for Word files), author, file size and last modification date. Click on a document to open it on SharePoint.

Searching for matching SharePoint documents

Another way to find a SharePoint document is to open the context menu item Find matching SharePoint documents... under the Search form. This will execute the current search and then use all resulting concepts as terms to search on the SharePoint server. The result is a dialog box listing all matching documents, and a click on a document will open it. The display will only succeed if the underlying search has returned no more than 100 documents, because it may otherwise be issuing too many requests to the SharePoint server.

EVN and TopBraid Composer

Your license of TopBraid EVN includes a single license of TopBraid Composer Maestro Edition (TBC-ME), the premier standards-based semantic web modeling tool as well as a powerful Integrated Development Environment for application development. TBC-ME is the tool that was used to develop EVN and other TopQuadrant products; many TopQuadrant customers use it to develop their own custom applications and some use it to configure and extend EVN. TBC-ME is also used for scripting sophisticated data transformations.

EVN was designed to provide a streamlined, web-based interface to make multi-user management of networked vocabularies as simple as possible. When you use EVN to maintain vocabulary data, we recommend that you do not use TBC-ME to edit that data, because accessing the data from outside of the EVN interface means that the EVN server's change management and other workgroup coordination features will be unaware of the changes.

At a given site using EVN, TBC-ME is typically used by a more technical, often IT, user who has had training in its usage to perform tasks such as: