Skip to end of metadata
Go to start of metadata

Page Contents

TopBraid Live — Server Administration

This document covers the administrative functions of the TopBraid Live (TBL) application. In the web-based interface, administrators can access the TBL (home) > Server Administration link in the page-header.

Controlling User Access

User authorizations in TBL are ultimately based on a user's identity and/or their affiliation with security roles, both of which are determined via Tomcat authentication. TBL supports two Tomcat installation options for defining users and their security roles. See the TBL Server Installation and Integration documentation for details on either:

  • <TOMCAT>/conf/tomcat-users.xml, a Tomcat-installation configuration file for users' login and roles (see Configuring Authentication).

Initially, all users will have permissions to all TBL 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 to their organization's defined administrative role(s) and then remove it from ANY_ROLE. See Permission Group Management: Access to the Server Administration page for details.

Administrative Functions

The Administrative Functions section links to pages providing administrative features, such as server and application configuration, management of authorizations (permissions, roles), cache control, 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.

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

For remotely stored graph data (e.g., RDBMS, MarkLogic; but not TDB), the Cached Graphs page allows a user to reset a graph's cached triples if they become out-of-sync with the version in the backend storage. This might 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 RDBMS Vacuum button, which deletes rows from the nodes table in the relational data store 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 RDBMS 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 TBL 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 TBL 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 TBL:

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 TopBraid Live 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.


Search the EDG Configurations

See Search the EDG Configuration.

Run all DASH Test Cases...

TBL can run unit tests defined as instances of dash:TestCase. Typically, such test cases are created with TopBraid Composer, which has a menu item for creating new test case files. See for details.

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 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 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 sends an TBL project, or its selected contents, from the current server to another TBL server. From the listed projects, an administrator can either send an entire project or its selected contents, such as an asset collection's graph-pair (data and teamwork, .tch).

The receiving server's  active database type configuration must be compatible with the source graphs. For example, if the source is using a relational database (RDBMS), then the receiving server must have a compatible RDBMS configured, presumably to an independent location (optionally in the same database server). If the Also send database triples option is selected, the transfer will also copy the triples from the source data to the destination data. If it is not selected, the database connection files will be transferred but without the triples. This could cause the asset collection(s) to be empty, in which case they might not appear in the users' listing of the corresponding asset collection type(s) (although an administrator could verify their presence via Administrative Functions: Base URI Management). If the Send UI configurations (etc.) option is selected, then it will send the UI configurations file from; 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 TBL 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), and the duration so far.


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

Server URL 

This URL should be the TBL web-application's own context path, without a trailing slash "/". It enables email notifications with "live" TBL-server links (back to the webapp) for governance events or for tasks. For example, for the TBL (Tomcat) server, it would be something like: http://serverhostname/tbl

For TopBraid Composer - Maestro Edition, it would be: http://localhost/:8083

Show Hidden FilesfalseDuring data selection, show all the files that are present on each project.

General Database Parameters

Max Connections per Database100For each RDBMS (relational) or D2RQ database, the maximum number of active connections permitted.

SWP Parameters

Constraint violations block editingfalseIf 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 constantfalseTrue to have ui:lib() always return the static value "lib".
maximum number of table rows1000The maximum number of rows to be displayed by (search results) table widgets

LDAP Servers (Service Providers)

TBL can support multiple LDAP service providers (e.g., multiple Active Directory domains or LDAP servers). For each one, click the plus sign "+" to create a new LDAP stanza (parameter group).

Before applying any LDAP changes, please double-check all settings for accuracy. Inconsistencies with remote LDAP systems could result in the loss of TBL permissions, which could be especially problematic for administrators (i.e., users having roles with AdministratorGrp group privileges; see Permission Group Management). Please verify before proceeding. Losing administrator permissions would block access to Administration pages, including this one, thereby requiring external access to the TBL system environment to modify the configuration files directly.

Connection URL LDAP service provider's connection URL
Username for server connection Username for connection login
Password for server connection 

This appears only if other LDAP parameters are set, and it is set after Save Changes has completed.

User pattern string Based on the Tomcat JNDIRealm (for LDAP), this is the userSearch and userBase (e.g., "sAMAccountName={0},CN=Users,DC=sharepoint,DC=tqinc,DC=info")
Role definition base roleBase: The base DN for role searches (e.g., "OU=Roles,DC=sharepoint,DC=tqinc,DC=info")
Role name identifier roleName: The name of the attribute that has the role-entry's name (e.g., "cn")
Role search string roleSearch: The LDAP search filter for selecting role entries (e.g., "(member={0})")

Membership search string

(OPTIONAL, Recommended)

 For certain LDAPs (e.g., Active Directory), this is the reverse of roleSearch, used to find role memberships for a given user (e.g., "(memberOf={0})").

SMTP Parameters

SMTP Authentication OnfalseTells if smtp server requires authentication.
SMTP Server Smtp Server to be used for sending emails in TopBraid Live.
SMTP Server Port Number587Port used by smtp Server.
SSL EnabledfalseIf SSL for mail is on
SMTP Username Username for authenticating on smtp server.
SMTP Password This appears only if other SMTP parameters are set, and it is set after Save Changes has completed.

Advanced Parameters

Allow Anonymous AccessfalseIf no authentication scheme is used and this flag is true, anonymous access with READ and EXECUTE permission is allowed to the application.
Enable SPARQL updatesfalseIf true, then the SPARQL end point (servlet) will allow update requests.
Timeout on SPARQL Endpoint If not set or 0, SPARQL endpoint has no timeout. Timeout is in milliseconds. If the timeout is reached, the system will throw a CancelQueryException to the user.
Enable Fair LockstrueIf true, then locks taken by TBL will use a first in first out queue, if false then order is less predictable.
Longer Stack TracesfalseCreate 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 InconsistencyfalseWhen a possible software design inconsistency is detected, fail with an error.
Disable Lucene Indexingfalse

EDG-only usage. By default (i.e., disabled= false), the contents of collections is indexed periodically, which signifcantly expedites searches.

NOTE: If disabling is true, the indexing is off and the syntax of users' search queries changes regarding the usage of explicit wildcard characters; see for EDG User Guide - Overview: Lucene integration details.

Enable Query Management PagefalseEnable the query management functionality to monitor currently running query in the system.
Secure Storage encryptionPBEWithSHA1andDESedeOptionally changes the encryption algorithm for storing passwords in the secure storage file. If changed, please use a new secure storage file and restart the server.
Suppress Warnings of Possible Design InconsistencytrueWhen 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 Out2The length of time to wait before a temporary graph can be garbage collected (minutes).
Use SaxonfalseUse Saxon rather than Xalan for XSLT/XML processing.
Verbose loggingfalse

If true, then some operations will send additional info to the log. This may slow down the server a bit.

Enable Ontology Optimizationstrue

When true, it implies that only ontologies define classes, properties, or shapes, and all other collection types get their schema definitions via include refences. Among other things, this recommended practice expedites some operations via caching. It also causes TBL to block the importation of graphs that would violate the condition. See documentation page Ontology View or Edit: Classes vs. Instances for more information.

NOTE: If false, any collection type may contain schema definitions, in which case, this parameter should not be reset to true until such collections are either removed or their schemas are moved into included ontologies.

URI mappings

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 associates with the name "kennedys".

User Interface Configuration

Some TopBraid TBL 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 TBL 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 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.

Enterprise Server Administration

Reconfigure Deployment Descriptor

This can be used to generate a new web.xml for Tomcat installation. See TBL 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.

Deploying Projects to the TBL Server

Like TopBraid Composer (TBC), the TopBraid Live server uses a workspace, which is a file system directory that contains various child subdirectories as its projects. Projects are used both for TBL itself and for user settings and data. For information on copying projects from external sources (e.g., TBC or other TBL servers) into an TBL server, please see Methods to Deploy Projects to Server.

  • No labels