Working with Asset Collections

Creating New Asset Collection

To create a new asset collection such as a Taxonomies collection, use the plus new icon in the EDG application header bar or use the Collections menu to navigate to the asset collection type to create and use the Create New button at the top of the collection type home page.

A System Administrator or any user with editor profile for the Governance Model can also create a new collection by using a Create link in the Governance areas page. This will automatically place a collection into the chosen subject area and assign the user permissions for that subject area. See Operationalizing Data Governance for more information on this feature.

Note

No user will have a link for creating any asset collection until an administrator configures EDG’s persistence technology as documented in Administrator Guide. Additionally, a user will not have the ability to create asset collections unless the user or their role has a Create permission for the EDG Repositories project as documented in Rights Management Admin Page.

The Create dialog box options are as follows:

  • Label: Required.

  • Default namespace: Required for all asset collections except Crosswalks and Content Tagsets where it is not available.

  • Description: Optional.

  • Search the EDG: Optional. Check this option if you want this collection to be included in the globally available “Search the EDG” feature of the application.

  • URI rules: Optional, not applicable to Crosswalks and Content Tagsets. URI construction rules for assets in a collection can be set in the server administration area as described in Product Configuration Parameters Admin Page. These selections override the server-wide settings for the collection. The rules will not apply if an asset type has a primary key as those URIs are based on the value of a primary key property.

The user creating a new asset collection will be assigned with the manager profile over the collection.

TopBraid EDG Create New Glossary

TopBraid EDG Create New Glossary

  • Ontology include: Required and is available only for Data Graphs and Reference Datasets. Used to specify an Ontology that defines data model for a collection.

  • Includes: Required and applicable only for Data Graphs and Reference Datasets. Specifies an Ontologies collection defining the underlying data model for the data collection.

  • Data source: Required and applicable only for Corpora. Selects a connector to use for harvesting documents.

  • From Graph and To Graph: Required and applicable only for Crosswalks. Identifies asset collections that will be connected by the Crosswalk.

  • From Entity Type and To Entity Type: Required and applicable only for Crosswalks and appears when the From Graph and To Graph are selected. Identifies the type of the assets to be connected by the Crosswalk.

  • Also generate property shapes for the match predicate: Optional and applicable only for Crosswalks. Makes the match predicate available on forms and search operations if the predicate is not already covered by a property shape.

  • Content Graph and Tagging Vocabulary: Required and applicable only for Content Tagsets. Identifies an asset collection containing content to be tagged and an asset collection containing tagging vocabulary – a Taxonomies or Ontologies collection.

  • Datatypes Collection to include: Optional and applicable only to Data Assets. Can be selected after creation using Settings, Includes.

For Reference Datasets additional setup is required after creation. Users will need to identify the main entity (class) for the dataset. Main entity is the asset type (i.e. class) for the assets that will be contained in the collection. The main entity must have a primary key property set in the underlying ontology.

For Data Graphs additional setup is required after creation. Users will need to identify the main class which sets the type that will be pre-selected on the Search panel. .

For Content Tagsets the Create page is a two step wizard. After making selections on the first page, users will be asked to make additional selections on the second page where the default property for tags and additional properties for tags are set.

Opening an Existing Asset Collection

Edit or View a Collection

The main ways to open an asset collection and have its content presented in the EDG Editor application are:

  • selecting it from the hamburger menu at the top of all EDG pages,

  • clicking on an asset collection label in any EDG page,

  • clicking on the first tab in the horizontal panel of tabs at the top of the asset collection page (e.g. Taxonomy in a Taxonomies collection),

  • select it after selecting the asset collection type from the Collections menu.

The Editor application may open in the edit mode or view mode depending on the user permissions:

  • The user that creates an asset collection is assigned manager profile for it and, thus, can edit its content.

  • If an asset collection is associated with a governance area, then every user with a governance role for the area will be able to view the collection (at least). If a governance role is set up to have editor or manage profiles, then people with this role will be able to edit collection’s content.

  • Governance roles and direct permissions can also be specified at the asset collection level by users with the manager profile via the Users tab (see Assigning Users to an Asset Collection).

Instead of making changes directly to an asset collection, a Workflows can be started. If a workflow is started, the user starting the workflow is its manager and will always be able to edit content of the asset collection in the context of that workflow.

Edits made directly in an asset collection are visible to all other collections that include it and to any workflows. In contrast, edits made as part of a workflow are only visible within the workflow managed by the workflow until and unless workflow changes are committed to the production copy.

Asset Collection Home

Once an asset collection (e.g. Geography Taxonomy) is in edit mode the horizontal menu bar on top of the page provids access to various operations and configurations applicable to the collection as a whole.

Horizontal Menu Bar of the Editor

Horizontal Menu Bar of the Editor

The name of the first tab varies depending on the type of selected collection (e.g. Taxonomy for a Taxonomies collection or Codes for a Reference Dataset collection or Mappings for a Crosswalk). That tab starts edit mode for the collection.

The other tab names are uniform across all collection types, however, the visible tabs may vary. For example, only users with Manager permissions for a collection will see the Manage tab.

The following screenshot shows edit mode when a concept in a Taxonomies collection is selected.

TopBraid EDG Taxonomy Page

TopBraid EDG Taxonomy Page

The label of an asset collection (e.g., Geography Taxonomy) is editable depending on user permissions on the collection.

Return to the Working with Asset Collections section of the user guide to find explanations of the functions available under each tab in the horizontal menu. In most cases the features are the same across collection types, providing a consistent user experience. Exceptions are also explained in the related documentation Guidance Specific to an Asset Collection Type.

The Manage Tab

The Manage Tab is home to various functions and features needed to manage Asset Collections.The manage tab categorizes features into common areas of functionality. Not all asset collections will have the same categories or features, for example in the image below observe the category Ontology Specific, which contains features that are only available to ontologies.

Note

The manage tab is only visible to uses that have the manager role for a particular asset collection.

TopBraid EDG Manage Tab

TopBraid EDG Manage Tab

Having trouble finding a manage feature? Use the search feature to find exactly what you need.

Note

The search can match on any text that is visible to the user.

TopBraid EDG Manage Tab Search

TopBraid EDG Manage Tab Search

Cloning and Versioning an Asset Collection

Create a Cloned Version

Create a Cloned Version is available under the Manage tab. It creates a clone of the current asset collection. The clone is created with the same content and user permission settings as the original asset collection. However, neither the change history, saved SPARQL queries, saved searches, workflows, comments or tasks will be cloned.

Cloning is often used to “fork off” a version of an asset collection, so that it can be referenced and imported separately from the current version. For example, a user might start with an asset collection called People and, upon reaching a milestone, create a clone and call the clone People 1.0.. Then, another asset collection that should only use terms from version 1.0 could change its includes to reference the clone, while ongoing work towards version 2.0 continues on the main People asset collection.

Note

The EDG Basket also offers Clone operation.

Asset Collection Versioning

Multiple asset collections can be cloned and versioned together in one step, including their “includes”. To do this, place collections to clone into the basket and select the check box for the ones to be cloned. Use the operations menu to select Create a new version.

TopBraid EDG Basket with Asset Collection

TopBraid EDG Basket with Asset Collection

This starts the versioning process and prompts for the following choices:

  • Clone Includes: Optional. If checked, the process will also create a new version for any directly included collections. If not checked, the new version will include the same includes as the original collection. Note that this feature is intended for the simple single-level includes case. If the included collection contains further includes, they are not handled automatically.

  • Version: Required. The version stored in the metadata about the collection.

  • Keep Subject Areas: Optional. If checked existing subject area settings will be retained for the new version of the collection.

  • Name: Required. The name of the new version of the collection. The new name for each “include” is also required.

The figure below shows a taxonomy that includes an ontology where the process will create a clone of both the taxonomy and the ontology and where the Subject Area settings will be retained.

TopBraid EDG Batch Create a New Version Form

TopBraid EDG Batch Create a New Version Form

Once the names and other options are set, select Continue. The following figure shows a screenshot indicating success and shows links to the new collections.

TopBraid EDG Successful Batch Creation of New Version

TopBraid EDG Successful Batch Creation of New Version

The new version number is set in the metadata for the collection.

TopBraid EDG Metadata Overview and Status

TopBraid EDG Metadata Overview and Status

Note that this process does not automatically change the External Graph URI under the Settings tab if that is in use. That URI is sometimes used as part of managing versions of collections outside of EDG.

Deleting or Clearing an Asset Collection

Delete

Delete is available under the Manage tab. Delete removes the asset collection. When selected a message to confirm the deletion appears and clicking OK deletes the asset collection including any workflows and history data. If the collection is included by another collection it cannot be deleted and and error is reported showing the including collections.

Note

Use caution as this action is not recoverable without resorting to restore from backup.

Clear

Clear is available under the Manage tab. Clear removes all content in the asset collection, including its history, workflows, comments, and tasks. The empty collection itself, its includes and its user permission settings are preserved. This feature can be used prior to import, for example, when replacing the collection content with an externally generated version.

Note

Use caution as this action is not recoverable without resorting to restore from backup.

Assigning Users to an Asset Collection

The Users tab lists current permissions and roles for the asset collection or workflow. For details on how permissions and roles work in TopBraid EDG, please see the Access Control documentation.

Users with at least manager profile use this page to modify roles and permissions, while it is read-only for other users.

Collection Permissions

For any asset collection and a workflow, access to its basic viewing, editing, and utility functions is controlled by the three nested permission profiles: viewer, editor, and manager (where each profile is a superset of the preceding one). On each collection, these permissions are set for various users, either as individuals or as security roles (e.g., from SSO).

Collection Permissions section list the three permission profiles and, for each, users that have it. A blank setting indicates that no users have this profiles.

In a context of a production copy of an asset collection, permissions can be set for any user. In a context of a workflow permissions can be set only for users that already have (at least) a viewers privileges for the production copy.

A given user can have permission profiles for the collection itself (production copy) that differ from a profile for one of its workflows. Similarly, they could have different permissions in the context of different workflows.

For example, if Jane has manager profile for an asset collection, she can give John viewer profile for it and editor profile for one of its workflow copies. John can then make changes in the context of a workflow.

A user that has any governance role for a collection is automatically granted viewer privileges for the collection and any of its workflows. Users can also be designated as managers or editors through their governance role.

See also

For more information see the Operationalizing Data Governance section of the documentation.

A user with multiple permission profiles on a given collection or workflow receives the greatest level assigned.

Collection Governance Roles

This section lists governance roles assigned either directly for this collection or indirectly through a governance area it belongs to.

Users with manager profile can use this page to assign governance roles to other users: as individuals, as security roles (e.g., from SSO), or as organizations.

See also

For details on governance roles, see Governance Areas (and Roles).

Changing Asset Collection Metadata

When a collection is in edit mode, clicking on the Home button in the header bar or the title of the collection in the header bar will display information about the collection itself. Edit the information about the collection itself, its subject area or version data for example, using the same Editor application as for other assets.

TopBraid EDG Geography Taxonomy Page

TopBraid EDG Geography Taxonomy Page

In addition to the Metadata view, Ontologies collections (see Working with Ontologies) have a drop down to switch to the GraphQL Schema view.

TopBraid EDG Ontologies Dropdown Views

TopBraid EDG Ontologies Dropdown Views

Use that view to set information used by EDG to generate a GraphQL schema that drives the EDG user interface if using the Data Graphs collection type, for example. In the following figure, three classes from the Geography Ontology are set to be public classes for the ontology.

TopBraid EDG Ontologies GraphQL Schema Settings

TopBraid EDG Ontologies GraphQL Schema Settings

Bookmarking Asset Collections and Assets

Basket

Each user can maintain a personal list of “bookmarked” asset collections or individual assets in a Basket. The Basket is available in the header bar and in addition to quick reference, allows for individual or batch operations on collections. Those operations are to create new versions of collections or export files in .ttl or .trig format to Amazon S3 buckets for external use.

TopBraid EDG Basket View

TopBraid EDG Basket View

To add a collection, open the collection and select the star icon in the collection’s header. Re-selecting the star icon in the collection’s header will remove it. When viewing the Basket, collections can be removed individually or as a group using the drop-down Remove element.

Star Icon to Add or Remove Collection

Star Icon to Add or Remove Collection

To add an asset, select it in the editor and then in the asset editing form for the asset select available actions for this (Available actions for this) > Add to Basket.

Importing Data into an Asset Collection

TopBraid EDG lets users load metadata and data from external sources such as spreadsheets, RDBMSs, DDL files, JSON, RDF files, XML, RSS feeds, SPARQL endpoints and other formats – with flexible mapping to EDG models. Pre-built import options are available under the Import tab for an asset collection or a workflow (working) copy of an asset collection. The Import tab is visible only for users with at least Editor privilege. The available importers vary depending on the collection type. Users may not see exactly the same importers because:

  • Additional importers may be configured by an organization using Import modules that are part of TopBraid EDG’s platform. In that case, the importer is listed as one of the available options alongside the pre-built importers.

  • Some or all of the pre-built importers may also be deactivated by an organization. Deactivation can be done a per collection basis using Configure Features under the Manage tab. In that case, fewer importers will be visible than described here.

In addition to being available under the Import tab, all importers can be executed as services. Dynamic imports from Linked Data sources, including the refreshing of previously loaded values, are executed using options available under the Transform tab. Importers described here are effectively “pull” operations where EDG is pulling data through various mechanisms and connectors.

tip_icon Using GraphQL and SPARQL endpoints to push data into EDG

EDG is an open solution and a powerful capability is for external systems to push data to EDG. This can be done by updating EDG through its GraphQL and SPARQL Endpoints.

Importing Spreadsheets

Import Spreadsheet using Template

Import Spreadsheet using Template is available under the Import tab for all collection types except Crosswalks, Content Tagsets and Corpora.

This importer lets the user select a spreadsheet and a “template” that will be used to convert and store the spreadsheet data. The “template” is created using the mapping process explained in the Import Spreadsheet using Pattern importer. The imported spreadsheet must have exactly the same structure as the spreadsheet used to develop the template. The names and order of the columns must be exactly the same. If multiple worksheets are used, the order and structure of each worksheet (even for worksheets that are not imported) must be the same.

The mapping can also be created or edited using TopBraid Composer if the mapping capabilities are insufficient and a more complex transformations is required (e.g. concatenation of values). TopBraid Composer’s SPINMAP tool provides a drag-and-drop interface that makes it especially easy to create more complex mappings.

Templates developed with TopBraid Composer must be stored in files with “.tablemap.” in their name (for example, myMapping.tablemap.ttl) and be uploaded to the EDG server to be available to EDG users.

Import Spreadsheet using Pattern

Import Spreadsheet using Pattern is available under the Import tab for all collection types except Crosswalks, Content Tagsets and Corpora.

To use this importer, the worksheet must have a header row with the names of columns. EDG will find the first row with data and will assume that it is the header column.

The Import > Import Spreadsheet Using Pattern link shows the following screen:

TopBraid EDG Import Spreadsheet using Pattern

TopBraid EDG Import Spreadsheet using Pattern

Use Browse to select the spreadsheet file to import. Supported file types are an Excel file (.xls or .xlsx), a tab-separated value (.tsv) file, or a comma-separated value (.csv) file. The file should have the expected extension.

Because an Excel file may have more than one sheet of data, there is an option to specify a sheet index value to identify which sheet to import. The default is 1, for the first sheet. The sheet index counts all sheets in an Excel workbook, including hidden ones. For example, if you enter a 3 here and EDG seems to import the second sheet, there may be a hidden one between the first and second sheet that made the third one look like it was the second one when Excel was displaying the workbook. The Excel online help explains how to check for the existence of hidden sheets.

The Entity type for the imported data identifies the class of the assets you will be importing. Each row in the spreadsheet will be imported as an instance of the selected class and the spreadsheet columns can be mapped to the declared properties of the class. Select Next to continue and specify the mapping.

Note

All imported assets are given the same type. To import assets of a different type, either import the same spreadsheet multiple times, with different mappings, or bulk edit the data after import.

Select Spreadsheet Type

The Select Spreadsheet Type view enumerates five possible (column-wise) spreadsheet layout patterns, showing an example of each pattern.

The 1. No Hierarchy layout is the most common and simplest to use. We recommend users become familiar with it first, before using other patterns.

Note

The No Hierarchy import pattern can create relationships in the imported data, including hierarchical relationships. However, referenced asset must exist prior to the import when using with this pattern. In the mapping, the column used to find existing assets to reference (e.g. hierarchical parents) can be indicated. This can be addressed, for example, by importing the same spreadsheet multiple times using different mappings - perhaps once to create assets and then again to add relationships between assets.

For data explicitly structured as a hierarchy, like a taxonomy, there are four layouts from which to select. The main difference between these four layouts and No Hierarchy is that children and parents can be imported and connected in a single import. EDG will create and relate both the children and their parents in the same import, even if they did not exist prior to the import.

