1) Install QVGuard

The first step is to ensure that you have QVGuard installed. If you have already installed QVGuard on your PC you should find an entry at:

Start -> All Programs -> QVGuard -> QVGuard Studio

If not then you can download QVGuard here - you should receive an installation program named 'QVGuard Studio Setup [VERSION].msi' which you should proceed to install on your Windows Operating system following the installation wizard.

Once the installer has run you should be able to find the above entry in your Start menu, clicking on which should launch a window similar to the following:

Notice at this point that the 'Vendor Info' field is showing that no licence has yet been installed. You should have a file with the '.lic' extension - you can now install this by clicking on the 'Install' button and browsing to this file.

If you have not purchased a commercial licence you can continue evaluating QVGuard Studio, however you will not be able to create secured licences and end users of your licensed QlikView applications will receive a 'nag screen'.

At this point you may wish to enter some details about you or your company as illustrated below. This information will be embedded into each licence file you create and can be extracted through variables in your QlikView application.

Notice that many of the field names have tool tips which show additional information about the field. You can access this by clicking on any field names which show a '?' cursor when you move the mouse pointer over them.

You are now ready to start using QVGuard Studio to license your apps!

2) Add Application

Once you have installed and launched QVGuard Studio you can click the 'Add App' button as highlighted below:

This will create a new node which represents the QlikView application which you wish to protect and publish.

You can now fill in the name of your QlikView application (note this is a friendly identifier and does not need to exactly match the name of your QlikView application):

Optionally, if you are using the Professional edition of QVGuard you may also enter a 'Tracking URL'. This url will be called and passed the user id of the licence file each time an end user reloads your QlikView application allowing you to track usage.

Please note that you are responsible for implementing this back end web service for tracking usage. Please see the additional information on thie feature in the advanced topics section and feel free to contact us us if you would like some sample ASP.NET code. Note also that if the end user's machine or network may be configured to prevent this http request from succeeding.

3) Setup QlikView App

You should now create a new QlikView application or open an existing one that you would like to license with QVGuard Studio. This is the application which corresponds to the new application node you added in QVGuard in the previous step.

We recommend that you place all your script in a hidden tab. To do this go to the following menu item in the 'Edit Script' dialog of QlikView:

Then enter a password for your script:

This will create a new empty hidden script tab:

You should now make sure all your QlikView load script is in this new hidden window.

4) Add QVGuard Script

PLEASE NOTE: This step is only necessary if you wish to protect the load script functionality of your QlikView application. If not then you can proceed to the next step.

You should now locate the node in QVGuard Studio for this QlikView application, and on the 'Script Code' tab click the 'Copy to Clipboard' button:

You should then paste this script into the top of your hidden QlikView script:

Note that you will probably wish to adjust the contents towards the end of the script to alter the load behaviour of your application depending on whether a valid licence file is present. This is discussed later.

5) Add QVGuard Macro

PLEASE NOTE: You need to carry out this step regardless of whether you are using macros in your QlikView application or not.

You should now locate the node in QVGuard for this QlikView application, and on the 'Macro Code' tab, select either VBScript or JScript (depending on your preference) and click the 'Copy to Clipboard' button:

You should then paste this script into the macro module of your QlikView application:

At this point you should also ensure that you have selected 'System Access' both the 'Requested Module Security' and 'Current Local Security' as illustrated below.

Note that end users of your protected QlikView application(s) will also need to allow Macros system access in order for the licensing functionality to work.

You will find in the auto generated macro code a function named QVG_CheckLicence. If you are not using the QlikView load script to run the QVGuard license check as shown in the this step then you should call this QVG_CheckLicence function in your QlikView application, for example when it first opens (in the OnOpen macro event) or when the user first interacts with the application. Once the function has been run once the QlikView variables should have been populated and available for you to check. Based on these variables you might want to limit the functionality of your QlikView application or prevent usage completely.

6) Adjust Load Script

PLEASE NOTE: This step is only necessary if you wish to protect the load script functionality of your QlikView application. If not then you can proceed to the next step.

At this point you should note the contents of the auto generated load script snippet which you added into your application. Much of the script is involved with reading values from the licence file (if it can be located) and allocating these values to QlikView variables which you can subsequently use in your application if needed.

The important point to notice is the lower section of this auto generated script, a section of which is illustrated below:

Here, as the application developer, you need to decide if and how you wish to run the load script based on the success or otherwise of the check which preceed it. You will see a number of the following entries which you can pay particular attention to:

The results of the licensing check are made available through a number of QlikView variables, some of which you can see tested and checked for in the above screen shot. Click here for tables highlighting the most important QlikView variables and error codes supplied by QVGuard.

The default pasted example, as highlighted above, causes the script to exit if the licence check fails. However it also illustrates how, if the licence check does pass, that a different load could be executed if the 'Is Trial Version' flag has been set in the licence file.

It is up to you as the application developer to use the results of the licence check as you see fit.

Notice also in the above how QVGuard allows you to easily display a message box to your users with the following syntax:

let = QVG_ShowMessage('MESSAGE TEXT');

7) Test Licensing

