The majority of configuration in Visualization Solutions by Nakisa (VSN) applications is achieved via the changing of settings in the AdminConsole, Nakisa's standard administration interface. For a typical configuration this is all that you would require. Unfortunately all too often, typical is not what a client wants and so we have to look beyond the current capabilities of AdminConsole. There are other occasions too where perhaps it is a laborious or inefficient task to do a particular piece of configuration in AdminConsole compared to another method. In those situations I turn to configuring the underlying configuration files directly.
Background
When I began learning about Nakisa applications I was fortunate enough to be guided by stephen.burr who had been configuring many iterations of the application suite and back when administration tools for the suite were not nearly so comprehensive. As a result a lot of my configuration knowledge has actually come from bettering my understanding of how the configuration files relate to each other and taking educated guesses as to how to amend those settings. Documentation at this level is scant at best and so it is very much finding the way through trial and error.
In this post I'm therefore going to share some of the basics about configuration at the file level. I'm not going to explain how everything fits together - to be honest I don't know. But what I am going to do is give you some pointers around doing such configuration.
The Structure of Configuration
The Delta
Nakisa application configuration files are held in the file system as a set of XML, XSL, TXT and to a lesser extent various other files. Rather than storing the configuration as a complete set of files, they are instead stored as a "delta".
If you've studied any branch of mathematics or a related numerate discipline and have come across the Greek letter delta, you will no doubt have come across it's assigned meaning of change (small or large depending upon the particular application of use). Here the delta configuration contains the set of files where there is a difference to the original base configuration on which this configuration is based.
In the main this will be files where the content has changed. However it could include files that are brand new (e.g. files to define a new chart view or an organisation's logo). Oddly it could even include files that are deleted. That may sound like an oxymoron, but think about it. How else could you define the removal of the file from your configuration if you don't have it in the delta configuration to indicate it should be discarded?
The Configuration
When you create a new build configuration, the VSN application creates a folder structure for the configuration within it's own folder structure. The configuration contains the delta configuration and when you save a build via AdminConsole it will carry out a number of activities including building a set of configuration files ready for copying down to the application's root folder level (or rather into folder structures held at that level) during the publishing process (which notably includes an implicit save).
This configuration is built from the original base build provided by Nakisa and the delta configuration held within the configuration build's folder structure.
File System
Whilst Windows and Linux systems have different file paths, the general location is the same. On Windows you will have a drive on which the usr folder structure has been created whereas on Linux it will almost certainly be a root level mount point. On Windows file paths are specified by back slashes whereas on Linux it's forward slashes. I'm going to define the file paths here for Windows, but if you're working with Unix you should find it straight forward to translate the path accordingly and do remember to set your character case precisely throughout.
The following line describes the file path to find the delta configuration.
{installation drive}:\usr\sap\{instance}\j{##}\j2ee\cluster\apps\Nakisa\{Nakisa Application}\
servlet_jsp\{Nakisa Application}\root\.system\Admin_Config\__{Tenant ID}__{Build Name}\.delta\
Here's a worked example to put it in context.
D:\usr\sap\NK1\j00\j2ee\cluster\apps\Nakisa\OrgChart\servlet_jsp\OrgChart\root\.system\
Admin_Config\__000__SAPRUS_EC9_05\.delta\
As a side note I always try to include an ID for the organisation, the ID for the ERP system it's connecting to (or at least the environment (DEV/QA/TST/PRD/etc.)) and a sequence number for which iteration of the configuration build it is. This helps track and identify specific builds when you work with multiple clients. I'd also strongly recommend you not have any spaces (I use underscores instead) in your configuration build names. This can lead to problems in the parameterisation for any command line jobs that might need to run.
Modifications
Backups
The first rule of making any changes to a Nakisa application is to export a backup copy of your build configuration. This goes doubly-so for making file level amendments. Any changes you do via AdminConsole can be managed by AdminConsole. You make the wrong amendment at the file level and you can easily get to the point where AdminConsole won't even load your build.
Backups are probably best carried out from AdminConsole. It simply creates a ZIP file, but the point is that if you generated it from AdminConsole you can be pretty safe in assuming AdminConsole will be able to import it if necessary. You can do it manually, but at the end of the day as long as you have a "good" backup in place you'll be all set to start making your changes.
- Check out the Nakisa configuration build backup instructions on SCN's VSN wiki.
Where to Make Build Configuration Edits
As you hopefully realise from the earlier discussion of the structure of the configuration, you should always make your changes in the delta configuration (the folder structure in the .delta folder of your build configuration). If you make changes at the higher, configuration build level, the next time you save or publish you'll find your changes mysteriously vanish as they get overwritten.
Likewise you don't want to make them at the application root folder level. There's an exception around testing XSL changes that you can make use of from time to time, but for now just leave it well alone.
Repeat after me: "I WILL ONLY MAKE CHANGES IN THE DELTA."
Louder! ... only kidding.
The Delta Folder Structure
Within .delta, the folder structure will match that of the configuration build one level higher ... or at least the parts of it that change. I'm not going to dig in to what all the folders and files are, but just know that they match.
One point to note is that there are a few special folders. Look out for a root folder. You'll often see this when you have additional images added (you'll find an images folder inside it when you do). There are some others that can go in here too and I certainly use it all the time for some standard customisations we do to add in some extra administrative automation to Nakisa applications. Folders within this root folder are copied down directly to the root level folder (sub folder structures are respected in the copy) on publishing.
Adding Custom Files
If you want to add a new custom file into the delta configuration you can just copy it in from another source or edit it directly in place. Having accidentally not added files into the delta configuration folder more than once when I first started I found copying in the file to be the best option from a practical point of view.
Changing Existing Files
If you want to amend a file that already exists in the delta you can just go ahead and amend it in place. I then usually grab a copy of the amended version and copy it over to somewhere else - again just because of a few bad experiences of data loss early on in working with Nakisa configuration at this level.
Adding Standard Files
If you want to amend a standard configuration file but it is not in the delta, you can simply copy it from the higher level configuration into your delta configuration and then follow the same approach as though you were amending an existing file.
Deleting Standard Files
Removing a standard configuration file is an interesting action. Copy the file from the higher configuration build level down into the delta folder structure. Amend the file name to append ".deleted". Don't replace the file extension, just append the text.
e.g. "nakisa_template_01C1_28.xml" would become "nakisa_template_01C1_28.xml.deleted".
In fact removal of standard export templates is one of the most commonly occurring uses for this sort of change.
Final Steps
At this point the process is "back to normal". Close all your browser sessions, open a new one and login to AdminConsole. Load in your newly modified build and publish it. After that login to the application and test your changes. Repeat the whole process until you have everything working just fine.
Just remember when you get some things working and still need to make some more changes ... consider taking another backup. No one ever got fired for having too many backups. At least not when they're typically less than a megabyte or two.
Another Way
Sometimes I've worked with clients where I was for one reason or another unable to directly access the file system. What then you may ask?
I'm glad you did. You have a couple of options to still work at the file level.
When you take your backup you can extract the files and folder structure from the ZIP file, make your amendments, compress it and upload it back into AdminConsole (as a new configuration each time).
Alternatively AdminConsole also has an "Upload Content" option where you can upload a subset of delta configuration files. This is in effect the same process as loading a new configuration build except the files are incorporated into the currently loaded configuration (in AdminConsole) rather than creating an entirely new configuration build. This is typically how most VSN administrators load in new export and ChartBook templates.
So you may now be asking how you can add standard files if your exported backups only ever contain the delta configuration files. Great question ... I'm glad you were paying so much attention.
To get those files you will want to grab a copy of the SCA file used to install the particular version of the application you are configuring. You should be able to open the SCA file in an archive utility (such as WinZip or 7-Zip). From there navigate into the DEPLOYARCHIVES folder and open the SDA file (all within the archive utility). Within that you'll find a WAR file ... which again you can open and navigate into using your chosen archive file utility. Finally navigate into the .system\Admin_Config directory and you'll find one or more (depending upon the VSN module) standard Nakisa configuration builds within which you can find the file(s) you require.
Conclusion
Nakisa's AdminConsole has grown in functionality and usability with each release. It should remain your primary point of access for configuring the system and you really can't make do without it. However if you should ever need to delve into the more manual (and quite frankly risky) file level configuration then hopefully this post will have provided you with the guidance you need to get you started.
One final note. Do remember to backup your configuration build before you start making amendments to your delta configuration folder structure.
Please leave a comment and or rate this post if you've found it useful and if you want to keep up with what I'm working on and producing, why not consider millard.stephen and/or on Twitter (@SAP_Stephen).
- SAP Managed Tags:
