Skip to main content
Announcements
Marching toward a simplified navigation! READ ON

How to: Getting started with the Oauth2 connector in Qlik Application Automation

No ratings
cancel
Showing results for 
Search instead for 
Did you mean: 
MarkGeurtsen
Support
Support

How to: Getting started with the Oauth2 connector in Qlik Application Automation

Last Update:

Apr 20, 2023 7:38:13 AM

Updated By:

Jayarams

Created date:

Jan 12, 2022 11:08:19 AM

This article is meant to get users starting on the Oauth connector in Qlik Application Automation.
This connector is meant for advanced users to platforms where we did not (yet) build a dedicated connector for.
The connector makes use of the authorization code flow of Oauth2. The authorization code flow is well explained on the following link: https://oauth.net/2/grant-types/authorization-code/

Limitations

  • This connector will work for most OAuth2 flows. In cases where there's additional fields to be sent such as additional query parameters in the authorize request, this connector will not work.
  • For the list endpoints other than those listed below The solution is to implement paging at the automation level. This is well explained in the following article.: https://community.qlik.com/t5/Knowledge/How-to-implement-pagination-using-Call-Url-block-in-an/ta-p/...
    • raw API list request - offset based paging
    • raw API list request - page number based paging.
    • raw API list request - cursor token based paging
    • raw API list request - cursor URL based paging
  • If the cursor token or cursor URL is returned in the response header instead of the response body, the cursor URL and cursor token endpoints do not work.
  • The list blocks won't work if the business data in the API response is not enclosed in a JSON key.

How to connect

First start by looking for the connector "OAuth2". When you click on connect it requests the following input parameters:

  • Base URL - This should be the base of the URL you will be making REST calls to. We recommend providing this as much as possible as it will prevent making calls to other URL's.
  • Authorize URL - Can usually be obtained from the documentation of the platform you're attempting to connect to.
  • Access Token URL - Can usually be obtained from the documentation of the platform you're attempting to connect to.
  • Refresh Token URL - Can usually be obtained from the documentation of the platform you're attempting to connect to. Most of the time this is the exact same as the Access Token URL.
  • OAuth Client ID - Will have to be created in the platform you're connecting to.
  • OAuth Client Secret - Will have to be created in the platform you're connecting to.
  • OAuth Scopes - Obtain from documentation.

When all of this is provided and you click the Save button, it will open a popup taking you to the login screen where you will be prompted to provide consent. Your connection is now ready to be used.

How to use in an automation

When selecting the connector in an automation you will notice Raw API Request block. This block has the following input variables:

  • Path - This needs to be relative to the Base URL you provided when connecting.
  • Method - Enum choice between GET, POST, DELETE, PATCH or PUT.
  • Query Parameters - Here you can provide a JSON object and the key/values will be added to the path as query parameters.
  • Request Body - A JSON object can be provided for POST, PATCH or PUT operations that will be sent as request body.
  • Headers - JSON object and these key/values will be added as headers to the request.

Apart from the above input variables, RAW API LIST blocks have the following input variables

  • Page Size Field NameName of the page size query parameter.
  • Page Size - The desired page size. The maximum value allowed is 200.
  • Offset Field Name Name of the offset query parameter.
  • Page Start - The initial value of the Offset Field Name or Page Number Field Name query parameter. It should be either 0 or 1.
    • For offset based pagination: Depending on the page size and the page start the value of the offset parameter for the second page will be calculated. 
    • For Page number based pagination: The page number is either a 1-based or zero-based value. The value will be incremented by 1 to fetch the next page's data.
  • Json Path For Output Records - The JSON key's name in the response will be used to parse a portion of the overall JSON returned by the API endpoint. This only returns a parsed VALUE.
  • Json Path For Cursor The JSON key in the API response whose cursor/token value can be used to request the next page of resources. 
  • Output Name For Cursor Token - Name of the cursor token query parameter.
  • Page Number Field Name - Name of the page number query parameter. 
  • Json Path For Cursor Url - The JSON key in the API response, which is effectively a URL, can be used to retrieve the next page of resources. 
Input variables raw API list request - page number based paging raw API list request - offset based paging raw API list request - cursor token based paging raw API list request - cursor URL based paging
Page Size Field Name Yes Yes Yes Yes
Page Size Yes Yes Yes Yes
Offset Field Name   Yes    
Page Start Yes Yes    
Json Path For Output Records Yes Yes Yes Yes
Json Path For Cursor     Yes  
Output Name For Cursor Token     Yes  
 Page Number Field Name Yes      
Json Path For Cursor Url
      Yes

 

An example