At this point you should have configured your application to either run the QVGuard licensing check during the load script or some macro event (for example the OnOpen macro event for the document).

Depending on your choice you should now find that when you try to reload or open/use your QlikView application, that the application fails to either load or run due to your checks and logic in the load script and or macro code.

You can see more information about how the licence check failed by adding an input box to your QlikView application. You can do this by right clicking on one of your sheets and selecting the following:

Then, right click on the new input box, select properties and then select and add all the variables which begin lic???????:

And add these to your input box:

You will probably find one of two scenarios at this point.

1) If you have not installed the free QVGuard Client on your machine then you might see something like the following:

You can see in this case the licFailureCode is 8 and there are also licFailureShort and licFailureLong variables with more descriptive information in. In a real world application you could use these variables to display more helpful information to your users.

2) If you have installed the QVGuard Client then you will more likely see results similar to the following:

Because you have not yet created and installed a valid licence file for your QlikView application.

8) Create Licence

You should now return to the QVGuard Studio application and click the 'Add User' button for the application created previously:

You can now fill in details for the user and the particular licence you wish to create for them.

The information in the top area of this screen will be embedded into the licence file you create and most of it is made accessible through variables in your QlikView application. You can click the field names to view tool tips with more information on this, including variable names. However it is probably easier to look into the auto generated QlikView script or macro code pasted in the earlier steps as this will show exactly the QlikView variables which are created.

You can now click the 'Export Lic' button to create a physical licence file for this user. This is the file which you would send to an end user of your application, typically as an email attachment.

You can now follow the instructions here on installing the licence file you just created on your own machine.

Once you have done so you should find that on re-running the QVGuard licence check (either by reloading your QlikView application or running the relevant macro code as discussed earlier, depending on your setup) the licence check passes and the input box added earlier shows something similar to the following:

9) Publish QlikView App

IMPORTANT - The following steps should not be completed until you have a version of your QlikView application which you are ready to distribute to your end users.

At this point you should make a copy of your QlikView application which you will then secure so that end users are unable to view or tamper with your scripts, further, the following step will also lock you out from being able to edit the QlikView application's script, macros and other settings!

Let's say your application is called "Bank Statement Analyser.qvw". Save a copy of this and name it "Bank Statement Analyser - Published.qvw". Open this application and place the cursor at the start of your load script, then on the 'Edit Script' dialog click the 'User Access' button as highlighted below:

The following form should appear. Ensure you have the checkboxes selected as shown and then click the OK button.

You should then simply enter the word 'user' in the first cell and leave the USERID and PASSWORD cells empty. This creates a default user for the document who will not need to enter a username or password when they open your QlikView application.

When you click OK you should have something similar to the following in your QlikView script:

You can now close the 'Edit Script' dialog.

Next, go to the 'Settings' menu in QlikView and select the 'Document Properties' option.

On the form which appears go to the 'Security' tab and then ensure that the following options are turned off:
Edit Script
Edit Module
Access Document Properties
Show Progress For Hidden Script

As shown below:

You can of course also turn off other permissions at this point to suit your own requirements.

Next, go to the 'General' tab and ensure that 'Generate Log File' is also unchecked, as shown below:

As a final precaution, you can password protect the macro module. This is done by clicking on 'Module Password' button on the Security tab of the Document Properties dialog in QlikView 9 or my clicking on the 'Password...' button of the Macros tab of the Document Properties dialog in QlikView 8.5.

You can now reload your document but before you do this you should double check that you have made the above changes and are doing this reload on a copy of your master QlikView application because this will now lock you out from being able to edit the QlikView application's script, macros and other settings!

You are now finished. You can distribute your protected application to other QliView users or market it through an online market place such as QVApps.

When you do send your QVGuard protected application to your end user(s), you will probably want to ensure they have installed the QVGuard Client. We would recommend sending them the following links in your communication with them:

http://www.QVGuard.com/download/qvguardclient/ (download page for the QVGuard Client)
http://www.QVGuard.com/docs/qvguardclient/ (user guide for the QVGuard Client)

We will maintain these page urls with the latest download and usage information for the QVGuard Client.

10) Advanced Topics

Backing Up Your Data

It is recommended that you regularly backup your QVGuard Studio Data Directory. You can find the location of this on the About sheet as highlighted below.

You could either backup this directory manually or configure you usual backup software to also include this directory. This is important because if you lose this data you will no longer be able to create valid licences for the QlikView applications you have already protected and delivered to your customers.

Implementing a Tracking Url

Users of the professional edition of QVGuard Studio can configure a Tracking URL on a per application basis as highlighted below:

The QVGuard Client will attempt to make a http GET request to this URL each time an end user reloads the QlikView application, appending the User's GVGuard generated ID (as highlighted below) to the url:

So, in this example as the application developer you would implement a http endpoint which would accept the following http get request:

http://www.mywebsite.com/trackmayapplicationusage.aspx?userGuid=???????????

And log any information you required, such as the time and IP address of the request. Please note that the end user may have a firewall or other network features in place which prevent this outgoing http request from succeeding. This is simply an additional way in which you can perform some level of tracking of usage of your applications.