View or Edit
If $AorAnModel $ModelType is associated with some governance area, every user with any governance role in this are will be able to view it, at least. For any other user to view or edit assets contained in $AorAnModel $ModelType, a manager must use the $ModelType's utilities > Users settings (see documentation) to grant them permissions.
Note that different workflows that process changes to $AorAnModel $ModelType can have their own permission-profile settings (for background, see Workflow Overview: Permissions for Production Collections ...).
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 working copy managed by the workflow until and unless workflow changes are committed.
$ModelTypes use a tabular editor to view, search, and edit the instances of their selected classes.
The tabular editor shows three vertical panes: a central table of class instances and two collapsable panes, showing search (left) and instance details (right). The left and right panes can each be collapsed/expanded by clicking the cross-hatched control section in the center of the vertical separator/border column.
The left pane specifies filters or searches that determine the subset of class instances showing in the central table. The right pane shows details of the instance most recently selected in the central table.
The editor always reflects the structure of the selected class in the "Go to:" drop-down list of the page header, upper right.
The right side of the upper header bar has a view toggle button, which switches the table view to a hierarchy view:
The tabular editor can also show a hierarchy view, which has two vertical panes. The left pane shows a tree of the $ModelType's resources, and the right pane shows the details of the tree's selected item. The left-pane tree's hierarchy is structured according to a selected property (or inverse property) with the editor's selected class as its domain (or range). The following example shows the hierarchy view of the "has border with" property from a Reference Dataset's Country class. A hierarchy shows up to 1000 nodes. The star button saves the currently selected property as the default hierarchy for all users.
Again in the right header bar, the view toggle button allows switching back to the table view:
Viewing and Editing Information about an Asset
Information about selected asset is shown in a form, with fields organized organized into groups. To get to the details form, double click a row or select a row and click the details button.
Checking data quality via Problems and Suggestions
When the Show Problems and Suggestions buttonat the top of the form is selected, form will display any issues that are found with the selected resource together with suggestions on how to fix them. It will also display some additional facts TopBraid EDG finds with some degree of certainty - for example it may suggest a connection between a data element and a business term. You can then accept the suggestion or ignore it. When the Show Problems and Suggestions button is de-selected, checking of values and making suggestions will happen only when information is modified and saved or when a user decides to run Problems and Suggestions report for the entire collection. This setting acts across all of the user's collections.
Editing Information about an Asset
The default viewing mode shows only the properties of an Asset that currently have values.
Users with sufficient permissions can edit information in two ways: (1) per individual property via the pencil iconthat pops up as the cursor moves over a property; (2) all information on the form by pressing the Edit button at the top of the page.
Clicking a property's popup pencil iconlets you edit "inline" values of that property.
The Edit-buttonopens all available properties for editing. Showing fields that have values and those that do not yet have values.
click to enlarge
The Edit-button mode also lets you log a message with the saved changes.
NOTE: When finished with Edit mode, be sure to click either the Save Changes or the Cancel button.
The Show History checkbox at the top of the page toggles the display of all saved changes made to the asset since it was first created. It lets you to undo or "revert" the changes back to what they were previously.
Displaying Relationships with NeighborGram and Class Diagrams
One can visually browse a resource's relationships to other resources (classes and instances) in an interactive graphical view called a NeighborGramTM. To launch this view from a resource's details pane, select the gear buttonand select the Display NeighborGramTM... item. The views opens in a new browser tab.
When a resource node has many relationships, they will be shown in disjoint groups that are "pageable" via a selector with arrows and a counter. Selecting a node shows popup controls for making it the central resource, configuring links, or expanding links.
The form in the right pane shows details of the central resource. When that resource is a class, the form shows a Class Diagram section. Selecting that section link opens a nested form showing the class's associations in a UML-like diagram.
If the JIRA LiC feature has been configured by an administrator, then for each asset collection, a manager can set an associated project-key string via Manage > JIRA Project Key (see documentation). Then, when the collection's editors are simultaneously logged into JIRA, they can launch from editor resources into related JIRA searches and new items in the collection's corresponding JIRA project. On a selected resource, use the gear button in the details pane to select any of the following: Create JIRA Issue, Search URI on JIRA, or Search label on JIRA. The two searches will open (as browser popups) JIRA pages that search on the indicated resource string (URI or label). The create option will open the start of a new JIRA item. Note that if the browser is not logged into JIRA (or if the administered JIRA settings fail), then the launches can result in a Server Interaction Error.
Search Within $AorAnModel $ModelType
To search for instances of the selected class, expand the Search pane (left-column toggle). There are two search modes: faceted and form-based. This describes the faceted search mode.
The top search field does a general string search on the instances. The Add Property selector lists available class-properties, by which you can filter the class instances in the table. Each selected property has an arrowhead toggle to expand/collapse the property's distinct instance-values and their counts. Selecting property values restricts the table results to matching instances. One can do sophisticated searches of the instance data by using different combinations of properties and their values.
Selecting Return local results only will deliver only resources whose rdf:type triple is in the base graph, thus excluding resources from included graphs. This search option will be presented if the vocabulary/asset manager has not pre-selected a choice.
Reloading the browser page will reset the search query and results table.
Note that the set of properties appearing as columns in the results table can be selected in advanced form-based search.
Basic Search Form
The basic search form provides many options in how you search and what you can do with your search results. For the selected class, the search form has a field for each property that you can add to it using the Filters dropdown in the upper right of the form. One can use a combination of fields to match instances only on those properties. Properties with two hyphenated fields allow one to search on a range of values. The Search any Text field matches on any property of an instance (See the Configuring Search Text Properties section in the Developer Guide for how to add this field to the search form for a given class and configuring which properties it should search). Each resulting instance must match all of the form's user-entered values (AND operator). Selecting Return local results only will deliver only resources whose rdf:type triple is in the base graph, thus excluding resources from included graphs. This search option will be presented if the vocabulary/asset manager has not pre-selected a choice.
For each property, one can specify the type of match. Different properties can use different match types, all combining together to produce an overall search result.
|Type of Match||How a search value matches instance property-values|
Text DEFAULT: Search text is a substring of a property- value (case-insensitive). Example: Search text "lis" on a city-name property would match instances having city-name values such as "Lisbon", "Lisboa", and "Minneapolis".
|text equals||Search text is exactly the same as a property- value (case-sensitive)|
|text matches regular expression||Search text is a regular expression that matches a property-value (case-insensitive). Example: Search text "^lis" as a regular expression matches city-name values that begin with "lis", e.g., "Lisbon" and "Lisboa" but not "Minneapolis". Conversely, "lis$" would match only at the name's end.|
|any value||At least one value exists for the search property (count >= 1). Example: See how extensively a property is used.|
|min/max number of values||The number (count) of property-values (occurrences) is within the search range, inclusive. Example: If most instances in a $ModelType have labels in three languages, entering a label search with values-range 0 to 2 would return those instances with fewer.|
|no value||No values exist for the search property (count = 0). Example: Use to clean up a $ModelType and check for remaining work.|
|boolean||Boolean DEFAULT: Search values restricted to true/false instead of free-text|
|equals||Class DEFAULT: Quick-search field for finding an instance of the property (object)|
|nested form||Adds an embedded search form for properties whose type is another class|
|label matches regular expression||Search text is a regular expression that matches the label of a property-instance (object)|
Searching by relationship values
As you start typing a value in a relationship field, you will get a list of autocomplete options that match the text you've typed so far—a list of the names (labels) of any entities that begin with the typed letters.
The triangle next to each relationship field displays a menu that gives you several options for how $ProductAbbrevName uses the value you enter in that field to search your reference data. The options are similar to the ones described above with a couple of exceptions: regular expression search is not available, but there is a nested form search option:
nested form displays a form denoted in dark gray where you can describe specific details about the items with the specified relationship to the data you're searching for.
label contains indicates that you want to search for codes that have the entered string anywhere in the label value for this resource. For example, if you search market identifier codes whose mic Country property has "land" in it, $ProductAbbrevName will return resources with values such as Thailand, The Netherlands, and Switzerland.
any value indicates that you want to search for codes that have any value at all for this property.
min/max number of values search for any code whose number of values for this property fall in the range specified by the one or two numbers you enter.
no value indicates that you want to search for resources that do not have a value set for this property.
Displaying Columns in Results Tables
Columns in the results table are configured by properties
The columns displayed in the central results table are determined by a setting on each property in the search form. The display selector is located between each property's label and search field(s), and the display setting is independent of whether the property is used in a search.
|This property will appear as a column in the results table|
|... (ellipsis)||This property will not appear as a column in the results table|
This property will appear as a count column in the results table (showing the number of property-values)
To change the table's columns, select or unselect fields in the search form (also see: gear-button > Unselect all columns, below) and then press the Search button. The order of properties in the form determines the column-order of the table.
Setting the default columns
In subsequent editing sessions, the column settings will revert to their defaults. However, a manager can reconfigure the default for all users by selecting the columns and then clicking on the star buttonat the bottom of the Search form. This preserves the current settings as the new default for all users.
A recommended practice is to set default columns (properties) on an ontology class, which is subsequently included by other vocabularies or assets, such as reference datasets. The resulting instance tables will have the ontology class's column settings as their initial default, which can then be overridden if desired.
Search Results Operations
The gear menubelow the search form gives you several options for what you can do with search results:
Batch edit search results... lets you edit property values for all the search results together. See Editing multiple codes together for further information.
Display chart of search results... generates a chart of your search results from your choice of formats.
Export results to SPARQL CSV spreadsheet creates a comma-separated value version of the search results that includes the URI of the resource represented by each result row in the first column. See the W3C SPARQL 1.1 Query Results CSV and TSV Formats standard for more details (although there aren't many more details—it's a very simple format).
- Export results to SPARQL JSON file creates a text page of results in SPARQL Query Results JSON format.
- Export results to SPARQL TSV spreadsheet creates a tab-separated value version of the search results that includes the URI of the resource represented by each result row in the first column. URIs are delimited by angle brackets.
Export results to SPARQL XML file creates an XML version of the search results that conform to the W3C SPARQL Query Results XML Format.
Export results to simple TSV spreadsheet creates a tab-separated value version of the search results, showing the preferred label of each resource instead of URIs. This creates a more human-readable version of the data than the SPARQL TSV spreadsheet.
Open faceted search dialog... displays a dialog box that lets you do a faceted search over the reference data for the selected entity.
Show SPARQL query... displays a pop-up window with the query that is being generated on the server when the search form is executed. Advanced users with knowledge of the SPARQL query language can copy and paste the resulting query string into a SPARQL execution window (for example, using TopBraid Composer) or send the query to the TopBraid Live SPARQL endpoint.
- Unselect all columns clears all selected columns (check-marked or hash-counted) in the form, which removes all non-default columns from associated search-result tables.
Exported search results will be displayed in your browser. Select Save As from your browser's File menu to save the results as a text file.
Spreadsheet programs such as Excel can easily read tab-separated value files, so saving search results in a tab-separated format is a simple way to create custom reports for people with no access to your $ProductAbbrevName installation.
Editing multiple results together
After executing a search with the search form, the Batch edit search results choice on the search form's gear menu lets you edit all the search results at once with a single form.
For example, when selected after searching for all country codes that became valid in 1991, this menu choice displays the following form in a dialog box:
The form displays only values that all of the results have in common - in this case only the value for the "valid since" property. If you change this value, the change will apply to all resources in the search results. Any new values you will add will also apply to all search results.
Common values can be deleted all at once by clicking the X to the right of the value on the batch edit form, and new values can be added by entering them the displayed fields before clicking the Save Changes button.
In the lower-right of the search pane, two buttons let you save and retrieve searches for later execution. In addition to executing these searches from within $ProductAbbrevName, the saved search servlet lets other applications execute saved searches by using the appropriate URL. The "Save current search" buttondisplays a dialog box where you enter a name for the search that you'd like to re-use later. The "Show saved searches" button displays a list of saved searches.
This dialog box has three buttons at the bottom:
The Select button closes the dialog box and fills out the search pane with the parameters set by the selected search so that you can execute it.
The Delete button deletes the selected search from the list of searches.
The Close button closes the dialog box.
Selecting a saved search on this dialog box also displays a URL in the Service URL (for copy and paste) field that can be used to retrieve the search results from another application that has HTTP access to $ProductAbbrevName. This can be a browser, Excel (after picking Open from the File menu), or any application that can make a RESTful API call. (The default format of the returned data is comma-separated values, but this can be modified in the URL.)
Saved searches will also be available on the Export Saved Search list available via the Export tab.
Table of Class Instances (Search Results)
The table pane has all the instances resulting from the search query. It also allows creating, deleting, and batch-editing selected instances. The most recently selected table instance (row) appears in the instance-details pane, for viewing and editing its properties and relationships.
Clicking a property name at the top of the Search Results sorts the results by the values in that column, and clicking the same name again sorts again in reverse order.
To create a new instance, click the Create <Classname> iconin control bar (top or bottom of table pane, which might require scrolling). To delete one or more instances, click their check-boxes and then click the delete icon . Note that deletion might be restricted for certain vocabularies/assets, such as a Reference Dataset with status "in use".