In the hierarchical layouts, each row also indicates its hierarchical path, either explicitly (absolute path, #2, #3, #4) or implicitly (recursive path #5); note that lighter text in the layout patterns indicates optional data. These are complex import patterns that behave differently depending on the URI construction method set for the asset collection. Depending on the URI construction method for the collection, they may not be able to be used.

TopBraid EDG Select Spreadsheet Type Page

TopBraid EDG Select Spreadsheet Type Page

Note

Note the header row of column labels in every layout. The imported spreadsheet must always have a header row.

Below the five layout options, the view will show a sample of the spreadsheet’s actual data. The following image shows a spreadsheet of airport codes.

TopBraid EDG Source Spreadsheet Page

TopBraid EDG Source Spreadsheet Page

Select the layout link that most closely corresponds to the structure of the spreadsheet.

Import No Hierarchy Spreadsheet

After selecting 1. No Hierarchy the Import Spreadsheet page appears where the user defines the data-mapping rules from the spreadsheet columns into the target properties of the class.

The page is broken into sections:

  • Column Mappings

  • Default Concept Scheme, if a Taxonomies collections

  • Unique Identifiers

  • various selectable options

  • prompt to enter the mapping template name if saving the pattern for future use

  • Your Source Spreadsheet, data read from the spreadsheet

When importing into a Taxonomies collection and not selecting a concept scheme, EDG creates a new scheme using the name of a spreadsheet. All concepts that do not have a broader parent nor are defined as top concepts of some scheme, will be made into top concepts of the selected or automatically created scheme.

Column Mapping Section

In the Column Mapping section, the user specifies the target property to which each spreadsheet column corresponds. The target properties are taken from target entity type (class or asset type) identified on the previous page. When column names and property names are similar, EDG automatically proposes the mapping. When mapping a relationship, the user can indicate inverse relationships to the target entities.

Unmapped columns and their data are ignored during the import.

The following example shows an example Column Mapping.

TopBraid EDG Import Spreadsheet Page

TopBraid EDG Import Spreadsheet Page

For the mapping to be successful, the datatype of the spreadsheet cell values should match that of the target property into which the column is being mapped. Do not use the string “abc” in a cell value being mapped into an target property with an integer datatype, for example.

In cases where a string-valued target property supports language tags, the user is can optionally set the Language value for the import to set.

If an imported row will result in a new instance, rather than adding data to an existing instance, then one of columns should be mapped to the label property or th preferred label if a Taxonomies collection. Those are used as the EDG display name, for auto-complete, etc.

When importing relationships EDG needs to find the existing asset to which to add a reference. If the asset does not yet exist, EDG may be able to create a URI as the value of the reference.

After selecting a relationship property from the dropdown, the following methods for directing EDG on how to build relationship values are possible:

  1. If the selected class has a designated Setting a Primary Key for a Class, no additional information is needed. EDG uses the value in each row of the mapped column to form the URI of the new instance according to the primary key definition. This option is demonstrated in the above screenshot – airport country is a relationship from airports to countries and the ontology defines a primary key for the class Country.

  • Therefore, the values in the mapped column must the exact value of the property used as the primary key meaning it must be unique for all instances of the class.

  • In the example, the Country primary key values are 2 character country codes and the Country Code column with those values is mapped to the “airport country” relationship.

  • Note that in this case, imported rows will always construct a reference with that URI structure regardless of whether it exists in the collection or not.

  1. If the values in the mapped column are actually valid URLs, then they can be used “as-is” to be the URI of the referenced asset, as indicated by the associated Use values as URIs label.

  2. If neither option 1 nor option 2 apply, the user selects a property of the related class on which to to match. The property will be used to find assets at the end of the relationship and will only create the relationship if the asset already exists in the collection.

  • For example, if Country did not have a defined primary key, the user could map the Country Code column and select “ISO 3166-2 alphabetic country code” as the property to match.

  • Values of the matching property must be unique across all instances of the class. If duplicate values are found, then the related resource will be assigned arbitrarily.

Option 3 is demonstrated in the screenshot below – after removing the primary key from the class Country.

TopBraid EDG Import Spreadsheet - Country Code Mapping

TopBraid EDG Import Spreadsheet - Country Code Mapping

For inverse relationships, the spreadsheet column represents links from instances of some other class to the instances the import creates. Similar to forward relationships, if an inverse relationship is the chosen mapping, then there is a further choice of which referencing-class property to use to identify the referencing instances.

Note

  • As explained under Other Parameters below, if the target of a relationship has the same entity type as the entity type chosen for the import AND Option 3 is being used then the Override existing values option must be unchecked for the relationship to be created.

  • When importing into a Reference Datasets collection, one of spreadsheet columns must map to the primary-key property of the main entity (class) for the dataset. For example, the screen image above identifies this field as the IATA code.

  • When importing into a Taxonomies collection, the user can select a concept scheme to contain the imported concepts. Otherwise, EDG will create a new concept scheme and make all concepts that have no parents in the spreadsheet its top concepts.

Unique Identifiers

This section explains the logic EDG uses to generate URIs for the imported data.

If the import target class has a Setting a Primary Key for a Class, no selections are required . Instead, use the Column Mapping section to map one of the spreadsheet columns to the primary key property. Otherwise, some selections are required.

The available selections depend on the URI Construction Rules configured for the asset collection.

If the URI Construct Method is label, specify the column(s) to be used to generate the URI of each imported row as shown below.

TopBraid EDG Unique Identifiers Based on Labels

TopBraid EDG Unique Identifiers Based on Labels

Typically, the spreadsheet column containing the label value will map to the Id column #1, leaving the rest of mappings empty. However, it is possible to select a different column to generate URIs or even a combination of columns. When multiple columns are selected, their values are concatenated to form the URI.

The Start of URIs option is also available to modify the default namespace of the collection to be used as the basis of the generated URI for the import.

For a successful import adding new information to existing assets, make URI choices that will match the URIs of those assets.

If the URI Construct Method of the asset collection is either the counter or uuid, a different set of options are needed, as shown in the following figure.

TopBraid EDG Unique Identifiers Based on Counter or UUID

TopBraid EDG Unique Identifiers Based on Counter or UUID

If the import is creating new instances, leave the selection empty and EDG will generate URIs according to the currently configured URI Construction Method for the collection, using the default namespace for the URIs.

If the import is adding information to existing assets:

  • use a spreadsheet containing a column with values that are the URIs of existing assets and select that column as the URI column;

  • match on a property to find the existing assets. Values of this property must be unique for the entity type. If duplicate values are found, assignments will happen arbitrarily.

Other Parameters

Other parameters are located directly below the Unique Identifiers section.

Selecting Overwrite existing values will delete an existing value for a mapped property before adding its new (different) value; otherwise, new values will be added to existing ones.

If the imported rows are adding new data values to existing instances and/or adding new instances, it is best to make sure that the Override existing values option is unchecked. Checking this option has the following consequences:

  • If an instance already exists and has a value for any of the mapped columns, the value will be replaced with the spreadsheet data.

  • Relationships between instances of the same type that rely on matching of values will not be created (because these values may be overridden as part of the processing).

  • When working with a Taxonomies collection, a combination of checked Override existing values and the No Hierarchy pattern will always make imported instances top concepts of a new Concept Scheme, even if they already exist in the Taxonomy and have parent concepts.

Selecting Record each new triple in change history (warning: not recommended for large files) prevents EDG from recording the addition of each new triple in the change history.

Note

This option will not let you build relationships to assets that are members of the same class as the one you are importing – because these values can be replaced as part of the import.

A Preview button on the Import Spreadsheet form shows the RDF triples that would be generated with the currently configured settings. The browser’s Back button returns to the form.

Make this a reusable mapping template is optional and saves all of the settings on this form for later reuse. Reusable mappings are selectable using Import Spreadsheet using Template on the Import tab instead of Import Spreadsheet using Pattern. When used, a drop-down list of the saved template names appears for selection.

When satisfied with the sample data shown on the preview, click the Finish button. EDG will start the import, running it in the background.

Import Using Hierarchical Spreadsheet Patterns

After selecting one of the hierarchical patterns, there are three sections:

  • Column Mappings

  • Hierarchy

  • Unique Identifiers

and, as on the previous page, for convenience an example of the source spreadsheet data is shown.

There are also URI column selections below the Unique Identifiers section, unless the URI Construct Method is counter or uuid, where no option to specify columns to use as URIs appears. EDG will always generate the URIs following the chosen method.

When the asset collection uses the counter or uuid methods, these importers CANNOT be used to overwrite existing hierarchies – they can only create new assets:

  • If the need is to add information to the previously imported hierarchies, use No Hierarchy import.

  • If the need is to add a child tree consisting of new resources to an existing hierarchy, these importers can be used. However, the top of the new tree will not be connected to an already existing parent, that connection must be added after the import.

Most of the options on the hierarchical import pages are the same as those described for the No Hierarchy pattern. Those are not described here again and this section of the guide focuses on the unique aspects of the hierarchy mapping.

For all the hierarchical patterns, select a Hierarchy Property (e.g. “has broader”) to connect items in the hierarchy.

Note

  • All hierarchical levels will be connected using the same relationship.

  • To create different relationships between levels, use the No Hierarchy pattern.

The Generate in inverse direction checkbox will reverse the direction of how the property specified in Hierarchy property is applied.

When working with Taxonomies collections, there is an option to select an existing Concept Scheme. If not specified, the importer creates a new concept scheme using the name of a spreadsheet. All concepts that do not have hierarchical parents will be made top concepts of the scheme.

Path with Separator Pattern

This pattern works ONLY if the URI Construct Method is label.

For Path with Separator spreadsheets, in which a spreadsheet entry such as “World > Europe > France” indicates the hierarchical structure above the term “France”, the Hierarchy mapping section works as follows:

  • Select a column containing the path and type a separator e.g., “>”.

  • Identify the Column containing the last node of each path string

  • In the Column Mapping section, to generate a name for imported resources, make sure to assign some column as the preferred label (in case of Taxonomies) or as the label (for all other asset collections) – to generate labels. This will typically be the same column as the one you selected in the Hierarchy section as containing a last node of the path.

  • Map this column again in the Unique Identifiers section. If not specified, EDG will use row numbers to generate URIs. Alternatively, use other column(s) to generate URIs.

Column-based Tree Pattern

When using this pattern and when URI Construct Method is counter or uuid, the spreadsheet needs a single column containing the label for each asset. When URI Construct Method is label, there is not need for such a column, EDG will assume that the hierarchy columns contain the labels.

For Column-based Trees spreadsheets, the Hierarchy mapping section works as follows:

  • Specify the top and bottom levels of the hierarchy by picking the first and last columns containing hierarchical levels. All hierarchical columns must be located together and sequentially in the spreadsheet.

  • If a column is mapped in the Hierarchy section, DO NOT map it in the Column Mapping section nor the Unique Identifiers section. These sections are used ONLY for mapping columns that do not specify the column based tree.

  • If the URI Construction Method is label, EDG will assume that the hierarchy columns contain labels of respective resources. If not label then, as mentioned above, a separate column (outside of the hierarchy) needs to contains the label for each resource

  • If the URI Construction Method is label, leave the Unique Identifiers section empty and EDG will use values in the hierarchical columns to generate URIs. Only make mappings in this section to override the Label-based approach and use some other values for the URIs.

  • Carefully examine the Column-based Trees sample layout on the Select Spreadsheet Type screen. It is important that each item in the hierarchy has a row of its own. See below for correct and incorrect options.

Column-based Tree Pattern Examples

Column-based Tree Pattern Examples

It is important to remember that, as with all spreadsheet import options, all resources will be imported as members of the same class as selected as the start of the import mapping definition. An import cannot support Level 3 representing countries and Level 2 representing continents.

Path with Fixed-length Segments Pattern

This pattern requires a path column, where values are such that removing a string of a fixed length from a value identifies a parent for a resource on that row. For example, if using 2 character segments and “Australia” has a path column value of “010201”, its parent would be on a row with a path column value “0102” and its parent’s parent would be on a row with path column value “01”.

EDG finds a parent by removing the exact number of characters specified in the segment length from the child’s path column value. The top most items could have a path column value that is different from the segment length e.g., 1 instead of 01.

For Path with fixed-length Segments spreadsheets, the Hierarchy mapping section works as follows:

  • Specify the column with the path values.

  • Specify the length of the segments to use to calculate the parent row.

  • In the Column Mapping section, to generate a name for imported resources, make sure to assign some column as the preferred label (in case of Taxonomies) or as the label (for all other asset collections). Otherwise, labels will not be generated.

  • If the URI Construction Method is label, map the same column again in the Unique Identifiers section. If not specified, EDG will use row numbers to generate URIs. Alternatively, use other column(s) to generate URIs.

Self-join Pattern

For spreadsheets following the Self-Join pattern, the Hierarchy mapping section works as follows:

  • Specify the Column containing the parent ids – this column will not necessarily be used to generate URI, it is simply a way to match children and parents

  • Specify the Column containing the child ids – this column will not necessarily be used to generate URI, it is simply a way to match children and parents

  • In the Column Mapping section, to generate a name for imported resources, make sure to assign some column as the preferred label (in case of Taxonomies) or as the label (for all other asset collections). Otherwise, labels will not be generated. Typically, but not necessarily, this will be the column you used as a Column containing the child ids.

  • If the URI Construction Method is label, map the same column again in the Unique Identifiers section. If not specified, EDG will use row numbers to generate URIs. Alternatively, use other column(s) to generate URIs.

Import Data Set from Spreadsheet

Import Data Set from Spreadsheet is available under the Import tab and is available only for Data Assets collections.

It reads the input spreadsheet and creates an EDG Spreadsheets Workbook instance, and a Spreadsheet DataSet instance that is part of the workbook and with related DataSet Element instances for each spreadsheet column. The import also includes data profiling for each imported column as shown in the following figure.

TopBraid EDG Data Profile Page

TopBraid EDG Data Profile Page

TopBraid EDG Frequencies Page

TopBraid EDG Frequencies Page

Import Crosswalk from Spreadsheet

Import Crosswalk from Spreadsheet is available under the Import tab and is available only for Crosswalk asset collections.

The input spreadsheet must contain two columns:

  • the first column must contain the primary key used to build URIs of resources in the From asset collection;

  • the second column must contain primary key used to build URIs of resources in the To asset collection.

Import Property Definitions (Schema) from a Spreadsheet

A spreadsheet can be used to to create property definitions for a class in an Ontologies collection. For information on how to do this, see the guide on Creating Property Shapes from Spreadsheet Columns.

Import DDL File

The DDL import service can be accessed from the Import Tab of Data Assets and Datatypes collections. It reads SQL Data Definition Language (DDL) statements (CREATE TABLE statements, etc.) from a text file and creates the corresponding entities in EDG.

When importing into a Data Assets collection, the following entities from the DDL file are created:

  • At least one Physical Data Model and its corresponding Relational Database

  • Relational Databases contain Database Schemas

  • Database Schemas contain Database Tables and Database Views

  • Database Tables contain Database Columns, Unique Constraints, and Foreign Keys

  • Database Views contain Database Columns

  • Database Columns specify various properties, including their Physical Datatypes and whether they are part of the table’s primary key

  • Unique Constraints specify the column(s) within a table that must contain unique values

  • Foreign Keys specify the column(s) within a table that reference the primary key or unique column(s) in another or the same table

  • Physical Datatypes define the various database datatypes

To perform a DDL import, arguments for the following parameters can be specified:

Input file: Select the text file containing the SQL DDL to be parsed and converted into Data Asset entities.

Default database name: Any entity (e.g. a TABLE) within the uploaded SQL DDL file that does not specify a database identifier will be assigned the value specified in this field. If no default database name is specified, the base name of the uploaded file will be used (e.g. NORTHWIND for northwind.sql). The database identifier is the first node of a typical 3-node, fully-qualified entity name (e.g. DATABASE.SCHEMA.TABLE).

Default schema name: Any entity (e.g. a TABLE) within the uploaded SQL DDL file that does not specify a schema identifier will be assigned the value specified in this field. If no default schema name is specified, a schema will not be added. The schema identifier is the second node of a typical 3-node, fully-qualified entity name (e.g. DATABASE.SCHEMA.TABLE).

Database Type: Select the database-specific dialect of the uploaded SQL DDL file.

Model for Datatype Definitions: The DDL import will associate each table (or view) column with the Physical Datatype corresponding to the column’s declared datatype. The import will create new datatypes for any types not previously defined. This model specifies where the DDL import is to look for pre-existing datatypes and where to add any new datatypes encountered. The options are:

  • Any EDG Datatypes collection included by the Data Assets collection (via Settings > Includes).

  • The Data Assets collection itself.

For imported datatypes, the recommended practice is to store the datatypes in a separate EDG Datatypes collection rather than in the Data Assets collection itself.

Record each new triple in change history: If this checkbox is enabled, the DDL import will create a change history record for each new triple created as a result of the import. Enabling this checkbox is not recommended for DDL scripts that define a large number of the database entities listed above.

SQL Compatibility

The DDL import service supports SQL DDL dialects for

  • Apache Hive

  • MariaDB

  • Microsoft SQL Server

  • MySQL

  • Oracle

  • PostgreSQL

  • SAP HANA

  • Snowflake

  • Teradata

The DDL import service supports only the incremental creation of various database entities via the following statements and clauses:

  • CREATE TABLE

    • Column definitions

      • Datatype

      • Length

      • Precision

      • Scale

      • Unsigned

      • Comment

      • Constraints

        • NOT NULL

        • PRIMARY KEY

        • DISTINCT/UNIQUE

        • FOREIGN KEY/REFERENCES

        • AUTO_INCREMENT

    • Constraints

      • PRIMARY KEY

      • DISTINCT/UNIQUE

      • FOREIGN KEY/REFERENCES

  • CREATE VIEW

    • Column names

  • ALTER TABLE

    • MODIFY COLUMN

      • Constraints (see Column Definitions - Constraints, above)

    • ADD CONSTRAINT

      • Constraints (see CREATE TABLE - Constraints, above)

  • COMMENT ON

All other SQL statements and clauses in the file are ignored.

Typical Problems

  • SQL statements cannot be parsed: When an uploaded file cannot be parsed, the import is aborted and nothing will be imported. An error message will indicate the location in the file where the parse error occurred. It may be possible to manually edit the SQL file to remove the problematic text.

  • SQL statements only partially understood: In some cases, the import service will be able to understand the basic intent of a DDL statement but not a specific clause or argument in the statement. In this case, the processing will continue and import whatever was understood. Therefore, imported data should be carefully reviewed to verify that all needed information has been imported.

Import From JDBC Connection

The JDBC import service can be accessed from the Import Tab of Data Assets and Datatypes collections. It connects to a live RDBMS server and uses the JDBC interface to gather metadata from the database.

To use the JDBC import service, the appropriate JDBC driver for the source RDBMS must be installed. See Installing JDBC Drivers.

When importing into a Data Assets collection, the following objects from the database metadata are created:

  • At least one Physical Data Model and its corresponding Relational Database

  • Relational Databases contain Database Schemas

  • Database Schemas contain Database Tables and Database Views

  • Database Tables contain Database Columns, Unique Constraints, and Foreign Keys

  • Database Views contain Database Columns

  • Database Columns specify various properties, including their Physical Datatypes and whether they are part of the table’s primary key

  • Unique Constraints specify the column(s) within a table that must contain unique values

  • Foreign Keys specify the column(s) within a table that reference the primary key or unique column(s) in another or the same table

  • Physical Datatypes define the various database datatypes

To perform a JDBC import, arguments for the following parameters can be specified:

Name: Unique name assigned to the import job.

JDBC URL: URL used by EDG to connect to the database server. The format and content of the URL is database platform-specific; for example, the URL for a MySQL connection will look something like this: jdbc:mysql://localhost:3306/mydb123.

User Name: A database login with access to the requested tables.

Password: Password for the User Name specified above.

Note

If the password is already in secure storage, it may be omitted.

Catalog pattern: An optional JDBC-style catalog pattern used to fetch table metadata from the database. The pattern supports wildcards. The _ character represents any single character; while the % character represents any sequence of zero or more characters.

Schema pattern: An optional JDBC-style schema pattern used to fetch table metadata from the database. The pattern supports wildcards. The _ character represents any single character; while the % character represents any sequence of zero or more characters.

Table pattern: An optional JDBC-style table pattern used to fetch table metadata from the database. The pattern supports wildcards. The _ character represents any single character; while the % character represents any sequence of zero or more characters.

Default database name: Any object (e.g. a table or foreign key) returned by the database that does not have a JDBC catalog will be assigned the value specified in this field. If no default database name is specified, a system-generated database name will be used.

Default schema name: Any object (e.g. a table or foreign key) returned by the database that does not have a JDBC schema will be assigned the value specified in this field. If no default schema name is specified, a schema will not be added.

Model for Datatype Definitions: The JDBC import will associate each table (or view) column with the Physical Datatype corresponding to the column’s declared datatype. The import will create new datatypes for any types not previously defined. This model specifies where the JDBC import is to look for pre-existing datatypes and where to add any new datatypes encountered. The options are:

  • Any EDG Datatypes collection included by the Data Assets collection (via Settings > Includes).

  • The Data Assets collection itself.

For imported datatypes, the recommended practice is to store the datatypes in a separate EDG Datatypes collection rather than in the Data Assets collection itself.

Include data statistics: If enabled, the JDBC import will gather and compute statistics summarizing the data contained in each imported database table, view, and column.

Include data samples: If enabled, the JDBC import will collect sample rows from each imported database table and view.

Note

This option is visible only if the system-wide Allow JDBC Sample Data flag is enabled (see Advanced Parameters Section).

Maximum number of data samples per table: When including data samples, the upper limit of sample rows to collect from each table or view.

Record each new triple in change history: If this checkbox is enabled, the JDBC import will create a change history record for each new triple created as a result of the import. Enabling this checkbox is not recommended for databases that contain a large number of the database objects listed above.

Note

This option is not visible if Manage > Record Triple Counts only is activated.

Cron expression: The cron expression for the execution schedule. Leave blank to cancel future executions.

Workflow: The workflow template to use for the import.

Import RDF File

Import RDF File is available under the Import tab. Any asset collection can import data from an external RDF file. The Import > Import RDF File link shows a screen where the Browse button opens a dialog to select the external RDF file.

TopBraid EDG Import RDF File Page

TopBraid EDG Import RDF File Page

Choose the RDF file and select its Format, noting that the file may be compressed. The compression formats ZIP (.zip), gzip (.ttl.gz etc) and bzip2 (.ttl.bz2 etc) are supported. Only the first file in a ZIP archive will be imported.

Then, if applicable select the following options:

  • Record each new triple in change history (use with care for large RDF files!). If importing into a workflow, history will always be recorded and this option is greyed out.

  • Direct streaming import into production copy, available only for users with at least Managers permission. Direct streaming is not available for import into workflows.

  • Perform constraint validation only Validate the RDF file content combined with the existing collection data This is necessary because some violations only become apparent for the combined data.

Click Finish to complete the the operation. A message will indicate whether the import was successful. For large imports, this process may take minutes. Please check the status on the Reports tab for File History Report.

Note

  • If an RDF file contains any “schema” definitions such as classes, properties, or shapes, then it can only be imported it into an Ontologies collection.

  • If an RDF file contains both “instances” and “schema”, either split the file before import or follow instructions in Copy or Move Instances from Other Asset Collection.

When importing RDF into a workflow, the addition of each triple will be recorded as an entry in the change history, where it will be available to all the relevant reports. When importing into a Production Copy, the Record each new triple in change history checkbox gives you the option of adding these to the change history;

Note

This is not recommended when importing large amounts of data.

The option of Direct streaming import into production copy imports the content much more quickly and uses less memory. This should only be used for large imports if the user is confident they do not need to do validation or clean up on the data. It’s best to perform a backup (e.g. Export RDF File) of the collection prior to importing with direct streaming or use a workflow so that reverting is possible should anything go wrong.

When importing RDF files into an Ontologies or a Taxonomies collection, EDG performs some transformations (unless the streaming import is chosen):

  • For Ontologies, “subclass of Thing” statements will be added for classes that have no parents. This is done to ensure that these classes are visible in the Class Hierarchy.

  • For Taxonomies, “narrower concept” relationships will be used to generate inverse “broader concept” relationships. This is done to ensure that such concepts are visible in the Concept Hierarchy.

Import from SharePoint Term store

Import from SharePoint Term store is available under the Import tab and is only available for Taxonomies. Its purpose is to connect directly to a Sharepoint installation and import the stored terms it finds into an EDG taxonomy collection

Once selected from the list of importers, EDG automatically uses the pre-configured Sharepoint connector. The user is then prompted to select a Term Set found in Sharepoint to import, and to then click Continue.

TopBraid EDG Import Sharepoint Term Store Select Set

TopBraid EDG Import Sharepoint Term Store Select Set

Th importer will then import the Term Set and populate an EDG model reflecting the Term Store concepts. The following figure shows the Term Store concepts as mapped into a taxonomy during import.

TopBraid EDG Imported Sharepoint Term Store Concepts

TopBraid EDG Imported Sharepoint Term Store Concepts

If the Term Set was previously imported, the newly imported model will be merged with the existing one. If a new, clean imported set of data is preferred, then delete the Term Set from the collection before re-importing it.

Create Multiple Asset Collections from TriG or Zip File

The Create Multiple Asset Collections from TriG or Zip File button is available after clicking the plus sign in the EDG header to Create new Asset Collection.

TopBraid EDG Create From Trig or Zip

TopBraid EDG Create From Trig or Zip

Clicking the button opens the Import TriG or Zip File page and the user simply clicks Choose File, selects the desired TriG or ZIP file, and then clicks Finish.

TriG files are an RDF-specific file type that contain one or more named graphs. Zip files are general compressed archives, in this case, containing RDF files that are named graphs. The named graphs that follow the EDG naming convention (e.g. urn:x-evn-master:geography_ontology) will be imported as asset collections with the importing user as the manager. Other named graphs will be imported as Turtle files in the EDG workspace. Any pre-existing graphs remain unchanged.

An import is not permitted if either of the following is true:

  • A matching named graph already exists in EDG to which the importing user does not have at least read permission.

  • There are any triples in the default graph of the TriG file.

EDG can create TriG or Zip files for most asset collection types by using Export > Export [Asset Collection Type] with Includes as a File.

TopBraid EDG Export to Trig or Zip

TopBraid EDG Export to Trig or Zip File

EDG administrators can create TriG files using Server Administration > Create TriG file of all EDG production graphs (used for testing to backup or replicate a set of collections).

Import Concepts from Documents

Import Concepts from Documents is available only for Taxonomies. It is particularly suitable as a way to seed a new taxonomy.

When the user selects a file to import, EDG will analyze the file extracting concepts from it. Extracted concepts are presented for selection in order of their frequency in the document. The user then selects the concepts to be added to the collection, placed in an EDG-generated scheme to “hold” the new concepts. The user then manually organizes them hierarchically, as desired.

Import Single Document

Import Single Document is available only for Corpora allowing users to upload documents into a corpus one document at a time. Import of documents and associated metadata into a Corpora asset collection is performed dynamically according to the connector option selected when creating the corpus.

Imported Data Reports

File Import Reports

File Imports Report is available under the Reports tab and shows the history of file imports into the collection. The form will periodically refresh, and the refresh timer can be paused as shown. This also shows any current running file imports.

TopBraid EDG File Import Reports Page

TopBraid EDG File Import Reports Page

The report includes information about the importing user, the success or failure of the import, a summary, the datetime, the process ID and the workflow name, if applicable. Currently executing imports are included in the list.

Audit Trail for Import Operations

When importing directly into an asset collection the Record each new triple in change history checkbox is available which sets the option to record each individual change in the change history.

Warning

The default is unchecked and it is not recommended to select this option when importing large amounts of data. When this option is left unchecked, the change history will contain a record capturing that an import was executed, but will not contain every individual addition or deletion of data.

Record Triple Counts can be activated under the Manage tab for an asset collection. If activated, the change history will only record the numbers of added and deleted triples instead of the details about each triple. That significantly reduces the size of the change history. This choice removes the Record each new triple in change history option for the collection during import.

When the import is executed in the context of a workflow, each change is included in the change history, where it will be available to all the relevant reports.

Additionally, the decision not to retain detailed history upon completion of the workflow could be made when designing a workflow template.

Archive workflows on Commit can be activated under the Manage tab. If activated, detailed change history for committed workflows will be automatically archived.

Note

This has precedence over the Record Triple Counts only option, i.e. the archive will contain the full history before being compacted.

Configuring the Editor UI

Custom Icons for Assets

EDG includes support for custom icons to be displayed in hierarchies and on forms.

A custom icon can be declared to be the same for all members of a class (e.g., the same icon for all countries) or it can be declared as a value of a property resulting in different icons for assets of the same type. The following figure shows an example.

TopBraid EDG Custom Icon

TopBraid EDG Custom Icon

These are set up by using the ‘dash:IconRole’ setting on a Property Shape.

See DASH Icon Role for details.

Configuring Editor UI

Editor Layout View

Editor applications are composed of panels that are combined to form layouts. Multiple layouts are available. Each collection type has its own default layout. Users can change these defaults.

For example, the default layout for business glossaries will have two panels – Search and Form, looking as follows:

TopBraid EDG SEC Glossary - Appendix C Page

TopBraid EDG SEC Glossary - Appendix C Page

While for an ontology (asset collection that defines schema for other collections), the default editor layout will have panels looking as follows:

TopBraid EDG Examples GEO Ontology Page

TopBraid EDG Examples GEO Ontology Page

Selecting and Arranging Panels

Each panel can be displayed in the entire with of the screen by closing all other panels. This is useful when you need more screen real estate for working. To reset the layout, just select a layout from the menu and your panels will come back. Or you can drag them back into view from the panels menu. The next image shows how the Glossary Editor Application would look if the Form panel was stand-alone.

TopBraid EDG Advisory Affiliate Page

TopBraid EDG Advisory Affiliate Page

Panels can also be rearranged by dragging and dropping. Panels can be stacked behind each other in the same screen area. In the image below, the Change History panel is stacked behind the Form panel.

TopBraid EDG Advisory Affiliate Change History Page

TopBraid EDG Advisory Affiliate Change History Page

Panels can be closed by clicking on the “x” button in the panel’s header. This action removes a panel from a page.

Clicking on the Panels button displays additional selection of panels to add to a page.

TopBraid EDG Panels List Dropdown

TopBraid EDG Panels List Dropdown

All available panels are described below, organized into categories:

Asset Information Panels

Search and Query Panels

Explore Panels

Schema Panels

Taxonomy Panels

Reports Panels

Scripts Panels (available if scripts are enabled)

Some panels can be placed on a page more than once and remain in the menu even if they already exist on a page. Other panels make sense only once per page and, when already shown on a page, they no longer appear in the menu.

Some panels may have a pin icon – for example, if two forms are open. Pining a panel down will ensure that its content will not change if another panel is clicked.

Once a panel is added or removed from a page, that choice is remembered for the user in their next session.

Using Layouts

The Layouts button save arrangements of panels as a layout. Users can also switch to one of the existing layouts.

A saved layout can be made available to other users or kept private. It could also be declared as a new default only for the user who created it or for others as well.

TopBraid EDG Save Layout Dialog Box

TopBraid EDG Save Layout Dialog Box

Pre-built layouts are:

  • Default layout for the selected collection type

  • Single Form Layout – displays only the form for the selected resource

  • SPARQL Layout – provides a way to run SPARQL queries as an alternative to clicking on the Export tab > SPARQL Endpoint. Unlike the option on the Export tab, it is fully integrated with the editor.

  • Classes and Instance Layout – useful for Enumerated values.

  • Search Layout – a convenient page layout for Search operations, combines Search, Search Library and Form panels

  • Problems and Suggestions Layout – provides a way to execute Problems and Suggestions checking

The Layouts menu also lets you manage existing layouts by selecting “Available Layouts”.

Using Editor-wide Configuration Settings

More icon in the header provides access to application settings and additional navigation options for user UX personalization. These settings are locally stored per user and won’t effect other users.

TopBraid EDG Editor-wide Configuration Settings Dropdown

TopBraid EDG Editor-wide Configuration Settings Dropdown

Display Edit Actions as Icons button turns various menu options into icons and vice versa. By default, Display Actions as icons is checked. Unchecking it will impact all panels that have Create New actions and there is more than one action in a panel. Currently, these are Property Groups and Taxonomy Concepts panels. Instead of the icons, we will see Add menu with dropdowns. For example:

TopBraid EDG Create Concept Methods

TopBraid EDG Create Concept Methods

Checking the option to Display Settings as icons will impact every panel that has a Settings menu (gear icorn). Instead of the menu, we will see icons for each option.

Checking Display Panels palette option, will place in the header an icon for each panel – as shown in the screenshot below.

TopBraid EDG Panels Palette View

TopBraid EDG Panels Palette View

Clear locally stored Settings button will clear out any personalization of the UI with the exception of the Layouts as those are stored in the system, not the browser. Any check box, Asset List, or other personalization you have made will be reset.

Checking Hide values in non-preferred languages option will hide property values tagged with languages that are not set in your browser as one of your preferred language.

Manage default settings for all users … button will appear only if you have Manager profile for a collection. It will display a page where you can pre-set panel Settings for all users of a collection. For example, you can use it to ensure that for all users, when they look at the content of the current asset collection, the Form will show properties even if they don’t have any values.

The remainder of the menu is navigation/search options.

Local Search Options

This option is available only if the asset collection editor offers Search Panel.

When using Search Panel, there is an option, Return local results only, which excludes results that come from included asset collections. (A local search only delivers resources having their rdf:type triple in the base graph.)

By default, users can choose for themselves whether to enable or disable this local results option on any particular search. However, managers can permanently set this option as either always local or always global for all users. If set by a manager, then users will still see the setting value on their search panes, but they will not be able to change it.

Main Class of Search Panel

This option is available only if the asset collection editor offers Search Panel.

It impacts the Type Selector in the Search panel, determining what will be shown in its drop-down list and what will be the root of the browsable hierarchical navigator listing available asset types. Each asset collection has a default main class. This option lets you modify the default.

Root of Class Hierarchy Panel

This option lets you reset which class will be shown as the root in the Class Hierarchy Panel.

The default root is Thing. However, you can use this option to limit the class tree to one of the subclasses of the owl:Thing class. You can also use this option to go “up the tree” by setting the root to rdfs:Resource class or any of its subclasses that are different from owl:Thing.

Root Shape of Asset Hierarchy Panel

When using Assets Hierarchy Panel, users can select a shape of resources to be displayed as roots in this panel.

If you select a shape here, it will be used as default for the panel. Users can still switch to another shape.

If nothing is selected here, the panel will be empty until a user explicitly selects a root shape.

Also Create Global OWL Properties

If activated, EDG will produce an owl:DatatypeProperty or owl:ObjectProperty type statement for a property when a new SHACL property shape is created.

Using Forms to View and Edit Asset Information

Creating and Using Asset Lists

TopBraid EDG Asset List Options

TopBraid EDG Asset List Options

You can add any asset or group of assets to an asset list through the Search Panel.

The asset list is a way of bulk editing or sharing groups of assets. The “batch actions menu” is in the top right.

TopBraid EDG Asset List More Options

TopBraid EDG Asset List More Options

Pencil icon lets you name an asset list. The above asset list has been named “customer”. To create another asset list, drag the asset list panel from the panel selection to your window. Now when you choose to add to an asset list, you will choose which of your two asset lists.

Asset lists are private until shared. Cloud icon opens a menu that lets you open an existing asset list and share an asset list you create with colleagues who have permissions to this collection. They will be able to go to “Open an existing Asset List” and find all of the shared asset lists along with their own.

The settings menu lets you configure how information about assets in a list is displayed e.g., whether a person who added it to a list is displayed as a column.

Editing Assets using Form Panel

You can modify asset information directly by editing it in an asset collection or you can use Workflows and edit information in the workflow of the collection that is managed by the workflow. Irrespective of the choice, editing options are the same.

Asset information is modified primarily using the form panel. Clicking on the Edit button on top of the form opens all fields for editing. Alternatively, to clicking on the Edit button, users can do inline editing. Mouse over the area between the field name (e.g., definition) and the field itself. You will see a pencil icon. Click on it to start editing one property at the time.

TopBraid EDG supports modular management of information. You can create resources in one asset collection, then include this collection into another one and add more information about these resources.

See also

See :ref:’combining_asset_collections_target’ on how to combine asset collections through includes.

The hue of the icon at the top of the form will indicate if that resource is from the selected collection or is included from another collection. If included from another collection, the icon will be a lighter color. Further, you will see at the top of the form information about a collection where this resource is defined in.

TopBraid EDG Actuality Tab

TopBraid EDG Actuality Tab

You will be able to click through to that “defining” collection and modify the resource there.

If you do not go to the defining asset collection and decide to edit an included (or referenced) resource in your current collection:

  • You will only be able to add information and will not be able to remove or modify any of the information from the included collection.

  • The changes you make are added to the collection you are currently in, not the collection this resource has come from.

Similarly if you choose to delete an included resource, only the changes you made in that collection will be deleted, not the original resource. If you want to make changes to the statements that are included, use Explore -> Open in Defining Asset Collection. This will open the asset in the collection where it was originally created.

TopBraid EDG Asset Information - United States

TopBraid EDG Asset Information - United States

Click on the + (plus) sign to the left of the editable field to get a slot for a new value. Plus sign will appear only if the property could have more than one value. Click on the – (minus) sign to the right of the editable field to remove a value.

For attribute values, you can just type the value. A convenient picker may appear depending on the datatype e.g., a date. EDG will protect you from making mistakes. For example, if a value is supposed to be an integer, you will not be able to enter letters.

Note

A language tag for a string can be selected from the dropdown to the right of the field – if a value is defined as a language tagged string.

The dropdown icon to the left of the delete icon lets you switch to a different edit widget – If multiple types are defined for an attribute e.g., a string or a language string or HTML. For string values, you will be able to switch between a “text field” (a single line entry field) and a “text area” (a larger text box). Options shown are determined by the schema (ontology) that defines the asset type.

TopBraid EDG Switch Widget Dropdown

TopBraid EDG Switch Widget Dropdown

For relationship values, you can:

  • Start typing the name of the existing resource and pick it from the auto-complete.

  • Enter the URI of the related asset. The dropdown menu available by clicking on the “v” sign to the right of the field will let you switch between using autocomplete (default) and entering a URI.

  • Use search to find the resource you want to connect to by clicking on the button directly to the right of the field – as shown below.

  • Create a new resource by clicking on the button directly to the right of the field – as shown below.

  • Drag and drop assets from other panels directly into a form.

TopBraid EDG Find or Create City Dropdown

TopBraid EDG Find or Create City Dropdown

After at least one change is made, Save Changes button becomes clickable. If any of the edits presents an issue, the page will display them. You will have a choice to correct issues prior to saving, cancel edits or save them as-is.

TopBraid EDG Save Changes Anyway Example

TopBraid EDG Save Changes Anyway Example

Preview button will display added and deleted statements as well as any issues.

TopBraid EDG Preview of Form Edits for United States

TopBraid EDG Preview of Form Edits for United States

Sometimes, to the left of a field open for editing you will see a + icon surrounded by a square shape. Clicking on it will open a subform that lets you make statements about property’s value. For example, you may want to say that a value of a country code or a status has an effective start and an effective end date.

When information shown on the form is a relationship, you can:

  • Right click to see and use menu options for the related resource.

  • Click on the dropdown to switch the display to show URI of the related asset instead of its label (in view not in edit mode). You can also click on Show Details to see the embedded form for the related asset.

TopBraid EDG Data Element Properties View

TopBraid EDG Data Element Properties View

Further, if you mouse over the related asset, you will see an info box with its description (aka Wikipedia) if a description is available.

TopBraid EDG Information Box in Location

TopBraid EDG Information Box in Location

Sometimes, a form may display information in tables and/or display generated diagrams. What to display as a table is defined in the associated ontology models and can be configured. For example, in the form below for a database table from Northwind you see two tables: one containing data sample (not editable) and one containing records of data quality runs (editable).

TopBraid EDG Data Sample & Data Quality Records Tables

TopBraid EDG Data Sample & Data Quality Records Tables

Values That Can’t Be Edited

If a value of a property is displayed, but not editable, it means that one of the following is true:

  • Values for this property are automatically calculated (inferred) by EDG. Rules for inferring values are defined in the underlying ontologies. Some values may also be inferred by default, but still editable. In this case, any user edit overrides system inferences.

Or

  • Value has been entered in an asset collection that is included in the currently selected collection. In this case, you will not be able to remove or change the value. To edit it, you must navigate to the defining asset collection. If, however, the property can have multiple values, you will able to create additional values for such properties.

Or

  • Property has been set as “read only” in the underlying ontology. This may happen if your organization wants to control addition and edits of values for certain properties in the UI e.g., to make such edits possible only through import or APIs or to make them possible only in certain asset collections or to protect users in certain roles from incidentally modifying these values.

Alternate Form Views

An asset may have more than one type. It may also be of a single type, but have multiple views defined.

See also

For information on defining alternative views, see Working with Ontologies view shapes.

The view you will see by default will depend on your role and selections made in the relevant ontology.

If an asset shown on a form has multiple types or different role-based views, it can be viewed and edited using any of these perspectives. In such cases, you will see a dropdown box at the top right of the form next to the settings menu.

TopBraid EDG Alternate Form Views Dropdown

TopBraid EDG Alternate Form Views Dropdown

You will also be able to select a Merged view that, for assets that have multiple types, will combine properties of all types. To do this, select Settings>Merge properties from all suitable view shapes.

Additional Options for Viewing and Modifying Data

Additional options for modifying data in other editors panels are as follows:

  • Source Code Panel: This is a low-level technical operation and should be only used by users who are well versed in RDF, the underlying data model behind EDG. Your EDG Administrator can disable access to this panel for some of the users.

  • SPARQL Query Panel Update access must be enabled on the server to modify through SPARQL queries.

You can also modify data through GraphQL in EDG accessible from each collection’s Export tab.

The Forms for classes, SKOS concepts and concept schemes have a section called “Display” where you will find the “hidden” property. Setting it to “true” will hide these resources from the panels that display tree views – Class Hierarchy panel (in case of classes) and Taxonomy Concepts panel (in case of concepts and concept schemes). When a parent is hidden in the tree, all its children also disappear from the tree – unless they have another parent. The Class and Taxonomy Concepts panels have a “ghost” setting to show hidden items. To do this, select Settings> Also show assets marked as hidden.

Batch Edit

Batch Edit is available from the Asset List Panel, Instances Panel and Search Panel. Where you see the following menu item once you select multiple assets:

TopBraid EDG Edit Selected Assets Option

TopBraid EDG Edit Selected Assets Option

The batch edit wizard tool will then be launched.

Note

  • You can only modify resources of the same type.

  • If you have selected resources with multiple types, you will be asked to choose one.

TopBraid EDG Batch Edit View

TopBraid EDG Batch Edit View

The wizard will then let you select properties you want to change and walk you through modifying data using features similar to those of the Editing Assets using Form Panel.

Source Code Panel

The Source Code panel allows users to view and edit asset data in the Turtle serialization format. Editing source code is a low level operation for expert users and care should be taken.

Warning

When editing Source Code it is possible to cause damage to the EDG workspace making it unavailable. An administrator can configure the EDG server to block all edits to source code, which is recommended for organizations without expert users knowledgable about editing Turtle serialization.

The Source Code panel can also be hidden from users in certain roles.

TopBraid EDG Source Code Panel View

TopBraid EDG Source Code Panel View

Depending on the situation, one or two two windows appear:

  • an upper window shows the content of the current graph (asset collection)

  • if there are included graphs, a second lower window shows their content which is not editable

The upper window lets you edit the current graph data. You can make changes and click on the Save Changes button. Save Changes will not be available if editing introduces any syntax errors.

Prefix declarations can be expanded and collapsed. Do not make changes to prefixes using Source Code panel. Only ever change them as described in Controlling Namespaces and Prefixes .

The Settings menu option will let you hide statements from an included graph by hiding the relevant window.

Matrix Panel

The Matrix Panel assists with batch editing of matrix-like instances. Related values can chosen as rows and columns in the Matrix Panel. For example in a Geography taxonomy, rows could be Countries and columns could be Continents, and the property would be broader concept. The Matrix panel would then allow editing of the data all at once instead of country-by-country. It also provides a high level picture of the current state of the data.

TopBraid EDG Matrix Panel

Assets Hierarchy Panel

These panels show tree views of assets based on any relationships. Use the circle icon to select the root node shape. The dialog then explains what the available choices mean. For example if the selected root node shape is a class from your ontologies, then the root nodes of the hierarchy will be the instances of that class. The default root shape can also be pre-set for all users in the Manage tab.

Once a root node shape has been selected, it is possible to also select one of the relationship properties of that shape or class. In this case, the hierarchy will only show that relationship, with a simpler tree structure.

TopBraid EDG Assets Hierarchy Panel

TopBraid EDG Assets Hierarchy Panel

Hierarchy of Selected Asset Panel

This panel shows a tree view starting with the currently selected asset, letting you expand its relationship values as children in the hierarchy. These children can then be similarly expanded and so on.

Problems and Suggestions Panel

This panel checks the content of the asset collection against all of applicable quality rules (i.e., applicable shapes and validity constraints they define). It also runs enrichment rules to suggest mappings.

The Problems and Suggestions panel will raise validation results if values of properties do not comply with the (SHACL) constraints defined in the ontology your data is based on.

Depending on the asset collection, it may also perform additional algorithms to produce suggestions. Among others, the Problems and Suggestions panel can be used to execute so-called Test Cases. Test cases are a mechanism to repeatedly verify that certain conditions are (still) met. See DASH Test Cases for technical background.

The context menu in the upper right corner of the Problems and Suggestions panel offers the following settings:

  • Generate Suggestions instructs the SHACL validation engine to also produce suggestions for fixes.

  • Hide redundant suggestions will skip any Info-level suggestions with less than 100 confidence if one of the others has a confidence of 100.

  • Max number of constraint violations defines after how many reported violations the engine will stop.

  • Minimum suggestion confidence will skip suggestions under a certain threshold.

  • Record validation profiling information will collect and present the execution time of the validation engine for each shape and constraint component.

  • Run Crosswalk matching suggestions is available for Crosswalk asset collections only.

  • Run DASH test cases defines whether test cases (see above) should be executed.

  • Run Spelling correction suggestions will run the spellchecker against properties whose shape have languages configured (using the property tosh:spellCheckLang).

  • Run Data-element-to-term mapping suggestions based on labels is available for Data Asset collections where at least one Glossary Term is available

  • Run Wikidata mapping suggestions is available when some class(es) have been mapped to WikiData (when wikidash:Entity is among the allowed classes of properties).

  • Skip system shapes during validation will skip the validation of the shape definitions themselves. This may reduce the execution time.

TopBraid EDG Problems and Suggestions Panel

TopBraid EDG Problems and Suggestions Panel

Note

RDF, as a flexible graph data model, lets you make statements that were not anticipated e.g., to say something about Person’s eye color even if no property “eye color” is defined for a Person.

Creating such values is not supported by the form-based editing in TopBraid EDG – the forms are entirely driven by what is defined in ontology models. Yet, it is possible to add values for undefined properties e.g., if you have appropriate permissions, you could use the Source Code panel to add any triple directly in Turtle or you could import RDF containing any kind of triples. The fact that these triples may be using properties not explicitly defined in the ontology is not a violation of the model. It will not be flagged by the Problems and Suggestions unless you explicitly say that no values except for the defined properties are allowed.**

Change History Panel

The Change History Panel will show all captured changes – additions and deletions.

Each change can be expanded to show details. Added statements are shown in green. Removed statements are shown in pink.

You can filter displayed changes by selecting a user who made a change, the time period when changes were made, and/or the property (predicate) which values were changed.

To see only changes made to the currently selected asset, click on the “on selected” button.

TopBraid EDG Change History Panel

TopBraid EDG Change History Panel

Changes can also be reverted from the change history panel. Click to select changes you want to revert and then click on the Undo icon – the first icon in the panel.

Note

This will create an audit trail entry for the revert operation.

Workflows will have a button “from workflow only” to narrow down to only changes made specifically in the current workflow.

Inferences Panel

Inferences panel lets you run rules. It will display all triples generated by the rules using a table with 3 columns: subject, predicate and object.

TopBraid EDG Inferences Panel

TopBraid EDG Inferences Panel

In addition to the button that runs rules, the panel provides:

  • A button to assert all inferred triples. It will be displayed only once you execute rules and they generate some statements that will be shown in the panel. Clicking on this button will write the inferred statements into the asset collection. Until you take this action, generated statements are not stored permanently.

  • A button that will display all available rules and let you activate and deactivate them for the run.

Note

Rules defined using sh:values are evaluated dynamically and will NOT be shown or executed by the panel.

The screenshot below shows the dialog that will appear when you click on this button.

TopBraid EDG SHACL Inference Rules Dialog

TopBraid EDG SHACL Inference Rules Dialog

  • Settings button. It lets you switch between the display of labels and URIs and between the tabular display of the inferred statements and display in the Turtle format (source code). It also lets you control the number of iterations.

If you expect your rules to produce a large number of triple statements, we recommend that you run them by using the option available in the Transform tab. The role of Inferences panel is primarily to help you with testing rules as you develop them.

Instances Panel

This panel will show a table of instances of a selected class i.e., resources with the type corresponding to the selected class. The free text search field at the top of the panel lets you filter the list. The panel also has New button for creation of new assets of selected type. Settings menu has further options governing what and how is shown. The first column of the table is a check box. If you select multiple assets, you will be able to use the “batch actions menu” at the top right to perform the same bulk operations as those available in the Assets List panel.

References Panel

References panel displays all assets that refer to the currently selected asset (in the form or one of the other panels). For each referring asset, you will see its label and the referring relationship.

If you click on one of the referring assets, it gets selected on the form, in the hierarchical panels, etc. Then, in turn, what is shown in the References panel will change. If you want to avoid this from happening, select the “pin” option under the Settings (gear) menu. This will prevent the contents of the Reference panel from changing as you click around.

Panels for Working with Schemas

Class Hierarchy Panel

In EDG, every asset is a member of at least one class. This panel displays hierarchy of classes starting with a selected root. Hierarchical relationship between classes is rdfs:subClassOf. Class information is only editable if you are in an Ontology. In other collection types you will only be able to view class information.

See also

For more information about this panel see Class Hierarchy Panel .

Node Shapes

While EDG will declare all new Classes also as Node Shapes. It also also supports creation of Node Shapes that are not Classes which may be useful when creating an alternative view of class members or when creating a shape that will be used in other shapes, for example, as part of logical expressions.

The Node Shapes Panel displays ONLY node shapes that are not Classes and supports creation of such shapes.

See also

For more information about this panel see Node Shapes Panel .

Property Groups

The Property Groups Panel displays properties associated with a selected class or a node shape. Properties are displayed organized into groups, reflecting how they would be shown on a form.

See also

For more information about this panel see Property Groups Panel .

RDF/OWL Property List

The RDF/OWL Properties List Panel is a table showing instances of rdf:Property class and its subclasses. New button lets you create new properties.

Local Assets Panel

This panel will display only assets that are defined in the current asset collection. Assets from included collections will not be shown. There is a Search field to filter results and check boxes for selection. You can then use the “More” button in the upper left of the panel to execute operations on selected assets.

Available Crosswalks Panel

This panel will list any crosswalks that map the current asset collection to another collection. Y ou will be able to access crosswalk mappings from this panel. You will also be able to create new crosswalks.

See also

For more information see Working with Crosswalks .

Taxonomy Concepts

Taxonomies collections include a Taxonomy Concepts Panel which displays taxonomy concepts organized into concept schemes. It also lets you create new concepts and schemes.

See also

For more information, see description of this panel in Working with Taxonomies guide.

Other Panels

Other more specific panels are documented in the relevant sections of this guide:

Using Asset Menus

Right clicking on an asset displayed in any panel brings up an action menu providing access to asset actions. Some of the actions are ungrouped and available directly from the right click.

TopBraid EDG Asset Menus

TopBraid EDG Asset Menus

Other actions are grouped into Explore and Modify buttons. Ungrouped actions are available by clicking on the More button.

Explore

Actions grouped under Explore may differ based on the type of the asset.

See also

See Working with Ontologies or Working with Taxonomies for additional features available in these collections.

For all assets, you will be able to:

  • Find similar assets

  • Show any workflows that contain changes to the selected asset

  • See and enter comments about the asset

  • See and create tasks for the asset

  • Select a number of diagrams and visualizations – available options depend on the type of the asset

  • Add and view endorsements. Endorsements will be recorded as activity in the what’s happening section of EDG home page, viewable in the form panel and in Search the EDG.

TopBraid EDG Explore Dropdown

TopBraid EDG Explore Dropdown

Modify

The Modify menu actions are only available if a user has editor privileges for an asset collection. Clone and replace actions are available for all assets. Delete action is available for assets that are defined in the current asset collection. Other available actions will differ based on the type of the asset and collection.

TopBraid EDG Modify Dropdown

TopBraid EDG Modify Dropdown

See also

See Working with Ontologies or Working with Taxonomies for additional features available in these collections.

Cloning and Replacing Assets

Clone and Replace operations are available under the Modify menu.

Clone creates a copy of the selected Asset. The label of the clone (preferred label in case of SKOS Concepts) will be set as the label of original asset with “ Copy” appended to it.

Replace creates a clone of the selected asset using URI that you will provide and then deletes selected asset. One difference with the clone operation above is that the label will be the same as the label of the original asset, “ Copy” will not be appended. You can use this operation if you decide that you need to modify URI identity of a resource. EDG will automatically adjust all incoming and outgoing references. However, it will do so only for the currently selected asset collection. Other asset collections will not be updated. If they contain references to the asset you are replacing, you will see broken links. To understand possible impacts of delete operations see Deleting Assets section.

Deleting Assets

Delete is available under the Modify menu.

You can delete assets directly in an asset collection or you can start a workflow and delete in the workflow of the collection that is managed by Workflows. Irrespective of the choice, delete options are the same.

Since asset collections in EDG can include each other by reference, some care needs to be taken when deleting assets. Delete operation only deletes references to the deleted asset that exist in your current asset collection. Consider the following scenario:

  • Taxonomy 1 defines Concept A

  • Taxonomy 1 also defines Concept B making it a child of Concept A

  • Taxonomy 2 includes Taxonomy 1

  • Taxonomy 2 defines Concept C making it a child of Concept A

  • You go to Taxonomy 1 and delete Concept A. Concept B’s reference to A will be removed, but Concept C’s reference to A will stay. Now concept C has a broader relationship to an undefined concept

Running Problems and Suggestions check on Taxonomy 2 will report the issue and assist you in removing such references.

Similarly, deleting a class (asset type) from an ontology will not remove class instances (assets of a given type) that may be stored in another asset collection. It will make them members of undefined class. Deleting a property does not delete property values that are held in another asset collection.

Running Problems and Suggestion check will help you identify and fix these issues. Further, by going to the Settings>Included By you will see all asset collections that include your selected collection. You can then go to them and use References panel to identify what may be referring to a resource you are planning to delete.

Merge

Merge is available under the Modify menu.

Merge replaces the ID (URI) of an asset and moves all information about it that exists in the current asset collection to the new ID. This includes any references to the asset. If no other collection refers to this asset then this operation will effectively delete the “old” ID. However, any information about this asset contained in other collections will continue to refer to the “old” ID. You should proceed with this operation only if all information about the asset is contained within this collection, or you understand the implications of this change and, if needed, are prepared to adjust other asset collections.

More

Actions grouped under More may differ based on the type of the asset.

TopBraid EDG More Dropdown

TopBraid EDG More Dropdown

Add to Asset List

Adds the selected asset to a sharable asset list. Asset lists are available in the Creating and Using Asset Lists and used for bookmarking or bulk actions.

Add to Basket

Basket (see Bookmarking Asset Collections and Assets) is similar to Asset List but for all of EDG. It is located in the main header bar. Here you create create new versions of collection or bookmark assets or collections. This is per user and not shared.

Endorse Asset

Lets you add an Endorsement for the selected asset. Endorsements are recorded as activity in the what’s happening section of EDG home page, viewable in the form panel and in Search the EDG.

Open on new Form

This opens the selected asset on a new form.

Open in New Browser Tab

This opens the selected asset on a new browser tab.

Start Workflow

Starts a Workflows for this selected asset in this collection.

Print

Generates a page to print showing the data about the selected asset and opens the browser print function.

Cross Panel Operations

Some features and options work the same across different panels. These are described below.

Undoing Changes

Undo button in the header lets you reverse the most recent Save operation.

TopBraid EDG Undo Cross Panel Operations

TopBraid EDG Undo Cross Panel Operations

You can also reverse one or more changes made in the past by using Change History Panel.

Drag and Drop Operations

Several panels support drag and drop:

  • You can drag and drop items displayed in the hierarchical panels e.g., Taxonomy Concepts, Class Hierarchy and Property Groups

  • You can also drag and drop from other panels into fields on the Form panel

  • In an ordered list (indexed property) on a Form, list values can be re-arranged by dragging and dropping

Note

by default, drag and drop in the hierarchical panels in order to re-arrange a tree structure performs “delete and add” as a resource gets moved. This, for example, means that if a taxonomy concept had two different parents – A and B, moving it from its position under parent A to a position under parent C will give it a brand new parent and remove the previous two parents. In other words, it will no longer be under both, A and B. It will only be under C.

If you want to simply add a new parent instead of replacing previously existing parents, press CTRL key when dragging. This will add a new parent without removing existing parents. Alternatively, you can select a resource for which you want to add a new parent and edit its information in a form by adding a new value to already existing values for the hierarchical property.

When you drag and drop into a form, TopBraid EDG will check that a resource you are dragging has a suitable type for the field (property) you are dragging it into. Otherwise, you will not be able to drop it.

Using EDG Diagrams

The EDG Diagram is the latest visualization feature of EDG replacing the Class Diagram, NeighborGram and the Relationship Tree Diagram. All of those visualization features have been combined into a single one-stop shop of relationship exploration.

The EDG Diagram is a panel and users can have multiple diagrams open at the same time. However, note that large diagrams can take a lot of resources to render/animate and maintain.

Definitions:

  • Node: A node is an element on the diagram that represents a Class, Resource or Property Shape.

  • Edge: An edge is an element on the diagram that represents a relationship between nodes.

For the purposes of this document diagram elements will be referred to as Nodes and Edges.

Using Explore and then Show EDG Diagram opening the EDG Diagram Panel.

EDG Diagram Panel

Once opened, nodes can be added to the diagram by drag and drop, for example from the class hierarchy in an Ontologies collection.

The EDG Diagram panel has buttons that perform actions on the diagram.

TopBraid EDG Diagram Buttons

TopBraid EDG Diagram Buttons

From left to right the buttons are:

  • Diagram Settings

  • Clear Diagram

  • Save Diagram

  • Open Diagram

  • Export (as GraphML, SVG, PNG files, or Default Styles)

  • Search (within diagram)

  • Zoom In

  • Zoom Out

  • Fit To Screen

  • Fixate selected nodes

  • Release selected nodes (from Fixate)

  • Undo

  • Redo

  • Toggle Overview Visibility

  • Align

  • Set Node Color

  • Set Border Color

  • Expand All Nodes

  • Collapse All Nodes

Undo/Redo

While working with the diagram all actions can be undone or reapplied. There are only three limitations:

  1. diagram history does not persist when the diagram is saved and reopened;

  2. diagram history does not persist when the panel is closed;

  3. if the diagram is reset by using the Trash button, the diagram history is cleared.

Fixate/Release selected nodes buttons can be used so that when fixated and the diagram needs to redraw/relayout, then those nodes are locked in place.

Search

Users can search for specific labels in the diagram by selecting the Search button and then entering text in the dialog. Nodes with matching labels are highlighted. Selecting the button again removes the dialog.

TopBraid EDG Diagram Search

TopBraid EDG Diagram Search

Toggle Overview Visibility

The EDG Diagram has a low fidelity overview panel in the lower right corner of the diagram. Users can control the visible nodes for very large diagrams by selecting and moving the overview rectangle. This panel is hidden by default.

TopBraid EDG Diagram Overview

TopBraid EDG Diagram Overview

Node Types

By default EDG Diagram supports three node types and their general layout is shown in the following figure. Resource Nodes, Class Nodes and Property Shape Nodes all follow this layout, but offer type-specific detailed information.

TopBraid EDG Diagram Node Types

TopBraid EDG Diagram Node Types

Node Type Interaction

All three nodes have a (right-click) context menu that is only accessible through the “header” of the node. This context menu is the same that is available throughout the EDG editor. However, there are now some node specific actions. These actions will vary depending on the current node type.

TopBraid EDG Diagram Node Types

Resource Node: A Resource Node is a node that represents an instance of a class. The information in a resource node is controlled by DASH Property Roles. (https://datashapes.org/propertyroles.html)

TopBraid EDG Diagram Resource Node

TopBraid EDG Diagram Resource Node

The following figure shows the context menu.

TopBraid EDG Diagram Resource Node Context Menu

TopBraid EDG Diagram Resource Node Context Menu

Class Node: A Class Node is a node that represents a class definition. It shows the list of declared properties. The diagram also has the ability to show inherited properties in a Class Node, controlled by a per-diagram setting.

TopBraid EDG Diagram Class Node Including Inherited Properties

TopBraid EDG Diagram Class Node Including Inherited Properties

The following figure shows the context menu.

TopBraid EDG Diagram Class Node Context Menu

TopBraid EDG Diagram Class Node Context Menu

Property Shape Node: A Property Shape Node is a node that represents a property shape definition. It mirrors the editor form, rendering the property group and all properties relevant to the property shape definition.

TopBraid EDG Diagram Property Shape Node

TopBraid EDG Diagram Property Shape Node

The following figure shows the context menu.

TopBraid EDG Diagram Property Shape Node Context Menu

TopBraid EDG Diagram Property Shape Node Context Menu

EDG Diagram Context Menu Explained

Show Neighborhood: Show Neighborhood expands from left (incoming) to right (outgoing) using the target node as the center. This action uses the same data algorithm as NeighborGram. Neighborhoods can be busy, depending on the target node type.

TopBraid EDG Diagram Show Neighborhood Result

TopBraid EDG Diagram Show Neighborhood Result

Expand Inherited: The expand inherited action uses the same data algorithm as the Class Diagram panel. This action will calculate the inheritance chain of the target node. The layout is from bottom to top, where the target node is the bottom.

TopBraid EDG Diagram Expand Inherited Result

TopBraid EDG Diagram Expand Inherited Result

Expand Associations 1 - Level / 2 - Level: The expand inherited action uses the same data algorithm as the Class Diagram panel. The default layout is top to bottom, where the target node is at the top. The only difference between 1 - Level / 2 - Level is the number of graph traversals. 1 - Level will reveal the immediate relationships the target node contains. 2 - Level will follow the immediate relationships and expand their relationships as well.

TopBraid EDG Diagram Expand Associations 1 - Level Result

TopBraid EDG Diagram Expand Associations 1 - Level Result

TopBraid EDG Diagram Expand Associations 2 - Level Result

TopBraid EDG Diagram Expand Associations 2 - Level Result

EDG Diagram Other Expansion Options

The EDG Diagram will automatically resolve relationships between existing nodes on a diagram.

Outside of the default layout algorithms each node has the ability to expand upon known relationships. This can be done in a directional manner (North: Bottom-Top, South: Top-Bottom, East: Right-Left, West: Left-Right). When selected, a node has several action buttons.

Selecting any of these buttons opens a dialog showing the available relationships. Only existing relationships will be available, not potential relationships as defined by Property Shapes. Select the target relationships and click Ok to accept. Then observe the layout of the nodes in that direction.

Once a relationship has been selected it is no longer available as a candidate for the other directions.

Focus Node in the EDG diagram means hiding elements that are not connected to the target node. The undo button can be used to revert the action.

TopBraid EDG Diagram Focus Node Control

TopBraid EDG Diagram Focus Node Control

Note

Focusing on a node in the earlier EDG NeighorGram meant re-drawing the entire diagram around the new focus node.

Zoom To Node is the control used to make the selected node be the center of the diagram.

TopBraid EDG Diagram Zoom To Node Control

TopBraid EDG Diagram Zoom To Node Control

Hide/Show Properties is the control at the top right of the node used to hide or show properties inside the box.

TopBraid EDG Diagram Hide Properties Control

TopBraid EDG Diagram Hide Properties Control

EDG Diagram Batch Node Alignment

The EDG Diagram has the ability to align selected nodes with one another. There are four alignment options Left, Right, Top, Bottom

TopBraid EDG Diagram Alignment Menu

TopBraid EDG Diagram Alignment Menu

There are two distinct behaviors for node alignment: global and local. The behaviors are only different in which node is considered the ‘leading’ node. When using the global context, the leading node is designated as the furthest node in the specified orientation.

For example, in the diagram below:
    1. Is the top most node

    1. Is the right most node

    1. Is the left and bottom most node

TopBraid EDG Diagram Alignment Example

TopBraid EDG Diagram Before Top Alignment

For each example below the diagram has been reset to the original layout and then the alignment is applied.

Example 1) after selecting nodes 1 and 2 select the ‘top’ alignment option from the menu, observe node 3 remains in place while nodes 1 and 2 are now aligned at the top edge.

TopBraid EDG Diagram Top Alignment Example

TopBraid EDG Diagram Top Alignment

Example 2) after selecting nodes 2 and 3 select the ‘right’ alignment option from the menu, observe node 1 remains in place while nodes 1 and 3 are now aligned at the right edge.

