Category: Triple’A Plus

Managing Languages in TAP R1X – Part 1

Triple’A Plus™ supports multiple languages and provides ways to extend/reduce this list or adapt each language. In these series of articles, will be discuss the possibilities offered to adapt the standard packaging and the best practices on implementation of the WUI adaptation regarding translations.

Languages in TAP Web:

Languages in TAP Web are exposed through the block.xml file (defining the WUI blocks) with the xml tag <nls-language locale=”en”/>. During the WUI initialization, a WUI Block discovery process takes place. Once they are listed on the classpath of the application, the content of the block.xml file is parsed and is added to the WUI: activities, modules, and nls. NLS stands for National Language Support.

In standard, the WUI discovers 3 languages: EN, DE and FR. The occurrences appear in the WUI block called wui-pms-models-manual.

Where the translations play a role in Triple'A Plus (TM)
Where the translations play a role in Triple’A Plus (TM)

In TAP Web, one has to take into account translations coming

  • from the Core packaging, these translations are stored into script files and imported into the Core
  • translations from the Design Studio projects and metadict/format imports
  • translations from nls-XX-manual and other manual wui blocks (wui-component-activity or wui-component-module)

Let’s spend a few lines on the chart above, bottom-up:

  1. Translations in Triple’A Plus™ Core are loaded via sql files (usually prefixed with dict_label), one for each language.
  2. The Triple’A database has triggers to generate a table in the TSL database containing all the occurrences of entities attributes with tsl_multilingual_f set to 1. When looking up for a portfolio, a manager, an instrument, the vertical search looks into this table for occurrences matching your search criteria
  3. During development/adaptation of the WUI, the metadict and format are imported to align the Web MML entities with the Core metadictionary and formats. Translations present in the Core are also imported in the project
  4. The custo packager has the responsability to package the relevant customization as a DPI compliant package and generates the messages_YY.xml files holding the translation keys. XXX-models project translations are located into the XXX-models-gen project when packaged. Other translations (nls or -custo-manual) are included as such in the package
  5. As best practice, custo wui blocks are loaded first (before the standard ones), therefore, key override (same key, different value) is usually practiced to change a translation in the standard block

There are basically many entry points to the management of translations in the Web solution. It can become to tricky to keep track on the long run of all the levels where translations were customized if the WUI-profile dimension is added on top of the cake!

WHAT’S IN THE NEXT EPISODES

The next parts will be about the translation hierarchy in Design Studio, practical cases,  i18n over ODATA, Right-To-Left implementations, chart translations, migrations and best practices. Many interesting topics to cover 🙂 The above was written for a R12SP1 implementation and is subject to changes in upper releases. Most of the principles may apply so reading the documentation is recommended.

If you (dis)agree or would like to share your insight, feel free to comment.

Packaging considerations

Packaging in Triple’A+ was imagined as a very simplistic scenario. The assumption was that we would do a one-fit-all package to deliver adaptation via Design Studio. The reality is not a simple as designed. Soon after the roll-out of TAP R11, developers needed to overcome the limitation that a workspace in Design Studio can host only one packager project. Luckily, it was/is possible to get rid of it and a small improvement in the custo-packager template can ease the setup of a build.

The journey of a package

If one looks at the roll-out of a package to production as a transport process, the development has to be wrapped as an “installable” and conveyed from checkpoint to checkpoint: development, integration, user acceptance, production. Each step requiring validation to progress till the endpoint. This journey is made possible with the custo packager.
The project template allows to create a customization package which can include several projects present in the workspace. The actual limitation of the template is that it doesn’t consider the variable “custo-name” inserted in the wizard setup and assumes that only one packager project type is needed/required per workspace. Whatever is filled in, the project name will be “custo-pms-packager”.

Wizard for the creation of a custo pms packager project
Wizard for the creation of a custo pms packager project

Divide & conquer

A one-fit-all package is not a good idea when a package has to cycle through several environments of different configuration. Packages are cumulative for the WUI installer. Generating one package reduces the flexibility offered by the installer. Moreover, after Triple’A+ 1.30.6, the installer was reviewed in order to shorten the installation procedure: all the packages are extracted and merged within the same repository first, the effective installation taking place in a second time.

Another reason not to do so: the WUI can be delivered internally and as a portal or part of one. Some configuration aspects may be necessary only in one of them. Therefore, isolating this difference in a separate package would allow to test a package that is common to both instances, the second one having the complement only. I often had this situation where one of the two production instances requires additional patches (HTTPS, Corda redirection, secured cookie, timeouts,…)

