Welcome Guest, you are in: Login

QVSource: The QlikView & Qlik Sense API Connector (Docs)

Getting Started With QVSource Web Edition

RSS
Modified on 2016/04/18 09:40 by chrisb Categorized as Web Edition
IMPORTANT: This page applies to the Web Edition of QVSource. For the WinForms edition of QVSource (which is now deprecated) please see this page.

Web Edition Doc Quick Links
QVSource Web Edition is now commercially available should be used - if you are still using the WinForms edition please upgrade now as this is deprecated and will no longer be supported after the 22nd May 2016.

You should find most of the documentation on this wiki for the WinForms edition of QVSource still applies, particularly the connector specific pages (ignoring the minor UI differences).

The following are the most important Web Edition specific pages:

  • Web Edition Overview - A short introduction to the new QVSource Web Edition including the benefits and high level differences.
  • Getting Started - A guide on running the QVSource Web Edition in its simplest mode (e.g. servicing requests from localhost only with no user authentication).
  • Example Deployment Scenarios - Some example diagrams showing how QVSource Web Edition might be deployed with QlikView and Qlik Sense.
  • Advanced Configuration - How to perform advanced configuration of QVSource, for example allowing remote access and setting up users.
  • User Management - How to manage users.
  • Upgrading from WinForms Edition - How to upgrade.
  • SSL Configuration - How to set up a test SSL certificate so that traffic between your browser (or QlikView/Qlik Sense) is encrypted.
  • Troubleshooting - Read this page first if you are having trouble running QVSource.
  • Cloud Hosted Demo - Information on a cloud host demo edition we are currently testing out.



Prerequisites

  • QVSource (you can request a download here).


  • Please note that we only support Windows 7 or later and Windows Server 2008 and later and we only offer support for the QVSource service on Windows Server editions.

  • You will need a modern browser, the QVSource Web Edition should run on IE9 and later, chrome, firefox and Apple Safari 6.1 and later. In general, expect us to support the same browsers supported by Qlik Sense.

  • QVSource should currently work with any version of QlikView (including Qlik Sense, as explained here). If you are using Qlik Sense please make sure you read this page. If you are using QlikView we strongly recommend version 10 or later which supports the QVX data format.

  • Note that for all of the connectors available so far (excluding MongoDB and the General Web Connector if you are connecting to an internal web service), QVSource needs to connect to the internet in order to download data from whichever API you are interested in - therefore if you have a personal or corporate firewall preventing this it will not work - we do have some features which might help you configure this.

Installing & Running QVSource

NOTE: These instructions are for running QVSource Web Edition in 'desktop' mode which is the recommended mode when you start using the product for the first time. If you would like to see the instructions on running QVSource on a server (so that it is always up and available) see here.

The following steps show how to run QVSource Web Edition in localhost mode only with no authentication. This is essentially a straight replacement for QVSource WinForms edition. See the deploy.config section here for how to open up remote access and authentication.

QVSource is delivered as a zipped folder, there is no installer and QVSource installs no additional components on your systems. This makes it very small, lightweight and trivial to 'install' or remove.

To allow for easy upgrading, we suggest taking the following approach.

  • Read this page regarding unblocking the downloaded files contained in the zip, particularly if you have followed these instructions once and are experiencing issues.
  • In a root drive, create a folder called 'QVSourceWebEdition' (e.g. c:\QVSourceWebEdition). We would specifically not recommend placing it under 'Program Files' due to the reasons mentioned in the notes on this page. Also, please do not run the program from a shared network drive or mapped folder you might experience issues.
  • Unzip the QVSourceWebEdition folder that your downloaded.
  • Copy the contents of the unzipped folder to your new QVSourceWebEdition folder

You should now have a folder structure that looks something like this:

Image

  • You can now run the QVSource.exe file.

Note also that if you are using the processParams[Sync|Async|Batch|Auto] parameter in any of your load scripts you will need to ensure that QlikView/Qlik Sense AND QVSource have access to a folder where QlikView/Qlik Sense can store intermediate CSV parameter files and QVSource can read them (typically c:\QVSourceWebEdition\Temp). This is explained fully on this page.