TopBraid EDG Diagram Right Alignment Example

TopBraid EDG Diagram Right Alignment

Example 3) after selecting nodes 1 and 3 select the ‘left’ alignment option from the menu, observe node 2 remains in place while nodes 1 and 3 are now aligned at the left edge.

TopBraid EDG Diagram Left Alignment Example

TopBraid EDG Diagram Left Alignment

Example 4) after selecting nodes 2 and 3 select the ‘bottom’ alignment option from the menu, observe node 1 remains in place while nodes 2 and 3 are now aligned at the bottom edge.

TopBraid EDG Diagram Bottom Alignment Example

TopBraid EDG Diagram Bottom Alignment

Utilizing the local behavior, the user selects which node is considered the leading node. This is done via the node context menu available through the hamburger menu (1). Make sure to hold down the control key while access this menu otherwise your selections will be lost.

TopBraid EDG Diagram Alignment Context

TopBraid EDG Diagram Alignment Context

EDG Diagram Routing Options

New with EDG 7.7 - EDG Diagram now supports straight line routing. With straight line routing all edges follow the most direct path from source node to target node. There are two ways a user can take advantage of straight line routing.

    1. Graph configuration at the global level. Hierarchic is the default but can be switched to straight line. Unless overridden by the user all edges will adhere to the defined global behavior.

    1. Individual routing, in the scenario a user can choose to re-route selected edges with the hierarchic (orthogonal) or straight line routing. Only selected edges will be impacted, all other edge routes are left intact, new routes will fall back to the global setting.

Note

Other routing options such as “Disable Orthogonal Routing” do not apply when straight line routing is selected.

TopBraid EDG Diagram Layout Settings

TopBraid EDG Diagram Layout Settings

EDG Diagram Hierarchic Routing vs Straight Line Routing

Comparing the images below observe the differences between the two layouts.

  • Hierarchic Routing will group edges use a common ports when possible. The straight line router will not.

  • Hierarchic Routing will position labels as close to the target as possible. Straight line routing might avoid placing a label near the target due to other layout considerations.

TopBraid EDG Diagram Hierarchic Layout

TopBraid EDG Diagram Hierarchic Layout

TopBraid EDG Diagram Straight Line Layout

TopBraid EDG Diagram Straight Line Layout

Manually re-routing selected edges

On occasion the route of an edge might not follow the most optimal path. Rather than manually manipulating the route by dragging the edge the user can simply select the target edge and then click one of the two routing options from the context menu.

    1. Hierarchic Routing

    1. Straight line Routing

TopBraid EDG Diagram Routing Options

TopBraid EDG Diagram Routing Options

Observe the result after selecting both edges and clicking the straight line router button (number 2 in the figure above)

TopBraid EDG Diagram Straight Line Routing Applied

TopBraid EDG Diagram Straight Line Routing Applied

