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.

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

Requirements

• RPE version 1.1.2 or above.
• Write access to %RPE_HOME% (your RPE installation directory).
• A copy of the project zip file.

The zip file comprises:

• \snippets - pre-built RPE template snippets for using the Storage and Logger functions.
• \schemas - XML schemas for creating Generic XML data sources in RPE.
• \win32 - contains the RPE Persistence Server.exe web server application.
• rpe-tools.js - the JavaScript source code.
• rpe-tools.min.js - minified JavaScript source, as used in the snippets.

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:

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:

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

• Only use RPETools.Storage.read() near the start of your template. When changing a retrieved variable's value elsewhere in a template, use a local RPE variable.
• Only use RPETools.Storage.write() at the end of your template.
• Never read or write variables mid-query (the IO used to persist variables and log messages is computationally expensive, and can severely affect publishing performance if used within an iterating RPE element).

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

• JavaScript Reference