OpenText Management Server API jRQL

Using RQL commands not implemented yet

Frank — Wed, 17 Nov 2010 10:25:26 +0000

jRQL did not offer all RQL commands existing. So you might need to use not yet implemented RQL commands within your programs. This is possible with jRQL of course, because you can trigger your own RQL commands and parse the response.

First, every jRQL object offers the following methods to call the MS with a self build RQL command string:
every object > callCms()
every object > callCmsWithoutParsing()

This is achieved by the interface CmsClientContainer which every jRQL class implements directly or indirectly. At the end the implementation in class CmsClient is used, therefore you can use should use it immediately there, if it is available.

Use the 2nd method, if you don’t need the result of a RQL command at all or the MS did not even return anything interesting. It’s a small performance improvement.

Second you need to get all GUIDs to build your own RQL request string. Please refer to the post get GUIDs from all jRQL objects.

At last you need to parse the returned RQL response from the method callCms(). jRQL encapsulate the parsed response in one of the following classes:
RQLNode
RQLNodeList

You need to retrieve the respective tags and attribute values from the response now. Most important methods to achieve this are:
RQLNode > getNode()
RQLNode > getNodes()
RQLNode > getAttribute()

After getting the GUIDs of an implemented jRQL object again, I recommend to retrieve it via the offered methods and proceed with jRQL objects instead of using raw RQL commands for further steps.

With this way you can even use RQL commands which jRQL do not offer. This is not very elegant, I know, therefore keep me informed what’s missing and i will try to implement it into next version of jRQL. I will announce an enhancement of jRQL API on the jRQL twitter stream.

Get GUIDs from all jRQL objects

Frank — Wed, 17 Nov 2010 09:54:37 +0000

The Management Server (MS) internally uses global unique identifier (GUID) as the primary key to all records. These GUIDs therefore are very important and you often need to get it back from jRQL objects to use it further, maybe in own RQL commands.

For every jRQL class which is tight to a MS object deliver the object’s GUID from a method of this style:
.getGuid();

Let me give some examples:
Project > getProjectGuid()
Template > getTemplateGuid()
TemplateElement > getTemplateElementGuid()
Page > getPageGuid()
AuthorizationPackage > getAuthorizationPackageGuid()
PublicationPackage > getPublicationPackageGuid()

Special are the main classes CmsClient and Project, because they encapsulate the session information additionally. For you own RQL command (or other reasons) you can get the session information back as following:
CmsClient > getLogonGuid()
Project > getSessionKey()

Please have in mind, that a session key is only available if you enter a MS project like it is in SmartTree and SmartEdit. Project still can be used in jRQL as it would be in ServerManager. In that case no session key is available and using a method requiring a session key will throw a MissingSessionKeyException.

jRQL ideal suited for project migration

Frank — Tue, 09 Nov 2010 10:37:04 +0000

If you need to migrate structures, assets, pages and content from existing MS projects into any other target, I can recommend using jRQL for it, if you have Java know-how. I used it myself very successfully in the relaunch of hlag.com in 2009 and my daily work.

As you maybe know a typical migration is not working in an one big export – one big import scenario. From my experience it rather goes iteratively for well structured bunches of pages in addition with manual building of a new project.

I want to share 3 possible ways of migration I used jRQL successfully in the mentioned relaunch. I translated this picture from my jRQL presentation into English.

Highest possible flexibility
For all scenarios it is true, that you have the most possible flexibility, because you can customize your migration in standard Java with all possibilities you have within. This maximum of flexibility therefore matches every need you have, which is not possible with every kind of export import tool.

Handling source data inconsistencies
Everybody has experienced or can at least imagine, that the source data are often not as consistent as needed to handle it by a program. This is especially true, if authors work on this data rather than a typically well structured administrator.

From my experience I therefore first get in touch with the source data to get an impression of the quality. I log it simply into the Eclipse console and make the program as robust as needed. You can imagine this migration as an iterative process rather than a write and run once approach. Typically I handle the data exceptions within my program (or manually in old project) until the output is acceptable. jRQL supports this iterative approach very well, because it offers high level functions instead of bothering you with the bits and bytes of raw RQL.

