Upgrading templates to Velocity - conversion approach

We’re upgrading Rx5.7 -> Rx6.5.2, with Oracle 10g, and we’ve created working Velocity versions of all the old templates, global template, etc.

When implementing, is it better to:
a) Tweak each legacy template individually, copying over the source and the bindings, thus keeping the relationships intact with the same template ids
b) Run apocalyptic SQL on psx_objectrelationships to replace the template ids, plus edit allowable slot content, plus…?
c) Something else?

(NB Long story, but the conjunction of the way site-based indexing has previously been implemented, together with the Rx6 schema changes - i.e. conversion of PSX_RELATIONSHIPS from a table to a view - means that alas, we can’t do the upgrade piecemeal. Hence the big bang approach.)

We upgraded from 5.6 to 6.5.2 about 3 months ago. Since we could not have a lot of down time, we ended up setting up a new site that contained all the velocity temlates, and the associated publishing location schemes, etc. This was published out to a slightly different publishing location root. Once this was verified, we then swapped the template id’s of the XSL templates with the Velocity templates. We did this because our inline rhythmyx links contained variant id’s and if we did not change it, they would assemle to the “old” variant. To do this, we had to manuallt update the PSX_TEMPLATE and PSX_TEMPLATE_BINDING tables. Once this was completed, we switched over to the “velocity” site. Just make sure yo disable the old variants and publishing options so that there is no user confusion. Hope this helps.

  • Raj

Hi Roz

If it is any help, we did something similar to ‘onpoint’ but because of the amount of XSL (and hackery) in the old templates, ended up ditching the entire 5.7 implementation and rebuilding our site from scratch in 6.5.2 (on a new box) with Odin’s assistance. The old Rx was left running as normal and only switched off when the final testing of the new and improved 6.5.2 site was completed. The major downside to this approach was that we had to migrate ALL the old content manually, but we did change a lot of our CTs at the same time.

Good luck,

Yes, that’s really helpful. I have the luxury of three days’ downtime and parallel hardware, so am going to run the upgrade, import all the ready-developed templates and then switch them over. Did you need to update any other tables?
One problem is that we are converting a handful of old type-specific snippets to use shared snippet templates, so there isn’t a precise one to one mapping, but fortunately none of them are used for inline links.

We’ve got 25 odd different sites and umpteen users, so rebuilding just isn’t an option, but happily it isn’t necessary. Due to the good offices of my predecessors, we have intact HTML source templates - very little hackery - so converting them to to Velocity has been relatively straightforward. (I feel for the pain you must have had.)



I believe the template tables were the only ones we had to modify. Good Luck!


Just so no-one else goes down the garden path - I’ve now found the ‘official’ method in the documentation. It wasn’t a PDF I’d immediately thought to look in, but here it is, on page 23:


Does the RhythmyxVariantsConverter tool actually work?

The documentation states that it only handles page templates. If this is accurate, what do you do about converting snippet variants/templates?


Percussion provides two tools to help with the conversion process, and, unfortunately, these tools have similar names:

[li]Use the Variant-to-Template Migration tool to generate a set of Velocity Templates from your existing XSL Variants. Use of this tool is documented on pp. 18-21 of the document you cited.
[/li][li]Use the Variant Converter tool to repoint inline Relationships from XSL Variants to the parallel Velocity Template. Use of this tool is documented on pp. 23-24 of the document.[/ul]
I hope that clarifies things a bit.


No, unfortunately it doesn’t. On page 24 section 7d, it states:
d) In the variantMap property, specify which Variants should point to which Template. Use the pipe character (|) to separate the Variants from the Templates. Use commas to separate each Variant/Template pair. For example, the default mapping property: variantMap=301|501,302|502 repoints Active Assembly Relationships that refer to Variant ID 301 to use Template ID 501 and repoints those that refer to VariantID 302 to use Template ID 502. Note that the specified Templates must be Page Templates.

So, if this is true - i.e. only works on Page templates - how do you convert snippet templates?


Do you have inline links that target Snippets rather than Pages?


