2023-06-19
Qlik Sense Integration
Qlik Sense Repository Service (QRS) API
Qlik Sense Repository Service (QRS) API is a very useful API service which allows to perform similar actions like in the QMC console. For example, it can import app, delete app, publish app and so on. It can also trigger reload tasks, getting lists of app objects, managing security rules (systemrule), etc. Basically, it is an interface to communicate with the backend Qlik Sense Repository Service and provides a full set of API calls for Qlik Sense integration and management.
There are two methods to connect to the QRS API. One is via the proxy with port 443 and the other is directly to the API endpoints with the port 4242. This article is focusing on the latter method to directly connect to API endpoints with the port 4242.
Pre-requisite
In order to call the QRS API, the following are required:
1. Qlik Sense Certificate
This is used for authentication. The certificate is similar to an access card to allow to call the QRS API.
* Please keep these files in a safe location. These files will allow the connection to the Qlik Sense QRS service and perform everything related to repository service!
2. Xrfkey
It is a string with a length of 16 arbitrary character long. It must provide in both the request parameters and the request header to avoid web vulnerability. The pair provided must be matched. The characters can only be number and alphabets, i.e. 0-9, a-z and A-Z.
3. HTTP Client
CURL, postman, some browser extension are typical HTTP clients. This article will focus on CURL because it is command-line based and can easily be used for integration.
4. Port 4242
It must make sure the port 4242 is not blocked by firewall. Or to be more secure and specific, you should decide to just allow certain IP to connect to the QRS server with port 4242.
Preparation
Preparation - Getting Qlik Sense Certificate
1. Go to the central node of the Qlik Sense server.
2. Navigate to the path C:\programdata\Qlik\Sense\Repository\Exported Certificates\.Local Certificates
3. Copy client.pem and client_key.pem files into a safe location, say, E:\Qlik Sense API\Certificate
Preparation - Xrfkey
It is easy to have one like abcdEDFGh0123456. Or you can use dynamic method to generate this character string to enhance the security.
Preparation - HTTP Client
The CURL can be downloaded in the link https://curl.se/download.html.
1. Download the latest version and extract the zip file. Say, E:\Qlik Sense API\CURL
2. We will need to call CURL.exe in the bin folder. Mark down the entire path, say, E:\Qlik Sense API\CURL\bin\curl.exe.
Preparation - CURL command to call QRS API
"E:\Qlik Sense API\CURL\bin\curl.exe" -X GET --cert "E:\Qlik Sense API\Certificate\client.pem" --key "E:\Qlik Sense API\Certificate\client_key.pem" --insecure -k "https://[Server FQDN]:4242/qrs/app?xrfkey=0123456789abcdef" --header "x-qlik-xrfkey: abcdefgh0123456" --header "X-Qlik-User: UserDirectory=internal;UserId=sa_repository "
Taking an example of the above, the CURL command contains the following elements:
1. The CURL execution file.
"E:\Qlik Sense API\CURL\bin\curl.exe"
2. The HTTP request method used by CURL. In QRS API, it can be GET, POST, PUT, DELETE.
-X GET
2. The certificate obtained from the Qlik Sense server for authentication purpose.
--cert "E:\Qlik Sense API\Certificate\client.pem" --key "E:\Qlik Sense API\Certificate\client_key.pem"
3. If this is specified, it allows self-signed certificate.
--insecure
4. The QRS API endpoint, the example is calling to get a list of app
https://[Server FQDN]:4242/qrs/app
5. The XRFkey in the request parameter.
?xrfkey=0123456789abcdef
5. The XRFkey header to match with the request parameter
--header "x-qlik-xrfkey: abcdefgh0123456"
6. Impersonating the account to perform the action. This account must have adequate privilege to perform the actions. sa_repository is the Qlik Sense internal account to handle repository related matters.
--header "X-Qlik-User: UserDirectory=internal;UserId=sa_repository"
7. [optional by API endpoint requirement] Sometimes, additional headers are required:
e.g. --header "Content-Type:application/json"
This specifies the request body to be JSON format.
e.g. --header "Content-Type:application/vnd.qlik.sense.app"
This specifies the request body is a binary QVF file.
e.g. --header "Content-Length:0"
This specifies the request body is with no content.
e.g. --data-binary "@[Path_of_upload_file/content]"
It specifies the path of the upload file/content.
Examples to call the QRS API
We are now ready to call the QRS API. For instance:
1. Getting a list of app
"E:\Qlik Sense API\CURL\bin\curl.exe" -X GET --cert "E:\Qlik Sense API\Certificate\client.pem" --key "E:\Qlik Sense API\Certificate\client_key.pem" --insecure -k "https://[Server FQDN]:4242/qrs/app?xrfkey=0123456789abcdef" --header "x-qlik-xrfkey: abcdefgh0123456" --header "X-Qlik-User: UserDirectory=internal;UserId=sa_repository"
2. Uploading an app
"E:\Qlik Sense API\CURL\bin\curl.exe" - T "E:\Qlik Sense\App\App Name.qvf" -X POST --cert "E:\Qlik Sense API\Certificate\client.pem" --key "E:\Qlik Sense API\Certificate\client_key.pem" --insecure -k "https://[Server FQDN]:4242/qrs/app/upload?xrfkey=0123456789abcdef&name=App%20Name&keepdata=true&excludeconnections=true" --header "x-qlik-xrfkey: abcdefgh0123456" --header "X-Qlik-User: UserDirectory=internal;UserId=sa_repository" --header "Content-Type:application/vnd.qlik.sense.app"
Note:
- -T is to specify to do multipart upload.
- "E:\Qlik Sense\App\App Name.qvf" is the QVF file location.
- keepdata=true is to retain the data.
- excludeconntions=true is to avoid creating the data connection.
3. Change App Owner and Unapprove
"E:\Qlik Sense API\CURL\bin\curl.exe" -X PUT --cert "E:\Qlik Sense API\Certificate\client.pem" --key "E:\Qlik Sense API\Certificate\client_key.pem" --insecure -k "https://[Server FQDN]:4242/qrs/app/[app_id]/object?xrfkey=0123456789abcdef "--header "x-qlik-xrfkey: abcdefgh0123456" --header "X-Qlik-User: UserDirectory=internal;UserId=sa_repository" --header "Content-Type:application/json" --data-binary "@E:\Qlik Sense API\json\appobject_[id].json"
Note:
- The change owner and unapprove details are inside the json file. This can be obtained and modified by getting the app/[id]/object/full to get the json and then to change the required details.
Tips
1. the endpoint to be called needs to be URL encoded, e.g. " " (a space) to %20.
2. Calling in batch file. % needs to be escaped by %%.
3. Majority of JSON required, you can refer to the /full to get an idea of how to build the json content.
4. Refer the API call in the method sections
5. Refer the API required JSON (model) in the model section.
6. If you exporting the details from Qlik Server, it always comes with a GUID and this GUID is an unique identifier to classify the uniqueness of the object. This GUID, in fact, can be retained when you are using the API to post it back to the server. Excepting App, App Object, the GUID must be changed. Other objects in the Qlik Sense server, in fact, can be maintained if the JSON has specified it in the API call
API call is very useful for system integration. For example, to trigger a reload task once the data is ready. The upstream system can send a QRS API to trigger the reload. Other useful example would be server migration. All the details can be obtained by the QRS API and these details can simply post back to the new server. This can also enhance durability of the server since the redundant content can be scanned and ignored during the processes.
I hope you find it useful! See you in the next post :-) !