EDG Diagram Setting Node Color

EDG Diagram has the ability to set colors to specific node attributes. These are:
    1. Node color

    1. Node border color

Note

Both functions need to have a selected node/s prior to clicking on their respective buttons.

Node Color

TopBraid EDG Diagram Node Color button

TopBraid EDG Diagram Node Color Button

Upon clicking on the node, the button corresponding to the functionality to change the node color will automatically be enabled. Once this button is clicked, a dropdown palette will become visible to allow the user to select a color.

Right upon clicking on any color, the selected node header will change to the selected color accordingly. Node body, node border color, and node text will also change to a complimentary color based on the selected color. This will allow for high-quality color schemes.

TopBraid EDG Diagram Node Color set

TopBraid EDG Diagram Node Color Set

Node Border Color

TopBraid EDG Diagram Node Border Color button

TopBraid EDG Diagram Node Border Color Button

Upon clicking on the node, the button corresponding to the functionality to change the node color will automatically be enabled. Once this button is clicked, a dropdown palette will become visible to allow the user to select a color.

Right upon clicking on any color, the selected node border will change to the selected color accordingly.

TopBraid EDG Diagram Node Border Color set

TopBraid EDG Diagram Node Border Color Set

Batch-setting default styles

EDG Diagram offers the convenient feature of batch-setting default colors for different elements. These include:
    1. Diagram Default Node Styles

    1. Diagram Default Edge Styles

    1. Diagram Default Label Styles