If you experience any issues running QVSource we would recommend ensuring that you are running it as an administrator - this is done on Windows 7 and other Windows versions by right clicking on the executable and selecting the option highlighted below. You may only need to run QVSource the first time as admin so that it can reserve the URL it runs on, although this will probably only be necessary when you start using more advanced configurations.

Image

You should now see the following window appear indicating that QVSource is running.

Image

PLEASE NOTE : This exe should be run from your local hard drive - if you run the program from a shared network drive or mapped folder you might experience issues.

QVSource runs as a small webserver, by default on port 5555. If you minimise the window shown above you will see this indicated by the balloon tip and icon in the status bar.

Image

This port can be easily changed using deploy.config (explained below). In most cases this should not be necessary, if you do alter this be sure to restart QVSource.

You can now click the 'open in default browser' link to view the QVSource Web UI.

Image

Startup Log Files

Note, at this point, QVSource should have generated either 'Startup_Log.txt' or 'Service_Startup_Log.txt' (if running as windows service) in the root folder. If you are experiencing any issues starting QVSource, please first check the contents of this log file. We would also recommend you send it if you are contacting us for support about this.

Installing the Licence File

You should now see something like the following in your default browser, note that the connectors are not licensed:

Image

You should have received either a trial, commercial or partner licence file. You should go to the 'Licence' tab in QVSource and:
  • Click the 'Choose File' button then browse to your licence (.lic) file.
  • Enter the name you used when registering for your trial or were given when purchasing QVSource.
  • Click the 'Install' button.

Image

Checking Your Licence

You should now find the licence tab has updated to reflect the installed licence. You should check the details of your licence after installation, in particular:

  • Expires: Shows when the licence expires. You might like to set a calendar reminder to remind you when this is approaching. The "Licence" tab will also change to indicate when this is close to remind you.
  • Licensed Connectors: Check that you have licensed the connectors you purchased. Note that for trial users all connectors should be enabled. If you have purchased a valid commercial licence then any connectors currently in beta (i.e. version number < 1.0) are enabled for use.
  • Server Edition: This shows whether QVSource is enabled to run in as a windows service.
  • Number Of Logins: If you have authentication enabled (recommended, see below) for your QVSource Web Edition then this sets how many logins are permitted. If you have installed an older QVSource WinForms edition licence this will probably say 'Not Set' in which case it should allow you 2 logins.

Image

It's also usually a good idea at this point to check the 'data endpoint' is up and running by browsing to:
http://localhost:5555/qvsource

Which should show something like:

Image

You can also request this as XML by appending ?format=xml to the url::
http://localhost:5555/qvsource?format=xml

Image

This also gives you a way of checking that QVSource is running correctly, is licensed and has the expected minimum version number from your QlikView or Qlik Sense load script before proceeding with the remainder of the load - you can see an example script for this here. Note that the above path will be different if you are accessing the QVSource server from another machine as explained here.

Using a specific connector

Selecting a Connector

On the 'Connectors' tab, select a connector you wish to use and click it to bring up its configuration form. In this example we use the Twitter Connector.

Image

Each connector should have a link to an associated help page on its 'Support' tab:

Image

Note that at present, most of the connector help pages will still have screen shots of the QVSource WinForms edition. However, the connectors are 99% identical in both editions in terms of available tables, input parameters and behaviour so the information on the help pages is still relevant.

Working With A Connector

Each connector will have a list of tables which it supports, underneath which appears a description for the currently selected table:

Image

Some connectors will also have tables grouped into particular categories for easier discovery:

Image

In this example we will select the Twitter Search table:

Image

Next click the 'Authenticate' button:

Image

A new browser window or tab should now open where you authenticate with Twitter.

Please ensure that your browser will allow Pop-Ups for the purpose of authenticating.

Once you have done this you should receive a code which you should copy:

Image

And paste back in to the connector:

Image

You should find you now have an authentication token saved with your settings:

Image

And you can now enter some parameters for the table:

Image

You should see a preview of the results:

Image

