Skip to end of metadata
Go to start of metadata

Page Contents


This guide describes options and advanced techniques for customizing aspects of TopBraid EDG. This is for advanced users, administrators, and developers who can address topics in EDG systems, semantic technologies, and development tools including the TopBraid Composer - Maestro Edition (TBC-ME) environment.

In general, any product modifications or extensions should be developed in a non-production environment and thoroughly tested under relevant conditions before deploying into production. This guide is for advanced users who are able to support the changes they make and adjust them at upgrade time. 

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

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

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

Preparing Ontology, Taxonomy and Crosswalk Data for Import

As described in the Importing RDF into the Taxonomy Editor section of the User Guide chapter,  EDG expects that RDF imported into the taxonomy editor conforms to the W3C SKOS standard. That section describes specific details about classes and properties that EDG expects to see such as skos:ConceptScheme and skos:hasTopConcept. If you have SKOS RDF that does not fit this model—for example, skos:ConceptScheme is absent —you can use SPARQL CONSTRUCT or UPDATE queries and TopBraid Composer to add or convert to the necessary SKOS data. TopBraid Composer includes a range of features for developing and executing these queries, as well as for saving them in a SPARQLMotion script if you need to run a given CONSTRUCT query or set of queries on a regular basis. Taxonomy Editor also expects the use of skos:prefLabel. If your RDF contains rdfs:label values, they will be converted to skos:prefLabel values.

EDG Ontology Editor has no special requirements on the classes, properties or instances that must be present. The only exception is the presence of rdfs:subClassOf statements for classes, which are needed for them to appear in the class tree.

EDG Crosswalks contain RDF triples of the following form: 

example:Vocabulary1_Resource1 skos:closeMatch :example:Vocabulary2_Resource1.

Valuable data for use in your vocabularies and asset collections may not be stored in RDF, but instead in another model or format. The Importing spreadsheet data section of the User Guide chapter describes how to import spreadsheets representing a taxonomy hierarchy in a choice of patterns; if your spreadsheet does not fit one of these patterns, TopBraid Composer offers several approaches for converting a spreadsheet into RDF that can then be converted to SKOS RDF with CONSTRUCT queries. In the TopBraid Composer > Help, see Importing Data Sources > Import external information > Import Spreadsheets for an overview of these approaches and links to more detailed information.

You can also use tabular (ho hierarchy) spreadsheets to import data, including creating relationships between resources. For crosswalks the spreadsheet should have only two columns representing the two sides of the crosswalk. No mapping will be required.

You can create an ontology from a spreadsheet - using the header row as properties and the worksheet name as a class.

If your data is in one or more relational databases, TopBraid lets you create connectors that make it possible to work with that data as RDF triples so that you can then convert it to SKOS. In Composer's online help, select Working with Data Back Ends > Working with Relational Databases to learn more.

SPARQLMotion scripts let you create scripts by dragging and dropping from a wide selection of specialized modules into visual data manipulation pipelines. You can run these scripts interactively from within Composer or as web services deployed to your EDG server. SPARQLMotion module choices such as ConvertJSONToRDF and ConvertXMLByXSLT give additional options for taking advantage of non-RDF data that may be available to you. In the Composer online help, select Application Development Tools > SPARQLMotion Scripts for an overview of SPARQLMotion and select Reference > SPARQLMotion Module Library Reference for a complete list of available modules. These modules can also be used within SPARQL Web Pages (SWP) scripts. Unlike SPARQLMotion where data transformation scripts are developed using a visual drag and drop approach, SWP is a textual scripting language using custom HTML tags and JavaScript.

TopBraid's Semantic XML feature gives you another option for converting XML to RDF, storing enough information about the input XML to let you round-trip the data back to a valid XML document. Select Working with XML and Table files > Creating, Importing, Querying, Saving XML documents with Semantic XML to learn more about this feature.

If you are unsure which choices in the TopBraid Composer toolset would let you best take advantage of the data available to you, contact your EDG support representative.

Once you create a custom import script with TopBraid Composer, you can make it available to all EDG users by following instructions in the ProjectPlug-ins section.

Advanced Debugging

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

For an RDF-based test-case framework, see DASH Test Cases Vocabulary

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

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

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

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

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

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

EDG Integration Points

TopBraid EDG's ability to import and export data gives you some batch-oriented options for using data from other systems as well as providing managed vocabulary data and metadata for use by other systems.

For more dynamic integration with other systems, EDG offers three options for developers:

  1. Using TopBraid EDG GraphQL Endpoint  - TopBraid's GraphQL service supports all standard features of GraphQL, providing access to data stored in EDG asset collections. Read nd update access is available
  2. Integrate by using either pre-built standardized RESTFul web services provided with TopBraid EDG or by using your own services developed with TopBraid technologies: templated queries, SPARQL Web Pages and SPARQLMotion services and functions.
  3. Using TopBraid EDG SPARQL Endpoint - to query data and, optionally, to update data

The API endpoints can be accessed by any user of TopBraid EDG.  Users will only be able to access asset collections they have access rights for.  Users will only be able make updates to the asset collections they have rights to perform updates for. All updates made through APIs will be recorded in the history of changes.

Authentication applied to EDG will also apply to the API call. Please see Server Installation and Integration#WebServiceAuthentication for more information.

GraphQL endpoint

GraphQL is a query language for APIs that produces JSON objects.

In a nutshell, GraphQL users define a query string that has a similar form to the desired JSON output. These query strings, possibly together with additional input variables, do not only specify which fields shall be returned but may also include parameters to filter, sort or page through the underlying data. TopBraid EDG supports GraphQL read queries with mutations (updates). Thus, you can use GraphQL for accessing and editing data in TopBraid EDG.

For any given asset collection (RDF graph) TopBraid's GraphQL service automatically generates a GraphQL schema that defines the types of objects and their fields that can be used in a query. Technically, this schema is based on the SHACL shapes that form the data model of most EDG asset collections. These shapes define which "views" on the underlying data gets exposed into what kinds of JSON objects.

For example, one of the shapes used by EDG asset collections defines a property  edg:name  with value type string and a maximum cardinality of 1. This gets mapped into a single-valued GraphQL field called  name of type string. All models used by EDG are already configured to generate GraphQl schemas.

If you are using the Ontology editor in EDG to built your own models that are unrelated to models already used by EDG, in order for the data based on these models be queryable using GraphQL two conditions must be met:

  1. Models need to be defined in SHACL. This means that classes should be SHACL Node Shapes.
  2. Classes that are to be queryable with GraphQL need to be declared as public classes of some GraphQL schema. This option is available on the class form in the GraphQL section. If a class is declare as public, its subclasses are also public.

In the Export tab of each asset collection, you will find an interactive tutorial for using GraphQL endpoint. Further documentation on GraphQL is available on the TopQuarant's GraphQL technology page.  The easiest way to explore how to use the GraphQL web service is to use the interactive GraphiQL browser that is accessible from the Export tab, with a network traffic monitor (such as Chrome Developer Tools) open.

The GraphQL endpoint for each asset collection is available at the following URL:


An example POST request against the Northwind example data asset collection with TopBraid EDG running under TBC-ME is


with the following examplar HTTP request payload:

	"query": "databaseColumns { name }",
	"variables": (optional)

Set the Accept header to application/json.

The entry point into GraphQL is the top-level query object, in between the curly braces. In TopBraid you have to select the type (shape) of top-level object that you want to retrieve. For example, for a data assets collection, you may want to fetch data base tables. The internal name for these in TopBraid is edg:DatabaseTable and their name in GraphQL is a lower-cased plural form of that name, i.e. databaseTables

Like every GraphQL object, each top-level query object must have at least one field, again enclosed by curly braces. There are two built-in fields that are always available:

  • label returns a human-readable label, using the preferred language of the HTTP request if available
  • uri returns the resource identifier (URI) of the object as a string

For example, the following GraphQL query will return all concepts ordered by their preferred label. For each concept, we will see their URI, their label, the value of a notation field and the value of the type field. For the type, we will see both the URI and the name of the class:

concepts (orderBy: label) {
                 type {

When ran for the Geography Taxonomy example the output would look as follows:

"data": {
"concepts": [
"uri": "",
"label": "Abilene",
"notation": [],
"type": [
"uri": "",
"label": "City"
"uri": "",
"label": "Abu Dhabi",
"notation": [],
"type": [
"uri": "",
"label": "City"
<the rest of the concepts>
"uri": "",
"label": "Zimbabwe",
"notation": [],
"type": [
"uri": "",
"label": "Country"


Any GraphQL object field, such as those on the top-level of a query, can take parameters - name-value pairs enclosed in round braces behind the field name. So for example if your query is about database tables, use DatabaseTables (...) to specify which database tables you want to have returned.

Filtering by Property Values

The simplest type of filter is by matching specific property values. For each field that the object can take, you can specify a name-value pair where the name is the field's name. So if your object has a field called acronym then you can write databaseTables (acronym:"PPL") { ... } to return only those instances where the acronym has exactly the given value. This is typically a very fast operation, as it can exploit existing database indices. Alternatively, use (acronym:null) to filter those instances that do not have any value for the given field (which is quite a bit slower).

In addition to the fields specific to the current object type, you can match values of uri to select exactly the one instance that has this URI, if it exists. It is however not possible to match by label. To match by display label, use something like filter:"regex($label, 'text', 'i')".

A note to the RDF geeks: GraphQL uses just a handful of datatypes such as String and Float. TopBraid's GraphQL mapping converts between these and the RDF/XSD datatypes on the fly. While the mapping is hopefully obvious in most cases, keep in mind that we use String to represent non-numeric types including xsd:date and xsd:dateTime. URIs are mapped to the GraphQL type ID which is essentially the same as String.

Filtering by Constraints

This type of filtering uses built-in constraint types (based on a subset of SHACL) that provide a declarative language to express common kinds of conditions. These constraints are used in values of the where parameter, which must be an input object that may have name-value pairs for any of the fields of the surrounding object type. Each of these values must be another object that uses the names from the table below to specify the actual constraints. This is best explained with an example.

The currently supported constraint parameters are:





hasValueSame as fieldObject must have exactly the given value (plus maybe others)
minCountIntObject must have at least minCount values
maxCountIntObject must have at most maxCount values
minExclusiveSame as fieldObject must have a value so that value > minExclusive
minInclusiveSame as fieldObject must have a value so that value >= minInclusive
maxInclusiveSame as fieldObject must have a value so that value <= maxInclusive
maxExclusiveSame as fieldObject must have a value so that value < maxExclusive
patternStringObject must have a value that matches the given regular expression
flagsStringOptional flags for the pattern regex engine, such as "i" to ignore case
existsNested objectOne of the values must conform to all nested constraints

From those, the exists constraint can be used to formulate conditions that walk into adjacent objects, such as to find Persons where the Address has a City with at least 1 million inhabitants.

For example, the following query over Geography Taxonomy

concepts (where: {prefLabel:{pattern:"Abu"}} orderBy: label) {
type {

Will return

"data": {
"concepts": [
"uri": "",
"label": "Abu Dhabi",
"notation": [],
"type": [
"uri": "",
"label": "City"
"uri": "",
"label": "Abuja",
"notation": [],
"type": [
"uri": "",
"label": "City"
Filtering by Text

Each object type supports the parameter queryText that can take any search string as value, implementing a general free-text search. If present, the system will return all objects where any literal (scalar) value matches the given string.

In TopBraid this is currently a potentially very slow operation because it performs an iteration over all field values and then does a regular expression matching. Future versions may use Lucene index and other kinds of fuzzy matching instead of regex matching.

Filtering by SPARQL Expressions

If the simple filters from the previous sections are not sufficient, you can fall back to SPARQL. Even if you are not familiar with SPARQL, this is worth exploring as the syntax for many scenarios is quite intuitive.

The parameter to use for arbitrary SPARQL expressions is filter. The values of filter must be strings that can be parsed into valid SPARQL expressions, in the syntax that is typically used in FILTER or BIND statements in SPARQL. SPARQL includes a large number of built-in functions and operators, including functions that are specific to the TopBraid platform.

In those SPARQL filter expressions certain variables have pre-defined values. For example, if your filter expression is $variance > 0.5 and you are inside of a database column object, the variable $variance will hold the value of the corresponding property (edg:variance) from that object. Note that these values are not available for multi-valued properties. In those cases, use EXISTS or NOT EXISTS in SPARQL expressions. The special variable $this points at the current object itself. The variables $uri and $label have the corresponding fields as their string values.

For advanced users, the filter parameter offers basically the full expressivity of SPARQL, including EXISTS and NOT EXISTS clauses that check against arbitrary RDF graph patterns. Take care with variable names in such complex scenarios, as they may overlap with the pre-bound variables. Using these advanced features does require knowledge of the underlying RDF data model and the available namespaces, so we do not cover those scenarios in this tutorial. See some SPARQL tutorials or the spec for more information.


For multi-valued object fields, use the orderBy parameter if you want the results sorted. This is slower and RDF data is inherently unordered, so use this only where needed. The values of orderBy come from an enumeration of the available fields including uri and label.

The optional field orderByDesc can be set to true for descending order.

The optional field orderByExpr can be used to specify a SPARQL expression as a String. This expression is evaluated prior to sorting, with each value of the orderBy field assigned to the variable $value. For example use orderByExpr: "LCASE($value)" to implement ignore-case ordering.


Like many other GraphQL implementations, top-level query objects in TopBraid support the parameters first and skip to return partial results:

  • first is the maximum number of objects to return in a transaction
  • skip is the offset, starting with 0 by default


This section assumes that Enable aggregation fields has been switched on in the server configuration parameters. The features are switched off by default because they can cause schema bloat in large data models. You are encouraged to use SHACL Property Value Rules to define the kinds of aggregations that users may ask via dedicated derived fields.

TopBraid's GraphQL implementation comes with support for common scenarios where multiple values need to be aggregated into a single value.


All multi-valued GraphQL object fields are accompanied with a _COUNT field that produces an integer value representing the number of (matching) values. For example, for a field column there is a corresponding column_COUNT field available.

The count fields (and the other aggregation types) can use any number of filters as described above, for example to only count those columns that have a specific datatype.

Concatenating Strings

All multi-valued GraphQL object fields are accompanied with a _CONCAT field that produces a string value built by concatenating strings for each value. This takes an optional parameter separator if the string should use something else than the default comma in between sub-strings. Furthermore, there is an optional argument labelExpr that transforms values on-the-fly using SPARQL expressions. For example, use labelExpr:"LCASE($value)" to produce a concatenation of lower-case strings.

There are no suitable examples for this section that work with the current Lineage Model. However, we have 1 example for Data Assets Collections, 1 example for Glossaries.

Derived Fields

This section assumes that Enable derive fields has been switched on in the server configuration parameters. The feature is switched off by default because it may give users too much expressive power that may lead to poor performance. You are encouraged to use SHACL Property Value Rules to define the kinds of derivations that users may ask.

In some cases, JSON fields should be computed on the fly. TopBraid's GraphQL implementation supports "magic" fields that are derived using SPARQL expressions. There is one such field for the built-in datatypes: deriveBooleanderiveFloatderiveInt and deriveString. It is common to use GraphQL aliases so that the names in the generated JSON will not start with derive.

The values of these fields must be valid SPARQL expressions, and these fields can access the values of other property values similar to how SPARQL-based filter expressions work.


Data is updated using GraphQL mutations.

The following query ran over the GraphQL endpoint for the Geography Taxonomy will add a new instance of the class Country:

mutation {
createCountry (input: {
uri: "",
prefLabel: { string: "Utopia" }

Success response will look as follows

"data": {
"createCountry": true,
"commit": "GraphQL mutation"

Mutations can add and modify multiple resources. For example, the following creates one new resource of type City an updates information about existing resource of type ConceptScheme.

mutation {
createCity (input: {
uri: "",
prefLabel: { string: "Harmony" }
broader: {
uri: ""
updateConceptScheme (input: {
uri: "",
hasTopConcept: {
uri: ""
report {
commit (message: "Added city and connected Utopia")

Pre-built RESTful Web Services

EDG exposes a variety of common operations for use in pre-built RESTful Web Services implemented using one of the following mechanisms:

  • SPIN Templates from .spin. files. These are templated (parametrized) SPARQL queries.
  • SPARQLMotion scripts from .sms. files
  • SWP Services from .ui. files.

TopBraid includes a facility for auto-generating API documentation. This means that any API that has been developed and deployed is automatically fully documented in your installation of TopBraid EDG when marked as public. This includes pre-built TopQuadrant provided APIs as well as any customer developed APIs. The documentation is available from the Server Administration console.

Selecting Server Administration > Available Web Services displays a page that lists web services available on this server. 

The following categories are currently available:

Selecting the checkbox next to any of these categories displays documentation below the list about each of the services in the selected category(s) and how to call that web service. For example:


You will see parameters accepted by a service, service syntax and code that implements the service (Service Body). It will typically be a SPARQL query or SPARQL Web Pages (SWP) script.

For the SPIN (SPARQL) template services, the following values can either be supplied in the HTTP request's Accept header or as the value of the _format argument:

Response type

Format name

Arguments accepted

application/sparql-results+xmlSPARQL XML Resultsxml
application/sparql-results+jsonSPARQL JSON Resultsjson
application/sparql-results+json-simpleSimple JSON Formatjson-simple
text/csvComma separated valuescsv
text/tab-separated-valuesTab separated valuestsv

If you do not explicitly specify the response type, defaults will be used. The default serialization of SELECT result sets is JSON, following the SPARQL protocol. When you call a service from a web browser's address bar, the mime type will typically be requested as something that includes the string "xml", and in this case it will produce SPARQL XML Results. CONSTRUCT queries are returned in Turtle format by default.

The value of the _base argument can be a full graph URI or a short graph name. To define short graph names, go to the Server Administration > Server Configuration Parameters page. In the section named "URI Parameters" define an instance of "Short graph names".

Custom-defined RESTful Web Services

When a user of EDG saves a search and/or saves a SPARQL query, they are creating a service that is available not only through EDG UI, but also as an API call.

To call a saved SPARQL query as an API, navigate to the Export tab: Export > Export using Saved SPARQL Query and copy the Service URL. 

To call a saved search as an API, navigate to the Export tab: Export > Export using Saved Search and copy the Service URL. 

Saved queries and searches use a predefine search criteria and return predefined result fields. The only variables you can pass to a saved query service are the format of the results (e.g., XML, TSV, CSV, JSON) using &format parameter, graph to run the query against using &default-graph-uri parameter and whether the query should query the specified graph only or specified graph with all it owl:imports closure using &with-imports parameter.

Templated queries, on the other hand, let you define and use additional parameters. For example, with a saved query or a search you could return all concepts that have at least two children. With a templated query, you can define a number of children as a parameter.

Using the provided IDE, TopBraid Composer, additional web services can be developed if needed. Just as pre-built services these can be implemented as:

  • SPIN Templates from .spin. files. These are templated (parametrized) SPARQL queries.
  • SPARQLMotion scripts from .sms. files
  • SWP Services from .ui. files.

For more information on Web Services with TopBraid see and

Detailed guide on developing using SWP is available at  SPARQL Web Pages - User Guide.

Any API that you develop using SPIN, SPARQLMotion or SWP and deploy on the EDG server will be automatically fully documented when marked as public. You will see their documentation by selecting Server Administration > Available Web Services.

SPARQL endpoint

SPARQL endpoints provide a programmatic interface to query RDF data using the  standardized query language SPARQL

Using SPARQL is similar to using a public endpoint of a database where you can perform your own queries instead of having to learn and use the - often restrictive - web service APIs. All you need to know is the query language (SPARQL). Results of SELECT SPARQL queries are tabular structures. If you are interested in APIs that return nested JSON structures, consider using GraphQL endpoint. SPARQL result sets are  standardized as described in the language specification .

There is a general SPARQL endpoint in TopBraid EDG for querying any graph hosted by EDG as well as SPARQL endpoints specific to each asset collection.

The general SPARQL endpoint is available at the following URL:


Each asset collection is stored as a separate named graph on the server; to find a given asset collection's graph name, mouse over its name on the EDG home screen and note the projectGraph parameter in the URL that the name links to. NOTE: The SPARQL standard treats references to non-existent graphs the same as references to empty ones, which means that incorrect graph URIs might not raise any obvious errors.

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

SELECT ?continent WHERE
   {GRAPH <urn:x-evn-master:geo> 
 {?continent a <>} 

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

SELECT ?continent WHERE
   {GRAPH <urn:x-evn-master:geo> 
 { ?continent a <>} 

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

An option to specifying the named graph with the GRAPH keyword, you can use an endpoint specific to the asset collection you want to query.

To do so, name the graph in a default-graph-uri parameter added to the URL. For example, let's look at this simpler query that does not mention the graph to query:

SELECT ?continent WHERE  
{?continent a <>}

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

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

SPARQL endpoint update

SPARQL Update statements can be executed on EDG project graphs. By default, SPARQL Endpoint Updates are disabled. To enable updates set the Advanced ParameterEnable SPARQL updates  to true in Server Administration > Server Configuration Parameters. Access controls are also available for SPARQL Endpoint Updates. For more information on setup for SPARQL Endpoint update, see SPARQLEndpointUpdate

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

tbl/sparql?update=INSERT{GRAPH <urn:x-evn-master:schemaexample>{< > < > "a comment"}}WHERE {}

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

tbl/sparql?update=INSERT{GRAPH <urn:x-evn-master:schemaexample:Administrator>{< > < > "a second comment"}}WHERE {}

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

Application Configuration

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

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

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

  • Adding or modifying business actions through SPARQLMotion and SPARQL Web Pages (SWP) scripts. SPARQLMotion is a visual scripting language for data processing and orchestration. SWP is a text templating technology that makes it easy to build powerful and flexible web applications that interact with RDF data. Many new operations can be added by developing new scripts.

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

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

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

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

As an example of developing extensions, watch this video that demonstrates how to add XML import option for EDG ontologies.

Detailed guide on developing using SWP is available at  SPARQL Web Pages - User Guide.

The rest of this section describes some of the most frequently used customization options.

Extension Process

Creating some of EDG customizations and extensions requires using TopBraid Composer-Maestro Edition (TBC-ME), which serves as the IDE for TopBraid EDG. TBC-ME is a development toolkit for TopBraid server products. Some experience with SPARQL Web Pages (SWP) is required to build EDG extensions. The general process of customizing and extending EDG using TBC-ME is as follows:

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

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

Common extension tasks

Adding SPARQL query templates for use in Taxonomy or Ontology Editors

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

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

Once the file has been created, if the new template is for use with Taxonomies, import into it, and then create a new subclass of skostemplate:IntegratedTemplates, using the existing subclasses that you see as a model. You will see that the rdfs:label property of each stores the text displayed as the template's name on the EDG Execute t emplate query... drop-down list, its rdfs:comment value provides the tooltip, and the spin:body property stores the query to execute. Define run-time parameters by adding spl:Argument values to the spin:constraint property.

Pre-built query templates for Ontologies are defined in graph.

After saving the file, upload the project containing it to the EDG server, and the new menu template will be available to your users on the Execute template query...  menu. This menu is accessible in the Taxonomy Editor from the  gear icon in the light blue header bar or in the Ontology Editor from the   play icon in the light blue header bar.

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

Adding SPARQL endpoints to the copy taxonomy concept from SPARQL endpoint list

The EDG user guide chapter's section on EDG Taxonomy Editing: Copying Data from Remote Sources and Other Taxonomies describes how to copy taxonomy concepts from SPARQL endpoints. SPARQL endpoints listed in the Copy Concept from SPARQL Endpoint dialog box are stored in a model that uses the SPARQL Service Description schema.

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

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

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

Creating and maintaining new SPIN constraint libraries (DEPRECATED; use SHACL)

NOTE: SPIN constraints are deprecated and users are encouraged to migrate to SHACL. Both ontologies and standard teamworkconstraints no longer import SPIN by default. Any ontologies that rely on the latter owl:imports (transitively), must be manually updated to include the SPIN Standard Library (SPL).

TopBraid EDG's includes a number of pre-defined constraint templates that let users specify data constraints - Constraint Libraries. You can use TopBraid Composer to define new SPIN constraint templates. Once a template is defined and uploaded to the server, it is available for selection. 

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

Deploying that model to your EDG installation's workspace will make that model appear in the manage tab on the vocabulary/asset collection's home page under Constraint Libraries. Each model created in this manner will show up as a separate choice on the list, so splitting constraints across models will let you use specific subsets of your total constraint collection in different combinations as necessary for your application.

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

Changing CSS Styles

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

  1. Identify the CSS style that you want to change. This is usually done by looking at the source code or the DOM tree of the HTML with a tool such as FireBug.
  2. Create a folder ending with .www in the workspace—for example, my.www. Restart TBC to make sure that it knows about that folder.
  3. In that folder create a CSS file, for example, my.css.
  4. Add your custom CSS In that CSS file.
  5. Create a .ui. file (File -> New RDF/SWP File), and add to its imports.
  6. In that file, select the SWA:Elements class and add an empty row to the ui:headIncludes property.
  7. In that row, enter a line such as <link href="lib/my/my.css" rel="stylesheet" type="text/css"/>.

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

.edg-product-logo {
    background-image: url(images/CustomizedLogo.png);

To verify that this worked, you should see the link to your CSS file in the generated source of EDG.

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

Customizing the login screen

To implement a background image, locate the following code in logon.html: 
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/> 
<style type="text/css"> 

And beneath it, insert the following code: 

html, body { 
    min-height: 100%; 

body { 
    background-image: url(http://path-to-your-background.jpg); 
    background-repeat: no-repeat; 
    background-position: 0 0; 
    background-size: cover; 

@media (min-width: 1024px), (min-height: 576px) { 
    body { background-size: auto; } 

Update the background-image url, add the @media’s min-width and min-height dimensions to match the image. 

To add an image to the login window, browse to the bottom of the file and locate the following section: 
<title>TopBraid Live Login Page</title> 

<div class="loginform-dialog"> 
<div class="loginform-container"> 
<!-- <img src="http://your-custom-logo-here.jpg" alt="Logo"> --> 

Uncomment the <img> tag and update the src attribute to point to the location where the image is hosted. 

Images cannot be hosted from within the application server. Authentication prevents any assets outside of the .html file from being accessed anonymously. Because of this, they must be hosted on a separate web server. You can also alter the html file to use colors, text and fonts. 

Customizing the Landing Page

  1. In TBCME File -> New -> RDF/SWP File
  2. Import edgproduct.ui.ttlx into the newly created file
  3. From classes view, navigate to edproduct:LandingPage
  4. Right Click -> Clone
  5. Set the ui:overrides in the newly created cloned class to edgproduct:LandingPage

At this point we should have a clone of the landing page that is overriding the standard one, and are ready to make some changes:


Replacing the EDG Heading Information -

The 'Welcome to TopBraid EDG' part of the landing page is coming from teamwork:EdgLandingPageHeading - so we can do the same sort of clone and override operation to change this content:

  1.  Navigate to teamwork:EdgLandingPageHeading
  2. Right Click -> Clone, and set the ui:overrides on the clone to teamwork:EdgLandingPageHeading
  3. Make some changes - update the body to something like this:


       <div class="col-xs-12">
           <h1>This is my Custom header EDG</h1>
           <span class="subHeading">Totally Customizable</span>
           <p>How cool is that?</p>

4. Save, and refresh the homepage.

5. You should see your changes reflecting:

Customizing Icons

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

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

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

.CountryStyle {
background-image: url('myCountryIcon.jpg');
background-position: center;
background-size: 100%;

Then, import the Geography schema file geo.tdb into your custom ui.ttlx file and assign the g:Country class a swa:typeIcon value of "CountryStyle". Finally, import into your custom .ui.ttlx file and add a ui:headIncludes value of the following to the evnui:Editor class, adjusting the name and path to point at your own CSS file:

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

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



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

Adding New Menu Choices

For an example of adding a new menu choice you can follow the procedure below.

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

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

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


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

Customizing Form Layouts

Versions 5.4 and up: Using SHACL constraints

From TopBraid version 5.4 onward, SHACL constraints are the recommended way of defining the layout of property groups in forms. For a given class, its form layout consists of the property groups used by its sh:property constraints (via sh:group), and sh:order is used for relative ordering of both the groups and the properties. This property grouping and ordering for form layouts can be customized in the Ontology editor for classes that have property shapes defined. For a selected class, in its details pane, select Actions (gear button) > View/Edit SHACL property layout groups...

This opens an interactive, non-modal window showing the selected class's property-groups, properties, and their relative-order values (integers or decimals). The pop-up window works in parallel with the main editor such that changes in one are reflected in the other.

In addition to grouping properties in to sections, you can also define a display name for a property that is different from the label. This can be particularly useful for inverses. And you can select different edit, search and view widgets. By default, widgets will correspond to the type of the value that a property has.

Versions 4.5 and up: Using form editor or SWP

TopBraid 4.5 introduced a graphical form layout editor, allowing end users to define which properties show up for a given class and in what order. Utilizing the editor, EDG users can create custom form layouts without having to use TopBraid Composer. This feature continues to be supported for advanced use cases and form configurations.

Note: If you are running version 5.4 or higher, majority of form configurations can be (and recommended) done by using SHACL, as described in the section above.

Forms created using web based form layout editor are stored in the uiconfig.ui.ttl file in the dynamic folder under  the  project. Note that form layouts are global to EDG. If a class has a custom form, all instances of the class will be using this form - irrespective of the vocabulary/asset collection they are in.

For advanced use cases please take a look at the SWA documentation (available from Help > SWA Help/Examples) for details on how to define custom form layouts via SWP. You can create an initial form with the web based form layout editor and then, if necessary, extend it further using TopBraid Composer. 

Forms are attached to classes using ui:instanceView property. Since uiconfig.ui.ttl file doesn’t import any ontologies, to find the class to which your form is attached to, you need to do one of the following:

  • Temporary import your ontology file, then you will see the class in the Classes view of TopBraid Composer.
  • Type the URI of the class in the global navigation field of the TBC toolbar, make sure to use <> around the URI. 
  • Use SPARQL. Run the following query in the SPARQL view. Then, in the results, select the subject (class) you are interested in.
    WHERE {
      ?subject ui:instanceView ?object .

SWA documentation (Help > SWA Help/Examples) explains how to create nested widgets when you want to fold into a form information about related resources. For example, for an organization, in its address field you may want to directly display the street address, city and state - as opposed to a link to a resource holding this information. To do so, set the address property to be a blank node as shown below. This statement can be added to the uiconfig.ui.ttl file and will be effective globally. EDG will interpret it as a direction to nest the form for this property.

<> swa:blankNodeProperty true .

The layout of the nested form will be determined by the class in the range of the "blank node" property. In our example, this may be a class Address. When used in editing, if user enters information in the fields of the nested form, EDG will automatically create a blank node (e.g., instance of an Address) as a subject to hold information entered a nested form.

Another useful example of customization you can find in SWA documentation explains how to define dynamic ranges for some of the form fields. For example, if you need the values for countries to be dependent on the values for states.

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

Adding descriptive text below section titles

When using SHACL to define forms, the property-group sections of either the view or edit forms, custom text (e.g., a line of description, instructions, etc.) can be added below each section title. When descriptions are available, users will see the text next to the sections name as shown below.

To add the descriptions set either of the corresponding properties: view group description or edit group description (cf. in code: tosh:viewGroupDescription and tosh:editGroupDescription).

Controlling order and collapse/expand status of form sections

When using SHACL, you can elect to have a form section closed by default by setting the open field to false and openable field to true. Section will be initially presented as collapsed and users will be able to open it.

Configuring search text properties

The EDG advanced search forms by default include a global text field called "Search any Text" that searches across all string properties of the matching instances. For large models with a lot of strings, this may be quite slow. It is therefore possible to limit the properties on a class-by-class basis, for example by searching only within a preferred and alternative names, but not descriptions or other text properties.

To configure this behavior and specify the properties to be searched by this field, execute the following steps in TopBraid Composer:

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

Adding custom actions on create

Custom plugins are used to modify behavior when new items are created.

For example, you may want EDG to perform additional initialization whenever a new taxonomy concept is created—to assign a new unique ID for each new concept or perform any other desired initialization. EDG provides a plugin mechanism that allows developers to add such initializations. See evn-plugins:ExampleCreateConceptPlugins for an example of such a plugin.

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

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

Plugins for initializing new resources

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

Custom plugins for dialog boxes

The dialog box that appears when new items are created can be customized. This applies to any item e.g., a taxonomy concept, a class, an attribute, a relationship, an instance of any class. For example, if we auto-generate URIs of newly created items, we wouldn't want to have the URI field be editable in the dialog. Instead, we want to generate and display it. See evn-plugins:UUIDCreateResourceDialogPlugin for an example of such a plugin.

Note that starting with version 6.1, you can specify options for URI creation in the Server Administration > TopBraid EDG Configuration > URI Creation Rules.

Custom plugins for creating vocabularies/asset collections

EDG can be configured to perform additional initializations whenever a new asset collection has been created through the user interface. Among other tasks, this can be used to automatically pre-populate the user permissions (in the .tch. graph) with certain user groups. See evn-plugins:ExampleCreateProjectPlugin for an example of such a plugin. The following image shows the custom dialog box from the example in evn-plugins.ui.ttlx. This dialog uses a UUID() generated namespace and does not allow the user to change that namespace. Defining static namespaces is also possible.

Custom plugins for cloning vocabularies/asset collections

EDG can be configured to perform additional steps after a vocabulary/asset collection has been duplicated via the Create Cloned Version action. This is done by creating a new subclass of the abstract class teamwork:ClonePlugins, and by defining the custom behavior using SWP in the ui:prototype of the new class. The arguments for prototype can be looked up in teamwork:ClonePlugins. To enable the new plugin for a particular project type, it must be added as a value of teamwork:clonePlugin to the teamwork:ProjectType instance.

Adding Event-Condition-Actions Rules

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

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

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

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

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

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

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

Status change rules

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

Additionally, there are two types of rules that are executed when working copies are committed. In TBC , navigate to teamwork:CommitRules and teamwork:PreCommitRules to learn more about them.

Customizing File Import using a Script

EDG can also incorporate custom scripts for importing arbitrary types of text files, including XML, JSON or spreadsheet files. Each such importer must be set up by a power user or Administrator based on a SPARQLMotion script. Once set up, the custom importers would show up on the Import view as shown in the following screenshot:

The common requirement of these script-based importers is that they take a single text file as input and output new RDF data. Script-based importers can be activated per model type (e.g. only for Ontologies) or even for only one specific model instance. They are a powerful mechanism to simplify repeatable tasks for end users.

This paragraph assumes the reader to be familiar with SPARQLMotion. In order to create such scripts, create a new RDF/SPARQLMotion file with TBC-ME. The file must end with .sms.ttl. Into that file, import the namespace  (from / Also import the XYprojects.ui.ttlx file for the vocabulary type that you want the script to be activated for. For example, if you want to add a script for Ontology vocabularies, add an import to ontologyprojects.ui.ttlx. Next, use Scripts > Create SPARQLMotion Function/Web Service to create a new service. This service must take a single argument of type xsd:string and return a module of type sml:ReturnRDF. This argument will contain the text content that has been uploaded, e.g. the data from an XML or CVS file. The script may access the currently active target graph (vocabulary) using sml:ImportCurrentRDF. The script needs to produce a graph of new triples that shall be added to the target graph. At the web service instance that you have created (instance of sm:Function), use the property teamwork:suitableProjectType to specify the vocabulary type(s) that the script should show up for, e.g. ontologyprojects:ProjectType. Alternatively, use teamworkscripts:suitableVocabulary to link the URI of individual vocabularies, starting with urn:x-evn-master: .

Customizing the Governance Roles

To customize the list of governance roles:

  1. In TBCME, create a new .ttl file, open it, and import
  2. To disable existing governance roles:
    1. Navigate to the class edg:Stewardship
    2. Navigate to the property constraint for the role to be disabled, e.g., edg:Stewardship-applicationSteward
    3. Set sh:deactivated to true
  3. To add a new governance role:
    1. Navigate to edg:WorkflowParticipantProperty
    2. Create a new instance of this class
    3. Choose its URI, rdfs:label, and rdfs:comment to represent the new governance role
    4. Navigate to the class edg:Stewardship
    5. On this class, create a new property constraint with the new property as predicate
    6. Optionally, navigate to the new constraint and set its sh:order to adjust the order in which the governance roles will appear in the EDG/EVN user interface
  4. In EDG, navigate to the Import/Export tab of the Governance Model
  5. Import RDF File, select the created file, check “Record each new triple in change history”

To undo the customization at a later stage, go to the Change History of the Governance Model, find the Change corresponding to the import, and revert it.

Adding Custom Workflow Templates

The stages that a workflow goes through are defined by in a workflow template. The Workflow Templates page allows users to view and, if permitted, modify the workflow templates. The workflow templates are defined in RDF in a dedicated graph, accessible via the function teamwork:workflowsGraph() in SPARQL queries. Users with a Teamwork Administrator Role in the EDG Configuration Parameters page are permitted to edit workflow template definitions.

Editing workflow templates is a low-level operation that should be handled with care. It is technically possible to modify workflow templates that are already in use and, as a result of this, an existing working copy may be in a state that gets disconnected from the other states in the template, or its whole workflow template may get deleted. We therefore strongly recommend that the development and editing of workflow templates is performed by expert users only, and tested in a sandbox environment (such as a TBC-ME instance) before deployment to a production server. Alternatively, consider having a TopQuadrant services develop custom workflows. 

The editing of workflow templates is currently performed via TBC or source code editing. For Teamwork Administrators, the basic mechanism is:

  1. Go to Workflow Templates on the production server
  2. Click Download as Turtle File to a local file
  3. Edit this file using TobBraid Composer (or a text editor of your choice). Note that also attached to this page (see below), is an example template file, which has workflow diagram layouts, with positioning, widths, and heights.
  4. In a test environment, use Upload Turtle File to replace the current definitions
  5. If any errors are detected, the Upload feature present a report of all the errors found in the file. These errors must be addressed in order for the file to be successfully uploaded.
  6. Carefully test the workflows in your test environment
  7. When satisfied, use Upload Turtle File to replace the definitions on the production server

Defining workflow template status

Each workflow template defines a start status (e.g. Uncommitted) and a set of transitions that specify which steps are possible and by whom, until the workflow is ended (e.g. by committing). The following list enumerates frequently used properties at workflow templates:

  • rdf:type: workflow templates must have rdf:type teamwork:TagWorkflowTemplate (for general asset workflows), teamwork:ExistingResourceTagWorkflowTemplate (for workflows that are specific to an existing asset), or teamwork:NewResourceTagWorkflowTemplate (for workflows that create a new asset).
  • rdfs:label: a human-readable label that is used to name the workflow template in the user interface
  • teamwork:defaultTagWorkflowTemplateForProjectType: enumerates the asset collection types for which the workflow template is the default. Asset collection types that don't have any default workflow template fall back to the system-wide default workflow template. For example, use edg:GlossaryProjectType as a value to make the workflow template the default for EDG Glossaries.
  • teamwork:suitableWorkflowForProjectType: enumerates the asset collection types for which the workflow template is suitable for use. If left empty, it applies to all types. For example, use edg:GlossaryProjectType as the value to make the workflow template only applicable to EDG Glossaries.
  • teamwork:suitableWorkflowForSubjectArea: the subject areas that asset collection must have so that the workflow template is suitable for them. If left empty, then it applies to all subject areas. Details about defining subject areas can be found at EDG Governance Model: Governance Areas
  • teamwork:editorWorkflowParticipantProperty: lists the workflow participant properties (e.g. edg:responsible) whose users are automatically granted editing permission. By default, workflow participants only get viewer permission.
  • teamwork:managerWorkflowParticipantProperty: lists the workflow participant properties (e.g. edg:responsible) whose users are automatically granted manager permission. By default, workflow participants only get viewer permission.
  • teamwork:initialStatus: specifies the initial status of a Workflow. Example values include teamwork:Uncommitted or teamwork:New.
  • teamwork:tagShape: (advanced feature) SHACL shapes that the working copy needs to conform to before it can be committed. These are validated using the union of the working copy and the TCH graph as data graph, and the workflows definitions graph as shapes graph. The focus node is the teamwork:Tag instance. There is an example below.

An additional property for templates that have the type teamwork:ExistingResourceTagWorkflowTemplate:

  • teamwork:editedResourceShape: the shape that edited resources need to have. Used to filter applicable workflows for a given resource. If multiple values are present then they are interpreted as a union, i.e. a candidate resource must conform to any one of them. An example of this is teamwork:editedResourceShape [ sh:class ex:Person ] to limit a workflow for instances of ex:Person.

Defining workflow template transitions

A workflow is started in the status specified by teamwork:initialStatus in the template. From there, the possible transitions are defined by the values of teamwork:transition. These values must be URI or blank nodes of type teamwork:TagStatusTransition, and can have the following properties:

  • teamwork:fromStatus: the status that the workflow (working copy) must be in for the transition to be applied.
  • teamwork:toStatus: the status that the workflow (working copy) will be in after the transition is applied.
  • teamwork:transitionLabel: the display label of the transition, e.g. "Accept changes to production".
  • sh:order: an optional number that is used to order the transitions in the Workflow tab. Transitions with smaller numbers show up higher, with 0 being the default.
  • teamwork:requiredGovernanceRole: the minimum governance role (e.g. informed) that a user must have on an asset collection to perform the transition. For example, the required governance role can be an instance of edg:JobRole, which means that any user who has edg:assignedJobRole edg:JobRole is allowed to execute the transition. The user will in this case see a corresponding button in the UI, and under My Workflows.
  • teamwork:requiredProjectPermissionRole: the minimum permission role (e.g. editor) that a user must have on an asset collection (master graph) to perform the transition. These are the roles defined on the User Roles tab of an asset collection.
  • teamwork:requiredTagPermissionRole: the minimum permission role (e.g. editor) that a user must have on a working copy to perform the transition. These are the roles defined on the User Roles tab of a working copy/workflow.
  • teamwork:minVoteCount: the minimum number of votes required before the transition can be performed.
  • teamwork:voteAutoTransitions: if true then the transition will be performed automatically, as soon as sufficient votes have been registered. This property can only be used if teamwork:minVoteCount is present.
  • teamwork:autoTransitionHours: the number of hours after which a working copy will automatically transition to another state. For example this can be used to give users a chance to comment without explicitly waiting on such feedback.

Example workflow-template file with diagram layouts

This example workflow template file (create-dataset-schema.ttl) shows diagram layout specifications with (x,y) positioning, widths, and heights: create-dataset-schema.ttl

Example of teamwork:tagShape

 This example illustrates the use of teamwork:tagShape to specify that a working copy can only be committed if it contains exactly one new instance of edg:GlossaryTerm and no other subject. If teamwork:tagShape statements are present for a workflow template, then the Commit button will force the user to first go through a dedicated page that checks whether the working copy conforms to the specified shapes. If violations are detected, the user may still proceed, yet he or she has been warned about the consequences.

    rdf:type teamwork:NewResourceTagWorkflowTemplate ;
    teamwork:initialStatus teamwork:Uncommitted ;
    teamwork:tagShape glossary-term-workflow:TagHasExactlyOneGlossaryTermShape ;

    rdf:type sh:NodeShape ;
    sh:sparql [
        sh:message "Working copy contains changes about {?other} while it should only be about {?newTerm}" ;
        sh:prefixes <> ;
        sh:select """
            SELECT DISTINCT $this ?other ?newTerm
            WHERE {
                ?change teamwork:tag $this .
                ?change a teamwork:Change .
                ?change teamwork:added ?added .
                ?added teamwork:subject ?newTerm .
                ?added teamwork:predicate rdf:type .
                ?added teamwork:object edg:GlossaryTerm .
                ?otherChange teamwork:tag $this .
                ?otherChange a teamwork:Change .
                ?otherChange teamwork:added|teamwork:deleted ?aod .
                ?aod teamwork:subject ?other .
                FILTER (?other != ?newTerm) .
            }""" ;
    ] ;
    sh:sparql [
        sh:message "Working copy does not create a new instance of edg:GlossaryTerm." ;
        sh:prefixes <> ;
        sh:select """
            SELECT $this
            WHERE {
                FILTER NOT EXISTS {
                    ?change teamwork:tag $this .
                    ?change a teamwork:Change .
                    ?change teamwork:added ?added .
                    ?added teamwork:subject ?gt .
                    ?added teamwork:predicate rdf:type .
                    ?added teamwork:object edg:GlossaryTerm .
            }""" ;
    ] .

Custom Rules in EDG

Often,  the word 'rules' is used interchangeably to refer to two types of rules:

  1. Data quality rules which check that data adheres to some defined constraints
  2. General rules that infer new facts from available facts

In TopBraid EDG, both types of rules are implemented using W3C standard SHACL. Rules of the first type are typically called shapes or constraints. Rules of the second type may be differentiated between Triple Rules, SPARQL Rules and Property Value Rules which are dynamically inferred values specified using sh:value and sh:defaultValues properties.

Data Quality Rules

SHACL shapes and constraints (data quality rules) are created when users define ontologies in EDG. All shapes and constraints applicable to an asset are checked when its information is modified in EDG. EDG will alert the user if any issues are found. Optionally, data issues can be checked any time information about a resource is rendered on a form. There is a Show Problems and Suggestions icon on the form that turns this option on and off. The setting selected by a user is remembered. To check data validity across all assets in an asset collection use Reports > Problems and Suggestions report. For more information please see Using SHACL Data Constraints In The TopBraid Web Products guide.

Note that the logic for finding matching resources in crosswalks is also incorporated into the Problems and Suggestions report.

General Rules

General rules that infer new facts are also specified in ontologies as described below.

Property Value Rules using sh:values and sh:defaultValue are specified within property shapes. sh:values is located in the Inferences section. sh:defaultValue is located in the Type of Values section of the property shape form. Once specified, you will see a diagram of a rule.

In the edit mode a rule expression looks as follows:

Rules specified using this method are executed dynamically. For more information see Inferring Data with SHACL Property Value Rules.

Triple and SPARQL Rules are specified for a class that is also a SHACL shape using sh:rule property. sh:rule property is located in the Rules section of the node shape form. See SHACL Advanced Features specification for more information on the rules syntax. Triple Rules specify inferred statement as a triple. SPARQL Rules specify inferred statement as a SPARQL CONSTRUCT query. 

These rules are not executed dynamically. Their execution must be triggered by some action. Unlike Property Value Rules, the triples inferred by these rules are materialized i.e., inserted into a graph. 

TopBraid EDG offers the following mechanisms for invoking execution of Triple and SPARQL Rules:

  • Transform tab lets a user start inferencing process by clicking on “Execute Rules”. Values generated as a result are permanently written into the asset collection user invoked transformation on. EDG remembers which triples were inferred and on the subsequent execution, inferences can be reset.
  • SPARQLMotion module sml:ApplySHACLRules lets users create different custom inferencing processes that could be triggered programmatically or through the UI.

Being a model-driven application, many configurations and customizations can be done by changing the underlying models of EDG.

Customizing EDG ontologies

Most asset collection types in EDG are based on some specific ontology. Specifically:
  • Ontology collections are based on SHACL or RDFS an OWL vocabularies.
  • Taxonomies are based on SKOS. The SKOS model is located in skos-core.ttl in the TopBraid project.
  • Glossaries, data assets, datatypes, requirements, technical assets, enterprise assets, enumerations an lineage models are based on one of ontologies developed by TopQuadrant and shipped as part of the project. These models are in Turtle files corresponding to the name of the collection type e.g., SHAPES_EDG-technical-assets-v1.0.ttl. They all use a common "core" ontology located in the same project.
  • Corpora is based on the model located in corpus.ttl in the project
Note that reference datasets and data graphs are an exception in that when a user creates collections of these types, they need to select an ontology to base them on. There is no default. 
Users of EDG can extend and configure the ontology models shipped with EDG. The models use SHACL to represent property constraints (e.g., datatypes) as well as to represent general display information such as how property fields are grouped, ordered and described. This information is defined in the ontologies each of the asset collection types is based on. You can extend and customize these ontologies.
Follow the instructions below for implementing customizations in a forward compatible way.

Setting up Customizations as a new Ontology

  • Using TopBraid EDG, create an Ontology for the assets you want to customize, e.g. to customize EDG Core: “EDG Core Customizations”
  • Add Includes: e.g., EDG SHAPES – Core or EDG SHAPES - Data Assets
  • For every asset collection type that is to use these customizations:
    • Edit Default Includes in the Server Administration -> EDG Config Page
    • Add to 'default includes' your new ontology e.g., “EDG Core Customizations". All new asset collections of this type will automatically include all customizations you will create in this new ontology
    • If you already have pre-existing asset collections, include the new ontology to each one

In the screenshot below, we have specified that all glossaries should include customizations we are about to create.


Removing “fields” (properties) from entities and, subsequently, forms

Example: Remove (make unavailable) “acronym” property.

  • Open the Customizations Ontology as its editor
  • Find “Identifiers, Codes and other Designators”

  • Click on the constraint below, then “Edit”:


  • Add “None” to “only applies to”, Save changes. (Internally this creates a sh:filterShape that is always false)

  • “acronym” no longer shows up:


Removing “fields” (properties) from a section in a form and putting them into a different section

  • First remove the old property as described before
  • Next create a new property constraint using the hollow blue button in the upper right corner of the Class Hierarchy:


  • Edit the newly created (empty) constraint
    • Under “group” select the new group
    • Under “order” specify a number (0 is on top)


  • See that acronym has been moved

Hiding form properties based on governance roles

One can selectively hide properties on forms based on a user's governance role. In the ontology containing the form customizations, navigate to the properties that should be hidden (selecting the property itself, not the property shapes mentioning it). Then enter the roles for which the property should be made invisible using "hidden property for role". Anyone with the given governance roles will no longer see (or be able to edit or search for) the selected properties.

Removing an entire section from a form

• A property group will only show up if there is at least one property in it that is NOT marked using “None”
• So: to delete a group, remove all its properties.

Adding new “fields” (properties) to entities and, therefore, forms

• Add a new property to your EDG Core Customizations Ontology
• Then create a property constraint for it
-Set group and order in the constraint

Adding new sections to forms


• Create a new property group in your customization Ontology
• You can create new groups on the fly from the context menu behind the “group” widget in edit mode
• See previous steps to create new properties or move existing ones

Changing EDG controllers

Each asset collection type that is based on ontologies in the project has a controller file located in the same project. In some situations you may want to modify a controller.

Controllers specify information such as:

  • Singular and plural name of the asset collection type e.g. glossary and glossaries
  • Items (tabs) to show on the horizontal navigation menu of a asset collection home page and what appears on each page accessed from the menu
  • The “main entity” for a dataset and what other entities to show in the navigation. This is configurable for an individual asset collection using Manage tab or can be changed for all collections of the type by changing the controller.
  • The “default” imports – graphs that are always included when a new asset collection of this type is created
  • The permitted and required asset collection types, whose instances can be or must be included into a /asset collection of the type controlled by the controller
  • Editor application to use
      • EDG 6.1 ships with a taxonomy editor, ontology editor, content tagset editor, crosswalk editor, dataset editor and a single-form editor applications
      • You can develop your own editor applications using SWP/SWA

If you modify a controller, we recommend that before changing it you back it up. If you have a license for customer defined asset collection types, you can clone the existing controller, modify the base URI and change the clone. You can also create a brand new controller.  You can deactivate the asset collection type a given controller describes in the configuration page of the Server Administration console.

Any new controllers you create should be located in your own TBC project. Optionally, you can specify any new controller as an owl:import in “edgproduct.ui.ttlx”. This is a best practice that documents the customization configuration. It is optional because TopBraid EDG will discover all files in the workspace that have “.ui” in their name at startup time.

Changing the name of the asset collection type

  • Open controller in TBC. You will need to unlock it.
  • Go to Model -> Find locally defined resources
  • Click on the resource of type teamwork:ProjectType e.g., edg:GlossaryProjectType – this is a “controller resource”
  • Change teamwork:pluralLabel and teamwork:singularLabel
  • You should get familiar with the other fields as well. 
    • For example, you can use teamwork:projectTypeWeight to modify the order in which each asset collection type appears in the left hand navigator on the EDG’s home page

Modifying the items (tabs) on the home page of an asset collection type

Controller resource for an asset collection type identifies so-called ‘plugins’ that are to be used for all asset collections of this type:

  • This information is provided in the teamwork:projectPlugin property
  • TopBraid EDG comes with several pre-built plugins. You can develop your own
  • Each plugin belongs to an item (tab)
  • If an asset collection type doesn’t specify any plugins that belong to a particular item (e.g., Reports), then the item will not appear on the home page

A plugin has a type e.g, a type of teamwork:RDFFileImporterPlugin is teamwork:ImportPlugin.  Items are subclasses of teamwork:ProjectTabs class. Each of the subclasses specify what type of plugins should be shown in an item's view. Items are defined in the teamworks.ui.ttlx file in the teamworks project


Post-processing of DDL Imports

The importing of DDL into Data Assets (import DDL file) and Datatypes (import DDL file) provides an extension point that allows developers using TopBraid Composer to add custom post-processing behaviour to the DDL import. This is done by overriding the ui:prototype of the SWP element edg-importer:PostProcessImportedDDL. The arguments provided to the prototype are documented on the SWP element itself.

The TopBraid Teamwork Framework

Getting Started with TTF

This section provides a basic overview of the TopBraid Teamwork Framework (TTF) and its motivation. See also the dynamically generated list of Teamwork SPARQL functions, accessible from TopBraid Composer's Help Menu.

You will need to understand TTF if you want to:

  • Programmatically access change history or working copies
  • Create new vocabulary types for Enterprise Data Governance
  • Make certain modifications to options available for pre-built vocabulary types

Why TTF?

TTF is a development and runtime framework for web-based multi-user read-write applications for different types of data assets or vocabularies.

For example, an application to work with SKOS-based Taxonomies consists of pages to create a new taxonomy, to manage user permissions, to track and review changes, to edit the taxonomy itself, to produce various reports and to run data exports and imports. Many of these capabilities are also applicable to other kinds of vocabularies, not just SKOS taxonomies. The role of TTF is to generalize those capabilities so that it becomes more efficient to develop similar applications in a componentized way.

Overview of TTF

TTF projects consist of two workspace files that connect to a database for data storage. The first database contains the actual data of the "master" graph. The second database, ending with ".tch" contains metadata that is used to keep track of changes, permissions and other vocabulary specific settings. Details of these files and their content are provided by Graphs, Permissions and Change Tracking.

TTF vocabulary and asset types (sometimes called "project types") are the kinds of models that are available to the end user.

Each vocabulary type is defined as a plugin to the teamwork framework. In a nutshell, each vocabulary type is backed by an instance of the class teamwork:ProjectType which is stored in an SWP file and points to the specific editors, plugins and other features that distinguish this vocabulary type from others. If you are interested in adding your own vocabulary types, see section: Vocabulary/Asset (Project) Types. You  can also modify features available for the pre-defined vocabulary types.

EDG home pages list all installed vocabulary/asset types. When a user clicks on the available type, they see a list of all vocabularies/assets of that type. From there, they have access to the available features.

Graphs, Permissions and Change Tracking

A combination of two related graphs, one containing the data and another one containing the change history of the data plus other information, is called a Teamwork project. This should not to be confused with the term Eclipse project. When using EDG, every vocabulary/asset is a Teamwork project. For the purposes of this discussion, Vocabulary/Asset is synonymous with Teamwork project. 

This section introduces the two kinds of RDF graphs involved in a Teamwork project.

Anatomy of a Teamwork project

Each Teamwork project consists of two graphs that have corresponding .sdb connection files in the TopBraid workspace. You can explore those files by opening the files created via EDG within TBC-ME. (When doing this, note that you should not close either of the two .sdb files because this may invalidate the connection with the localhost server).

  • The master graph (e.g. XY.sdb) contains the actual data such as the edited SKOS concepts, also known as a "production copy".
  • The TCH (or team) graph (e.g. XY.tch.sdb) contains metadata about the project, including the change history, available working copies, user permissions and comments.

TopBraid identifies Teamwork projects by their graph URIs: urn:x-evn-master:XY is the master graph for the vocabulary with the short id "XY". Its metadata would be stored in urn:x-evn-master:XY.tch. The teamwork namespace contains SPARQL functions that can be used to derive those URNs from ids and to extract ids from a given URN. These functions are the preferred way of working with those graphs. You can find a complete list of those functions in Appendix: Teamwork SPARQL Functions Reference.

The project id (sometimes called graph id) is the short name of the vocabulary, usually consisting of letters only.


All users with access to the surrounding TopBraid Live server can log into the Teamwork pages. However, who is allowed to do what can be controlled by the system administrator as well as the corresponding vocabulary managers.

Teamwork supports the following three roles per vocabulary:

  • viewer: can only view a vocabulary or working copy, and make comments.
  • editor: same as viewer but also has editing rights to make changes to a vocabulary or working copy. See Working Copies (Tags) for a definition and description of working copies.
  • manager: same as editor but also has administrative control over a vocabulary or working copy, including the permission to grant or deny permissions to other users.

Any user can create a new vocabulary, and will become the initial manager of this project. At any given time, there must be at least one manager per vocabulary. The vocabulary home page can then be used to grant additional permissions to other known users. All of those permissions are stored in the TCH graph. For example if Administrator is the manager of the Teamworks project with the id XY, then the TCH graph will contain the following triple:

<urn:x-evn-master:XY.tch> teamwork:manager <urn:x-tb-users:Administrator>

As shown above, the URIs of the users are always following the same pattern. Use the SPARQL function smf:currentUserName() to access the currently logged in user, and smf:userWithName(?userName) to construct the user URIs as above.

In addition to assigning permission roles to individual users, it is also possible to assign roles to security roles from LDAP or tomcat. The UI provides simple drop down boxes for this. In terms of the internal RDF representation in the TCH graph, an LDAP role is represented with a URI such asurn:x-tb-role:ROLE.

You can get the union of all master graphs that the given user (in the example, : Administrator) has at least read access to by using special named graphs of the pattern urn:x-evn-union<:user>. For example, urn:x-evn-union:Administrator. This can be convenient for global search across multiple graphs. Note that such graphs are strictly read-only.

Change tracking

A change is an atomic unit of modifications to a given graph. They are usually created by the user through buttons and menu items such as the Create Concept buttons in EDG or the Save Changes button of the SWA edit forms. Whenever the user sends such a request to the server, master or working copy graph will be updated and the TCH graph will be updated with a new instance of teamwork:Change. An example Change object is shown below (in Turtle):

	a       teamwork:Change ;
	rdfs:comment "Create Class with URI"^^xsd:string ;
	dct:created "2013-04-03T00:32:05.915Z"^^xsd:dateTime ;
	sioc:has_creator <urn:x-tb-users:Administrator> ;
	[ teamwork:object owl:Class ;
		teamwork:predicate rdf:type ;
		teamwork:subject <>
  	] ;
  	[ teamwork:object "Sub3"^^xsd:string ;
		teamwork:predicate rdfs:label ;
		teamwork:subject <>
  	] ;
  	[ teamwork:object owl:Thing ;
		teamwork:predicate rdfs:subClassOf ;
		teamwork:subject <>
  	] ;
  	teamwork:status teamwork:Committed .

This is a set of changes indicating that the user:

  • Created a new class with the id
  • Set the label of the new class to "Sub3"
  • Made the class a subclass of owl:Thing

A change may also point to a working copy via teamwork:tag if it has been made while the user was editing a working copy. Each added or deleted triple is stored in reified form via teamwork:subjectteamwork:predicate and teamwork:object as shown above. This makes it possible to find all changes for a given resource via a SPARQL query over the TCH graph. Note that teamwork:deleted is used to point at triples that were deleted.

The teamwork:status triple of a change indicates whether the change has been committed to the master copy or whether it only exists in a working copy - in which case the value would be teamwork:Uncommitted.

Working copies (tags)

working copy (internally often called tag) is a specific collection of changes that have been made to the master graph, but have not been saved in the master graph. Since all these changes are stored only in the TCH graphs, the working copy is a virtual construct that is computed on demand only. TopBraid has a mechanism that can temporarily apply a set of changes to an RDF graph (without modifying the underlying graph). All changes that are part of a working copy are associated with the working copy via the property teamwork:tag.

In order to access a specific working copy for a given graph (with id "XY"), and tag "myTag") use a graph URI such as urn:x-evn-tag:XY:myTag:Administrator. In general, although it is possible to create such URIs "manually", the preferred mechanism is through the SPIN function  teamwork:queryGraph  as in the following example:

SELECT ?concept
	BIND (teamwork:queryGraph(true, "XY", "myTag", "Administrator") AS ?graph) .
	GRAPH ?graph {
		?concept a skos:Concept .

Comments and Tasks

EDG forms have a button to add a comment and/or task to the currently selected resource. These items are stored in the TCH graph, as instances of sioc:Post where the sioc:about property points at the resource. You can explore details by looking at the TCH graph.

Vocabulary/Asset Collection (Project) Types

This section explains how developers can add their own types of collections as alternatives to the pre-existing collection types defined for TopBraid EDG, such as SKOS Taxonomies, or Content Tag Sets. All collections of the same type share the same edit application and the same plugins. Note that defining custom collection types is a licensed feature of EDG. To upgrade a license file, please contact TopQuadrant.

Creating a new vocabulary/asset collection (project) type

Each of the default collection types that come with TopBraid EDG are plug-in modules within the more general Teamwork Framework. It is possible to add new modules by creating an instance of the class teamwork:ProjectType in a globally registered SWP file (ending with .ui.*). This file should import the file teamwork.ui.ttlx. The best practice is to create a new Eclipse workspace project and place your file within it. 

Note that while you will be able to develop and test new project types in TopBraid Composer, once you deploy your code to the EDG server, new types of collections will only be available if your solution is licensed for creation of new asset collection types.

Simply create an instance of teamwork:ProjectType and fill in the properties similar to how it's done in the default Ontology application (from ontologyprojects.ui.ttlx). You need to enter values for teamwork:singularLabel and teamwork:pluralLabel. You also need to enter value for the teamwork:vocabularyType. These values must be subclasses of the teamwork:Vocabulary class. For the ontology projects this value is ontologyprojects:Ontology. Under teamwork:Product select the one instance for EDG and add the "yourprojectype":ProjectType to the defaultProjectType property

Once you have filled in the minimum properties for your new ProjectType, make sure that the framework "knows" about your new file by selecting Model > Refresh global SWP graphs.... Then you should already see a new tab for your vocabulary type on theEDGhomepage, on the same level as any other pre-existing vocabulary types such as Ontologies. 

Create-new pages

The section for your new vocabulary/asset collection types on the home page will have a link to create a new vocabulary/asset collection of your type. The framework will use the singular or plural labels that you have specified wherever possible, so the link may be "Create New My Custom Collection" if that's how you have called it. The link will by default go to a default create page where the user can enter label, default namespace and a description of the new asset collection.

If you need additional parameters at creation time, take a look at how this is done in the case of Crosswalks, in crosswalkprojects:CreateProjectPage.

Project plug-ins

As you might know, the main page of any collection's production or working copy contains links to various "utilities" features such as Import/Export, Report, etc. These come from plug-ins. You may want to explore the standard plug-ins shipped as part of the Teamwork Framework, e.g.teamwork:TurtleFileExportPlugin.

In a freshly created teamwork:ProjectType, no plug-in would show up. You need to select those plug-in that you want to expose via the teamwork:projectPlugin property.

There is also a generic SPARQLMotion-based importer mechanism that applies to all vocabulary types. Such importers receive an uploaded file as input and produce triples that shall be added to the current vocabulary or working copy. Open the file teamworkscripts.ttl in TBC-ME and read the supplied comments to learn more about this feature.

Custom icon for project type

To add a custom icon to the project type:

Search the properties pane for edg.v:icon and drag this property onto your new project type resource form, give it a value.


The value for custom icons must start with the string "custom-" or they will be ignored and the default icon (a circle) will be used. Add a style block which defines your custom icon style like seen below. This can live in any external stylesheet. We suggest you create your own "*.www" directory to hold these types of customizations.

#primaryNav .custom-menu-icon {
background-image: url("");

(Ensure that the sytlesheet is loaded in the application pages.)

Extending the Problems and Suggestions Reports

The Problems and Suggestions report feature implements data quality rules for collections (see a collection type's User Guide ...Utilities > Reports > Problems and Suggestions Report for documentation). This feature includes an extension point allowing developers to plug in their own algorithms written in Java or SWP. For an example of SWP-based suggestion generators, in TBC open tosh.ui.ttlx, select tosh:ReportsGenerator and go to Resource > Find usages in workspace. Use a copy of the example(s) as a starting point.


The Teamwork Framework includes a notifications mechanism that can be configured to send notification emails (and other notification) to subscribers. The process to set this up consists of two steps:

  1. Assign organizations, persons, users or user groups to RACI roles using the Metadata tab
  2. Select which notification events shall be triggered for which RACI role

New notification types can be added by creating subclasses of teamwork:Notifications in a .ui. file. There are two ways of triggering notifications:

  • Manually, by calling the SWP element teamwork:sendNotifications
  • By hooking into direct changes against the master graph (subclassing teamwork:MasterEditNotifications) or the TCH graph (subclassingteamwork:TCHEditNotifications). In those cases, an arg:expression needs to be specified to determine whether the notification must be sent for the given set of changes.

The file teamworknotifications.ui.ttlx contains plenty of examples.

In order to have notifications sent to other channels than emails, you need to create a new SWP file with .ui.ttlx ending, and define a subclass ofteamwork:sendNotifications that points at teamwork:sendNotifications via ui:overrides. In the ui:prototype of that subclass, you may repurpose the incoming arguments such as ?text, for example, to call sml:ExportToJMS for output into a JMS bus.


Editors are the SWP applications that are loaded when the user clicks on Edit Production XY or Edit Working Copy. While these editors can in principle be any type of web interface, it is often the easiest to start with the procedure below.

Creating an Editor

The easiest way or creating a new editor is to take an existing editor as a starting point. Use File > New > SWP Application from Template and select from one of the available options. For example, if you want to base your new editor on the ontology editor, select ontologyapp. Then link your teamwork:ProjectType with that editor via the teamwork:projectEditorClass property. A side effect of this procedure is that you can in principle reuse the same editor class for different vocabulary types.

From there on, your copy of the Ontology editor application can be modified by adding, changing or removing gadgets and their surrounding windows. The SWA user guide should provide you enough information to get started with that.

Adding New Tabs for Asset Collections

Developers can add new tabs to the tab-bars of asset collections. These tabs can appear on all or some asset collections. To create a new project tab, create a subclass of teamwork:ProjectTabs and use the following properties to configure that tab:

  • rdfs:label for its title
  • ui:prototype for its content (written in SWP, with the variables ?projectGraph for the current asset collection and ?tag for the current workflow, if any)
  • teamwork:pluginIndex to control its position within the tab bar
  • teamwork:pluginRequiresRole if the plugin should be visible only to users with the teamwork:editor or teamwork:manager role
  • teamwork:validForTags to control whether the tab is accessible while in a workflow (If this is set to true, the tab should also be made subclass of teamwork:TagElements to inherit the ?tag argument.)

To control what asset collections the tab appears on, there are various options:

  • To enable it for selected asset collection types, add it to the respective teamwork:ProjectType instances as a teamwork:projectPlugin.
  • To enable it for all asset collections, set the tab's teamwork:pluginValidExpression to true
  • To enable it for selected asset collections based on an arbitrary condition, set the tab's teamwork:pluginValidExpression to a SPARQL expression that checks for the condition, using the variables ?projectGraph and ?tag.
  • To disable it for selected asset collection types, add it to the the respective teamwork:ProjectType instances as a teamwork:disabledPlugin.

Scheduled Jobs

TopBraid EDG and TBL include a mechanism for running SWP scripts on a schedule.

Example use cases. This can be used in EDG customizations and TBL applications to automate recurring tasks, such as:

  • Checking an external source for updates and importing the new version
  • Pre-computing data for expensive dashboard charts
  • Archiving off old data every night
  • Re-training the AutoClassifier once a week

Limitations. But the mechanism is not intended for some other things:

  • Background tasks triggered immediately after a user action (e.g., long-running imports, inference or validation tasks)
  • Execution intervals shorter than a minute or so (due to the overhead of starting up an SWP engine)
  • Jobs that require recovery or re-tries in case of job failures or server downtime (see section on server restarts and server downtime below)
  • Jobs written in Java

All jobs run with administrator privileges, so it is up to the SWP programmer to implement access control if needed.

Creating a scheduled job through TBCME

  1. Create a new .ui.ttlx file (or use an existing one)
  2. Import
  3. Create a new subclass of scheduler:ScheduledJobs; it will automatically also become an instance of scheduler:ScheduledJob
  4. Add the property scheduler:cronSchedule to specify the schedule; 0 * * * * ? (“every minute”) can be a good value for testing; see further below for syntax
  5. Write SWP code in ui:prototype
  6. TBCME menu: System > Refresh TopBraid system registries
  7. Check TBCME Error Log for any reported errors/warnings
  8. If there are no errors, the job should be active!
  9. If the job is long-running (more than a minute or so), make sure to read the section below on long-running jobs

Deploying a scheduled job to EDG

Simply deploy a project containing the .ui.ttlx files with scheduled jobs to EDG. The jobs should become active immediately. The scheduler logs to the TBS Log.

Reviewing and troubleshooting scheduled jobs

In the TBL Server Administration there is an item “Scheduled Jobs” that opens a page with a table of all scheduler:ScheduledJob instances, with details about the job's status.

  1. If a job is not listed there, then verify that it is indeed an instance of scheduler:ScheduledJob, and that it is part of the UI graph (in a .ui.ttlx file).
  2. Refresh registries to ensure that the scheduler has picked up any changes.
  3. Check the log for any errors or warnings about problems with the job definition.
  4. Check the next execution time in the table to ensure the schedule is correct.
  5. When a job is triggered, its start and completion are logged as an Info message.
  6. If a job aborts with an exception, a Warning with the stack trace will be logged.
  7. While a job is running, its runtime an other details will be shown in the table. This can be used to identify stuck or slow jobs.
  8. Sending debug information to the log from SWP: <ui:log ui:debug="message"/>

Issues with long-running jobs

  • TBCME shutdown and TBL server restarts are blocked while any jobs are executing. The system will wait for all jobs to finish, unless the job is written to be cancelable. Therefore, any jobs that take longer than a minute or so should be written to be cancelable, see below.
  • Job execution uses a thread pool whose size (3) is hardcoded. There cannot be more than this number of jobs executing in parallel. If all threads are busy, job executions are delayed until a thread is free.
  • If a job execution takes longer than the schedule interval (e.g., an hourly job takes two hours), then the next execution will be delayed until the current execution has finished.

Making jobs cancelable and reporting progress with ui:task and ui:subTask

Long-running jobs (longer than a minute or so) should be written using <ui:task> and <ui:subTask> to break the job down into smaller independent chunks. This has two benefits:

  1. It makes the job cancelable. If the system shuts down while the job is being executed, the current ui:task and ui:subTask will finish, but all subsequent tasks and subtasks will be skipped.
  2. It allows reporting of the job's progress. Progress can be checked in a number of ways:
    • On the Scheduled Jobs page in the TBL Server Administration
    • From SWP, using the ui:progressMonitorStatus magic property
    • From JavaScript, with swa.openProgressMonitorDialog

Manually cancelling job execution

As of version 6.0.0 there is no UI for cancelling running jobs, but it can be done manually:

  1. In the table on the Scheduled Jobs page, in the “Currently running?” column, there is a link to the URI that identifies the current job execution. Copy it.
  2. Run the following SPARQL query, with the right job execution URI: (in the TBCME SPARQL pane or TBL SPARQL endpoint form):
SELECT ui:cancelProgress(<urn:x-job-execution:1527863743785>) {}

Server restarts and server downtime

The system cannot guarantee that scheduled jobs are actually executed! In particular:

  • If an exception occurs during job execution, the execution will be aborted. The system will try again at the next scheduled time.
  • If a job execution is in progress when the server is shut down or restarted, the current ui:taskand ui:subTask will finish, but all subsequent tasks and subtasks will be skipped. The system will not try to recover or continue when the server comes back up. It will execute the job again at the next scheduled time.
  • If the scheduler is not running at the scheduled execution time (e.g., because it is in the middle of a server restart), then that execution is skipped completely.

An example job

This is the ui:prototype of a job that simply sleeps 100x for 10 seconds each. It reports its progress to the Scheduled Jobs admin page, and supports cancellation after each ten-second sleep chunk.

    <ui:log ui:info="At start of sleep job"/>
    <ui:task ui:taskName="Sleeping" ui:totalWork="100">
        <ui:forEach ui:resultSet="{#
                SELECT ?i
                WHERE {
                    ?i tops:for ( 1 100 ) .
                } }">
            <ui:subTask ui:subTaskName="chunk {= ?i }" ui:work="1">
                <scheduler:Sleep arg:ms="{= 10000 }"/>
    <ui:log ui:info="At end of sleep job"/>

Expressing schedules with Quartz cron expressions

Cron expressions are a syntax for expressing recurring events. We use the Quartz flavour of cron expressions. The full syntax is described in this tutorial, but the basics are:

sec min hour day month day-of-week [year]

In the simplest case, each position is either a number, or * to indicate “every”. The day-of-weekslot is ? to indicate “whatever the day happens to fall on”. The year slot is absent. Examples:

  • 0 * * * * ? - At the start of every minute
  • 0 15 3 * * ? - 3:15am every night
  • 0 0 12 ? * MON-FRI - Every weekday at noon
  • 0 */10 * * * ? - Every ten minutes
  • 0 0 6,9,12,15,18 * * ? - Every three hours from 6am to 6pm

Search the EDG Customizations

Search the EDG manual configuration has been removed in favor of an automated process. Collections can be included in search upon creation or by selecting this option on the manage tab. Once added all properties are indexed for search as well as applicable facets. Customization of the results page can still be implemented with overrides explained below. The searchconfig.ttl graph will still remain in your workspace which holds the contents of what graphs are searchable, the properties and facets in the config file are now ignored.

Customizations to the number and selection of facets of Search the EDG using TBC-ME

To introduce a custom facet order, you will just need to write a custom SPIN template, and override saf:FacetsListJS to replace the template call to point to this new one.

Here is an example of adding a second rdf:type to the list, and rdfs:label. Changing the filters could, which defaults as 10 can be done here as well.



Overriding Search Results in Search the EDG using TBC-ME

There are several ways to override what is rendered for a search result in Search the EDG. We’ll cover two ways to accomplish such an override using SWP.

Override all search results.

1) Define a new project.
2) Create a new RDF/SWP file.
3) Import saf.ui.ttlx (teamwork/saf/saf.ui.ttlx)
4) Create a new sub-class of ui:ViewElements
5) Set ui:override to saf:SummaryRowItem

edg:SummaryRowItem by default will pass along the rendering responsibility to saf:EDGSummaryRowItem.

By comparison this is what a sample override could look like.

Override a specific class

Perhaps the default layout is sufficient but not enough specific data about a class is visible. To extend result summary for a specific class follow the steps below.

1) Define a new project.
2) Create a new RDF/SWP file (if necessary).
3) Import saf.ui.ttlx (teamwork/saf/saf.ui.ttlx)
4) Import schema definition for the target class.This example uses wgs84_pos.ttl (Topbraid/Common/wgs84_pos.ttl)
5) Find the target class definition (geo:SpatialConcept)
6) Add a new ui:InstanceView
7) The new instance view must have an outer tag that defines a ui:id and ui:priority. The id must be ‘saf-summary’ and the ui:priority must be lower than 10 (the default value is 10).

Default Summary

Overridden geo:SpatialThing Summary

Mixed results: Note only type of geo:SpatialThing is rendered with the new override.

Override both?
Yes, but only if the ui:ViewElement that is overriding swa:SummaryRowItem allows it by including a ui:resourceView that ‘saf-summary’. For example:

The attached file contains the customizations to the results used above.

ui_ext (1).zip

  • No labels