Note

To access these options, simply navigate to the diagram settings dialog ‘Set Style’ tab.

Diagram Default Node Styles

When configuring the default node style, you will be presented with multiple options. You have the flexibility to customize both the node style and border style for the following node types: Class, Property Shape, Resource, and Note.

TopBraid EDG Diagram Node Default Style

TopBraid EDG Diagram Node Default Style

Diagram Default Edge Styles

When configuring the default edge style, you can choose from multiple options to customize the appearance. You have the flexibility to adjust the edge color, thickness, dash style, and arrow type to your liking. These customization options can be applied to base, aspect and superclass edges, allowing you to achieve your desired visual result in a formal context.

TopBraid EDG Diagram Edge Default Style

TopBraid EDG Diagram Edge Default Style

Diagram Default Label Styles

When configuring the default label style, you will have the option to customize one aspect: the label color. This customization option can be applied to base, aspect and superclass edges.

TopBraid EDG Diagram Label Default Style

TopBraid EDG Diagram Label Default Style

Additionally, with EDG Diagram, you have the option to apply a consistent style effortlessly to a group of attributes that you find suitable. You can achieve this by utilizing a convenient toggle switch, ensuring a unified and visually appealing appearance throughout your diagram.

Import / Export default styles

EDG Diagram offers an additional feature that allows users to set default styles and conveniently share them with others. With this functionality, you can export any defined styles and distribute them to individuals who need to utilize the same styles. Furthermore, the diagram also provides the capability to import these shared styles.

To export default styles, you can access the functionality by navigating to the diagram toolbar and clicking on ‘export default styles’.

For importing styles, you can find this option within the Diagram Settings Dialog under the ‘import styles’ tag.

EDG Diagram Add Diagram Notes

EDG Diagram can add Diagram notes to the diagram. These include:
    1. Adding Diagram Note Node

    1. Adding Diagram Note in Node

Adding Diagram Note Node

The user can add a Diagram Note Node within the EDG diagram. This is achieved by triggering the context menu and clicking on the ‘Add Note’ button.

TopBraid EDG Diagram Add Note Node Button

TopBraid EDG Diagram Add Note Node Button

Upon clicking the ‘Add Note’ button a new Note node is added to the diagram. The user may add any text inside this node, to do so the user needs to double-click on the newly created node and a new input text field will show. Right upon this input field loses focus the text is persisted into the diagram.

TopBraid EDG Diagram Note Node

TopBraid EDG Diagram Note Node

TopBraid EDG Diagram Note Node text field

TopBraid EDG Diagram Note Node text field

TopBraid EDG Diagram Note Node with text

TopBraid EDG Diagram Note Node with text

Adding Diagram Note in Node

The user can add a Diagram Note within any other Node. This is achieved by triggering the node context menu and clicking on the ‘Add Note’ button.

TopBraid EDG Diagram Add Note in Node Button

TopBraid EDG Diagram Add Note in Node Button

Upon clicking the ‘Add Note’ a dialog box with an input text field will show, to allow the user to start typing the note details. Once all details are inputted, the user is required to click on ‘Ok’ to persist the note into the diagram.

TopBraid EDG Diagram Add Note in Node text field

TopBraid EDG Diagram Add Note in Node text field

Once the diagram note is persisted into the diagram, the note will become part of the node information. From there the user can edit or delete the note by clicking on the corresponding buttons.

TopBraid EDG Diagram Note in Node

TopBraid EDG Diagram Note in Node

Note

  • Diagram Notes header will not be visible if no notes are added to node.

  • All notes details are saved within the local storage of the particular browser only.

EDG Diagram Add Images

EDG Diagram offers the capability to include Image Nodes within your diagram. You can achieve this by activating the context menu and selecting the ‘Add image’ option.

TopBraid EDG Diagram Add Image action

TopBraid EDG Diagram Add Image action

Upon selecting the ‘Add image’ option, a dialog prompt will appear, presenting the user with multiple options to choose from. The user can then perform one of the following actions:

  • Import Media: This option allows the user to import an image file from their local storage or device.

TopBraid EDG Diagram Import Media

TopBraid EDG Diagram Import Media

  • Select Media from library: By choosing this option, the user can select an image from a pre-existing library of media files.

TopBraid EDG Diagram Media Library

TopBraid EDG Diagram Media Library

Note

The images listed here are images that were included in an EDG diagram within the same graph and were saved as public.

  • Insert from URL: This option enables the user to insert an image into the diagram by specifying its URL or web address.

TopBraid EDG Diagram Insert from URL

TopBraid EDG Diagram Insert from URL

These options provide flexibility and convenience for incorporating images into the diagram based on the user’s preferences and available resources.

Once the user has selected the desired image, they should proceed by clicking the ‘Ok’ button. This action will ensure that the selected image becomes visible within the diagram’s canvas.

TopBraid EDG Diagram Image Node

TopBraid EDG Diagram Image Node

EDG Diagram Relationship Filtering

The EDG Diagram has the ability to filter relationships. There are two filter options: global and local. If global filters are applied, local filters are possible as the number of filter combinations would become difficult to maintain.

Global Filtering is managed using the Diagram Settings dialog accessible through the gear icon in the diagram toolbar has four setting areas.

TopBraid EDG Diagram Settings

TopBraid EDG Diagram Settings

To set a relationship filter, select one of the options:

  • No Filter removes any filtering.

  • Filter All hides all relationships and properties.

  • Include hides all relationships except for those selected.

  • Exclude shows all relationships except for those selected.

Include/Exclude list all Available Properties (relationships) for the current Asset Collection.

TopBraid EDG Diagram Available Properties Dialog

TopBraid EDG Diagram Available Properties Dialog

Local Filtering is handled by the Property Control action. It has the same options as global filters, the primary difference is that the filter only applies to the target node and relationships that are connected to the target node.

TopBraid EDG Diagram Property Control

TopBraid EDG Diagram Property Control

When selected the properties of the asset are shown to be selected for filtering.

TopBraid EDG Diagram Property Filters Dialog

TopBraid EDG Diagram Property Filters Dialog

Property Hover Menu (Class Nodes Only)

The property hover menu presents quick actions. Properties that have a relationship with another Resource have three options:

  • Expand Relationship: which expands upon the target property. The default layout is bottom-to-top, expanded nodes may layout above or below the target node depending on the direction of the relationship.

  • Quick Hide Relationship: hides the property from the ClassNode and close any open edges/node on that relationship. If a relationship is hidden with the quick hide the global/local filters will have no effect on that relationship.

  • Open Menu: opens the context menu for the target property.

TopBraid EDG Diagram Property Hover Menu

TopBraid EDG Diagram Property Hover Menu

Edge Customizations

When an edge is selected a context menu will be presented. This context menu provides the ability to customize and re-route edges. Edges can be customized several ways: color, thickness, dash style, edge style (e.g. polyline or bezier).

TopBraid EDG Diagram Edge Customizations

TopBraid EDG Diagram Edge Customizations

TopBraid EDG Diagram Edge Color

TopBraid EDG Diagram Edge Color

TopBraid EDG Diagram Edge Thickness

TopBraid EDG Diagram Edge Thickness

TopBraid EDG Diagram Edge/Dash Style

TopBraid EDG Diagram Edge/Dash Style

Routing Edges

The path of an edge can be less than optimal for a given diagram. For example this can happen through the diagram nodes or edges being manually moved, this scenario can be observed in image below.

TopBraid EDG Diagram Edge Routing

TopBraid EDG Diagram Edge Routing

The user can instruct the diagram to re-route the selected edges by clicking the last button in the selected edge menu.

TopBraid EDG Diagram Edge Routing Menu

TopBraid EDG Diagram Edge Routing Menu

Observe the now optimized edge routes.

Note

Labels are automatically positioned near the target end of the edge path.

TopBraid EDG Diagram Edge Routing After

TopBraid EDG Diagram Edge Routing After

Moving Edge Labels

All edge labels are automatically placed along the edge as close to the target node as possible. Originally users had no option but to accept where a label would land. Now users have the ability to move labels along the path of an edge, while still limited to position candidates provided by the diagram this gives the user the ability some control on the final location of a label.

Note

Should the diagram re-draw or the path of the edge be recalculated the position of the label will be reset.

TopBraid EDG Label Position

TopBraid EDG Diagram Label Position

In the image below observe the rectangles along the edge, these are the provided label location candidates. Location candidates are only rendered when the user starts to move the selected label.

Note

It’s easy to move the edge instead of the label, take note of which element has the focus before attempting to move the label.

TopBraid EDG Diagram Save Diagram Dialog

TopBraid EDG Diagram Save Diagram Dialog

Removing Nodes

While not obvious that nodes can be removed from the diagram. This is done by selecting the nodes and clicking the delete or backspace button. The nodes and connected edges will be removed.

Automatic optimisation of edge routes on node movement

To optimize the routing of edges and minimize bends and crossings, EDG Diagram employs a feature that automatically reroutes connected edges when a node is moved. This ensures maximum edge route optimization and enhances the overall clarity and organization of the diagram.

Saving and Sharing

Diagrams can be saved to asset collections. This allows users to save their work, create snapshots at intervals and also share diagrams with other users. Diagrams can be marked as public or private, all public diagrams are discoverable by other users, but only the owner can make modifications.

TopBraid EDG Diagram Save Button

TopBraid EDG Diagram Save Button

TopBraid EDG Diagram Save Diagram Dialog

TopBraid EDG Diagram Save Diagram Dialog

After a diagram has been created, to share the link, select Open saved diagram to browse the available diagrams. Keep in mind that diagrams can only be viewed by EDG users.

TopBraid EDG Diagram Open Saved Diagram Button

TopBraid EDG Diagram Open Saved Diagram Button

Click the link for a specific diagram to copy it to the clipboard. Use Delete to removed the selected Saved diagram.

TopBraid EDG Diagram Open Saved Diagram Dialog

TopBraid EDG Diagram Open Saved Diagram Dialog

Using SPARQL to Query and Modify Data

SPARQL Query Panel

This panel lets you compose, run and save SPARQL queries. For example, a query shown below will identify assets that do not have a preferred label in Russian, effectively providing a translation list.

TopBraid EDG SPARQL Query Panel

TopBraid EDG SPARQL Query Panel

You can use either URIs or Qnames. The panel will automatically resolve prefixes and put out PREFIX statements. The panel will detect and report query syntax errors. Query parts can be collapsed and expanded for readability.

See also

To see results of query execution, use SPARQL Results Panel.

You can use SPARQL Layout which already integrates SPARQL Query and SPARQL Results panels as well as SPARQL Library panel.

To save a query for re-use, use Save icon. You will be able to name the query and decide the scope of its sharing. Your query can be parametrized. This will let users enter a parameter when they run saved query. To indicate that a variable is a parameter, replace “J” with “$” e.g., use $label instead of ?label.

Use the algebra button to see the SPARQL algebra associated with the query for advanced debugging. This will show how the SPARQL engine is executing the query allowing optimizations to be discovered.

TopBraid EDG Save SPARQL Query to Library Dialog

TopBraid EDG Save SPARQL Query to Library Dialog

TopBraid EDG supports SPARQL 1.1, including SPARQL Update. If the EDG server has been configured (see Administrator Guide, System Configuration Parameters) to allow SPARQL updates, editors (and managers) can run them, but viewers cannot.

GeoSPARQL is also supported. To enable your asset collection for Geospatial queries, use the Manage tab to enable GeoSPARQL. This will create and maintain the geo spatial index.

Note

The Pivot Table and Geo functions can be slow on some platforms and are not supported for Internet Explorer.

SPARQL Results Panel

This panel shows results of SPARQL query execution from the SPARQL Query Panel in a tabular format and lets you export them. Table columns are sortable and rows are clickable so that you could see more information about returned resource on, let’s say, a form.

TopBraid EDG SPARQL Results Panel

TopBraid EDG SPARQL Results Panel

By default, returned resources are displayed using their labels. Settings menu lets you request that IDs (QNames) are displayed instead of labels. Export menu lets you export query results in a variety of formats. Results of SPARQL SELECT queries can be exported in any of the standard export formats as defined by the W3C specifications: TSV and CSV, JSON and XML. Results of SPARQL CONSTRUCT and DESCRIBE queries can be exported in one of the standard RDF serializations: Turtle, JSON-LD, RDF/XML.

SPARQL Library Panel

This panel will show the list of queries saved using the SPARQL query panel. What it shows is determined by the scope of the saved queries and the asset collection you are currently in.

You will be able to select and run a query. You will also be able to delete saved queries.

TopBraid EDG SPARQL Library Panel

TopBraid EDG SPARQL Library Panel

The settings menu lets you configure how much information about a query should be displayed.

The following buttons can be used to show the query and to copy the URL for the query results.

TopBraid EDG Show Query and Copy URL Buttons

TopBraid EDG Show Query and Copy URL Buttons

TopBraid EDG SPARQL Library Query Example

The SPARQL Library panel

SPARQL Endpoint

In addition to the built-in panels of the main application, TopBraid EDG includes a general SPARQL endpoint at /tbl/sparql.

SPARQL Endpoint Page

When called from a browser, /tbl/sparql opens an interactive editor for entering and executing SPARQL queries.

Screenshot of TopBraid's SPARQL endpoint page

TopBraid’s SPARQL Endpoint page

Note

Only use the SPARQL endpoint if you need to make arbitrary SPARQL queries that are not only about a specific asset collection. Or if you need to query other graphs such as the change history data as shown in the screenshot above. For most users, the SPARQL Query Panel is typically a more user-friendly choice.

See also

SPARQL Best Practices for tips on how to write efficient SPARQL queries.

SPARQL Endpoint Web Service

The SPARQL endpoint can also be called programmatically from external systems, for example to query terms from a Taxonomy.

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 that are delivered in standardized formats as described in the SPARQL 1.1 Protocol.

See also

An alternative to using SPARQL is GraphQL, which is suitable for use cases such as fetching an array of instances with certain characteristics. An even more flexible alternative is using Scripting with JavaScript and ADS, which offers the ultimate flexibility to produce any type of output.

If you want to query a TopBraid server from arbitrary SPARQL 1.1 processors, you can use the SERVICE keyword. To make this work, you just need to know the URL of the TopBraid server and the name/URI of the graph that you want to query. The general pattern of the graphs representing the EDG asset collections is urn:x-evn-master:XY where you substitute XY with the identifier that you see before .editor in the URL of the main editor of your asset collection.

For example, if you have EDG installed at the domain name ourserver.com on port 8080, use the following query to send a query to that endpoint requesting a list of Continent resources in the Geography vocabulary:

1SELECT ?continent
2WHERE {
3   SERVICE <http://ourserver.com:8080/edg/tbl/sparql> {
4      GRAPH <urn:x-evn-master:geo> {
5          ?continent a <http://topquadrant.com/ns/examples/geography#Continent>
6      }
7   }
8}

