Skip to end of metadata
Go to start of metadata

Table of Contents

TopBraid Enterprise Vocabulary Net — Server Administration

This document covers the administrative functions of the TopBraid Enterprise Vocabulary Net (EVN) application. In the web-based interface, administrator-users can access the EVN (home) > Server Administration link in the page-header. See details of the AdministratorGroup in Access to the Server Administration page.

Initially, all users will have permissions to all EVN resources and functions via the default assignment of AdministratorGroup to ANY_ROLE. An administrator's initial task should be to use Permission Group Management to transfer the AdministratorGroup from ANY_ROLE to their organization's defined administrative role(s). See Permission Group Management: Access to the Server Administration page for details.

Controlling User Access

User access for TopBraid EVN is determined by a users affiliation with security roles.  Security Roles are derived from one of two places:  LDAP (including Active Directory);  tomcat-users.xml (Tomcat local users file).

User Access for TopBraid Servers

TopBraid EVN relies exclusively on the Tomcat authentication. Tomcat supports a few authentication methods, with the most common being LDAP authentication or an in-memory authentication file (tomcat-users.xml).

LDAP

Please refer to LDAP Configuration

Tomcat users

See the Configuring Authentication section of the TopBraid EVN Installation Guide for more on this.

Administrative Functions

The Administrative Functions section contains links to a set of pages that provide administrative features, such as configuration, server information, cache control, access controls, etc.

Base URI Management

Displays all projects and all registered graphs in the TopBraid workspace. Each graph will have a base URI (the graph name) and the file name in the project's workspace. If there is more than one file with the same graph name (base URI) a Warning icon will be displayed. Information icons indicate projects and graphs that import missing ontologies not registered in the workspace. These can be ignored if the system is expected to get the graphs form the web using the base URI (graph name).

Server Configuration Parameters

To configure parameters for the TopBraid server platform and integrations, see Administrative Functions: Server Configuration Parameters.

EVN Configuration Parameters

To configure the application's data persistence, vocabulary/asset types, notifications, etc., see Administrative Functions: EVN Configuration Parameters.


Custom Configuration Parameters

This page displays customer-specific, custom variables that are not part of off-the-shelf TopBraid solutions. These are commonly used in installation that have multiple environment, such as DEV, SIT and PROD. Initially, the page contains only the instructions for creating a file in TopBraid Composer, how to create custom properties, then upload to a TopBraid server. Once the custom environment variable property is defined, the Custom Configuration Parameters page will display the defined properties. The following image illustrates that the variable 'myEnvVar' is defined using the steps stated on the Custom Configuration Parameters page. Property values can then be entered, such as 'HelloWorld' in this image.

After the 'Save Changes' button is clicked, the variable will be defined in the Graph defined by following the instructions. The page also shows how to access the variable value via a SPARQL query.

Auto-Complete Management

This lets an administrator manually rebuild the search indexes used for GUI auto-complete and quick-search fields. This may be (rarely) needed in case an auto-complete gets corrupted due to updates outside of the control of TopBraid, or due to other unforeseen situations.

Cached Graphs

The Cached Graph page allows a user to reset a graph's cached triples if they become out of synch with the version in the backend storage. This may have happened, for example, if the backend version has been modified by another user or process. This is common when using TopBraid Composer to modify data on the server.

The Cached Graphs page also includes the SDB Vacuum button, which deletes rows from the nodes table in the relational data store behind SDB if those rows are no longer connected to other data. Use with care; the text on the screen explains this further.

If Cache all graphs is unselected, a Cache at startup checkbox will appear in each row to let you decide which graphs shouldn't or shouldn't be cached at startup.  If Cache all graphs is selected, all SDB graphs are cached upon system restart. 

Password Management

Users with privileges to view the Password Management page can add, delete, or edit the password entry in the secure storage. The "Add Password" button lets users add the password, and when the entry is selected, the user then can change the password for that entry or click the x to delete that entry.

The Password Management page manages the contents of Equinox secure storage, which defines an encrypted file indexed by a URL and user id and storing a password encrypted by the secure storage password and the key. This means in particular that if the user id or URL changes for a given entry, the password must be re-entered using this page or any other sources for secure storage entries.