The following example will obtain tasks from the Microsoft Todo application. We do not yet have a connector to do this and Oauth is used to obtain the value for the Authorization header.
We first start by obtaining the Authorize URL, Access Ttoken URL and Refresh Token URL. From the Microsoft documentation we can find these at https://docs.microsoft.com/en-us/graph/auth-v2-user. We use the following values:

The documentation of the Microsoft Graph API  can be found at https://docs.microsoft.com/en-us/graph/use-the-api?context=graph%2Fapi%2F1.0&view=graph-rest-1.0.
We obtain the Base URL: https://graph.microsoft.com/v1.0.

We will have to obtain a client ID and client secret. We can do the registration for an app at https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade. We register a new application, give it the name "Todo App" and set it to only allow accounts from this organizational directory only. For the redirect url the following value needs to be provided: https://connector.qlikcloud.com/callback. Set the platform to Web.

On the next screen you can obtain your Client ID. Copy this value. Click on Add a certificate or Secret and it will take you to a page where you can create a new client secret.
Create one and copy the value that is now visible.

In the left sidebar click on the button API Permissions. Click on Add a Permission and provide the scope Tasks.ReadWrite.

Back to your connector configuration - Provide the client ID and client secret that were obtained and for the scopes provide the following: User.Read Tasks.ReadWrite offline_access openid
Now click on Save and you should be presented with a screen to login.

 

MarkGeurtsen_5-1642003557556.png

Using it in an automation

1) Raw API Request block:

Create a new automation and drag the Raw API Request block on to the canvas. Set the path to /me and the method to GET. When you now execute it, you should receive a JSON result containing the keys response, headers and status. Most relevant information should be part of the response.

Next let's obtain a list of tasks. Drag another Raw API request block and put it below the earlier one. Set the path to /users/{$.rawApiRequest.response.id}/todo/lists and method should remain at GET. Now when you execute this, it will return you the lists you keep in Todo.

MarkGeurtsen_7-1642003686087.png

2) List Blocks: Depending on the type of pagination, we have 4 different List blocks. Therefore, depending on the type of pagination in API, any one of the List blocks should be used for a certain API.

We tested the blocks using four distinct APIs, each with a different pagination implementation.

  • raw API list request - page number based paging: Zoho
  • raw API list request - offset based paging: JIRA
  • raw API list request - cursor token based paging : Google People
  • raw API list request - cursor URL based paging : Bitbucket
  1. raw API list request - page number based paging: 
    Create new automation and drag the raw API list request - page number based paging block onto the canvas.
    Create a new connection. We used the Zoho API. Please visit the API documentation link for your API to obtain Oauth information and the pagination documentation to obtain pagination information.

    Page-number.png
    Below are the input parameter
    1. path: If the baseUrl in the connection parameter ends with '/', do not prefix the same character at the beginning of the path in the endpoint input parameter. We are using "Leads" to list the lead in Zoho.
    2. Query Parameters: We haven't used them in the example. Similarly, we can try a variety of other query parameters listed in the API documentation.
    3. Headers: We don't use it because we don't require any further header information.
    4. Page Size Field Name: per_page is the query parameter name used to reduce the amount of data returned in a single API call.
    5. Page Size: The query parameter per_page's value. We made use of 8. If the entered value exceeds 200. We'll set it to 200 in the backend.
    6. Page Number Field Name: Because this is page-based pagination, the page query parameter is 'page'.
    7. Page Start: This is the number that indicates where the page begins. The value should be either 0 or 1. This value will only be used in the first API request; in subsequent calls, it will be increased by one in the backend and used in the above page query parameter name. We have used 1.
    8. Json Path For Output Records: Parse a portion of the JSON returned by the API endpoint. This only returns a parsed VALUE. We have used 'data' in our example.

  2. raw API list request - offset based paging : 
    Create new automation and drag the raw API list request - offset based paging block onto the canvas.
    Create a new connection. We used the JIRA API. Please visit the API documentation link for your API to obtain Oauth information and the pagination documentation to obtain pagination information.

    Offset.png
    Below are the input parameter
    1. path: If the baseUrl in the connection parameter ends with '/', do not prefix the same character at the beginning of the path in the endpoint input parameter. We are using "Search" to search the issues
    2. Query Parameters: We utilized the fields query parameter to limit the data returned by JSON Object. Similarly, we can experiment with many additional query parameters listed in the API documentation.
    3. Headers: We don't use it because we don't require any further header information.
    4. Page Size Field Name: maxResults is the query parameter name used to reduce the amount of data returned in a single API call.
    5. Page Size: The query parameter maxResults's value. We made use of 50. If the entered value exceeds 200. We'll set it to 200 in the backend.
    6. Offset Field Name: Because this is offset pagination, the offset query parameter is startAt.
    7. Page Start: This is the offset's starting number. The value should be either 0 or 1 
    8. Json Path For Output Records: Parse a portion of the JSON returned by the API endpoint. This only returns a parsed VALUE. According to the JIRA API docs, we're getting a list of issues from the "issues" key.
  3. raw API list request - cursor token based paging:
    Create new automation and drag the raw API list request - token based paging block onto the canvas.
    Create a new connection. We used the Google People API. Please visit the API documentation link for your API to obtain Oauth information and the pagination documentation to obtain pagination information.

    Cursor-Token.png
    Below are the input parameter
    1. path: If the baseUrl in the connection parameter ends with '/', do not prefix the same character at the beginning of the path in the endpoint input parameter. We are trying to list the contactGroups in Google People.
    2. Query parameters: We haven't used them in the example. Similarly, we can try a variety of other query parameters listed in the API documentation.
    3. Headers: We don't use it because we don't require any further header information.
    4. Page Size Field Name: pageSize is the query parameter name used to reduce the amount of data returned in a single API call.
    5. Page Size: The query parameter maxResults's value. We made use of 20. If the entered value exceeds 200. We'll set it to 200 in the backend.
    6. Json Path For Cursor: The JSON key in the API response, the cursor value will be used to request the next page of resources. Use '.' to denote objects within an array. This endpoint block will not work if the cursor URL is returned in the header.
    7. Output Name For Cursor Token: The name of the cursor Query parameter, which will be used to fetch resources for the following page. We used pageToken in this case.
    8. Json Path For Output Records: Parse a portion of the JSON returned by the API endpoint. This only returns a parsed VALUE.

  4. raw API list request - cursor URL based paging
    Create new automation and drag the raw API list request - URL based paging block onto the canvas.
    Create a new connection. We used the Bitbucket API. Please visit the API documentation link for your API to obtain Oauth information and the pagination documentation to obtain pagination information.

    Cursor-URL.png
    Below are the input parameter
    1. path: If the baseUrl in the connection parameter ends with '/', do not prefix the same character at the beginning of the path in the endpoint input parameter. We are trying to list the commits.
    2. Query parameters: We haven't used them in the example. Similarly, we can try a variety of other query parameters listed in the API documentation.
    3. Headers: We don't use it because we don't require any further header information.
    4. Page Size Field Name: maxResults is the query parameter name used to reduce the amount of data returned in a single API call.
    5. Page Size: The query parameter maxResults's value. We made use of 50. If the entered value exceeds 200. We'll set it to 200 in the backend.
    6. Json Path For Cursor Url: The JSON key in the API response, which is effectively a URL, can be used to retrieve the next page of resources. Use '.' to denote objects within an array. This endpoint block will not work if the cursor URL is returned in the header.
    7. Json Path For Output Records: Parse a portion of the JSON returned by the API endpoint. This only returns a parsed VALUE.

