[Deep Dive] How to build Content Intelligence “Apps” using CSApps

In a previous blog post (Using Content Intelligence for Content Suites Customizations) I described some of the great functionality and capability of the Content Intelligence(CI) suite of products for Content Suite (CS). I also described a feature called Application Management which is typically referred to as CSApps.

 In this blog I describe in more depth what this is and how you can leverage it to make your CI development more portable and manageable.

This overview is current as of Content Server 21.3 and is fairly high level in most parts. If you are interested in more detailed information or to consult with us on your specific requirements please contact Ravenblack.

A Well kept Secret!

I have to admit, I love nothing better than hearing from customers and partners who use WebReports and ActiveView (let’s face it very few of them use the term Content Intelligence). I like to think that when we (RKT, my first company) designed these products we had a pretty good read on how they could and would be used but I’m still frequently surprised by how people have taken these concepts and applied them to their business needs.

Sometimes there are features that I had assumed were too obscure for developers to notice or apply and yet people totally seem to get these features. Of course there are probably still a few features that are under-utilized and I will hopefully be writing about these in future blogs. Today I’m writing about a fairly major piece of functionality that appears to remain a fairly well kept secret: Content Server Applications Management (CSApps).

History

Ever since the first versions of WebReports and particularly since the “Constants” feature was developed, the product included some functionality to aid in porting between different Content Suite instances. Most if not all WebReports based functionality requires more than one Content Server object and sometimes hundreds of linked WebReports objects. Often these developments need to be moved between Content Server systems and these object relationships need to be preserved even though the actual Data Ids on each system may be different.

Mostly the solution to this requirement was engineered through the existing XML export and import, leveraging various callback functions to allow us to manage object dependencies. Originally customers had to use the standard XMLexport and XMLimport request handlers but as time went on we created a small module that provided some minor UI improvements over the basic XML request handlers. Initially we built custom versions of these for customers as part of PS engagements but over time we had versions called “LiveApps”, “WebApps”, and “RKTApps” which was ultimately renamed to “CSApps” after RKT was acquired by OpenText.

To be clear, these modules were never designed to create a new method of transport or object importing, or to replace any of the various products that are designed to do this type of thing. We simply embellished on the existing XML functionality (this was built prior to the newer “Transport” functionality) to make sure it managed WebReport ID dependencies and then we created a layer to cater to some of the other characteristics of an application.

Basic Functionality

Specifically, the latest versions include features like:

• Identification, cataloging, version tracking and packaging for all Content Suite objects
• Identification, cataloging and packaging for all support files (JS, image, etc.)
• Naming and version control of the CSApp
• Creation, exporting, installation and upgrading for all application components
• Language properties, file management
• Custom launch URL with defined “start object"
• Initialization object (runs as part of installation)
• Installation of any custom sub-tags
• Pre-setting of any required INI settings
• Pre-setting and enabling of ActiveView override settings
• Specifying if the app requires any specific OScript modules (will notify during installation)
• Specifying if the app has any dependencies on specific tags or sub-tags. If the tags/sub-tags exist but are disabled, this feature will enable them

This is by no means a full list but hopefully this provides a sense of the features this functionality  provides to aid in building Content Intelligence based applications. Additionally there was some work done to support the use of license files. Currently this is used to allow OpenText modules (particularly RM) to deploy CI based functionality, even for customers who do not have WebReports or ActiveView licenses. There is some potential to expand this functionality to allow the creation of applications that require a license key but this has not yet been developed. 

One other future feature is the ability to register widgets (for the new smartView UI) as part of your application. This functionality appears to be supported on the back-end but has not yet been implemented in the UI. 

Application Management

This “well kept secret” is actually hidden in plain view. If you go to the admin.index page, you will notice an entire section called “Application Management”. Selecting this option takes you to an admin area where you can build, import, remove, upgrade and generally manage any CSApp. This option also provides a screen that lists any CSApps that are either installed, partially installed or uninstalled - waiting to be installed (e.g. in csapplicationsstaging).

Typically if you have Records Management on your system you will have a couple of CSApps already listed on this management page as RM provides reporting components that are built as CSApps. Additionally, some early versions of Content Suite 16 also have the Perspectives Manager deployed as a CSApp. I won’t explain all of these options here but it is worth having a look at this screen and reading the various help icons.

Besides the Application Management option there are two other admin options:

• Open Content Server Application Volume - This is an area that can be used to house installed CSApps. Note that you can install a CSApp in any location on Content Suite but this location is specifically provided for customers who want to keep the apps separate from other CS objects.
• Applications Management Configuration - There are a few default paths you can alter here. I have not seen any customer take advantage of this but it is available nonetheless.

CSApps Specific Tags and Sub-tags

Because a CSApp provides a unique context for a collection of WebReport and ActiveView objects, there are also some tags that are specifically designed to leverage this context. These are:

• [LL_REPTAG_APPSUPPORTDIR /] - Returns the root CS Application support folder for a given application. Unless the default has been changed, this usually resolves to:
• <root support folder>/csapplications/
• e.g. /img/csapplications/

This means that you have to add your application name after this tag to appropriately reference any files associated with your app. Additionally you need to add any sub-folders. E.g.:

• <img src=“[LL_REPTAG_APPSUPPORTDIR /] myCoolApp/images/logpic.jpg” ....>
• Sub-tag: APPPROPERTY - Returns a string from the CSApp’s properties file for the user's default language.
• Sub-tag: CSAPPLICATIONINSTALLED - Returns true if a given application is installed. Also can be used to detect a the existence of a particular version and if the application is partially or fully installed, i.e. both Content Server objects and support files have been installed.

Support File Management

When you are building or re-building a CSApp, in addition to specifying the various Content Server objects, you can upload and manage various support files in the file system. For example .js library files, image files, text files, etc. Additionally it is possible to use property files to manage multi-lingual applications (see multi-language applications below). It is important to set this up if you want your application to be fully portable and full encapsulated as an installable application. There are a few different options used to set this up.

• If you specify “Add Support Files” you can browse for a new file on your desktop to add to the application. The file will be placed in the default application support folder for later usage in the application. If you are working on the server you could also do this by simply moving or copying the file to the default folder.
• Support files are files and or folders that are already in the default support folder. This options lists all of the top level items in the default folder. It also allows you to remove any of these files or folders. If you have added any files manually to this support folder you will need to re-build the app in order to include these files as part of the application.
• Support Paths allow you to specify other files or folders that you want to be included with the application. When the CSApp is packaged it will include any files from this support path. On installation any of these files or folders that are not on the target system, will be added.

Note, in the future, “Support Assets” should also be supported. We’ll post a blog on that as and when it is fully supported by CSApps.

Multilingual Applications

CSApps support the ability to support multiple languages via a system of property files. Currently there is no automatic way to manage this so to use this feature, you have to manually create a property file and populate it with labels. You could edit this file on your desktop and then upload it during an application build or re-build operation. Alternatively you could manually create a folder called properties under<support>/csapplications/<CSApp Name>/ and put your properties files in there. When you rebuild or build your app this file will show up as a property file and will be added to the actual application folder.

Each property file must be named using the format:<csapp name>_<language>.properties

• e.g. myCSApp_en_US.properties

For each label in the properties file, add an entry using the format:<csappname>.<label> = Label Text

• e.g. myCSApp.helloWorld = Hello World

Make-up of the CSApp Folder Structure

This information is not necessarily important to using CSApps but you may find some of it useful to know during development. Content Server systems prior to 21.1 will have two folders related to CSApps under the root folder structure. From 21.1 onwards, these folders are located under: appData/webreports/csapps. Although these folder names can be configured, they will usually be called: csapplications and csapplicationsstaging.

When a CSApp is built and active on a system, there will be a folder under the csapplications folder with the name of that CSApp. When a CSApp is uninstalled (but not deleted) and or waiting to be installed, this named folder exists under csapplicationsstaging. Conversely if you have a new CSApp that you want to install on a system you would put the named app folder into the csapplicationsstaging folder. In some cases you will receive a CSApp in a zip file that can be extracted into the csapplicationsstaging folder.