What about building 2 or more packages from the same packager ? In essence possible but not practical. Example: creating a package to deliver the pms-models takes 1/2h and is build frequently. Whereas a package that contains a configuration patch needs only a few seconds and as it doesn’t change much, is built less regularly. Why would you wait 30min for a 2s package? What if the build fails ? Spend 30 more mins…

Splitting/Dividing allows also to package by purpose or specifically for an environment. More generally speaking, the flexibility one gain hedges the effort to set it up. And so far by experience, system administrators prefer to manage smaller configuration and not mix their patches with the front end customization.

How many packages then ?

On the other hand, too many packages can reduce the efficiency that we gain. Moderation is advised. I usually propose to deliver:

  • one package that is environment independent and
  • several packages that are applied specifically to an environment or to fulfill a purpose.

We implemented this strategy at work and have the following situation:

  • common-pms-packager: for a common package which holds the pms-models and “custo-manual” project types like the customization equivalent wui-pms-models-manual, wui-default-profile-manual or nls-en-manual,…
  • registry-pms-packager: builds a package containing the otf-registry keys to use in the configuration and patches
  • config-pms-packager: builds a package for the configuration and patches. Includes usually custo-config, custo-lib, custo-install project types
  • <env-name>-pms-packager: environment specific package that holds patches to be applied for a specific environment

After a rollout, most of the packages are stable. When the number of packages to deliver becomes important, they can be grouped. Example: when adapting the configuration of the TSL, a separate package can be provided to facilitate the delivery and decouple it from the rest of the adaptation. As soon as the package is validated and stabilized, it can be added to an existing package.

Removing the unnecessary cocoon views

Triple’A Plus® Web contains more than needed in a production environment. One way of knowing it is for example to look at the front end code for example like the main client side script xgui2html.js. The debug instructions are coupled with the logic or the debug toolbar that is inserted in the layout via the green dot appearing on the top right of the screen.

Another example is the delivery of several cocoon views for debugging purpose. Appending to the http query string the parameter cocoon-view with a certain value activates a view of the page. For example: with the value pdf the page (activity) is rendered as a PDF document, with the xls value as an Excel spreadsheet, i18n-content as an XML document containing the translations but before HTML generation.

The list of cocoon views supported by the WUI is not defined completely in the sitemap of the application… In the table below the views and their purpose.

  • content: the raw XMLview
  • popup: view that is exclusively used for popup windows / not suitable for mobile applications
  • layer: this view opens the target as a layer in the main window
  • pdf: renders the current page as a PDF document
  • xls: renders the current page as an Excel spreadsheet
  • frame: view that is used when the page is to be included as an html frame document
  • embed: view that embeds the activity/modules in a page. This view is mainly used in portals
  • analyze: this compares the page against the scheme and will reveal the violations of the scheme rules on the screen as HTML.
  • xsource: aka XGUI Source Code Analyzer, is very similar
  • i18n-keys: The WUI is rendered as an HTML document without the i18n translations replacement
  • i18n-content: returns the result as XML document after i18n keys replacement and before HTML serialization.

If they are very useful for development purpose, they constitute a security risk as they can provide information before the HTML transformation. Inside a secured and controlled network, the threat is purely internal but when the application allows clients to connect externally, they shall be removed from the sitemap.

This post is about how to do it and deliver it in a customization package

Create a project based on the custo-manual template with as custo value: wui-sitemap. The project name in the DS navigator will appear as: wui-sitemap-custo-manual.

wui-sitemap-custo-manual

After the regular clean-up of the project artifacts like the helloworld.cmd script, the correct setup of the block.xml file (id & weight), create a block.xmap file in the src/main/resources/Block-inf folder.

The views that can be removed are

<!--
===============================================================================
 SITEMAP PATCH
===============================================================================
Block Name: WUI-SITEMAP-CUSTO-MANUAL
===============================================================================
 -->
<patches>
 <patch xpath="/sitemap/views" remove="/sitemap/views/view[@name='analyze']"></patch>
 <patch xpath="/sitemap/views" remove="/sitemap/views/view[@name='xsource']"></patch>
 <patch xpath="/sitemap/views" remove="/sitemap/views/view[@name='i18n-keys']"></patch>
 <patch xpath="/sitemap/views" remove="/sitemap/views/view[@name='i18n-content']"></patch>
</patches>

Adapt the file content to your needs: add or remove patch tag node as you wish  or change the value in the @name attribute. After that, add the project to the embedded server, start it and after the login, append “cocoon-view=i18n-content”. If you see something else than an HTML page, it means the patch isn’t properly applied.

In conclusion, this project can be packaged separately, to install it only in a production environment or wherever needed.