And even you created new pages within the new project which are not correct jRQL helps you to get rid of them and start over again. Within the jRQL plug-ins you can rely on the plug-in Reset all draft pages to make your page creation/updates not happen at all. Usually I empty my Tasks within the new project before I start the creation/update in the new project (program runs with my logon guid and session key) to make this work smoothly.

After this general aspects, let me give some more details on each of the scenarios with it’s strength and weaknesses.

Scenario 1: Copy on-the-fly
This approach is best used if only less conversion of content is needed in between. I used it for copying the press releases pages from a non-language variant project into the new project which uses language variants. The migration program therefore covers the structural differences of source and target project.

In addition I fixed several errors in the HTML code within my program, because some text editor functions are not available in the new project. A migration log collects all pages where this automatic patching did not work for manually re-work.

Scenario 2: Export, correct and import
This scenario is perfect if another person is needed to correct the data before importing them in the new project. Of course there is the flexibility to collect and prepare the data from page elements in old project to be able to write them in line by line fashion into an Excel tab file format (*.tab). jRQL offers the handy class TabFileWriter for this purpose.

Of course you can use only the second half of this scenario to create a bunch of pages from the data contained within an Excel file. I use this approach often in my dayily work with the system, because it’s much faster to enter all needed page details into an Excel sheet than using the slowly MS SmartTree or SmartEdit interfaces with it’s tons of clicks needed.

Scenario 3: Migrate assets
This scenario needs some additional explanation how it works. In my example I used it to migrate vessel certificates (2 PDFs per vessel page) into the new project. But it’s of course possible to use it for migration images.

The steps needed are as following:

use jRQL for every page and download the asset (jRQL supports downloading assets from media and image elements)
save them locally with the unique identifier for each page, in my case I used the unique vessel name. As a positive side effect all assets are named by a unique style, what authors only seldom do unfortunately.
copy the whole folder with all assets to the MS server machine
use the function Import assets on the target folder and refresh attribute values by using Update asset manager too
use jRQL and get the unique page identifier back from the filename, in my case simply the vessel’s name. Find or create the target page and set the filename into the image or media elements of this page

Please have in mind, that jRQL download the assets from the RedDot ImageCache. Unfortunately this is not always up-to-date, but usually this is much more comfortable than doing it manually with several mistakes either.

Plug-in Show Language Variant values

Frank — Tue, 02 Nov 2010 13:36:45 +0000

With this plug-in you can display all content element values from all language variants (LV) on only one screen. On top you get an overview of the workflow state of the page in all language variants (except translation editor states, yet).

This plug-in displays a matrix between the content elements (language variant dependent and not dependent) and the value of these elements per language variant. Each language variant gets his own column.

Is a value from a LV different from the main LV the row is marked yellow. This makes a check easier, because you can focus on the differences. For text element values the HTML code is included into the plug-in’s table. The plug-in checks the language variant values against the main LV and add a yellow comment “different from …” for a difference.

You can start the plug-in regardless of the current language variant you work in. The main language variant is always the first column, all other language variants are coming right beside. Therefore the layout of the matrix is always the same to prevent confusion.

Although the plug-in code switches the language variant to collect all values it preserves your current language variant selection. The displayed LV in MS is still correct after you close the plug-in again (and even after an error).

Benefits
The goal of this plug-in was to check the translators work. The plug-in is used to get all information on only one big screen.

With this plug-in you get a fast overview of the content of a page for all language variants. Using standard functionality you have to change the language variant which is quite time consuming.

Location in SmartTree
You found the plug-in under Administer Project Structure > On every page.

How it works
The plug-in immediately starts without any further questions. On top the screen echos the page you selected and the language variant you are currently working in.

This example uses 4 LVs and English is the main LV.

As mentioned the table on top show all page meta data and the workflow state while collecting all LV values from the current page. Currently the states from translation editor are not included, e.g. waiting for translation.

In the bottom table you get the matrix between content elements retrieved from the underlaying content class and the LV value.

The number of columns of both tables depend from the number of LV you have in your project. Therefore a horizontal scrolling could not be prevented (but is not shown) here even for this example for 4 LVs.

