Merge pull request #15 from qlik-oss/qvdoc

Documentation and an example for QlikView

GetStarted.md

@@ -1,6 +1,6 @@
 # Build and Run the R-Plugin!
 
-If it is your first time, make sure you set up the R environment and create the executables as described below in the first two steps. Otherwise you can continue directly to [3. Example Sense apps](#3-example-sense-apps).
+If it is your first time, make sure you set up the R environment and create the executables as described below in the first two steps. Otherwise you can continue directly to [3. Example Qlik apps](#3-example-qlik-apps).
 
 ## 1. Set up R Environment
 1. Install R and R Studio by following the instructions on https://www.rstudio.com/
@@ -14,22 +14,23 @@ If it is your first time, make sure you set up the R environment and create the
 _Prerequisites_: Visual Studio 2015 (or later)   
 To be able to run the _SSEtoRserve_ plugin you must follow these steps:
 1. Open the `ServerSideExtension.sln` solution file located in the `csharp` folder.
-2. Build the solution to pull down the dependent libraries.
-3. Rebuild the solution again. Now you have your executables located in `csharp/SSEtoRserve/bin` folder.
+2. Note that there are two files missing in the ServerSideExtension project, ServerSideExtension.cs and ServerSideExtensionGrpc.cs. This is ok and will be automatically fixed in the following steps. 
+3. Build the solution to pull down the dependent NuGet packages and libraries (like Grpc.Tools).
+4. Rebuild the solution again. This time the missing files will be generated from the proto file (the protocol) using Grpc.Tools. Now you have your executables located in `csharp/SSEtoRserve/bin` folder.
 
-## 3. Example Sense apps
-There are several example Sense apps located in the sense_apps folder. Here follows a short description of each and what functionalities are covered as well as dependent libraries.
+## 3. Example Qlik apps
+There are several example Qlik apps located in the sense_apps and qlikview_apps folders. Here follows a short description of each and what functionalities are covered as well as dependent libraries.
 
 | __Example__ | __R Libraries__ | __Description__ |
 |-----|------|-----|
 | __R_DecisionTree__ | rpart, d3r, partykit, jsonlite | A d3.js visualization showing a decision tree, based on a json result string returned from R. |
 | __R_TimeSeriesAnalysis__ | TTR, forecast, tseries, colorspace | Time series use cases. |
 | __R_BasicExample__ | | Examples for all the different script functions. Also example when calling R from load script. |
 
-## 4. Install Dependent Libraries
+## 4. Install Dependent R Libraries
 Install the dependent libraries for the chosen example by
 1. Start R Studio.
-2. Run `install.packages('<library>')` for each library that will be needed based on your use case. For the example Qlik Sense apps you can see the needed libraries in the table above.
+2. Run `install.packages('<library>')` for each library that will be needed based on your use case. For the example Qlik apps you can see the needed libraries in the table above.
 
 ## 5. Start Rserve
 Assuming R Studio is still running. Run the following commands in the console.  
@@ -42,21 +43,21 @@ Rserve()
 
 ## 6. Start the R plugin
 1. If you have built the plugin from the source code, browse to the `csharp/SSEtoRserve/bin/Release` directory.
-2. **[optional]** Configure which Rserve host and port to connect to as well as which gRPC port this plugin should open (the port Qlik Sense is connecting to). This is done by editing the file `SSEtoRserve.exe.config`.
+2. **[optional]** Configure which Rserve host and port to connect to as well as which gRPC port this plugin should open (the port the Qlik engine is connecting to). This is done by editing the file `SSEtoRserve.exe.config`.
 3. **[optional]** Enable secure connection (Mutual Authentication) between this plugin and Qlik, by specifying the certificateFolderFullPath in the file `SSEtoRserve.exe.config`. Three files must be copied manually to that folder and the files needs to have the following names `root_cert.pem`, `sse_server_cert.pem`, `sse_server_key.pem`.
 4. **[optional]** Configure the SSEtoRserve log level that is written to the logs folder. Default level is Debug. By enabling Trace level you will see all data that is sent to the plugin from Qlik for easier debugging. This is done by editing the file `NLog.config` (at the bottom of the file). This is also the case for changing the level of console prints.
 5. Start `SSEtoRserve.exe` located in the folder.
 
-## 7. Configure the Plugin in Qlik Sense
-* __Qlik Sense Desktop__  
+## 7. Configure the Plugin in Qlik
+* __Qlik Sense Desktop, QlikView Desktop and QlikView Server__  
 Add the following line in the settings.ini file:
 `SSEPlugin=R,localhost:50051`
 * __Qlik Sense Enterprise/Server__  
   1. In the QMC, add a new Analytic Connection. To match the name used in the example apps, use the Analytic Connection name `R`.
   2. Restart the Qlik Sense Engine service.
 
-## 8. Start Qlik Sense and start using the apps
-Note that if you make changes to the plugin config in the settings.ini file or in the QMC you need to restart Qlik Sense (Engine service in server) for the changes to take effect since a connection to the plugin is only made during startup.
+## 8. Start Qlik and start using the apps
+Note that if you make changes to the plugin config in the settings.ini file or in the QMC you need to restart the Qlik engine (Engine service in Qlik Sense Server) for the changes to take effect since a connection to the plugin is only made during startup.
 
 # Usage from Qlik expressions and load script
 Eight script functions are automatically added to the functionality of the plugin. What is needed to be covered on the plugin side to fulfill the functionality is to implement the EvaluateScript rpc function. 
@@ -109,7 +110,7 @@ Here we pass two data fields of type string from Qlik (age_b and sex, defined as
 
 # Configure SSEtoRserve
 In the file `SSEtoRserve.exe.config` you can configure the following: 
-* **grpcPort** :  Default `50051` . The gRPC port this plugin should open (the port Qlik Sense is connecting to). Set to another port if you have other SSE plugins already defined on that port.  
+* **grpcPort** :  Default `50051` . The gRPC port this plugin should open (the port the Qlik engine is connecting to). Set to another port if you have other SSE plugins already defined on that port.  
 * **grpcHost** :  Default `localhost` . The gRPC host this plugin should open the port for. Set to `0.0.0.0` if you want this plugin to be reachable from another machine than this (typically if Qlik is installed on another machine).  
 * **rservePort** :  Default `6311` . The Rserve port this plugin should connect to.  
 * **rserveHost** :  Default `127.0.0.1` . The Rserve host this plugin should connect to.  

README.md

@@ -9,6 +9,7 @@ R is not a supported language in gRPC by default. The purpose of this repository
 ## Status
 **Current Plugin Version and State:** v1.0.0  
 **Matching Qlik Sense Version:** Qlik Sense June 2017 release (or later). Both desktop and enterprise.  
+**Matching QlikView Version:** QlikView November 2017 (or later). Both desktop and server.  
 **Disclaimer:** Use it at your own risk. See [License](#license).  
 
 [Previous Versions](docs/versions.md)
@@ -26,25 +27,25 @@ See the docs folder and the general SSE repo (server-side-extension).
 
 * [Get Started](GetStarted.md)
 
-## Secure connection using certificates
+## Security
+
+#### General Security Attention 
+Since R scripts can be very powerful and you will never know what R script will be executed by this plugin (and R installation) you must be extra careful to secure the machine that this plugin and the R installation are deployed to as much as you can. If possible, sandbox the execution. Be aware of which user account that is starting the plugin and R installation and what access rights this user got in the machine and in your domain to minimize any harm a malicious script can cause. 
+
+#### Secure connection using certificates
 Enable secure connection between the plugin server and Qlik by enabling mutual authentication. See the folder `generate_certs_guide` that explains how to generate proper certificates. This can be found in the general SSE repo (server-side-extension).
 
 ## Limitations in this version of SSE
 
-#### Load Script (Qlik Sense Limitation)
-- The functions that the SSE plugins provide may not show up properly in the script editor in Qlik Sense which means the intellisense may complain about it and show error, even if it works just fine to execute.
+#### Load Script (Qlik Limitation)
 - No support for Tensor calls from load script. Only scalar and aggregation.
 - Resident Table load only.
 
 #### Returning Data
-- There is NO support of returning more rows or a matrix of data back to Qlik Sense. The cardinality of the response from the plugin must be the same as sent from Qlik Sense.
-
-#### Changed Plugin Configuration (Qlik Sense Limitation)
-- If you make changes to the plugin config or add/remove plugins you have to restart Qlik Sense Desktop or the Qlik Sense Engine Service in Server version. It is only during Engine startup that the plugin is connected and the GetCapability plugin method is called.
-
-#### QlikView
-- This version of SSE is not supported in QlikView yet. We are planning to release SSE support in QlikView during 2017-H2.
+- There is NO support of returning more rows or a matrix of data back to Qlik. The cardinality of the response from the plugin must be the same as sent from Qlik.
 
+#### Changed Plugin Configuration (Qlik Limitation)
+- If you make changes to the plugin config or add/remove plugins you have to restart the Qlik engine (i.e. restarting the Desktop process for Qlik Sense Desktop and QlikView Desktop, and restarting the Qlik Sense Engine Service or QlikView Server Service for server version). It is only during Engine startup that the plugin is connected and the GetCapability plugin method is called.
 
 ## License
 See [LICENSE.txt](LICENSE.txt).

docs/communication_flow.md

@@ -1,6 +1,6 @@
 # Communication Flow
 
-The sequence below describes the communication between Qlik Sense Client, Qlik Sense Engine, the SSE Plugin and R. The only difference from the communication flow described in the general server-side-extension repository is the communication between the plugin and R (Rserve).
+The sequence below describes the communication between Qlik Sense Client, Qlik Sense Engine, the SSE Plugin and R  (the communication between _QlikView_ and the SSE plugin works in the same way). The only difference from the communication flow described in the general server-side-extension repository is the communication between the plugin and R (Rserve).
 
 The sequence in words:
 

docs/versions.md

@@ -1,6 +1,6 @@
 # Released Versions
-This page maps all released SSE R-plugin versions with the appropriate Sense versions.
+This page maps all released SSE R-plugin versions with the appropriate Qlik versions.
 
-| __R-plugin Version__ | __SSE Version__ | __Sense Version__ |
-| ----- | ----- | ----- |
-| [v1.0.0](https://github.com/qlik-oss/sse-r-plugin/releases/tag/v1.0.0) | [v1.0.0](https://github.com/qlik-oss/server-side-extension/releases/tag/v1.0.0) | Qlik Sense June 2017 release |
+| __R-plugin Version__ | __SSE Version__ | __Qlik Sense Version__ | __QlikView Version__ |
+| ----- | ----- | ----- | ----- |
+| [v1.0.0](https://github.com/qlik-oss/sse-r-plugin/releases/tag/v1.0.0) | [v1.0.0](https://github.com/qlik-oss/server-side-extension/releases/tag/v1.0.0) | Qlik Sense June 2017 release | QlikView November 2017 release |