Table of Contents
- 1 TopBraid Enterprise Vocabulary Net — Server Administration
- 1.1 Controlling User Access
- 1.2 Administrative Functions
- 1.2.1 Base URI Management
- 1.2.2 Server Configuration Parameters
- 1.2.3 EVN Configuration Parameters
- 1.2.4 Custom Configuration Parameters
- 1.2.5 Auto-Complete Management
- 1.2.6 Cached Graphs
- 1.2.7 Password Management
- 1.2.8 Permission Group Management
- 1.2.9 Role Management
- 1.2.10 Server Information
- 1.2.11 OSGI Bundle Information
- 1.2.12 Available Web Services
- 1.2.13 Product Registration
- 1.2.14 Project Upload
- 1.2.15 Project Delete
- 1.2.16 Send Project to Another Server
- 1.2.17 Provide secure storage password
- 1.2.18 Memory Management
- 1.2.19 Query Management
- 1.2.20 TBL Log
- 1.2.21 Log of SPARQL Function Calls
- 1.3 Administrative Functions: Server Configuration Parameters
- 1.4 Administrative Functions: EVN Configuration Parameters
- 1.5 Enterprise Server Administration
- 1.6 Methods to Deploy Projects to Server
- 1.7 Permission Group Management
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).
Please refer to LDAP Configuration
See the Configuring Authentication section of the TopBraid EVN Installation Guide for more on this.
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.
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.
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.
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:
- 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",
- Using this page.
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.
Users with privileges to view the Role Management page can use it to define vocabulary access policies by assigning users to roles such as viewer, editor 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.
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.
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 firstname.lastname@example.org. 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 email@example.com to get a new license file.
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.
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.
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.
A detailed report on current memory usage. The report includes a link that lets you request garbage collection to clean up the memory.
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.
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.
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 URL||This must be a localhost URL, and needs to have another /tbl added to give the main page.|
|Show Hidden Files||During data selection, show all the files that are present on each project.|
General Database Parameters
|Max Connections per Database||For each Apache Jena SDB or D2RQ database, the maximum number of active connections permitted.|
|Constraint violations block editing||If 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 URI||The 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 base||The server URL to prepend in calls of ui:createLink. If set, then ui:createLink will create absolute URLs.|
|ui:lib function is constant||True to have ui:lib() always return the static value "lib".|
LDAP Server Parameters
|Connection URL||LDAP server connection URL|
|Username for server connection||Connection Username|
|User pattern string||Userpattern|
|Role definition base||Rolebase|
|Role name identifier||Rolename|
|Role search string||Rolesearch|
|Use long lived connection to LDAP server||Use long lived connection to LDAP server|
|SMTP Authentication On||Tells if smtp server requires authentication.|
|SMTP Server||Smtp Server to be used for sending emails in TopBraid Live.|
|SMTP Server Port Number||Port used by smtp Server.|
|SSL Enabled||If SSL for mail is on|
|SMTP Username||Username for authenticating on smtp server.|
|SMTP Password||Password for authenticating on smtp server.|
|Allow Anonymous Access||If no authentication scheme is used and this flag is true, anonymous access with READ and EXECUTE permission is allowed to the application.|
|Enable SPARQL updates||If true, then the SPARQL end point (servlet) will allow update requests.|
|Timeout on SPARQL Endpoint||If 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 Locks||If true, then locks taken by TBL will use a first in first out queue, if false then order is less predictable.|
|Longer Stack Traces||Create 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 Inconsistency||When a possible software design inconsistency is detected, fail with an error.|
|Disable URL graph loading||If true, then imported URI that is not found in the workspace will not be loaded from the web.|
|Enable Query Management Page||Enable the query management functionality to monitor currently running query in the system.|
|Secure Storage encryption||Choose 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 Inconsistency||When 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 Out||The length of time to wait before a temporary graph can be garbage collected (minutes).|
|Time before a TDB diskflush||Any TDB with changes made but not yet written to disk will be flushed to disk after this number of milliseconds|
|Use Saxon||Use Saxon rather than Xalan for XSLT/XML processing.|
|Verbose logging||If true, then some operations will send additional info to the log. This may slow down the server a bit.|
|Short Graph name||A 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 associateswith 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
|Download general config graph||Click this link will download the current config.ttl from the system folder.|
|Downoad uiconfig graph||Click 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.
|Teamwork Platform Parameters|
|Repository project||See persistence technology, below|
|Viewers cannot create working copies||Blocks users with only viewer access for a vocabulary or asset from creating a working copy of it|
|Comments activated||Allows comments on data resources|
|Tasks activated||Allows user tasks on data resources|
|Send task emails||Users with an email address receive email when a task is assigned to them|
|Active database type||See persistence technology , below|
|AutoClassifier Configuration Parameters|
|Maui Server URL||The 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 name||Must be specified if Maui Server has been configured to require a user name and password (via the HTTP Basic Authentication protocol).|
|Explorer server||URL of an EVN Explorer server to upload files to when a vocabulary is being published.|
|Explorer server anonymous access||True if the EVN Explorer server does not require a user name and password.|
|Explorer server user name||User name for authentication on EVN Explorer server.|
|Editor server||URL 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. " ".|
|Editor server user name||User name for authentication on EVN Editor server.|
|MarkLogic Configuration Parameters||See persistence technology , below|
|SDB Configuration Parameters||See 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:
- relational databases (via the Apache Jena SDB interface): Oracle, Microsoft SQL Server, or MySQL,
- Apache Jena TDB, or
- MarkLogic's NoSQL database.
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: SDB, TDB, 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.
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:
|(BOTH) user name||Database username. NOTE: The password will be entered after Save Changes is clicked.|
|SDB database type||Select the supported type of relational database being used.|
|SDB Update Batch Size||OPTIONAL: 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:
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 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