Underneath the top folder for each one of these apps, there is a specific folder structure. As of August 2021, this folder structure is as follows:

• A manifest file with a .manifest extension. This file is normally in a human readable, XML based form and will reflect a table of contents for all application items (whether CS objects or support files and folders), metadata and option selections. This file also tracks version numbers of Content Server objects as they were when the application was built which helps to identify any application changes.
• An XML Import file. This may change as and when CSApps start to use the “Transport” approach to object movement (see the section below on Transport). This file could be separately imported using the admin.xmlimport request handler but will normally be automatically imported during a CSApp install.
• An Applicationfiles folder. This folder has all of the items (folders and files) that will reside in the support folder for the app.
• A supportcollaterals folder. This folder has any items that were specified under “Support Paths”. These items originally exist in folders under the support folder. They will be stored here in a folder hierarchy that matches the path that was specified during building.
• A properties folder. This folder stores any language property files that were created as part of the application.
• A subtags folder. If the application includes any “drop-in” sub-tags, the sub-tag files will be stored here (each sub-tag has a .txt file and a .txt.json file).
• An optional license file with a .lic extension. This is currently only used by some OpenText CSApps as they are designed to run on a customer system even if the customer does not have a WebReports license. The CSApps license file acts as a proxy and grants a license only to the WebReports that are included in the CSApp that includes the license file.

Defining Special Components

When building a CSApp you will be presented with a screen titled “Define Special Components”. You can jump past this screen but it is worth understanding the three different features this screen provides. If you select “Show Detail” you will get some useful information about these features and how they can be used. In particular this screen explains how each item can be given a unique nickname within the CSApp, allowing it to be involved independently of the dataId if necessary.  While Content Server supports nicknames for objects, this feature allows a nickname that only needs to be unique within the context of the CSApp. 

There are various reasons why this level of abstraction can be useful, particularly if you need to invoke a WebReport from an object or screen (or through an integration) where the object Id for the WebReport does not get updated during an import. The “default launch component” also lets you define a WebReport that will run as and when a “csapp.launchapp” URL is executed.

The “Initialize Component” feature allows you to define a WebReport that will automatically be run when your app is installed. This allows you to perform a bunch of setup actions when your app is installed.

How does this work with “Transport“

There is some confusion around various technologies or tools that can be used to do similar things to CSApps. Some of these are tools created by OpenText partners but OpenText also supports a separateTransport feature found in all versions of Content Suite. In my opinion, even if you choose to use one of these other products or paradigms in order to move objects between systems,  it is well worth creating a CSApp in order to manage an application holistically with all component parts, configurations, and meta data in one place. The CSApp uses a manifest file that can represent all of these pieces at a given snapshot in time associated with a particular version number.  This capability can be leveraged in application development and support and our "Application Analyzer" tool uses this to provide several useful management features. We have also used this feature to aid in saving applications to a version control system such as GitHub.  

I won't do any in depth comparison of transport and CSApps but it is fair to say that there are some common functions between CSApps and Transport, in fact they both use similar technology on the back end. the main difference at present is that Transport is specifically targeted at object movement without any specific focus on Content Intelligence or the concept of building and maintaining applications. Hopefully this blog illustrates most of the main features that are included in CSApps that make it the most appropriate tool for building applications using Content Intelligence objects. Conversely there are plenty of customers who might want to export and import objects using a friendly paradigm but who are not interested in such things as support files, sub-tags or INI settings, thus there is room for both of these technologies and hopefully OpenText can find ways to make these products a bit more integrated. 

Ongoing Development of CSApps

Despite my mostly positive review here, there are still some limitations and shortcomings of the current CSApps technology; however, other than the somewhat primitive  UI, the basic features of CS Application Management work fairly well. I’m not going to list any limitations here but Ravenblack are trying to work with other partners and customers to establish some prioritization of features that we can communicate to OpenText. If you are interested in being involved in a focus group around this and other Content Intelligence features please drop your thoughts to me through our contact form.