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 edg.topbraidlive.org 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 teamworks.topbraidlive.org 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
    • 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 in every asset collection that is to use these customizations:

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 for a Glossary Term.

  • Open the Customizations Ontology 
  • Find Glossary Term class
  • Click on the acronym property on its form, then “Edit”
  • Set deactivated to true

Note that the acronym property is inherited by the Glossary Term from the class called Identifiers, Codes and other Designators. Deactivation, deactivate the property for all subclasses of this class. If you want to keep it for some subclasses, either add it to each of the subclasses or create a new common parent class and add it at the parent class level.

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

  • First deactivate the property as described before
  • Next create a new property constraint for the same property and specify for it a different group

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 their forms

  • In your EDG Core Customizations Ontology, select a class which instances should have a new property
  • Then create a new property for this class
  • Set group and order as necessary

Adding new sections to forms

  • Create a new property group in your customization Ontology
  • You can create new groups by clicking on Create Property Group in the Property Group panel
  • You can also create a group on the fly from the context menu behind the “group” widget on the property shape form
  • 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 edg.topbraidlive.org 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

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

 

  • Set group and order in the constrain