If you do not want to use the SERVICE keyword, you can invoke the SPARQL endpoint service directly. For example, let’s say you wanted to send the following query to the endpoint http://ourserver.com:8080/EDG/tbl/sparql:

1SELECT ?continent
2WHERE {
3   GRAPH <urn:x-evn-master:geo> {
4      ?continent a <http://topquadrant.com/ns/examples/geography#Continent>
5   }
6}

You can add an escaped version as a query parameter value to the endpoint URL shown above, resulting in the following URL. The best practice is to use a URL encoding function to properly format the query for HTTP:

http://ourserver.com:8080/edg/tbl/sparql?query=SELECT+?continent+WHERE+{GRAPH+<urn:x-evn-master:geo>+{?continent+a+<http://topquadrant.com/ns/examples/geography%23Continent>}}

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:

1SELECT ?continent
2WHERE {
3   ?continent a <http://topquadrant.com/ns/examples/geography#Continent>
4}

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

http://ourserver.com:8080/edg/tbl/sparql?default-graph-uri=urn:x-evn-master:geo&query=SELECT+?continent+WHERE+{?continent+a+<http://topquadrant.com/ns/examples/geography%23Continent>}

As an alternative to those GET-style requests you may send a POST request with the query string in the request body and the optional default-graph-uri parameter.