No, but I’m not sure why you’re asking.

The aim of the exercise is to convert all our existing variants to templates, so that we get the benefit of the shiny new Active Assembly interface. (As well as performance improvements, of course.)

Looks like I’ve been operating on incorrect information. I’d been working with the belief that the whole shebang had to be converted to get the new AA.

However, is there a way to do the snippet conversion?

So, if this is true - i.e. only works on Page templates - how do you convert snippet templates?[/QUOTE]


No, it’s not true. You can migrate snippets using the “Migration Tool”.

The chapter and verse that you cite applies ONLY to the “Variant Converter”, which is used to update the targets of inline links (and all inline links point to pages, not snippets).

As Bob pointed out, there are 2 different programs documented in 2 different sections of the manual that deal with 2 different parts of the process. This has caused great confusion, and many of us have fallen into the trap along with you.

As the documentation describes it, the migration tool doesn’t actually convert your code to Velocity, but it sets up the registrations and all of the infrastructure so that you can easily re-write your XSL Variants as Velocity Templates.

I hope this helps



I’m still somewhat confused, I’m afraid, but I think the source of the confusion has arisen from different meanings of the term ‘conversion’. The documentation refers to the creation/‘conversion’ of the equivalent Velocity snippets, but I’m trying to additionally ‘convert’ the existing relationships so that the XSL snippets can be completely decommissioned.

The reason for doing so is to prevent the clutter and user confusion arising from keeping an old and a new version of each snippet, particularly since we have a large contingent of very occasional users.

(Also, many of the snippet variants could be converted to use shared snippet templates. This makes user-created indexes of multiple content type much easier to achieve. )

If I’m not misunderstanding again, in order to be able to decommission the XSL snippets, the existing relationships would need to be ‘converted’. Hence the reference in my original post to running SQL on the psx_objectrelationships table. I’m not expecting to be able to convert inline links, by the way.



I’ve been through the documentation and the code, and had some discussions with various people here.

The “Variant Converter” does exactly what you need it to do. The documentation is incorrect. It works on both snippets and pages, and converts both regular slot links and inline links to use the correct Template id. (Under the covers it is doing updates to the database tables that you would need to update).

There is a a known bug in the 6.5.2 version. It depends on a DTD file on the JBoss website that has been removed for some reason (there are still references to the DTD in other places on the JBoss site, but the file itself is gone).

To workaround the issue, you will need to edit the file login-config.xml at <Rx root>\AppServer\server\rx\conf.
Comment out the DOCTYPE policy element and run the variant converter:

<!DOCTYPE policy
  PUBLIC "-//JBoss//DTD JBOSS Security Config 3.0//EN" "http://www.jboss.org/j2ee/dtd/security_config.dtd">-->

This is bug Rx-15473 and it is scheduled to be fixed in the next release.

In addition, the next section of the document that describes “Decommissioning” of XSL variants is inadequate. It simply states that you can switch the Publish When flag to “never”. In fact, you’ll want to remove the old XSL Variants from the target website and the community (in the community visibility view in the workbench). This will prevent them from appearing in the menus, which will reduce clutter and user confusion.

We have discussed here how to improve the documentation to make this clearer for customers, and there will be an update soon.

I hope this clears up some of the confusion.


Hi Dave,

Yes, that clears up pretty much all the confusion, thanks!

It may be a bit late to be able to take advantage of the tool, as we’ve now gone into the user testing phase; I ended up converting last week by running SQL directly on psx_templates to make the XSL variants show up in the template list, with source & bindings tabs showing, then pasting over the new code.

I’m intending to test it out this week, though, so if the process does work smoothly without error, we might risk it for the sake of getting a complete conversion. :slight_smile:


A couple of further questions:

  1. presumably the login-config.xml change requires a server restart?
  2. is there anything I can do to check the Variant Converter process has indeed run correctly before embarking on the large task of pasting in the code and bindings? (e.g. run an sql query)

Thanks in advance. I’d really like to use the tool if I can get it running right in the next couple of days.