RPE Tools JS

Data persistence & logging utility for IBM Rational® Publishing Engine™.

View the Project on GitHub reportablesystems/rpe-tools

Visit the Reportable Systems website.

Multi-Template Variable Persistence

Ever found yourself wishing for an easy way to persist variables between multi-template IBM Rational® Publishing Engine™ document specifications?

With this library, it's as easy as adding the following to one document template:

RPETools.Storage.write("myVariable","My variable's value");

And this to another:

var myVariable = RPETools.Storage.read("myVariable");

Supercharged Logging

It can often by useful to embed log style messages within the body of an RPE-generated document; for example, when an expected DOORS attribute couldn't be found or if a required condition was not met.

This library provides a sensible mechanism for recording, tagging and processing log messages, such that you may easily bookmark them in your generated document and construct a hyperlinked table of "Publishing Log Messages" in your document's front matter.

Logging a message is effortless:

// record a simple log message...
var bookmark = RPETools.Logger.log("The requested Rhapsody package could not be found.");

// record a log message tagged "DOORS"...
var bookmark = RPETools.Logger.log("Expected DOORS module attribute not found.","DOORS");

How It Works

  1. The RPE Tools JS source is embedded as an assignment in an RPE container element.
  2. Within the assignment's execution context, a JavaScript object named RPETools is instantiated.
  3. The RPETools object contains a number of functions that template authors can call to help read and write variables and log messages.
  4. The functions construct and send HTTP GET requests to an external web server, RPE Persistence Server.
  5. Responses from the web server are decoded appropriately by the calling function.

Overview

Using a web server as an external store simplifies data sharing, especially for multi-template document specifications:

Multiple Templates

Requirements

The zip file comprises:


Getting Started

Install the RPE Snippets

The easiest way to use RPE Tools JS is via RPE's snippet mechanism. This allows you to drag and drop storage and logging actions onto your document templates from the RPE Palette:

RPE Palette Snippets

  1. Copy the eight .dta templates from \rpe-tools\snippets\ to %RPE_HOME%\source\snippets\

    RPETools - Storage - Reset.dta
        RPETools - Storage - Read Variable.dta
        RPETools - Storage - Write Variable.dta
        RPETools - Storage - Save XML.dta
        RPETools - Logger - Reset.dta
        RPETools - Logger - Add Log Message.dta
        RPETools - Logger - Save XML.dta
        RPETools - Quit.dta
    

    Note - the default local installation path will be similar to C:\Program Files\IBM\Rational\Publishing Engine\1.1.2\source\snippets.

  2. Launch RPE Document Studio and select Template > Organize Snippets...

  3. Use the Publish Snippet dialog to add each snippet from %RPE_HOME%\source\snippets\.

Install & Launch RPE Persistence Server

  1. Copy RPE Persistence Server.exe from \rpe-tools\win32\ to %RPE_HOME%\source\utils\.
  2. Double-click the application icon; a console window should appear:

RPE Persistence Server

Launching via pre-command

RPE Persistence Server can be launched using the pre-command property in a document specification:

cmd /c "${RPE_HOME}\utils\RPE Persistence Server.exe"

See IBM's Preprocessing and postprocessing of output documentation for learn more about using pre-commands.

Non-localhost deployment

If you elect to run RPE Persistence Server on another system, you will need to override the default hostname and port settings (localhost:27465) in the JavaScript library.

A means of achieving this is helpfully included in all of the pre-built snippets; simply uncomment and adjust the line that contains the setHost() function call:

RPETools.setHost("10.0.2.3",27465); //uncomment & adjust hostname:port if defaults are unsuitable.

Terminating the service

The quit() function is used to shutdown RPE Persistence Server:

RPETools.quit();

This, in combination with the earlier pre-command example, can be used to fully automate the start/stop cycle of RPE Persistence Server during the publishing process.

Hints & Tips

Using the pre-built snippets is the easiest way to use RPE Tools JS. To write a variable, drop the RPETools - Storage - Write Variable.dta into your document template. To read a variable, use RPETools - Storage - Read Variable.dta, and so on.

The snippet approach avoids copying and pasting JavaScript code, leaving you to focus on customising the function calls for your storage and logging needs.


Storage

Full API documentation for RPETools.Storage, in addition to the examples given below, can be found here.

Resetting / Initialising Storage

To avoid using stale or invalid data, the reset() function should be used to initialise Storage at the start of publishing:

RPETools.Storage.reset();

This function call would typically be placed at the start of the first template in a multi-template document specification. A good idea is to add this to an "initialisation" template that can be re-used across all of your document specifications.

Writing Variables

To save a variable to RPE Persistence Server, use the write() function:

RPETools.Storage.write("myVariable","My variable's value");

RPE Tools' use of JSON to serialize and deserialize data means you're not just limited to storing String:

// store some simple JS vars...
RPETools.Storage.write("myBooleanVariable",true);
RPETools.Storage.write("myNumericVariable",256);
RPETools.Storage.write("myStringVariable","Some string.");

// store an array & simple JS object...
RPETools.Storage.write("myArrayVariable",["Audi","BMW","Jaguar"]);
RPETools.Storage.write("myLiteralVariable",{"host":"localhost","port":"27465"});

// store a more complex JS object...
var myObjectVariable = {
  name: "Test Object",
  someArrayNumbers: [1,2,3],
  aFlag : true,
  aNestedObject : {
    name : "Test Object's Nested Object"
  }
};
RPETools.Storage.write("myObjectVariable",myObjectVariable);

Reading Variables

Use the read() function to retrieve a named variable's value from RPE Persistence Server:

var myVariable = RPETools.Storage.read("myVariable");

How about retrieving a more complex JavaScript object, like myObjectVariable from our earlier example?

var myObjectVariable = RPETools.Storage.read("myObjectVariable");
myObjectVariable.aNestedObject.name // => "Test Object's Nested Object"

Exporting Storage to XML

It may be useful to directly query all variables stored on the RPE Persistence Server as an RPE data source. For this, use the saveXML() function:

RPETools.Storage.saveXML("c:\\temp\\storage.xml");

The corresponding XML schema, storage.xsd, can be used to add a Generic XML data source to your template.

Best Practice


Logger

Full API documentation for RPETools.Logger, in addition to the examples given below, can be found here.

Resetting / Initialising Logger

To initialise Logger at the start of publishing use the reset() function:

RPETools.Logger.reset();

Similar to initialising Storage, adding this to an "initialisation" template will greatly benefit re-use.

Recording Log Messages

Log messages are recorded using the log() function:

var bookmark = RPETools.Logger.log("The requested Rhapsody package could not be found.");

A second argument may be used in the function call to "tag" similar or related messages:

var bookmark = RPETools.Logger.log("Expected DOORS module attribute not found.","DOORS");

Then later:

var bookmark = RPETools.Logger.log("There was another DOORS problem!","DOORS");

Bookmarks

Each call to log() returns a unique 36 character UID-like identifier which was automatically associated with the logged message. This identifier can then be used to place a hyperlink-able bookmark element alongside an in-line log message in the body of your generated document.

Exporting to XML

The saveXML() function is used thus:

RPETools.Logger.saveXML("c:\\temp\\logger.xml");

The logger.xsd XML schema can be used to query the output as a Generic XML data source.

Creating a "Publishing Logs" Index

Coming soon.


Source Documentation