Application Configuration

 

 

Extension Process

 

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 ontology editor. The UI is flexible enough to handle any number of custom classes and 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.

  • Developing custom workflow templates

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. 

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.

 

Common extension tasks

 

 

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 edg.topbraidlive.org/edgproduct.ui.ttlx 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:
<html>
<head>
<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:
</style>
<title>TopBraid Live Login Page</title>
</head>

<body>
<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:

edgproduct.ui.ttlx

<ui:group>
   <section>
       <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>
       </div>
   </section>
</ui:group>

 

4. Save, and refresh the homepage.

5. You should see your changes reflecting

 

Customizing Form Layouts

 

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.

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 specified for a property.

 

 

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).

 

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.

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.

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:

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

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

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.

There are also two types of rules that are executed when working copies are committed. To learn more about them, in TBC , navigate to teamwork:CommitRules and teamwork:PreCommitRules.

The above actions will apply to all workflows.

Actions specific to only certain types of workflows can be specified in a workflow template. EDG supports two types of actions – actions on the entry to a state and actions on the exit from a state. These are specified for a state as values of  teamwork:stateEntryAction and teamwork:stateExitAction.

To understand how state transition actions work, download sample workflow templates and examine them in TBC.

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  

http://topbraid.org/teamworkscripts  (from /teamwork.topbraidlive.org/system/teamworkscripts.ttl).

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: .

Add XML import option for EDG Ontologies

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

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.

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.

Adding a new panel to the editors

Starting with EDG 6.3, the editor has been rewritten using React and a front-end build process. In order to create a user interface extension to the editors you will need to be familar with SWP, RDF, React, WebPack and Babel. We have created a sample guide and sample project that adds a new panel to the editor. Please download the items below to get started.

create-tb-app_guide

create-tb-app

Customizing Columns on the Collection Home Page

In EDG 6.4, you can customize the columns on the Asset Collection Home Page as shown in the image below. Please note that additional data added to the table could slow the performance of this page.

 

Please see the attached guide and code for an example of adding a new column as shown in the image above.

CUSTOM_COLUMNS

sample-asset-collection-table

 

Appendix A: Search Customizations file