Data persistence & logging utility for IBM Rational® Publishing Engine™.
View the Project on GitHub reportablesystems/rpe-tools
Visit the Reportable Systems website.
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");
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");
Using a web server as an external store simplifies data sharing, especially for multi-template document specifications:
The zip file comprises:
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:
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.
Launch RPE Document Studio and select Template > Organize Snippets...
Use the Publish Snippet dialog to add each snippet from %RPE_HOME%\source\snippets\.
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.
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.
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.
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.
Full API documentation for RPETools.Storage, in addition to the examples given below, can be found here.
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.
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);
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"
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.
Full API documentation for RPETools.Logger, in addition to the examples given below, can be found here.
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.
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");
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.
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.
Coming soon.