Unlock a world of possibilities! Login now and discover the exclusive benefits awaiting you.
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
- If the cursor token is returned in the response header instead of the response body, the 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 Name - Name 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.
| 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 |
| Page Size Field Name | Yes | Yes | Yes |
| Page Size | Yes | Yes | Yes |
| Offset Field Name | Yes | ||
| Page Start | Yes | Yes | |
| Json Path For Output Records | Yes | Yes | Yes |
| Json Path For Cursor | Yes | ||
| Output Name For Cursor Token | Yes | ||
| Page Number Field Name | 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:
- Authorize URL: https://login.microsoftonline.com/common/oauth2/v2.0/authorize
- Access Token URL: https://login.microsoftonline.com/common/oauth2/v2.0/token
- Refresh Token URL: https://login.microsoftonline.com/common/oauth2/v2.0/token
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.
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.
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 - 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.
Below are the input parameter
- 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.
- 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.
- Headers: We don't use it because we don't require any further header information.
- Page Size Field Name: per_page is the query parameter name used to reduce the amount of data returned in a single API call.
- 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.
- Page Number Field Name: Because this is page-based pagination, the page query parameter is 'page'.
- 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.
- 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.
- 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.
Below are the input parameter
- 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
- 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.
- Headers: We don't use it because we don't require any further header information.
- Page Size Field Name: maxResults is the query parameter name used to reduce the amount of data returned in a single API call.
- 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.
- Offset Field Name: Because this is offset pagination, the offset query parameter is startAt.
- Page Start: This is the offset's starting number. The value should be either 0 or 1
- 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.
- 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.
Below are the input parameter
- 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.
- 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.
- Headers: We don't use it because we don't require any further header information.
- Page Size Field Name: pageSize is the query parameter name used to reduce the amount of data returned in a single API call.
- 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.
- 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.
- 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.
- 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.