Assuming that SPARQL UPDATEs have been enabled in the server administration pages, you can also use the tbl/sparql endpoint for UPDATE requests.

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>{<http://topbraid.org/examples/topquadrant%23TBEVN> <http://www.w3.org/2000/01/rdf-schema%23comment> "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>{<http://topbraid.org/examples/topquadrant%23TBEVN> <http://www.w3.org/2000/01/rdf-schema%23comment> "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.

Hint

A good way of learning the details of the SPARQL endpoint syntax is by using the interactive SPARQL Endpoint Page and look at the Network tab of your browser’s inspection tool.

Transforming Data

The Transform Tab lets users run various transformation operations that will modify an asset collection they are working with. This view and its operations are only available to users with editor or manager privileges for the collection.

Execute Inference Rules

Executes SHACL and/or SPIN rules that are defined for the current collection and asserts the resulting statements. Also, one has the option to revisit all previous rules executions to remove results that are no longer valid and bypass change history.

Copy or Move Instances from Other Asset Collection

Copies or moves assets from other asset collections. “Copy” adds instances of selected classes from another asset collection into this Taxonomy. “Move” will also update the source asset collection by removing the instances from it. Executing “Move” requires editing permissions for the source asset collection. This option is useful for separating your instance data from schema.

Delete Sample Data for Data Assets

For Data Asset collections that have sample data imported from data sources, this allows collection editors to remove or reduce the sample rows currently retained by the collection. This does not effect future imports.

Convert OWL Axioms to SHACL Constraints for Ontologies

This scans the ontology, either replacing any OWL restrictions or RDFS domain/range axioms with their corresponding SHACL shapes or simply adding SHACL shapes. This provides a starting point for the full use of SHACL as described in Working with Ontologies. It is recommended to create a workflow for this operation to verify its results before committing them.

See also

  • For the exact and up-to-date details, see the rdfs:comment items in the owl2shacl.ttl workspace file (path: <EDG-WORKSPACE>\projects\TopBraid\SHACL\).

Convert SKOS-XL Labels to Reified Values for Taxonomies

This feature will convert any instances of skosxl:Label to values of their corresponding direct SKOS properties:

  • skosxl:prefLabel is converted to skos:prefLabel

  • skosxl:altLabel is converted to skos:altLabel

  • skosxl:hiddenLabel is converted to skos:hiddenLabel

If the skosxl:Label has other properties than skosxl:literalForm and rdf:type then these values will be converted into reified statements. For example, if your skosxl:Label instances have values for ex:isAbbreviation and skosxl:prefLabel was used to point to the label, then there will be a reified triple attached to the skos:prefLabel statement to store these additional values. The ontology should define suitable node shapes that define the properties such as ex:isAbbreviation for display and editing purposes, and attach them to the property shapes of properties such as skos:prefLabel using dash:reifiableBy

Optionally, the original URIs of the skosxl:Label instances will be stored as reified triples and the property dash:uri which can then be used to restore the original skosxl:Label instances as part of an exporter.

Exporting Data

TopBraid EDG supports the export of metadata and data to JSON-LD, RDF/XML, N-Triples, Turtle, Turtle+, TriG, JSON, CSV, TSV and XML through pre-built functions, a SPARQL endpoint and a GraphQL endpoint.

Search and the SPARQL Query and SPARQL Results panels support the export of subsets of the data in an asset collection based on custom criteria and sorting. These panels provide fine-grained control over the selection of data. Menus in these panels offer several choices to export the results into spreadsheet-compatible formats (e.g., for Excel) as well as other formats.

Bulk export to AWS S3 can be done through the Basket (see Bookmarking Asset Collections and Assets).

Export Collection as an RDF File

Export <collection type> as an RDF File is available under the Export tab.

These operations support exporting a collection’s data in a standard RDF serialization format.

TopBraid EDG Export Taxonomy Options

TopBraid EDG Export Taxonomy Options

Sorted Turtle includes an extension that supports the TopBraid reification capabilities. Reified statements in EDG are converted to standard RDF Statements in the exported file.

Sorted Turtle+ is an extension to the standard Sorted Turtle that supports TopBraid’s reification capabilities known as “RDF-star” or “RDF*”. In this case, the serialization is Turtle+ and requires a Turtle+ parser in order to import the file.

See also

RDF-star is not yet an official W3C standard, but work on the specification is well under way. TopQuadrant is one of the contributors to the specification document. In the meantime, many of the RDF technology vendors, including TopQuadrant, already implemented support for this concept.

Browser interactions during export vary: the data may be directly displayed, via a kind of view source command or the browser might provide (on the link) a right-click menu option to save the link target to a file, without first displaying the link result in the browser,. prompting for the file location and name.

The export of multiple asset collections is supported by placing them into the Basket and then selecting Export to S3 option.

TopBraid EDG Export Asset Collections Using Basket

TopBraid EDG Export Asset Collections Using Basket

This requires that at least one S3 bucket is configured by the EDG Administrator. Once set up, select a bucket using Select S3 Bucket for Exports under the Manage tab. The export will run in the background and, once exported, files will be saved to the S3 bucket. This option supports specifying that the exported files be compressed.

Export Collection with Includes as a File

Export <collection type> with Includes as a File is available under the Export tab. Two formats for export with includes are available, TriG and Zip File.

TopBraid EDG Export to Trig or Zip

TopBraid EDG Export to Trig or Zip

With inferences options will add a dedicated graph named urn:x-topbraid:inferences, which has any triples inferred via SHACL or SPIN rules.

Note

Inferences are computed on-the-fly and therefore the export may be slow.

Publish for Explorer Users

On an EDG server that is paired with a TopBraid Explorer Server (for read-only access), managers can publish it to the Explorer for viewing.

Note

The workflows of all published asset collections might or might not be viewable, depending on the Explorer’s administrative configuration.

Any manager of an asset collection can control its Explorer publication status by selecting Export > Publish Glossary for Explorer Users. The view shows a Status drop-down for the asset collection, which indicates whether the asset collection was ever Published or not (Unpublished).

TopBraid EDG Publish for Explorer Users Status Options

TopBraid EDG Publish for Explorer Users Status Options

TopBraid EDG Publish Included Graphs Options

TopBraid EDG Publish Included Graphs Options

It also lists any included asset collections that might also require publication.

Ensure that all included graphs are either already present on the Explorer server or published along with the asset collection. Changing the status causes the following action.

Current Status

Chosen Option

Result

Unpublished

Published

Sends a copy of the asset collection and selected includes to the Explorer server. Changes the source collection’s status to Published.

Published

Update Published Copy

Re-sends a current copy and selected includes to the Explorer server, overwriting the previous version(s). Keeps the source collection’s status as Published.

Published

Unpublished

Deletes the asset collection on the Explorer server. Changes the source collection’s status to Unpublished.

GraphQL Queries

This options allows users of the collection to retrieve and modify asset collection data using new or saved GraphQL queries.

See GraphQL for details.

Asset Collection Specific Exports

These exports are only available for specific collection types

Export Hierarchy Spreadsheet

Export Hierarchy Spreadsheet is available under the Export tab only for Taxonomies collections. It outputs an entire taxonomy tree in a spreadsheet compatible format.

Export Concept Overview Spreadsheet

Export Concept Overview Spreadsheet is available under the Export tab only for Taxonomies collections. It outputs all taxonomy concepts in a spreadsheet compatible format. For each concept, this output includes every available property as a spreadsheet column.

Export SharePoint Term Store

Export SharePoint Term Store is available under the Export tab only for Taxonomies collections. It updates the SharePoint term store to reflect the current contents of a collection. All terms in the collection are updated.

Export Ontology as RDF Schema File

Export Ontology as RDF Schema File is available under the Export tab only for Ontologies collections. It produces a simple, approximated RDF Schema version of the current ontology in SHACL. The output in in Turtle format.

Export Ontology as OWL File

Export Ontology as OWL File is available under the Export tab only for Ontologies collections. It produces a simple, approximated OWL version of the current ontology in SHACL. The output in in Turtle format.

Export Crosswalk as Spreadsheet

Export Crosswalk as Spreadsheet is available under the Export tab only for Crosswalks collections. It creates a comma-separated spreadsheet containing one row for each mapping in a Crosswalk.

Export Avro JSON

Export Avro JSON is available under the Export tab only for Data Assets collections. It creates one or more Avro files in JSON format for database tables and allows users to select the tables to export.

Normalized Concepts

Normalized Concepts (Troubleshooting) is available under the Export tab only for Content Tagsets collections. It generates a normalized version of the Tagging vocabulary used in a Content Tag Set, as it would be seen by AutoClassifier (useful for troubleshooting). The output is in Turtle format.

Export to S3

Setup

TopBraid EDG Setup Options

TopBraid EDG Setup Options

  1. From Server Administration in EDG, configure your S3 bucket in External System Integration Management.

TopBraid EDG External System Integration Page

TopBraid EDG External System Integration Page

Choose authentication type appropriate for your organization. https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html#credentials-default

Test the connection after saving.

TopBraid EDG Test Connection Button

TopBraid EDG Test Connection Button

  1. In Product Configuration, select the bucket for the default location for S3 storage for your EDG application and save.

TopBraid EDG S3 Configuration Paraemeters Section

TopBraid EDG S3 Configuration Paraemeters Section

Using the S3 Export

S3 Export uses the Basket feature of EDG.

Add your collection(s) to the Basket:

TopBraid EDG Add Collection to Basket Dialog

TopBraid EDG Add Collection to Basket Dialog

Navigate to the Basket:

TopBraid EDG Navigation Bar with Basket Highlighted

TopBraid EDG Navigation Bar with Basket Highlighted

Check the collections you want to export and select Export to S3:

TopBraid EDG Export to S3 Options Highlighted

TopBraid EDG Export to S3 Options Highlighted

Version will be added from the version metadata in the collection automatically. Change any settings here and then submit:

TopBraid EDG Export to S3 Form

TopBraid EDG Export to S3 Form

The export will run in the background. An Administrator can check on the status through the Server Administration – Scheduled Jobs page. Once the job completes, it is no longer listed on this page. Success or failure is logged to Tomcat logs and also notifications sent (if enabled).

TopBraid EDG Scheduled Jobs Page

TopBraid EDG Scheduled Jobs Page

If email is configured on the EDG application, the user who submits the export will get an email notification when it is complete.

TopBraid EDG S3 Export Complete Email

TopBraid EDG Export Complete Email

The folders are automatically created in S3 for the type of collection that is being exported.

TopBraid EDG S3 Export Folders Page

TopBraid EDG Export Folders Page

Comparing Asset Collections

Comparison Report is available under the Reports tab. When used while in the context of a production copy of a collection, it compares the production copy of the current collection with the production copy of another selected collection. When used while in the context of a workflow, it compares the workflow and production copy of the current collection.

This report only compares information contained directly in the selected collection. It does not compare contents of included asset collections. The report lists each changed asset and properties that were changed, showing the changed values. If a value was added, it is shown in a green background. If a value was deleted, it is shown in a pink background. Selecting the asset link opens the edit form for an asset in the report.

The following figure shows report results for the example of the editing the preferred label property for “South Korea”, adding an alternative label, and a adding “Seoul” as a narrower value of the “South Korea” resource (renamed to “Republic of Korea”).

TopBraid EDG Comparison Report

TopBraid EDG Comparison Report

Combining Asset Collections

The Includes wizard is available under the Settings tab. It controls what other collections are visible in (i.e. referenced, not copied into) the current collection. The choice of collections to include is restricted to collection types that are either required or permitted for the current collection type.

Note

Includes are technically managed by setting the standard owl:imports property from one collection to another.

Includes Wizard

If a user wants to add an include via the Includes Wizard, EDG analyzes the direct permission assignments of the current collection, and compares these assignments to the collection we are trying to include.

If a non-administrator user or role has a direct assignment (teamwork:manager, teamwork:editor, teamwork:viewer - or direct governance role - data steward, etc) - on the current collection, but does not have the same direct assignment on the collection we want to include, EDG will report to the user that, if such an inclusion is added, some users may lose access to the current collection.

Include Conflicts

When this happens, the user is given a variety of options. They can generate a request to add a direct permission assignment to the graph we’re trying to include, or proceed anyway, knowing they may be locking users out. Managers of the collection we’re looking to update permissions on receive an In-app Notification informing them of the request.

Includes Wizard

The notification provides a link to the Users tab for the requested collection, where a view of all the open Permission update requests is shown.

Include Approval

When the request is approved by a manager of the collection, the user who made the initial request is notified via the same In-app Notification mechanism.

When all permission update requests are approved, ensuring no users will be locked out of a collection if the include is added, the requested include is applied.

Included-By is available under the Settings tab. It lists the other collections that include the current collection. The Included By list is derived from the inverse of the Includes that are set by users. It cannot be set directly.

Note

Assets that are included in the current collection cannot be modified but can be extended (i.e. a property value cannot be removed but a new property value can be added).

Configuring Asset URIs

Default Namespace

Default Namespace is available under the Settings tab. The default namespace is used to construct URIs (unique identifiers) for the assets in the collection. The default namespace was set when the collection was created but users with manager privileges can edit it at a later time. Changing the default does not affect any existing asset URIs.

URI Construction Rules

URI Construction Rules is available under the Manage tab. URI construction rules are first set when a new asset collection is created and this feature allows the user to change those rules. These override the default EDG-wide construction rules for the URIs for new assets created in the collection.

Changing the rules does not modify any existing asset URIs, they are only applicable to newly created assets.

EDG offers the following options for the local name part of the URI construction:

  • label – create URIs using the labels of resources

  • counter – generate and increment a numeric count when a new resource is created and use that in new URIs. A Counter Offset can be set, to avoid conflicts with existing counter-based URIs for example.

  • uuid – generates a new standard universally unique identifier (UUID) for use in each new URI.

Note

Using a UUID guarantees the uniqueness of URIs across the widest scope.

Additionally, users can specify that EDG to pre-pend the class name or class acronym to the local name. The Class acronym must be stored using edg:acronym property. All classes in the EDG models already have acronyms.

The user can also use specify here whether users can modify the EDG-generated URIs or not when creating a new asset.

Viewing and Creating Comments

If enabled on the EDG server, the Comments tab allows users to associate comments with asset collections and assets.

Note

The Administrator Guide contains instructions for how an administrator can enable the Comments activated configuration parameter.

Recent Comments

When viewing or editing information about an asset, the Comments button shows how many comments have been added to it. Clicking the button displays a dialog box where you can see previous comments and add your own under the “Add Comment” title; click the OK button when you are finished.

TopBraid EDG Comments View

TopBraid EDG Comments View

Comments have a status such as “open,” “declined” or “resolved.” The status of those can be changed using a drop-down list to the right of each comment entry. If you also have the TopBraid Explorer (Viewer) application, the display can also include comments from those viewers, marked with (via TopBraid Explorer).

To get a list of of the most recent 100 comments for a production or workflow copy, select its Comments management view. These comments can be filtered by status, for example, to only display the “open” comments.

TopBraid EDG Recent Comments View

TopBraid EDG Recent Comments View

When resources are deleted, their comments are not automatically deleted with them. These are known as “orphan comments.” If there are any orphan comments associated with a given asset collection, the Comments view will include a hypertext link saying “Delete the X orphan comments about entities that no longer exist,” where X is the number of orphan comments associated with this asset collection. Clicking this link will delete these comments. You may wish to keep these for historical purposes or auditing purposes.

Using Tasks in EDG

If enabled on the EDG server, the Tasks tab shows all tasks associated with an asset collection. Tasks can be created for an asset in a collection and for an entire collection. In addition to showing all tasks, tasks can be created for the collection as a whole in this view.

Note

The Administrator Guide contains instructions for how an administrator can enable the Tasks activated configuration parameter. An administrator can also activate a feature to Send task emails. When activated, users with an email address (e.g. via SSO) will receive emails whenever a task gets assigned to them, or if there is a change in the assigned task.

Creating Tasks

Tasks can be created for a single asset in a collection and for an entire collection:

  • When working with a particular asset, Explore > Show/Create Tasks… menu option lets you view existing and create new tasks for the asset.

  • The Tasks tab for a collection displays all the tasks in a collection - created for individual assets or for the entire collection. The task list for a collection can be filtered by status and assignee. The Create New Task button creates a task associated with a collection as a whole.

  • The dialog for creating new tasks, lets you enter task description and assign it to a user. New tasks are set to the “open” status. There is no delete option for a task, instead its status can be changed to “resolved”.

Changing Task Information

After a task is created, you will be able to set its due date. A user assigned a task can change its status and enter comments about the task. Users with manager privileges for the asset collection can re-assign the task.

Changes in the task information are displayed in the Change History section of the task view.

Using Protected Mode

Protected mode is a feature flag that can be configured either globally or per asset collection. When configured globally all Asset Collections with the exception of the Files and the Governance Model will be considered protected. When configured locally only the specified asset collection will be considered protected.

Protected Mode Explained

A protected asset collection can only be modified via workflows. This means that actions such as edit, clone, delete, SPARQL update, ADS scripts cannot be performed against the production copy. Simply stated the EDG interface will be presented as if the asset collection were read-only. However, features such as the ‘new’ button will be available on most panels that provide them and will guide the user through the process of creating a workflow for the new asset.

More information about workflows can be found at Understanding and Using Workflows.

Note

Protected mode is currently a feature of the user interface and not a feature of the server. However, protected mode will be expanded upon to include API calls in a future version.

Enabling Protected Mode

Enabling protected mode can be accomplished in two ways

    1. Globally (This setting can only be configured by a system administrator)

    • Navigate to Server Administration > Product Configuration Parameters

    • Select the Teamwork group

    • Find Protect Asset Collections on the view.

    • Set the value to ‘True’

Note

Globally applied protected mode does not apply to the Files or the Governance Model.

TopBraid EDG Server Administration Protected Mode

TopBraid EDG Server Administration Protected Mode

    1. Locally (This setting can only be configured by those that have the ability to Manage the Asset Collection)

    • Navigate to the desired asset collection

    • Open Manage tab

    • Select the Features group

    • Find the Protected item

    • Toggle the checkbox

TopBraid EDG Asset Collection Protected Mode

TopBraid EDG Asset Collection Protected Mode

Identifying Asset Collections in protected mode

Asset collections that are in protected mode will contain a ‘shield’ icon within the sub-navigation section of the editor.

TopBraid EDG Asset Collection Protected Mode Indicator

TopBraid EDG Asset Collection Protected Mode Indicator

Creating Assets in protected mode

Protected mode augments the typical asset creation flow by first requiring the creation of a workflow. This is accomplished by the addition of a wizard to the creation dialogs. The new wizard will instruct the user to first define a workflow followed by the usual asset creation forms. When possible the wizard will provide the full editor form for the target type, allowing the user to provide more information at creation time.

    1. Define a workflow

Select a workflow template from the dropdown and provide a label for the new workflow.

TopBraid EDG Protected Mode Wizard Step 1

TopBraid EDG Protected Mode Wizard Step 1

Note

Users will have the ability to select from all applicable workflow templates.

    1. Populate required fields

Populate the required fields to continue the process.

TopBraid EDG Protected Mode Wizard Step 2

TopBraid EDG Protected Mode Wizard Step 2

TopBraid EDG Protected Mode Wizard Step 2 Options

TopBraid EDG Protected Mode Wizard Step 2 Options

Note

Notice at this step the user has the ability to go Back, Create and Open Workflow, Preview, and Next. If the selected workflow template has the ability to freeze for review the wizard provides the action Create and Freeze Workflow.

    1. Preview

Once the user is far enough along in the process, the preview button will be available.

TopBraid EDG Protected Mode Wizard Preview

TopBraid EDG Protected Mode Preview

    1. Optionally fill out more fields

Provide additional information about the new assets. The presented form is derived from the chosen type.

TopBraid EDG Protected Mode Wizard Step 3

TopBraid EDG Protected Mode Wizard Step 3

Note

Providing more information is optional. The initial type and label cannot be changed as those where utilized to create the URI. However, additional types and labels can be added.

    1. Create and Open Workflow

The last step in the wizard is to Create and Open the Workflow. The user will be presented with a progress report as the wizard completes the steps of creating the new asset within the new workflow. Once complete the user will have the ability to directly navigate to the newly create resource.

Note

Do not close the dialog until the wizard is complete.

TopBraid EDG Protected Mode Create and Open

TopBraid EDG Protected Mode Create and Open

Using Jira Tasks

Jira Integration

Jira is Atlassian’s Web application for team issue-tracking. EDG’s Jira Launch-in-Context (LiC) feature allows users who are working in both EDG and Jira to launch from editing particular EDG asset items into related Jira searches and new items.

Users with adminstrator privileges can set up the EDG Jira feature - see the Jira Integration Configuration Section.

Jira Launch-in-Context

LiC requires that a user be logged into Jira and is logged into EDG using the same browser.

When editing an EDG asset, editors can use its gear menu to create or search for related Jira issues . This also adds a Jira link in the horizonal tab menu of an asset collection, which launches into Jira to show the configured project’s open items.

On the asset form panel, use the modify menu select from the Jira options as shown in the following figure.

TopBraid EDG Create and Search Jira Issue Dropdown

TopBraid EDG Create and Search Jira Issue Dropdown

The create option opens the start of a new Jira item. The searches open Jira in a new browser tab that search on the indicated resource string (URI or label).

Note

If the user is not logged into Jira (or if the Product Configuration Jira settings fail), then the launches can result in a Server Interaction Error message dialog. Please check the server logs for details in that case.

Jira Project Key

Jira Project Key is available under the Manage tab.

Note

This item only appears if the EDG server has been configured for Jira Integration.

If the EDG Jira feature has been administratively setup, then each collection manager can optionally set a Jira project key string for the asset collection, where the Jira-key identifies a specific project in the Jira application. Setting the project key then enables Launch-in-Context functions for collection editors. When editing any asset item, editors can use its gear menu to create or search for related Jira issues.

Setting the project key also adds a Jira link to the collection’s utility view header, which launches into Jira to show the configured project’s open items.

Working with Geo-Spatial Data

Enabling GeoSPARQL

Enable GeoSPARQL and Related Features is available under the Manage tab. It specifies whether GeoSPARQL and related features are available for the collection. If enabled then all SPARQL queries issued by the editor use a spatial index for the production collection and its imports.

Building the spatial index may consume time and memory, yet geography-related queries will be significantly faster.

Map Explorer Panel

This panel works with EDG’s GeoSPARQL support. In order to use the Google Maps panels, your EDG Administrator needs to set a Google Maps API Key in the configuration parameters page. Geo location information must use W3C vocabulary for representing latitude, longitude and altitude information in the WGS84 geodetic reference datum (namespace http://www.w3.org/2003/01/geo/wgs84_pos). The W3C vocabulary has properties for specifying geo coordinates.

TopBraid EDG provides the W3C vocabulary within its own Geo vocabulary that adds additional features for controlling map display. You will find it as an option in the Settings>Includes dialog by using Other as the collection type. If you do not see it in the dialog, click on the Home button in your asset collection and in the Source Code panel add:

owl:imports <http://topbraid.org/tbgeo>;

To make geo coordinate properties directly available to your resources, you will typically declare their types as subclasses of geo:SpatialThing class. As an example, you can look at the TopBraid Example Geo Ontology in the Asset Collections Samples project where this is already done.

The Map Explorer panel will display selected resources on the map using their geo coordinates – values of geo:lat and geo:long properties.

The panel can display items using markers of different types, sizes and color. This is controlled using properties such astbgeo:fillColor. It can also display shapes (e.g., polygons) as shown below. These features require inclusion of TopBraid GeoSPARQL Vocabulary (tbgeo: namespace).

TopBraid EDG Map Explorer - Germany

TopBraid EDG Map Explorer - Germany

TopBraid EDG Map Explorer - Switzerland and Austria

TopBraid EDG Map Explorer - Switzerland and Austria

Follow the below example to get started with the polygon display.

Create an Ontology, include TopBraid GeoSPARQL Vocabulary. In the class that will contain data to display on the map (e.g. Country), use Create or Add Property> Add an existing property definition (property shape): geosparql:Feature-hasGeometry. This defines the property hasGeometry that can hold instances of geosparql:Geometry and those can carry either a GML or WKT rendering of the polygon or multi-polygon. Mark geosparql:Geometry as a public class of your ontology (click the Home button and switch to GraphQL Schema View in the Form to do this) so you will be able to readily create its instances.

Create an asset collection based on your new ontology e.g., a Data Graph. Enable GeoSPARQL support on the Manage tab, Create an instance of geosparql:Geometry class. Using the Form or the Source Code panel, enter the information in the below example. Most data of this type will probably be imported.

Example:

ex:SwissGeometry
a geosparql:Geometry ;
geosparql:asWKT "MULTIPOLYGON(((7.697223 47.543327, 8.57642 47.59137, 8.566111 47.806938, 9.566724 47.540451, 9.533569 47.274544, 9.474637 47.057457, 9.598635 47.063835, 10.471235 46.871353, 10.465277 46.546387, 10.050278 46.539993, 10.129999 46.227219, 9.28194400000012 46.495827, 9.036665 45.837776, 8.43638800000014 46.463333, 7.855742 45.919052, 7.038054 45.931938, 6.79138900000015 46.434166, 5.966666 46.209442, 6.99055500000014 47.497215, 7.588268 47.58448, 7.697223 47.543327)))"^^geosparql:wktLiteral ;
.
ex:Switzerland
geosparql:hasGeometry ex:SwissGeometry ;
tbgeo:fillColor "green" ;
tbgeo:fillOpacity 0.8 ;
tbgeo:strokeColor "blue" ;
.

An example value in GML:

geosparql:asGML """<?xml version=\"1.0\" encoding=\"utf-8\" ?>
<gml:Polygon xmlns:gml=\"http://www.opengis.net/ont/gml\">
<gml:exterior>
<gml:LinearRing>
<gml:posList>13.833611 48.773605 14.70028 48.581379 15.025833 49.018883 16.946182 48.619064 17.166386 48.012497 17.053886 47.709442 16.450554 47.698051 16.713886 47.543884 16.510555 47.00666 16.111805 46.86972 14.544998 46.407494 13.718655 46.526611 12.440554 46.690826 12.127777 47.001663 10.471235 46.871353 9.598635 47.063835 9.533569 47.274544 9.566724 47.540451 10.173332 47.274719 10.478054 47.591942 11.095554 47.396111 12.735554 47.684166 13.016666 47.470276 12.758333 48.123886 13.833611 48.773605</gml:posList>
</gml:LinearRing>
</gml:exterior>
</gml:Polygon>"""^^geosparql:gmlLiteral ;

The values of tbgeo:fillColor, etc., can be dynamically computed using sh:values rules. The map will automatically update when (asserted) values for tbgeo:fillColor etc., change after edits, but this will not work for dynamically computed values.

Working with Document Attachments

S3 Buckets for Attachments

Once S3 buckets have been configured by an Administrator for EDG, you can select which bucket to use for attachments in this collection.

Attachments Panel

After configuring the S3 Attachments bucket and selecting the appropriate bucket from the Manage tab, the attachments panel will be accessible. Files can be added as an attachment to individual assets or the entire collection. Attachments will stored in the configured S3 bucket. These can be downloaded from the attachments panel as well. Removing them only removes them from the panel, not from S3.

TopBraid EDG Attachments Panel Page

TopBraid EDG Attachments Panel Page

Synchronizing Data with Git - not available for SaaS

TopBraid EDG Git Integration adds the ability to:

  • Import asset collections to EDG from Git repositories

TopBraid EDG Import From Git

TopBraid EDG Import From Git

  • Reload asset collection from Git repository

TopBraid EDG Reload From Git

TopBraid EDG Reload From Git

  • Commit asset collections to Git repository

TopBraid EDG Commit To Git

TopBraid EDG Commit To Git

  • Execute capabilities listed above as services for integration with workflows and/or other on-demand or scheduled jobs.

To use these features an EDG administrator must set up the parameters under Product Configuration Parameters Admin Page Git Integration.

Note

Git integration requires a local folder on the server that connects to a git repository.

Controlling Change History

Record Triple Counts only

Record Triple Counts only is available under the Manage tab. It disables recording change history at the level of individual triples for production copies. When activated, EDG only records summary counts of changed triples – added or deleted. This significantly reduces storage and memory impacts at the cost of losing detailed change information and the ability to undo (revert) the changes.

workflows and existing change history are not affected by this setting.

Archive Workflow on Commit

Archive workflows on Commit is available under the Manage tab. When true, workflows are archived automatically when a workflow is committed.

Note

The archive always contains the full history, regardless of the Record Triple Counts only setting.

Changes made in the archived workflows will not show up in the Change History after commit. Archived workflows continue to be listed in the Completed Workflows table on the Workflow tab.

The archives are stored in a special “archive” folder on the server. System Administrators can move or permanently delete the archived data so that it isn’t using up storage space when not needed.

Clear Change History

Clear Change History is available under the Manage tab. It removes the audit trail from the collection, meaning users can no longer revert a change using the editor form.

Over time, the change history about a collection can become very large adding to the workspace/database causing more memory to be used by EDG. In order to improve performance, users may want to periodically clear change history if it is not being used.

Note

This operation is not reversible. To recover cleared content, use backups.

Viewing Asset Collection Statistics

Statistics

Statistics is available under the Reports tab. It shows the number of triples in the collection and shows a count of instances of each class used in the collection, for verification purposes.

Viewing Configured Inferences

Property Value Rules

This shows what properties in the collection’s will be inferred through SHACL: sh:defaultValue or sh:values

The listing is organized by class. Rules for inferred properties are depicted diagrammatically.

Advanced Settings

Controlling Namespaces and Prefixes

Namespaces and Prefixes is available under the Settings tab. The namespace prefixes used in the collection, for use in SPARQL queries for example, are visible when this is selected. Users with manager privileges for the collection can edit them using Turtle notation.

Note

Although comments (#) are accepted, they are not preserved.

External Graph URI

External Graph URI is available under the Settings tab. It defines a URI for the collection for use during imports and exports. The Import RDF function automatically redirects any owl:imports statements in an imported RDF file to the collection in EDG with a matching External Graph URI. The Export RDF function for a collection with External Graph URI set uses that in the resulting RDF file rather than the internal Graph URI defined by EDG when the collection was created.

Limiting Search to Local Resources

Local Search Options is available under the Manage tab. This option is available only if the asset collection editor offers Search Panel. It determines whether users can select to ‘Return local results only’ on search forms.

When using Search Panel, there is an option, Return local results only, which excludes results that come from included asset collections. (A local search only delivers resources having their rdf:type triple in the current collection.)

By default, users can choose for themselves whether to enable or disable this local results option on any particular search. However, users with manager privileges can permanently set this option as either always local or always global for all users who will then see the setting on search panels, but cannot change it.

Configure Notifications

Configure Notifications is available under the Manage tab. For each asset collection, EDG can send notifications to users in specified roles when specific kinds of change happen. Notifications for each asset collection type can be configured for the EDG server. but users with manager privileges can override the EDG-wide defaults. In order to receive email notifications, the SMTP parameters in the System Configuration must be configured.

Clicking on the Configure Notifications link will display a page listing all available Notification Events together with check-boxes to select the governance roles that will be notified:

TopBraid Product Configuring Notifications Example

TopBraid Product Configuring Notifications Example

The association of users with the governance roles for a collection is configured via either Governance Areas page or directly for a collection on the Users tab.

See also

See The Governance Model and Workflows for more details.

Note

Workflows will also produce notifications after each step for each user able to move to the next state. Enable this in System Configuration -> Mail Settings.

Configuring Asset Collection Tabs

Configure Features is available under the Manage tab. It allows managers to selectively remove particular features from the user interface for the specific collection. Features that may not scale for large asset collections are marked with “*”. The removal of features from the UI might be desired to simplify the user experience or to prevent users using long running, high impact operations.

Note

Regardless of this configuration, all features remain available to EDG Administrators.

Setting Collection to Read-only

Read-only is available under the Manage tab. There are two options:

  • Everything which makes the collection read-only for all users. No edits or workflows are allowed in the collection.

  • Includes Only which makes included collections read-only for all users. Included assets cannot have new property values set for them, for example.

Setting Default Language

Default Language is available under the Manage tab. It specifies the default language code for new literals that will be pre-selected on forms. The user may select another language code in forms if multiple languages are configured for the EDG server.

The default language code in EDG are en ar de es fr it pt ru zh. These may have been changed by an Administrator or Power User on the Languages Configuration Section. Please check the language codes available on the EDG server prior to setting this field.