Simple tips to make your WebReports more robust

Ravenblack will be at OpenText World again this year with a kiosk so we hope many of you will come by to chat or ask questions about your WebReports developments, and to check out our vast enhancements to the WebReports ecosystem. In the meantime, I thought I would share a few simple pointers to make your WebReports developments more robust.  

One of the common reasons customers adopted WebReports in its early days was the fact that functionality created with WebReports tended to be more resilient when performing software upgrades, particularly compared to bespoke Oscript customizations. This was generally true, largely due to the use of tags and sub-tags to interconnect with the Content Server software that created a layer of abstraction from software changes. Besides insulating WebReports from software changes, many of the tags and features were also designed to provide an abstraction from references to other Content Server objects, and also from any URL reference that might include specific domains, or folder locations.   

All in all, moving WebReports, or whole WebReport applications, between servers can be painless.  Software upgrades tend to require that functionality is migrated between different servers with different domains and folder specifications. Additionally, customers who follow a defined process of deployment from development servers to test servers, to UAT servers, and on to production servers, need any functionality developed with WebReports to be easily portable. With this in mind, I’m going to share a few points here to encourage developers to take advantage of several features designed to create robust WebReports and WebReport applications.  

Some tips 

Here’s a piece of general advice—if you have any text in your WebReport that references something specific to the server, consider using a tag to replace it (if one exists).  

More specifically the sections below show most of the tags and sub-tags that are available for you to make your WebReports even more powerful. 

1. Creating URLs 

Any URL references, or parts of URLs that are specific to the host server, can be replaced with one of the tags in the table below. Examples are shown in the right column, but as you can see, these tags allow any part of the Content Server base URL. You can use as much or as little of the URL as required for each example.  

Following the base URL, more often than not, there will be a set of “query parameters” forming the necessary information to execute a request on Content Server. In classic Content Server, these parameters will look something like this:  

In many cases, these object specific URLs will be added literally in the WebReport source code; however, there is a sub-tag that is designed to automatically create the appropriate URL for an object. E.g. the syntax here would create a browse URL for a folder.  

The original intent of this sub-tag was to insulate WebReports code from any possible changes to the object URLs that might happen with newer versions of Content Server; however, the object URLs have become very static and in general, hard coding this part of a URL is fairly safe. That being said, it is automatic and can save looking up, copying and pasting URLs. Also, LLURL allows the correct URL to be created in some ambiguous situations, for example: LLURL:OPEN will return the correct default link for any type of node. In addition, LLURL can generate object specific icon URLs, and a variety of other context-specific content including breadcrumb trails and function menus. If in doubt check the help.  

Currently there is no equivalent LLURL sub-tag for REST URLs but we will likely create one in due course. The URL prefix tags are obviously still useful for REST URLs.   

2. Support Folder References 

In addition to the base URL, the following tags reference various support folder aliases.  

3. Object References 

Perhaps the most obvious way to make your code more robust, is to have a diligent use of WebReports Constants. Specifically, any Content Server ID in your WebReports code should be replaced with a constants tag that has been defined on the Constants tab. We’ve been reminding (read: nagging) developers about this particular point for years, as using hard-coded IDs is one of the most common ways to create a non-portable application. While there are other ways to remove literal IDs, these methods don’t work for all scenarios. One such scenario is the use of references to categories and attributes. Here are two examples of references you might come across:  

Using a nickname (for example) doesn’t work in this scenario, but you could do something like this: 

The point of using constants in these cases, is that you may need to copy source between systems and once you have created a constant like this, the WebReport object on each system has the correct value for the system it lives on. Additionally, if a category like this is part of a transport package, CSApp, or other transport package type, the correct ID can be mapped between constants.  

In some cases it might also make sense to use constants to reference the attribute numbers. This might be necessary if the WebReport is run on different systems where a category doesn’t completely match between systems, i.e. the attribute IDs do not match.  

Besides constants, you may also have some objects referenced as defaults on the WebReports parameters tab. In these cases, resist the urge to paste a literal ID in the parameters tab. The WebReports interface provides the ability to browse for objects to look up IDs. If you use this capability your parameter ID references will be safe.  

What's the downside?  

In general, using constants and the various reference tags is never a bad idea; however, the main argument against using these tags is basically performance. Looking up a reference from a tag costs more processing time than literal text. This is almost never an issue unless a particular tag combination is being processed thousands of times. Typically you can reduce this particular risk by avoiding the use of these tags in loops and the row section wherever possible. Using variables to capture multiple tag references is one way to reduce any performance concerns as variable lookups are relatively quick. 

For example, imagine that you’re creating a large number of links with URLs in your WebReport. Prior to entering the loop, you could pre-build the reusable parts of the URL.  

Of course, the other reason people don’t use these tags is that it (theoretically) takes less time to add a literal value to source than to use a tag. With regards to constants, this doesn’t take account of the fact that the literal ID still has to be looked up in order to paste into the source. The constants tab actually provides a mechanism to look up objects in order to get the IDs.  

There’s an Application Analyzer for that 

The Ravenblack Application Analyzer editor makes adding any one of these tags roughly a 3- to 4- character task, as easy as typing the literal text—probably easier. Adding a constant tag only requires typing $ followed by a name, and you can set the value directly from the source.  

Plus, the latest version of the Application Analyzer now looks for portability issues automatically, which enables developers to hunt down and address these issues with the click of a mouse.