And you can now copy and paste the generated load script into your QlikView or Qlik Sense application:

Image

Common Connector Configuration

Each connector has its own 'Settings' tab. This is where you can delete any settings associated with the connector (i.e. input parameters saved in the table's UI) as well as clear any cached data (a small number of connectors cache some data to improve performance and/or minimise API calls).

Image

Change Log

Each connector should also have a change log where you can see changes made over each version. We would recommend you read this each time you upgrade QVSource.

Image

Monitoring Updates and Changes

We update the wiki regularly and every connector page has a detailed change log (see one example here) and there is also a change log for the QVSource 'core':

Image

We would recommend using the wiki as a tool to stay up to date and receive automatic notifications of these changes as explained here.

We also post regular updates on Twitter and on also on our Facebook and Google+ pages.

Upgrading

Upgrading QVSource Web Edition is relatively easy, but by following some simple steps you'll be able to continue using any data which connectors may have cached, as well as continue using your existing connector settings.

IMPORTANT: Please note however that you should read the change logs for QVSource as well as any connectors you are using. In particular because, very occasionally due to API changes out of our control, we have to introduce breaking changes which might affect your QlikView or Qlik Sense applications. Therefore it is important to check the change logs for any items which might apply to you and update your applications and test where necessary.

  • Stop running QVSource (note - if you are running QVSource as a service you should stop the service).
  • Take a back up of your QVSourceWebEdition folder, which you created, by zipping it up and keeping it somewhere safe.
  • On downloading the latest version of QVSource, you will have received a zip file - unzip this file somewhere. Note you should also unblock this file.
  • Copy and paste its contents into the QVSourceWebEdition folder (i.e. over the top of the existing contents which you have just backed up) EXCLUDING the deploy.config and logins.xml files.
  • IMPORTANT - Because you have likely edited both deploy.config and logins.xml, you will want to retain these settings rather than overwriting them with the 'master version from the latest download. You therefore have two options (and we hope to improve this situation in time):
    • 1) [Recommended] Copy across your just backed up versions of deploy.config and logins.xml into your QVSourceWebEdition directory and then check the deploy.config and logins.xml files from the latest download zip and add any additional elements which may have been made (which should happen rarely).
      OR
    • 2) Also copy the deploy.config and logins.xml files from the latest download over your existing files AND THEN manually copy any changes you had made to these files from the just backed up version of your site.
  • When prompted overwrite all files and folders. NOTE - It has been seen very occasionally that when you unzip QVSource (or any zip for that matter) to your machine the files/folders sometimes do not pick up or inherit the correct users/permissions which might result in a WinIOError when you try to run QVSource. You should check that your user account and/or whichever user account you have configured to run QVSource still has full access to this folder.
  • Your cached data in the \QVSourceWebEdition\App_Data folder should still be there. If it's not, go to your backed up zip file and copy its App_Data folder's contents into your 'live' App_Data folder.
  • Start QVSource again (note - if you are running QVSource as a service you should re-start the service).

Running QVSource As A Service

If your licence file permits, you can setup QVSource to run as a windows service as explained here. This is the recommended method when using in conjunction with a QlikView or Qlik Sense server as it will ensure QVSource is always up and running to provide data to the QlikView or Qlik Sense reloads.

Advanced Usage

This page explains how to run QVSource Web Edition in localhost mode only with no authentication. You can also configure QVSource Web Edition to run on a server and be accessible other machines. Please see the deploy.config section here for further details.

QVSource also has some enterprise features which help users further secure their QVSource installation.

Advanced users may also wish to check through some of the wiki pages classified as advanced for more tips and advice on getting the most out of QVSource.

Support & Troubleshooting

If you are having trouble getting QVSource running, first ensure you have carefully read the above page and then consulted this troubleshooting page.

If you are still experiencing issues we recommend submitting a support request to support [at] qvsource [dot] com or using the link in the application:

Image


(QVSource works with Qlik Sense as well as QlikView - See this page for notes.)
QVSource - The QlikView & Qlik Sense API Connector | © Copyright 2011 - 2016 Industrial CodeBox Ltd