This article provides an overview into the mechanics of WebReports “sub-tags.” I discuss how to deliver new sub-tags, or extensions to existing sub-tags. I also discuss the pros and cons of using this feature along with some useful tips and tricks you can use if you choose to take advantage of it.
If you don’t know what a sub-tag is, why are they so important, or just how you can use them, take a look here, we explained the basics of sub-tags for WebReports.
How do you create WebReports drop-in objects?
To start with, it’s probably worth mentioning that there are two types of drop-ins, one for the original WebReports parsing engine and one for the current parsing engine that was introduced several years ago. For any of you that are still on an older version of the Content Suite platform you can confirm whether you are using the newer engine, by running a WebReport that contains the [LL_REPTAG_RKTENGINEENABLED /] tag. If this tag doesn’t exist, then you probably have a very old version prior to the introduction of this engine. We will not be discussing the older drop-in version in this blog, but you can contact us if you need any further information.
Drop-in sub-tags are stored in one of two different places.
For Content Suite 16.2.9 and earlier, sub-tags were stored under:
- <root>/module/WebReports/subtags for every single installed server.
Starting with Content Suite 16.2.10, sub-tags are stored under:
- <root>/appData/webreports/subtags
The largest benefit of the most recent “appData” location is that you only need to add the sub-tags on one server and they become available to all servers.
If you look at a “sub-tags” folder on your server, you should see at least two sample files. These files are very helpful as they include significant comments to aid in your development.
Every drop-in requires two different files as seen with the two sample files:
- sample.txt
- sample.txt.json
In this example, the sub-tag name is SAMPLE and this is the syntax you would use in your WebReport. E.g.: [LL_REPTAG=DataId SAMPLE /]
The first file with the .txt extension is the source for the sub-tag. The second file is a JSON definition that specifies some sub-tag settings as well as any documentation.
How to interface the new functionality with the WebReports tag engine?
To create a brand-new sub-tag you need to use a new (unique name). If you are creating a new version of an existing sub-tag, you simply use the same name as the sub-tag you are overriding.
Having created next step is to determine how to develop the new functionality in a way that interfaces with the WebReports tag engine.
The SAMPLE sub-tag that is preloaded in the WebReports sub-tag folder provides a lot of useful information. We won’t duplicate this information, but we have provided some additional explanation about:
- Function Structure
- Object Features and Functions
- Object Utility Functions
- Complex Utility Function Examples
- Error Handling
- Side-car Parameters
For full details, download the in-depth sub-tag documentation.
How to develop with Eclipse / Builder?
For the purposes of this explanation we will just reference Eclipse. However, the original Content Suite Builder is similar
One approach to developing a new sub-tag is to create a new module/Ospace and actually add a new sub-tag as an orphan of the sub-tag object hierarchy through the Content Suite platform. While we are not advocating this as the main method of delivery, this approach does allow you to utilize the various features built into the sub-tag object hierarchy. Having populated these features, and having developed the main execute function, you can then run a script that will automatically create the drop-in sub-tag files for you.
The basic steps to do this are as follows:
- Create an Ospace and make sure it is unlocked.
- Select any sub-tag in the hierarchy (ideally you could pick one that is similar to the one you are developing). The hierarchy is:
- RKTEngine/RKTEngineRoot/All Tags/Sub-tags/<sub-tag name>
- Create an orphan of this sub-tag object in your new Ospace.
- If necessary select the “Show inherited features” buttonto reveal any features or scripts that you may need to override.
- Edit any or all of the features mentioned in the table above, e.g. Execute, Documentation, fMinParms, fMaxParms, etc. Note, it is particularly useful to edit documentation with this approach as the creation of the drop-in will handle any quote escaping required in the JSON file output.
- Select and execute the ExportAsDropin script
- Your newly created Drop-in files are created under the root OpenText folder (unless you want to edit the ExportAsDropin script.
- Having created these files, you need to move them to the appropriate WebReports sub-tags folder (as explained above).
Creating your own sub-tag object allows you to test compile your sub-tag; however, as described later, there is another way to compile your drop-in if you don’t want to create a sub-tag object. An alternative to this approach, is that you could simply select a similar sub-tag and execute the ExportAsDropin script. You could then edit the generated files to meet your development requirements.
Development without Eclipse
While access to Eclipse is preferred it is possible to develop sub-tags without Eclipse. The best way to do this would be to duplicate the SAMPLE sub-tag drop-in files that are found in the subtags folder. Once you have performed your changes you can test compile your new sub-tag as described in the next section. The main problem with this approach is that if you have a run-time or logic issue, it can be very difficult (though not impossible) to debug.
Debugging
Regardless of how you create the sub-tag drop-in files, having Eclipse open and running Content Server also allows you to debug run time issues with your sub-tag. You can also insert Scheduler.debugBreak() into your code if you want to stop and step through your code.
The basic approach to debugging is to edit the sub-tag, test compile it (see below), restart the server (or use the sub-tag builder – see below), and then execute a WebReport that is using your new sub-tag. Ideally you will create multiple examples covering any different cases you are supporting. Obviously if you find issues, you re-write your script and re-test.
WebReports sub-tag builder
From the admin.index page there is a WebReports section designed to aid in building sub-tags. It can be accessed using: ?func=webreports.BuildTags&tagtype=subtags.
Simply by executing this URL you will cause WebReports to load and compile any drop-in sub-tags. (Note that, the .json side-car file is not explicitly parsed and if it is not correctly formed you could cause a trace.)
Once on this page you can use the Refresh button to re-compile the sub-tags. This can make a convenient alternative to editing your script and then re-compiling. Note, the Ravenblack Sub-tag Loader product (included with our productivity suite) overrides this basic page and provides several additional features and functionality. See Sub-tag Loader under: Ravenblack Productivity Suite
Deploying drop-in sub-tags
The best way to fully deploy your sub-tag is by restarting any and all servers that you want the sub-tag to be available on. Unfortunately the out-of-the-box tool only deploys your sub-tag on whichever thread receives the request.
In order to fully deploy your sub-tag to all threads on a given server you would have to refresh multiple times in order to “load” your sub-tag into memory for each thread running on that server. Usually, if you refresh the tool as many times as there are threads, your sub-tag will be fully deployed as the threads usually cycle through in a circular fashion. Wiith the aforementioned Ravenblack Sub-Tag Loader tool all threads can be populated without a restart but without this tool, a restart is ultimately the best way to ensure that your sub-tag is fully and correctly deployed.
This was a bit of a primer to get your started with developing WebReports (aka Content Intelligence) sub-tags. If you want more information I’ve written up a detailed technical guide that you can download.
If you still have some doubts about implementing sub-tags within WebReports, our experts can help you understand the capabilities and limitations of this features, capture user requirements, write technical specifications, develop WebReports code, and test, debug and optimize your final application. Contact us today to gain the experience only available through pure mastery over WebReports.
About the author