There are two sources for secure storage passwords:

  1. Checking the "Send necessary connection credentials" in TopBraid Composer's Export > Deploy project to TopBraid Live Server. This sends the contents of the Composer user's local secure storage to the server's secure storage. This is necessary when one is deploying a project from the IDE (Composer) that may contain passwords for connector files, SPARQLMotion scripts, etc. Note that to transfer the data form Composer's secure storage to the server's secure storage requires unencrypting Composer's secure storage and sending the content in plain text. For full security, use https when performing a deploy that includes "Send necessary connection credentials",
  2. Using this page.

Password Management

Permission Group Management

This page provides a way to manage access controls to TopBraid assets such as graphs, files, Eclipse/Equinox projects, and web services. Access control groups are defined for the role that's specified in Tomcat Realms, such as LDAP, LDAP/MS, Active Directory or Tomcat's in-memory user database (conf/tomcat-users.xml). Each group can define access control to different kinds of assets. Asset permissions can be Create, Read, Update, Delete and Execute. For example, a graph can be specified with CRUD access, whereas a SPARQLMotion script should have CRUD+E, and an exposed web service should only have E access.

For details in configuring permission group management, please refer to TopBraid EVN Permission Group Management.

Role Management page

Role Management

Users with privileges to view the Role Management page can use it to define vocabulary access policies by assigning users to roles such as viewereditor or manager of one or several vocabularies (reference datasets, ontologies, crosswalks) along with their working copies. The scope of these roles is limited to EVN and does not extend to TopBraid Live.

A role assignment associates a user to a role for a vocabulary. The first three sections of the page let you define, remove or replace such assignments of a specific user for all the vocabularies available in EVN:

The sections below let you define or remove assignments specific to each vocabulary:

In the following, the Administrator and Jane Smith have been assigned an editor role for the Enterprise Ontology vocabulary, and JimHarrison is being assigned a viewer role for the same vocabulary:

Note that roles are modular and thus can be assigned roles like users.

Server Information

Information about the copy of Enterprise Vocabulary Net being used and the system on which it is running.

OSGI Bundle Information

A list of the Open Services Gateway Initiative (OSGI) bundles (Eclipse plugins) in use and their release numbers.

Available Web Services

Selecting this displays a page that lists web services available on this server. Selecting the checkbox next to any of these names displays documentation below the list about how to call that web service.

      

Product Registration

This page displays any previously entered license information (for example, the number of users or expiration dates). User can now update the registration with the license keys obtained from sales@topquadrant.com. To register your product simply click the "Change or Update license" link, this will display a button which will allow you to upload your license key. Once uploaded your license key file will be validated and registered for you. Note: prior to 4.5.0 numeric license key files were used, if you still have one of these license key files they were deprecated as of 4.6.0, you will need to contact sales@topquadrant.com to get a new license file.

License Registration File

Project Upload

This menu choice lets you add a project developed elsewhere (for example, a local copy of TopBraid Composer Maestro Edition) to run on this server. The Project Upload page gives you a field to identify the zip file of the project you're uploading. To create the zip file, zip up the project folder within the development machine's workspace, including the .project file created by Eclipse.

Project Delete

This menu choice lets you delete projects from the server. Selecting it lists projects on your server, with Show buttons for each and Delete buttons for projects that are not part of the default installation of your server.

The Show button lists User Applications and User Sessions for that project, and Delete deletes the project.

Send Project to Another Server

This page lets an administrator send a project from the currently running server to another server. Users can select the project from the list of projects presented. If the "Also send database triples" checkbox is selected, it will also send the triples from the source SDB to the destination SDB; if it is not selected, the SDB connection files will still be sent over but without the triples. If the "Send UI configurations" checkbox is selected, it will then send the UI configurations file from server.topbraid.org/dynamic/uiconfig; otherwise, the default uiconfig file will be used at that location. For details of other methods to deploy project to server, please refer to Methods to Deploy Projects to Server.

Send Projects to Another Server

Provide secure storage password

Enter here the Master password that EVN uses to encrypt its secure storage (e.g., for database passwords). This is an alternative to storing the Master password in plain text in the server's web.xml file.

Memory Management

A detailed report on current memory usage. The report includes a link that lets you request garbage collection to clean up the memory.

Query Management