The information in this article is provided as-is and to be used at own discretion. Depending on tool(s) used, customization(s), and/or other factors ongoing support on the solution below may not be provided by Qlik Support.

Tags (1)
Labels (1)
Comments
Chotana2
Partner - Contributor III
Partner - Contributor III

Hi Mark,

 

As per following documentation page,

https://help.qlik.com/en-US/connectors/Subsystems/REST_connector_help/Content/Connectors_REST/REST-c...

REST connector doesn't support OAuth (see page bottom).

 

Does you article apply only for SAAS version? I'm trying with QSEOW August 2022 and struggle getting a token with the REST connector vs OAuth2.0

Thanks

Thanks

Sonja_Bauernfeind
Digital Support
Digital Support

Hello @Chotana2 

The REST connector in general does not support OAuth at this point: Does Qlik REST connector support OAuth authentication? 

I'd recommend looking into logging a feature request/idea (I couldn't find one already logged specifically for the REST connector).

All the best,
Sonja

Chotana2
Partner - Contributor III
Partner - Contributor III
Sonja_Bauernfeind
Digital Support
Digital Support

@Chotana2 aha! I misunderstood, I thought you meant only the REST connector 

 

Chotana2
Partner - Contributor III
Partner - Contributor III

Well,

My request concerns the REST connector, but it's better to open it more widely.

joostvanegmond7
Partner - Contributor II
Partner - Contributor II

Hi Mark, 

Thank you for this article. It helped me creating an oauth2.0 connection to MS Projects.

Yet, the connection seems to disconnect after a while. When I click on SAVE, I fill in my Username and Password. I receive the message 'Connection is linked' and everything works fine. But after a few hours the connection seems "unlinked", although the message is still 'Connection is linked'. When I run the automation it gives an 403 error. I just need change the URL and click on SAVE so I can login with the user again, but I don't want to do this all the time 🙂 

Is it possible to keep the user connected? 

 

Version history
Last update:
‎2023-04-20 07:38 AM
Updated by: