User Tools

Site Tools


vortex:configuration

Configuration of the Vortex

The Vortex is configured using a couple of XML configuration files as follows:

The Database Instances also keep a couple of configuration files:

The specifics of the diffent files follow.

Main Vortex Config

The main Vortex configuration file is located in the Vortex framework under /config/xml/config.vortex.xml. This file contains general information about the Vortex Framework and information about where to find the Database Instances to use. This file is an XML version 1.0 file using encoding ISO-8859-1. The root element is called vortex. Examples follow the element descriptions.

Element descriptions

TagnameAttributeDescription
localefile
detailsfileWhat does this do?
database Each database tag specifies information about a database instance.
availableA list of hostnames that this database will be visible for. Separated by ; [Optional]
defaultOne host that this CBI will be default for. When surfing to this host no database choise will be available, this DBI will be loaded. [Optional]
idThe ID of the database instance. This value is used when referring to the database from Command Line and direct links.
pathRelative path of the root of the database instance. Knowing this the system knows where to find the DBI Config.
user Information regarding users in the framework.
user.password Information regarding the password.
user.password.lifetime What does this do?
user.password.lockfailures How many attempts the user has before the account is locked.
user.password.expirewarning What does this do?
user.loggedinfor How many minutes until automatic logout.
user.admin Settings for the admin user created by default for new Database Instances.
iduserID of the admin user.
usernameDefault admin username.
passwordDefault admin password.
user.ad Settings for AD connection
serverIP to AD server authenticating the users
enabledTrue or false, wether to allow AD authentication

Sample config file

<?xml version="1.0" encoding="ISO-8859-1"?>
<vortex>
    <locale file="swedish" />
    <details file="config.details.xml" />
    <database id="myTest" path="../TestDBI/" default="mytesturl.mytestdomain.com" />
    <database id="myTest2" path="../TestDBI2" available="mytesturl2.mytestdomain.com;127.0.0.1" />
 
    <user>
        <password>
            <lifetime>0</lifetime>
            <lockfailures>5</lockfailures>
            <expirewarning>10</expirewarning>
        </password>
        <loggedinfor>10</loggedinfor>
        <admin iduser="1" username="vortexadmin" password="vortexpassword" />
        <ad server="server_ip" enabled="true/false" />
    </user>
</vortex>

Vortex SQL Config

The Vortex can use several different database engines. To ensure this no SQL syntax is hard coded into the vortex. All SQL commands are stored in SQL configuration files. Translating these files for use with a new database engine requires good knowledge of the database engine and of the Vortex SQL Configuration syntax.

These files reside in /config/xml/sql.[Database Engine name].xml. To see which tags should be translated, use one of the currently working configurations. Currently the following Database Engines are supported:

  • MySQL

The SQL Configuration files are XML 1.0 files with UTF-8 encoding. The root element is called sql and the structure below must be strictly followed in all new SQL Configuration files. The syntax is as follows:

<command_name [noescape="[true/false]"]>[SQL COMMAND]</command_name>

The noescape attribute executes the SQL command without using the internal SQL escaping. All parameters that are sent to the SQL command must be escaped before passed. The SQL commands can be built using printf syntax substituting variables with either %d or %s:

SELECT * FROM myTable WHERE id=%d OR name='%s'

These type of SQL Commands are referenced in the code with the same type of syntax:

$res = Vortex::$dbh->query( "sql.mycommand", $id, $name );

Another option, which is preferred, is the Vortex syntax for variable substitution:

SELECT * FROM myTable WHERE id=%[id]% OR name='%[name]%'

These type of SQL Commands are referenced in the code with the following syntax:

$attribs = array( "id"=>$id, "name"=>$name );
$res = Vortex::$dbh->query( "sql.mycommand", $attribs );

One thing that makes this the preferred method is that it simplifies keeping track of passed parameters, and allows the SQL Command to re-use variables only passed once.

Vortex Language Config

DBI Config

The configuration of the DataBase Instance is done in the file /config/config.xml in the DBI directory. In this file the configuration of the database connectivity, DBI description, loggers, menu and webservices is done.

The root element of the config file is the <config> element.

Database connectivity configuration

The database connectivity is configured within the database element. This element contains the following attributes, and no child elements.

AttributeDescription
idThe ID of the database, used when referencing the database in webservices and direct calls
databaseThe name of the database to connect to
usernameThe username to use when authenticating the database connection
passwordThe password to use when authenticating the database connection
serverThe name of the server hosting the database
typeType of database, currently only mysql is supported

DBI Description configuration

The DBI description is configured within the description element, which has the following attributes and no child elements.

AttributeDescription
titleTitle of the DBI, shown in the title bar of the browser
iconThe icon shown in the database selection
icon2The icon shown in the database selection when the mouse is over the icon
cssWhich CSS to load
menuheadThe title in top of the menu

Default user configuration

By adding a defaultuser element to the configuration default values can be set for every attribute for a new user. Default groups can also be specified, and theese default values will be set for a new user where no overriding value is specified.

   ...
   <defaultuser>
      <valid_from_time>{date}</valid_from_time>
      <valid_to_time>{date.Y+1}</valid_to_time>
      <group>UsersGroup</group>
      <group>MyGroup</group>
   </defaultuser>
   ...

Attribute values are parsed as VxStrings and groups are identified by supplying the UUID for the chosen group. All the fields in the database can be given a default value using this configuration element, even your own custom fields.

Logger configuration

The configuration of the loggers is done within the loggers element. This element has one attribute, logpath containing the relative path within the DBI directory where the logfiles are kept. Make sure the user running the webserver has full permissions on the files in this directory. The bind and logger elements are subelements to the loggers element.

The configuration of the loggers is done in two steps. First the actual loggers are defined, within logger elements.

AttributeDescription
nameName of the logger, used when binding the logger
fileName of the logfile
levelLoglevel, valid values are LEVEL_ALL, LEVEL_FINE, LEVEL_NORMAL, LEVEL_COARSE, LEVEL_NONE
formatNames the formatter to use. Default value is StdFormatter. This formatter needs to be implemented in the vortex /classes/logger path
keepfilesHow many files to keep when cycling
sizelimitThe logfile is cycled when exceeding this sizelimit

The configured loggers are then bound to PHP classes using bind elements.

AttributeDescription
className of the class to bind
loggerName of the logger to bind

If the class attribute is set to all, all classes that has no specifically bound logger will be logged using the given logger. Likewise, the class ERROR will be used as an errorlog where all caught Exceptions and handled errors are logged to.

The menu shown on the left of the screen in the Vortex can be customized. If no menu configuration is given, all Tables are shown in the menu as a straight list of items. Using the menu configuration, the menu can be configured as a tree structure containing only the wanted Tables. Permissions can be set only allowing a subset of users to see certain submenus or Tables, and Scripts can be added to the menu.

The base element of the menu configuration is the menu element. This element has no attributes and contains the rest of the menu elements.

The menu configuration currently consists of the menuitem, table, spacer and script elements.

The menuitem describes a sub menu structure. The menuitem can contain other menuitem(s), table(s), spacer(s) and/or script(s).

  <menuitem name="My SubMenu" default="open">
    <table name="myTable" />
  </menuitem>
AttributeDescription
nameThe name of the submenu, shown in the menu
default open/closed , the default state of the sub menu
requiredgroupIf given, contains a comma separated list of groups to see this menuitem
iconPath to an icon to show for the menuitem
table

The table element describes a reference to a Table to be shown in the menu.

AttributeDescription
nameThe name of the Table to show
idThe ID of the table to show, either name or ID is required, not both
requiredgroupIf given, contains a comma separated list of groups to see this table
iconPath to an icon to show for this table
typeFor import/export functionallity.
descriptiveFor import/export functionallity.
spacer

The spacer shows an empty row in the menu, for layout purposes only. It has no attributes or sub elements.

script

Describes a script to run and to show the output for. Scripts are defined in the /script folder in the DBI directory.

AttributeDescription
nameName to show in the menu
classClass containing the method to run
methodName of the method to run
param_[x]Where x = 1,2,3,4,… Parameters to pass to the method. All numbers must be given in sequence.
requiregroupIf given, contains a comma separated list of groups to see this script
iconIcon to show for this script
Enabling the user to edit My Profile

In order to let the current user edit details regarding his/her own profile the My Profile script can be added to the menu.

  <script name="My Profile" class="User" method="myProfile" requiregroup="users" param_1="password" />

This calls the myProfile() method of the User class which lets the current user edit details of their profile. The param_1 parameter contains a comma separated list of the names of the fields in the user profile that the user is able to edit. Related fields can be added here by giving their full name, ie relation.fieldname. If a fieldname is prefixed with an asterix * the field will be shown as read-only for the user.

Showlist configuration

Configuration of default ShowList properties is done with the showlist element in the config file. Currently this element only supports one child element displayrows which controls how many rows will be shown .

    <showlist>
        <displayrows>100</displayrows>
    </showlist>

Webservices configuration

Custom SQL Scripts

In order to use SQL queries from the Searchbox and in filters those queries need to be predefined on the server. This is done by placing XML-formatted .sql files in the /sql path under the DBI. The syntax of the .sql files is described in the section above.

To include custom sql files in a DBI add the sql element to the config.xml file:

...
<sql>
    <file filename="my_custom_sql.sql" nodename="custom" />
    <file filename="my_other.sql" nodename="other" />
</sql>
...

Theese queries can be addressed from the Vortex like:

  $res = Vortex::$dbh->query( "sql.custom.mysqltagname" );
  $res2 = Vortex::$dbh->query( "sql.other.mysqltagname" );

where mysqltagname is the full name of the sql query in the .sql file. The type of the database is added before the extension in the file so the files that will be opened in the example above for a DBI using a mysql type database will be

my_custom_sql.mysql.sql
my_other.mysql.sql

DBI Import Scripts

DBI Webservice Config

Customizing the looks of the Vortex

All CSS-files and icons can be overridden by making local copies in the DBI. Files that are put under the local/ path in the DBI will be accessable through the vortex using the URL syntax

http://vortex/?vortex_callertype=getlocal&vortex_localfilename=[filename]

where filename is the full path under the public/ folder for the file to be fetched.

By copying the files from the Vortex css/ path into the DBI public/css/ path you can make DBI-local changes to the CSS files. By having icon files in the DBI path public/gfx/icons/ with the same names as the icons in the Vortex gfx/icons/ path, the local DBI icons will be used instead.

vortex/configuration.txt · Last modified: 2019/06/28 07:11 by hubbe