SPECT (Simple Portal-Enhancing Configuration Tool) is a simple-to-use utility for batch-loading reports and configuration information into Brio.Portal (which used to be called ReportMart) from Brio Technology. It reads a control file and performs the processing it specifies. This control file is a text file in the format described below.
The program is written in Java and uses the ONE/API provided by SQRIBE. It is intended to be more robust than ONE/Script (in terms of error handling and speed), without requiring the user to know any Java. However, the source code is freely available so that sites wishing to customize the program can do so.
(Note that initial installation of SPECT will require some knowlege of how Java and Portal are installed and configured on your machine, and a basic understanding of how Java programs are executed. See the INSTALLATION section for more information.)
This program has been tested against both ReportMart 1.5.x and Brio.Portal 6.0.x. In genereral it operates the same for both versions, though of course certain features are only available when used with Brio.Portal. It should run on any system supported by ONE/API. (Note: Installation on Windows systems has not yet been tested or properly documented, though it "should work.")
The program ©Copyright 1999, 2000 by Ray Ontko & Co., and is released under the GNU General Public License. (See the "Licenses" section of the GNU web site or the COPYING file included with the SPECT distribution for more information.) The SPECT Home Page is found at http://www.ontko.com/portal/spect/ .
Note: This is an alpha release of SPECT. This means that it has not yet been widely used and tested by "the public." We are currently using it in several environments and believe it will be useful to others, but just be warned that each site is different and you may run into bugs that no one else has found yet. (This is particularly true of the documentation, which is even less tested that the code itself....)
If you do try out SPECT and run into troubles, we want to hear about them. We can't guarantee a fix will be available, but we'll do our best to incorporate fixes in later releases. Please send comments and suggestions to mailto:spect@ontko.com .
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
The installation process is fairly simple but it does involve some manual editing of file-location information in a shell script or BAT file.
SPECT is written in Java and requires a Java run-time environment to be installed and configured on your system. You should get a usage help screen when you type "jre" (or "java") at your command prompt. If you get a "comand not found" type of error, then Java is not correctly configured in your environment. Please see the documentation that comes with your Java package for more information. (Java is also required to run Brio.Portal, so if you are running Portal on your machine there must have a working Java installation on that machine. You may still need to configure your own account in order to access it.)
You also need to have the Brio.Portal ONE/Integrator package installed on your machine. This package is one of the options presented to you when you install the Brio.Portal services from the distribution CD. You will need to know the path to the directory which contains the rmapi##.jar file. This is will be the "lib" subdirectory under the Portal install directory you specified to the installation program. (For Reportmart, the package was called "InSQRIBE"; the files you need to locate have the same name and location relative to the installation directory.)
If you haven't already, you will need to download a SPECT distribution file from the SPECT Home Page. SPECT is distributed both as a .ZIP file (for use with WINUNZIP or PKUNZIP, etc.) and as a .tgz (a TAR archive compressed with gzip); you can choose whichever format works best for you.
There are two "branches" of SPECT available, which differ in the version of ONE/API against which they will compile. If you are running against ReportMart, you should choose the "spect_for15" branch; if you have Brio.Portal, choose the "spect_for60" branch in order to take advantage of the new Portal features. (If you are not attempting to recompile the program, you should be able to use either version of the JAR file with either version of the API, as long as you don't attempt to actually use the new functions against the old API. This is mostly an issue at sites which concurrently running both versions of ReportMart/Portal who don't want to install two versions of SPECT.)
When you unpack the archive, it will create a subdirectory containing all of the SPECT files. In the instructions below, this subdirectory is called the SPECT home directory. In the directory you will find the following files:
You will need to edit the spect_sample or spect_sample.bat files to reference the proper paths to the Java and ONE/API libraries on your system. You should rename the file before editing it so that your edited version is not lost the next time you install SPECT. The comments in the file explain which lines you need to change.
Normally, you would just rename the file to "spect" or "spect.bat", but you can use any name (or names) you like.
You may also want to hard-code connection information into the script file so that you do not have to specify it each time you invoke SPECT. (One of the items you may hard-code is a password. Be sure to consider the security implications of including that password in the script file.)
Finally, you may want to install the script file somewhere in your PATH (or modify your PATH to include the directory where you put the script file) so that you can invoke it easily.
In order to invoke the program, you simply need to pass it the username, password, hostname, and (optionally) the port number used to connect to ReportMart, as well as the operating system filename of the control file that SPECT will process. For example:
spect sqribe mypass localhost controlfile.spect
spect sqribe mypass server3.mycompany.com 2400 controlfile.spect
Note, however, that any or all of these parameters can be hard-coded into the "spect" script so that they don't have to be entered each time SPECT is invoked. A common approach is to include in the script everything but the control file (assuming that you will always use one particular Portal user for all SPECT processing). In this case, the command becomes simply
spect controlfile.spect
(Of course, if a different name was choosen for the script file when it was customized for your site, you'd use that name here.)
Below is a brief description of the control file format. For full details on all available actions and options, please see the SPECT Reference Guide.
The control files are ordinary text files. White space is ignored (except between double quotes.) Comments start with "#" characters and continue to the end of the line.
There are two basic units in a control file, actions and configurations.
An action statment looks like this:
<ACTION> <OBJECT_TYPE> object_name <KEYWORD>=value <KEYWORD>=value ... ;
There can be any number of keyword-value pairs following the object type. The statement can be broken onto multiple lines of the control file, as required. Actions, object_types, and keywords are not case sensitive. Object_names and values should be enclosed in double-quotes if they contain white space.
Configuration statements look like:
SETCONFIG <KEYWORD>=value <KEYWORD>=value ... ;
Again, there can be any number of keyword-value pairs, the word "setconfig" and the keywords are not case sensitive, and the values should be enclosed in double-quotes if they contain white space.
Here is a sample control file show both types of statements.
setconfig log-file=rm_loader.log when-preexists=error;
create user test1 description="test user" password=Portal
group=test_group permissions=755;
setconfig when-preexists=warning
create report "Sample Report" description = "This is the sample."
filespec=/tmp/sample.spf mime-type=application/x-spf
category="/Miscellanous_Merchandise/Samples"
OWNER=test1 GROUP = test_group;