A report on currently running queries. For each query, this shows an internal ID, the query itself, the source (for example, the server's SPARQL endpoint), the duration so far, and a button that lets you abort the query.

TBL Log

Accesses the TopBraid error log, including warnings and errors from the Web application container (for example, Tomcat).

Log of SPARQL Function Calls

This screen lets you start, stop, clear, and refresh the logging of SPARQL function calls, as shown below. This can be especially useful when debugging applications under development.

Administrative Functions: Server Configuration Parameters

Server Configuration Parameters has three sections: Server Configuration, User Interface Configuration, and Download Configuration Files.

Server Configuration

This is the first and most prominent section. The section's Edit button opens all of the property values for changes. Be sure to click Save Changes when finished.

Server Parameters

NameDescription
Server URLThis must be a localhost URL, and needs to have another /tbl added to give the main page.
Show Hidden FilesDuring data selection, show all the files that are present on each project.

General Database Parameters

NameDescription
Max Connections per DatabaseFor each Apache Jena SDB or D2RQ database, the maximum number of active connections permitted.

SWP Parameters

NameDescription
Constraint violations block editingIf true then the SWA edit forms will report those SPIN constraint violations marked as spin:Error or spin:Fatal as errors that cannot be OKed by the confirm dialog. By default (false), all SPIN constraint violations are non-Fatal are reported as warnings that the user can manually bypass.
ui label function URIThe URI of a SPARQL function that takes a resource as argument and returns a string representation. If set, this will be used whenever ui:label is called, making it possible to define custom label algorithms in a single place.
ui link baseThe server URL to prepend in calls of ui:createLink. If set, then ui:createLink will create absolute URLs.
ui:lib function is constantTrue to have ui:lib() always return the static value "lib".

LDAP Server Parameters

NameDescription
Connection URLLDAP server connection URL
Username for server connectionConnection Username
User pattern stringUserpattern
Role definition baseRolebase
Role name identifierRolename
Role search stringRolesearch
Use long lived connection to LDAP serverUse long lived connection to LDAP server

SMTP Parameters

NameDescription
SMTP Authentication OnTells if smtp server requires authentication.
SMTP ServerSmtp Server to be used for sending emails in TopBraid Live.
SMTP Server Port NumberPort used by smtp Server.
SSL EnabledIf SSL for mail is on
SMTP UsernameUsername for authenticating on smtp server.
SMTP PasswordPassword for authenticating on smtp server.

Advanced Parameters

NameDescription
Allow Anonymous AccessIf no authentication scheme is used and this flag is true, anonymous access with READ and EXECUTE permission is allowed to the application.
Enable SPARQL updatesIf true, then the SPARQL end point (servlet) will allow update requests.
Timeout on SPARQL EndpointIf not set or 0, SPAQL endpoint has no timeout. Timeout is in ms. If it's reached, the system will throw a CancelQueryException to the user.
Enable Fair LocksIf true, then locks taken by TBL will use a first in first out queue, if false then order is less predictable.
Longer Stack TracesCreate longer stack traces, adding very large overhead. These are very useful for rapid resolution of certain types of problems. Set this parameter only if requested by TopQuadrant Customer Support.
Fail With Error on Design InconsistencyWhen a possible software design inconsistency is detected, fail with an error.
Disable URL graph loadingIf true, then imported URI that is not found in the workspace will not be loaded from the web.
Enable Query Management PageEnable the query management functionality to monitor currently running query in the system.
Secure Storage encryptionChoose different encryption algorithm for storing your passwords in the secure storage file. Default is 'PBEWithSHA1andDESede', if you choose to change it, please use a new secure storage file and restart the server.
Suppress Warnings of Possible Design InconsistencyWhen a possible software design inconsistency is detected, and the system is not configured to fail, then suppress the warnings. Setting this parameter to false will result in logged error message of any design inconsistencies.
Temporary Graphs Time OutThe length of time to wait before a temporary graph can be garbage collected (minutes).
Time before a TDB diskflushAny TDB with changes made but not yet written to disk will be flushed to disk after this number of milliseconds
Use SaxonUse Saxon rather than Xalan for XSLT/XML processing.
Verbose loggingIf true, then some operations will send additional info to the log. This may slow down the server a bit.

URI mappings

NameDescription
Short Graph nameA tuple consisting of a graph (URI) and a short name. Can be used to abbreviate graphs in servlet calls. For example the SPIN template servlet handles abbreviated names such as /tbl/template/swa/GetResourceValues/kennedys?... If you want to address the kennedys ontology with that URL, you need to add a short graph name that associates http://topbraid.org/examples/kennedys with the name "kennedys".

User Interface Configuration

Some TopBraid EVN features support assigning language tags to string attribute values using a drop-down list when editing, for example:

 

To customize the list of available choices, go to the Server Administration page, then Server Configuration Parameters. The bottom of the Server Configuration Parameters screen has a space-delimited list where you can enter the language choices that will appear on EVN editing screens. Any codes can be entered, but the codes will interoperate better with other systems, such as Web browsers, if the ISO 639 language codes and, optionally, ISO 3166 country codes, are used. In the following, ISO codes for Spanish, English US English have been entered. These will be the only languages that appear in the language tag drop-down:

 

Be sure click Save Changes when finished.

Download Configuration Files

                                                                   

NameDescription
Download general config graphClick this link will download the current config.ttl from the system folder.
Downoad uiconfig graphClick this link to download the current uiconfig.ui.ttl from the system folder.

Administrative Functions: EVN Configuration Parameters

EVN Configuration Parameters are accessible from the Administrative Functions page, and consists of sections for Server Configuration, Tagger Content Graphs, Tagger Property Graphs, Configure Vocabularies/Asset Types, Default Notification Setup.

Server Configuration

Teamwork Platform Parameters
Repository projectSee persistence technology, below
Viewers cannot create working copiesBlocks users with only viewer access for a vocabulary or asset from creating a working copy of it
Comments activatedAllows comments on data resources
Tasks activatedAllows user tasks on data resources
Send task emailsUsers with an email address receive email when a task is assigned to them
Active database typeSee persistence technology , below
AutoClassifier Configuration Parameters
Maui Server URLThe URL (with, if necessary, the port number and path) of the server running the Maui auto classifier, e.g., " http://myserver.org:8080/mauiserver/ ".
Maui Server user nameMust be specified if Maui Server has been configured to require a user name and password (via the HTTP Basic Authentication protocol).
Explorer Parameters
Explorer serverURL of an EVN Explorer server to upload files to when a vocabulary is being published.
Explorer server anonymous accessTrue if the EVN Explorer server does not require a user name and password.
Explorer server user nameUser name for authentication on EVN Explorer server.
Editor serverURL of this EVN Editor server that will receive the feedback from published vocabularies. Needs to be specified on the editor server which will send this info to the browser server when a vocabulary is published, basically pointing to itself. Must end with /swp, e.g. " http://myserver.org:8080/tbl/tbl/swp ".
Editor server user nameUser name for authentication on EVN Editor server.
MarkLogic Configuration ParametersSee persistence technology , below
SDB Configuration ParametersSee persistence technology , below

 

Configuring the persistence technology for new vocabularies and assets

To create new vocabulary or asset models, EVN needs a persistent store for the RDF graph data. This requires an EVN administrator to configure the persistence settings according to the customer's environment.

If these settings are ever incomplete (e.g., post-installation), EVN users will receive the following page.

To resolve this, an administrator must configure some Teamwork Platform Parameters for (1) the name of EVN's own project within the EVN workspace and (2) the persistence technology for storing the RDF graph data. The persistence technology can be one of these options:

Open the EVN view: Server Administration >  EVN Configuration Parameters, and in the System Configuration grouping, click the Edit button. In the Teamwork Platform Parameters section, configure the following parameters:

  • Repository project: (Default value:  Repositories NOTE: The name may not contain spaces.) This is the name of the project (subdirectory) in the EVN workspace that is used for connectors of the EVN-created vocabularies or assets. If the project does not exist, it will be created.

  • Active database type: Select one of the options: SDBTDB, or MarkLogic.

TDB requires no additional setup or parameters. SDB and MarkLogic each have an additional required section: SDB/MarkLogic Configuration Parameters for their external database server.

ParameterDescription
(BOTH) URL

The URL of the relational database. For example, for SDB, jdbc:oracle:thin:@localhost:1521:delphi, where delphi is the name of the instance, or jdbc:mysql://localhost:3306/myDatabase. The database with that name must already exist on the database server. (In the latter case, the myDatabase database must already exist on the MySQL system.)

Common formats for the SDB URL include:

jdbc:mysql://<server>/<database>
jdbc:oracle:thin:@//<server>:<port>/<service>
jdbc:oracle:thin:@<server>:<port>:<SID>
jdbc:sqlserver://<server>[:<port>][/database][;property=value]

(BOTH) user nameDatabase username. NOTE: The password will be entered after Save Changes is clicked.
SDB database typeSelect the supported type of relational database being used.
SDB Update Batch SizeOPTIONAL: This is the number of rows written to the SQL database in each batch. If unset, then 1000 is used. Adjusting it might improve bulk insert performance.
SDB Update Fetch Size

OPTIONAL: The number of rows returned from the SQL database on each network round trip. Certain values have certain meaning to difference database types. Not all databases use this value.

NOTE: Leaving the Batch and Fetch sizes unset should generally yield acceptable loading/caching performance. Each can be fine-tuned for a particular application by adjusting it up or down and observing the performance changes.

Click Save Changes at the bottom of the configuration section.

Supply the password if necessary, and use the Save button (do not use Enter; if an error occurs, re-Edit the System Configuration group).

For the either the relational SDB or the MarkLogic parameters, the corresponding database must already exist before a user can use the web-based EVN interface to create a new vocabulary in that database.

For more information on deploying projects from TopBraid Composer to TopBraid Live, see TopBraid Composer > TopBraid Live Integration (ME) > Overview of TopBraid Live Integration in the TopBraid Composer online help.

Example: Using MySQL to store data

EVN can be configured to store its data in MySQL, the free relational database management system. Installing MySQL with all the default settings lets you get up and running with EVN if you do not have one of the other relational database managers that supports the Apache Jena SDB interface available.

Going to the MySQL download page will display the installation packages for the operating system where you are running your web browser. As part of the installation procedure, you will be asked to supply a password to go with the root login name. Because configuring EVN to use an SDB database requires you to specify a username and password for access to the database where the data will be stored, you can use root and the password that you assign in this step.

Once the MySQL server is up and running, create an empty database for EVN to store its data. From the MySQL command line client program (which requires the password you assigned to start up) you can enter the following to create a database named myDatabase:

create database myDatabase;

After pressing Enter, enter the following to close the command line client, and the MySQL installation will be complete:

quit;

Next, configure EVN as described above.

Tagger Content Graphs

When licensed for EVN Tagger, this section lists all content graphs that can be used in the Tagger application. Content graphs contain resources that are tagged in EVN Tagger, i.e. the subjects of the subject-predicate-object tag triples. All RDF graphs in the workspace will appear here, except for those found in system projects, such as TopBraid, teamwork.topbraidlive.org, server.topbraidlive.org. When checked, the change is saved, and the graph will be available when creating new Content Tag Sets in the EVN Tagger application. Unlike the first section of this page, there is no Save button. For additional discussion of these settings, see the EVN Tagger User Guide: Configuring content and property graphs.

Tagger Properties Graphs

When licensed for EVN Tagger, this section lists potential graphs that can provide property types used for tags in Content Tag Sets, i.e. the predicates of the subject-predicate-object tag triples. When checked, the change is saved, and the graph will be available when creating new Content Tag Sets in the EVN Tagger application. Unlike the first section of this page, there is no Save button. For additional discussion of these settings, see the EVN Tagger User Guide: Configuring content and property graphs.

Configure Vocabularies/Asset Types

For the vocabulary and asset types allowed by the installed TopBraid product license, these settings allow administrators to show or hide those types in the user interface.

Default Notification Setup

These settings provide default initial values for the RACI event notifications of newly created vocabulary or asset instances. These settings will initialize RACI notifications only for subsequently created vocabularies or assets. Changes here will not affect any existing instances. For additional discussion of the RACI notification settings, see the Manage View: Configure Notifications documentation of any vocabulary or asset type.

Enterprise Server Administration

Reconfigure Deployment Descriptor

This can be used to generate a new web.xml for Tomcat installation. See EVN Server Installation and Integration: Tomcat Installation Instructions.

Refresh Workspace

Refresh workspace rereads the workspace directory an re-registers SPARQLMotion scripts, SPIN functions and templates, and SWP views. If modifications to a file are made outside of TopBraid, i.e. on a file system instead of Export... Deploy on Composer or ProjectUpload on the server then Refresh Workspace will add the file to file registry and register any scripts, templates, and views defined in the file.

Methods to Deploy Projects to Server

This section is deployed as a separate document. Please see Methods to Deploy Projects to Server.

Permission Group Management

This section is deployed as a separate document at TopBraid EVN Permission Group Management. Also see a brief overview at Permission Group Management.

 

  • No labels