HowTo implement subversion revision details in your QV app

    The problem to solve

     

    In order to get better information from your customers in case of support it is good to know the exact version of an app, the customer uses, even if you are not the only developer in your company and if there are many apps under development.

     

    This HowTo will show, how to implement subversion revision details of your app in your app that you have version controlled. So the customer can tell you, what version it is, our you can see it by yourself.

     

    This HowTo is for people that are familiar with the version control system "subversion" and it's client implementation named "TortoiseSVN". But the solution shown here can be adapted to other SVN clients and perhaps other version control systems as well.

     

    If you have a continuous integration system (ok, QV apps do not need to be compiled) or you have installed your version control system on your QV Server it might be possible to adapt this solution for server side use.

     

    First proofread this HowTo and test it before you use it for production. There is no warranty that it will work as described here. The code this HowTo contains is not bulletproofed and is just for demonstration. So it is simplified.

     

    The solution

    Prerequisites

    TortoiseSVN

     

    As you might know, it is possible to implement subversion as an version control system into the QV Client. But as you might also know, this implementation does not support a lot subversion features and commands. So myself and many others decided to use a full subversion client to have all the commands you need.

     

    The client this HowTO uses is TortoiseSVN so it is possible to use client side post-commit hooks and if you installed the svn binaries as well, your system should know the SubWCRev command as well. To check this

     

    1. Open a command window
    2. Execute the SubWCRev command without parameter
    3. The command output should displays a full description of what the command is for (see figure 1)

     

    a.SubWCRev Command.png

    Figure 1: Output of SubWCRev command

     

    I you get something like "Command not found" verify that the command location is in your path. In a standard 64 bit installation the default location is "C:\Program Files\TortoiseSVN\bin\". Be sure to work with the 64 bit command interpreter, if you have 64 bit TortoiseSVN installed and with the 32 bit command interpreter if 32 bit TortoiseSVN.

    Qlik Deployment Framework preparation

    The solution assumes that you have got a 99.Shared Folder and within your other container(s) you should have apps under version control so that folders with "-prj" suffix exists belonging to the apps.

    In order to get this feature you first have to create two folders and place three files in there.

     

    In the .\QDF\99.Shared_Folders\6.Script\ folder create a folder named "3.VersionControl"

    Within the subfolder "3.VersionControl" create another folder named "1.Subversion" so you end up with this folder: ".\QDF\99.Shared_Folders\6.Script\3.VersionControl\1.Subversion"

    Within this new created folder place the three files contained in the attachment SVNRevision.zip of this HowTo.

     

    The files in SVNRevision.zip are:

     

    • SVNRevision: This is the command, we will call in the post-commit client side hook later on. It does some "magic" things and ends up with calling the SubWCRev command with some parameters
    • SVNRevisionDefault.tmpl: This is a qlik view code template that contains all keywords that are documented in subversion documentation and could be substituted by SubWCRev command. I also put it there in case I accidentally destroy the third file...
    • SVNRevision.tmpl: This file contains the qlik view code template with the subversion keywords that should be replaced by the SubWVRev command in my use case. The SVNRevsion command uses this file

     

    At a final step you have to edit the AppPath in SVNRevision.cmd file to point to the root folder containing your apps under version control. ( You also could edit the value of SVN.RepositoryRootOfProject in SVNRevsion.tmpl so that evaluating SVN.Path in your case will work later on)

     

    That's it. Now you are prepared to implement the solution.

    Implementation

    Manual execution

    You just have to double click the file SVNRevision.cmd. So what has happened? First of all a SVNRevision.log file is generated. (If you want, you could have a look inside later on).

    I will describe more details now and finally you can have a look at figure 2, the big picture.

     

    If you take a look into your App folder and navigate to your app, let us name it "SVNTest.qvw" you will see your folder "SVNTest-prj" and an new created file SVNTest.qvw.svn.revision.qvs. If you use TortoiseSVN diff tool or any other diff tool and compare the file SVNRevision.tmpl with the new created file you will see, that each keyword is substituted by an exact value.

    It must be clear to everyone that this new file should not be added to version control. You have to add this in your ignore list or you add a general pattern *.svn.revsion.qvs to your ignore list. Read subversion documentation for detailed explanation.

     

    Notice that the name of the new created file is created with the name of the QVW file followed by the suffix ".svn.revision.qvs".

     

    To implement information of this file in your app while reloading, you simply have to copy two lines in the comment of the new file and paste it in your LoadScript. Simply copy

     

    let SVN.DocumentName=DocumentName();

    $(Include=$(QvWorkPath)\$(SVN.DocumentName).svn.revision.qvs);

     

    and paste it into your app. Then simply reload and you have the information in your app.

     

    You can see all this in figure 2.

    b BigPicture.PNG

    Figure2: Implementation within you app

     

    On the upper right hand side of this picture you see the file browser showing the SVNTest.qvw, its "-prj" folder for version control and the new created ".qvs"-file.

    On the upper left hand side you see the reload code. On the lower left hand side you see the table viewer. The table you see has been created by the included file. On the lower right hand side you see the content of the SVN_Revsion table.

    If you want you can display this table in your app.

     

    Customizing for a single app

    If the command SVNRevision.cmd is executed, the template file SVNRevsion.tmpl is used for keyword substitution so that you have a standard generation of the ...svn.revision.qvs files.

    If for some reason you want a special template for one of you apps, you can place a template file beside the QVW file named "<QVW-Filename>.svn.revision.tmpl". So in my example I just copied the file SVNRevisionDefault.tmpl beside SVNTest.qvw, named it SVNTest.qvw.svn.revision.tmpl and did the SVNRevsion.cmd command again (see figure 3).

    It's a good practice to add this special template to version control.

    c BigPicture Custom.PNG

    Figure 3: Customizing the generation for a single app

     

    After reloading I found all keywords that are documented in the subversion documentation as variables in the app (figure 4).

    d VariableOverview.PNG

    Figure 4: Revision details as SVN variables

     

    Implement as a post-commit hook

    So as I told at the beginning, we will implement this feature as a post-commit hook so that the included qvs-files reflect the actual version information. So to do this (in TortoiseSVN) you just have to configure the hook.

    In my case I decided to use relative path based on the repository root. So I first added and committed the SVNRevsion.cmd and template file SVNRevsion.tmpl to the version control system.

    Then on the Application Root folder ( You have set the path in the SVNRevsion.cmd file before) I added the hook as you could see in figure 5 as a property on the Application Root folder ( not recursively!).

    e TSVN Project Property Local Hook 2.png

    Figure 5: Settings of the post-commit client side hook

     

    So if you do changes to your app now and commit the "-prj" folder, this hook is fired and the SVNRevision Command is executed. The "...svn.revsion.qvs" files get updated and after reload of the app you have "up to date" revision information in you app.

     

    If you what to move your app and deploy it, you have to move/copy the qvs file as well. Don't forget this as a final step.

     

    Conclusion

    With the solution shown here you have a easy and configurable way of implementing detailed revision information in your app. You can define default code for your include files using the SVNRevsion.tmpl or even define special code for special apps using a template for this app.

    You can implement this as a command that you simply execute manually or implement it as a client side hook. It should also be possible to implement it in a continuous integration server like cruisecontrol, if subversion is installed on that server as well.