After the columns for the element name and type you get 2 columns showing if the element’s value is LV dependent or not.

Column 5 contains always the element’s value of the main language variant. To the right you get an additional column with the element’s value for each LV. If an element is not LV dependent in the cell n/a is displayed to indicate this.

All LV dependent elements are marked yellow. For text elements the yellow text in the cell “different from en” is used to indicate that the text in a LV is different from the main LVs text. The plug-in checks this explicitely, because small differences are often very difficult to see.

Installation
This plug-in can be installed using the combined setup routine for all jRQL API based plug-ins. Follow the instructions in this blog to download the installer and configure the plug-ins you want.

For API developers
The plug-in works mainly in 2 steps:

collect all content element values in a loop by LV
write out the result table in a loop by content element

To support this conversion I mainly uses the helper class LanguageVariantDependentValuesMatrix from the util package to collect the meta data and all content element values. All content element could be retrieved by the method Page > getContentElements().

In addition the standard functions for looping and changing the LV in a project.
Main methods are

Project > getAllLanguageVariantRfcLanguageIdsOrdered() – delivers fix ordered list of LV codes (en, zh, de, es), main LV always first
Project > setCurrentLanguageVariantByRfcLanguageId() – used this code to switch the LV

Plugin Find user group in authorization packages

Frank — Tue, 02 Nov 2010 10:34:17 +0000

With this plug-in you can find in which authorization packages a user group is used. The following authorization package types are scanned:

authorization packages
details authorization packages
content class authorization packages
project variant authorization packages
language variant authorization packages

Global, plug-in and folder authorization packages are not included yet.

Benefits
This is very helpful when you did not know in detail anymore how the setup was implemented or you are working in a project originally created by another person. I can imagine, that this plug-in would be helpful for partners for the last mentioned reason.

The MS at least in V9 did not offer this functionality. You have to go through all packages of all types manually, what I felt is not acceptable. Therefore I wrote this plug-in.

Location in SmartTree
You found the plug-in on node Administer Project Settings > Packages.

How it works
In the first screen you get a list of all connected user groups of your current project. You have to select one user group before you can proceed.

Click the button Find authorization packages to start the scanning. After only a short time you get the result.

With this information you can go back into SmartTree to check or change the respective authorization packages directly.

For API developers
The functionality is backed solely by the method Project > collectAuthorizationPackagesContaining().

While in the older plug-ins often the scanning code is implemented within the plug-in itself I extended jRQL instead in the latest plug-ins I wrote. This makes the code more reusable.

Plug-in Show page by GUID

Frank — Tue, 02 Nov 2010 10:08:07 +0000

With this plug-in can easily find a page by the GUID. You get the page ID, headline and content class or a message that the GUID is not a valid page. The page could be found, even it is in the recycle bin.

If the page GUID is not valid you will get the RQL error Page GUID missing.

Benefits
This is helpful if you are working intensively with RQL, because often only the page GUID is delivered as result.

Unfortunately the MS search function cannot search by GUID, so this plug-in fills the gap. You get very easy the page details you need to find the page via the Search.

Location in SmartTree
You found the plug-in under Administer Project Structure.

How it works
After starting the plug-in you get a screen presented where you need to paste the page GUID.

After a click on the button Show info you will get the

page ID
page headline
name of the content class

Usually I copy the page ID and use the standard MS search to find the respective page. You will get an error message, if the GUID is not valid or the message “No page for GUID … found.”

If you know how to jump to the page in SmartTree, I would try to add this function in this plug-in.

For API developers
The functionality is delivered by the method Project > getPageByGuid(). There is a method getPageByID() as well.

The line with the details information can be retrieved simply by calling Page > getInfoText().

Interactive RQL tool

Frank — Mon, 01 Nov 2010 09:41:05 +0000

With this plug-in you can execute RQL commands and explore the response delivered from MS at lowest possible level. The plug-in preserves your request and responses into a re-start of the tool.

In addition you can have several RQL requests in parallel. You need to select the command you want to execute, so there is still space to comment RQL requests. Use the plug-in Show session variables to get the IODATA tag with your current session.

The tool was not written by me. A consultant from the RedDot service handed it over to me after a RQL training session.

Benefits
Without this handy plug-in it’s almost impossible to work intensively with RQL. I uses this plug-in intensively, while developing of the jRQL API.

For me it is and was the basis to investigate all RQL commands. I grab quite often undocumented commands from the common log files and uses this tool to test the core command (remove unavailable attributes).

How to start the interactive RQL tool
You found this plug-in not in SmartTree. Instead open the Windows Start Menu and use the provided link “Interactive RQL”.

The URL in the form http://server/cms/ExecuteXml.asp to the Interative RQL tool can be distributed to your local desktop PC too. You don’t have to work on the server machine to use it!

How it works
After start of this tool you get a separated screen. On top an entry box with your latest used RQL requests and below a text are with your latest response.

You need to select the RQL request and click the button above Execute marked XML.

It’s quite handy, that the tool remember your requests and responses so you can even proceed with your work the next day. The most used RQL commands can be collected and stored this way for easy access.

I strongly recommend to use the plug-in Show session variables in addition to get the IODATA tag with your current logonGUID and sessionKEY.

Plug-in Show all session variables

Frank — Mon, 01 Nov 2010 09:19:55 +0000

This plug-in helps you to investigate all MS session variables. You can easily check the complete session if the needed data are already contained.

If you need to grab only the connection information as RQL tag or Java source code, you are better served by the plug-in Show session variables.

Benefits
This small but fine tool helps you out of the box to search the complete session data for an information you expect there.

This is helpful for RQL and plug-in developers. I used it quite often, when I try to integrate a plug-in into MS SmartTree.

Location in SmartTree
You found the plug-in under Administer Project Structure.

How it works
Immediately after the start you get a quite long list of all current session variables. Please have in mind, that this plug-in is a simple ASP page, means a running Tomcat is not needed to use it.

Plug-in Show Session Variables

Frank — Mon, 01 Nov 2010 09:03:47 +0000

With this plug-in RQL enthusiasts and API developers get the needed connection information (LogonGUID, SessionKey, ProjectGUID) as Java Source code and as RQL command.

For further investigation of the MS session variables, please refer to the plug-in Show all session variables too.

Benefits
Instead of copying and pasting these GUIDs one by one this plug-in combine it all into only one copy step needed.

If you need to explore the RQL command, for instance with the interactive RQL tool, this is the perfect companion to get the first line of every RQL command in a one step copy fashion.

As an API developer you often need to copy the connection information into your Java IDE for a quick try. At my desk this happen quite often within the day.

Location in SmartTree
You found the plug-in under Administer Project Structure.

How it works
When you start the plug-in it immediately opens the result screen. Please have in mind, that this plug-in is a simple ASP page, means a running Tomcat is not needed to use it.

The first 3 lines are Java source code for the API developers. The IODATA tag provided can be copyied directly into the interactive RQL tool and can be supplemented with other RQL tags.

Plug-in Show users in user group

Frank — Sun, 31 Oct 2010 20:48:23 +0000

With this plug-in you can immediately in SmartTree check, if a user you might have on the phone can access a specific page. You only need to open the authorization package on the page, select the user group within and start this plug-in to see all user within the selected user group.

Benefits
This plug-in is very handy, because it frees you to switch to the ServerManager module for the simple check, if a user is contained within an user group.

Every person working in support will love this tool, because it speeds up an authorization check dramatically.

Location in SmartTree
You found the plug-in on

on every authorization package user group
on every detailed authorization package user group

How it works
First open the authorization package (regardless of what type it is) and select the user group. From the menu right start the plug-in and you will get immediately, means without any further clicks needed the result.

You get a table with the user short and full name, the e-mail address and the description. You can immedeately send the author an e-mail from this table.

The plug-in show you the number of users in the group below the table.

For API developers
The functionality is delivered mainly be the method UserGroup > getUsers().

Per row some of the most important user attributes are displayed. If you want to extend the table, check the class User for the attributes available. Maybe some values from your LDAP directory (configurable in rql_fw.properties) or if the user is SiteBuilder.