Kyvos Web Portal Integration with Third-party Application

Applies to:Kyvos Enterprise Kyvos Cloud (Managed Services on AWS) Kyvos Azure Marketplace

Kyvos AWS Marketplace Kyvos Single Node Installation (Kyvos SNI) Kyvos Free (Limited offering for AWS)

Integrating Kyvos UI with third-party applications

Kyvos web application can integrate into your enterprise application for a seamless user experience.

Kyvos supports the following types of integration environments:

Environments where the host application and Kyvos are running as separate web applications. In this case, both applications respect cross-domain requests via Cross-Origin Resource Sharing (CORS) requests.
Environments where the Kyvos application folder is embedded/placed in the host (third-party) application folder, and both are running as a single application on a web server.

The Kyvos web portal integration with any third-party application is facilitated through HTTP calls. In an integration environment, the host application calls the Kyvos pages through an HTTP URL along with the configuration parameters. This is needed irrespective of whether the Kyvos application is physically placed under the folder structure of the host application (embedded) or Kyvos is running as a separate application.

As Kyvos UI integration is HTTP based, so the scheme in which the two web applications (host and Kyvos) are running plays an important role in integration. The following table explains the results for various combinations of HTTP protocols between Kyvos and the host application.

Host Application protocol	Integrated Kyvos protocol	Result
HTTP	HTTP	Kyvos pages can open in the host application as Inline Frame (iframe) element.
HTTP	HTTPS	Kyvos pages can open in the host application as an iframe.
HTTPS	HTTPS	Kyvos pages can open in the host application as an iframe.
HTTPS	HTTP	Kyvos pages can open in a new browser window, but not in an iframe. As this may be a security threat to the secure host application, the browser does not support opening as iframe.

Browsing Kyvos use cases

The Kyvos web application introduces a URL pattern for all integration-based URL requests.

To connect/browse Kyvos functionalities (use cases), use the below URL pattern in your application:

http://<hostname:hostport>/kyvos/kyvosIntegration.jsp?page=<usecase>&name=<entityName>&folderName=<folderName>&workbookName=<workbookName>& EXT_AUTH_PARAMETER_VALUE_TYPE=sessionId&<EXT_AUTH_HEADER_ID>=<token>&mode=<modeName>&overrideConfig=<config>&actionCode=<action>&integrationId=<integrationId>

Here, the request parameters are:

Request parameter	Value	Description
Page	Usecase Name	Name of the Kyvos functionality/use case to open. Allowed values are: workbooks: Allows users to access Kyvos workbooks from the host application. semantic models: Allows users to access Kyvos semantic models from the host application. relationship: Allows users to access Kyvos relationship designer from the host application. datasets: Allows users to access Kyvos datasets from the host application. files: Allows users to access Kyvos file registration from the host application. monitor: Allows users to access Kyvos Activity Monitor from the host application. users: Allows users to access Kyvos user configuration from the host application. groups: Allows users to access Kyvos groups configuration from the host application. connections: Allows users to access Kyvos connection configuration from the host application. license: Allows users to access the Kyvos license screen from the host application. export semantic models: Allows users to access the Kyvos user configuration from the host application. import: Allows users to access Kyvos import functionality from the host application. export: Allows users to access Kyvos export functionality from the host application.
name	Entity Name	Name of the entity to open from the host application. For example, the name of the semantic model, dataset, or dashboard, etc.
id	Entity ID	The ID of the entity to open from the host application. NOTE: Use this parameter if the name is not available.
folderName	Name of the folder	If the entity to be opened is placed in a folder, then provide the folder name in this parameter. If the entity is not contained within any folder, then ignore this parameter.
folderId	Folder ID	The ID of the entity containing the folder to open from the host application. NOTE: Use this parameter if the name is not available.
workbookName	Name of the workbook	Name of the dashboard or worksheet to open from the host application.
workbookId	Workbook ID	The ID of the workbook to open from the host application. NOTE: Use this parameter if the name is not available.
<EXT_AUTH_HEADER_ID>	Authentication token parameter	Value of this parameter is the token(sessionId) received from the successful Kyvos login REST API response. Name of this parameter is defined in kyvosclient.properties. (For more details, please refer user authentication section below in the same document.)
mode	Mode Name	This parameter is optional. Set this value to the name of the mode(defined in integration.config.json), so that when workbook use case is loaded with the URL, all configuration related to that mode will be applied on the viewer workspace. For example, mode=”VIEW”
overrideConfig	Config to override Integration.config.json	This parameter is optional. A comma-separated list of properties to override the property in integration.config. For example, header.show:false,usecases.listing:false,header.homeIcon:false.
actionCode	Action Code	This is an optional parameter. The possible values are: add: Use this to add a worksheet in a workbook. addWorkbook: Use this to add a workbook inside a folder or root. Show: Use this to open a worksheet or dashboard. The default value is Show.
integrationId	Integration identifier	This parameter is optional, possible value is any unique string, that will be used to identify a particular kyvos application in embedded mode. This identifier will be used to map runtime communication between a particular iframe (Kyvos application) and host application, when multiple iframes are there.

The following figure shows Kyvos folders and workbook listing integrated with the host application.

The following figure shows the Kyvos viewer integrated with the host application.

The following figure shows the Add New Worksheet option in the Kyvos Visualization integrated with the host application.

User authentication mechanism

Authentication for all integrated environments depends on the type of integration, and in most cases, the Kyvos login page is not needed. Session expiry is also handled as per the authentication mechanism used in the integration.

The Kyvos pages in an integration environment, follow the authentication mechanism defined within the Kyvos application. However, if your application has already authenticated the user, then no authentication is required to open Kyvos pages.

User authentication configuration

Kyvos application needs user details for authentication and authorization to serve different requests as per the logged-in users’ roles and rights. So, the host application and Kyvos needs handshaking to transfer user details to Kyvos.

Configurations for user authentication setup in Kyvos in integration mode.

Set the value for the authentication provider as HOST_APP in the config.json file. Details about the integration.config.json file are mentioned below in the configuration section.
Provide the value for the userAuthenticationVerificationUrl property in the config.json. This property is used for passwordless SSO. See the SSO section below for details.
Provide value for EXT_AUTH_HEADER_ID property in the properties file. EXT_AUTH_HEADER_ID defines parameter name of request to the Kyvos page corresponding to which user token would be provided. (Details about kyvosclient.properties file is mentioned below in the configuration section).

SSO between the Host application and Kyvos application

With username and password

To authenticate the user and create a session, call Kyvos login REST API with username=<username> and password=<password>.
Sample:
```
http://<hostname:hostport>/kyvos/rest/login?username=<username>&password=<password>
```
If the user is successfully authenticated, this call returns a success response.
For example, on successful authentication, REST API produces the below response.
```
{
     "RESPONSE":
   {
          "SUCCESS": "90DB354A-EE34-6827-B3E2-2BAAECE5C2E2"
   }
}
```
Pass the value of the SUCCESS property in the integration URL as the value of the parameter name defined by EXT_AUTH_HEADER_ID (as mentioned in the above section).

With username and token (password less authentication)

In this mode of authentication (passwordless), Kyvos relies on the host application for user authentication. Below is the flow diagram and its description:

The user logs into the Host web application by any authentication mechanism supported by the Host web application.
After the successful login of a user in the Host web application, the Host Web Application should also create a session at Kyvos to integrate Kyvos use-cases(workbook/worksheet).
To create a session with the Kyvos application, the Host app calls a Kyvos login REST call by passing the following parameters: username, bearer token (GUID), mode=INTEGRATION, and optional custom data.
http:<hostname>:<port>/kyvos/rest/login?username=&token=&mode=INTEGRATION&customData=
Now Kyvos validates parameter values received in the login REST by making the REST call to the verification endpoint with username, token, and custom data. Verification Server is provided by the Host web app and its URL is configured as userAuthenticationVerificationUrl in integration.config.json. This URL may or may not be the same as the Host web app end.
The verification endpoint validates the data, ensures that given parameters are valid, and returns true or false based on successful validation or failure, respectively.
If this verification REST call returns true as the HTTP response, then the SSO is successful, and the user session is created in Kyvos. Kyvos login REST call would return the success response for this user session. For example, on successful authentication, REST API produces the response below.
```
{
"RESPONSE": {
      "SUCCESS": "90DB354A-EE34-6827-B3E2-2BAAECE5C2E2"
   }
}
```
On Successful Validation, the Host web app embeds Kyvos use cases (workbook/worksheet) in an iframe (or new browser window) using an embed URL with sessionId as an HTTP parameter.
If the verification REST call returns a false response, the Kyvos login REST call will not issue any success response, and SSO will fail.

User roles and rights

The integration configurations define what options/actions are available to users.

If any option/action is allowed in configuration, then it will be allowed to the specific user only when the user’s rights/role allows that option/action. However, if an option/action is not permitted in configuration, then that option/action will not be available to the user even if the user's role/rights suffice for that option/action.

The following figure illustrates the mechanism for actions available for users.

Configurations for Kyvos functionality

To configure Kyvos functionality in your host application, define the following configurations.

For X-Frame-Options: To open Kyvos pages in Iframe, set the URL of the host application in the ALLOW_FROM parameter under HTTPFilterServlet in the xml file of the Kyvos application. It is available in the <kyvos web application folder>\WEB-INF folder.
For user authentication handshaking: Provide values for EXT_AUTH_HEADER_ID and EXT_AUTH_PARAMETER_VALUE_TYPE properties in the properties file, as explained in the User authentication configuration section. It is available at <kyvos web application folder>\client]config folder.
In the properties file configure the following properties:
1. EXT_AUTH_HOMEPAGE_URL: Provide a valid URL for the host application. Users will be redirected to this URL when the current http session in Kyvos expires.
2. EXT_AUTH_SIGN_OUT_REDIRECT_URL: Optionally, provide this to enable logout option in Kyvos while used in Integration. In this case, users will be redirected to this URL on logout.

For use cases in integration mode: Kyvos provides a user-friendly configuration file where you can configure the behavior/actions/options of all the use cases when called from an integration environment.

The configuration file integration.config.json is available at the <Kyvos web application folder>/client/config location. By default, the values for all the parameters are set to blank, which means all are enabled.

Here’s a snippet of the integration.config.json for your reference.

{
"authentication": {
"provider": "HOST_APP", /* this is to overwrite authentication mechanism to host app for Kyvos web application.*/
"userAuthenticationVerificationUrl":  "" /*REST call URL for reverse authentication handshaking, Kyvos would send username and token parameters to get it verified from host application*/
"ssoUserIdentifierType": "username" /*this is to tell the kyvos about the type of the value provided against username parameter in the login request. Kyvos supports username, email, and userid for SSO. Kyvos handles the value as per its type. If its an email or userid, then kyvos will resolve those to username, and then it will return a token.*/

},
"theme": {
       "name": ""/*name of custom theme folder, if present at location “kyvos\client\themes”*/
   },
   "header": { /*to configure header panel */
       "show": true,  /*whether to show header panel at all*/
       "recent": true,  /*in case header panel is visible, whether to show recent option*/
       "logout": true,  /*in case header panel is visible, whether to show logout option,if external auth is enabled then logout would not be visible anyways*/
       "notification": true  /*in case header panel is visible, whether to show notification option*/
   },
   "usecases": {
       "allow": "", /*comma-separated list of use cases to be allowed in integration mode. In case the value is blank, then all the use-cases would be available through the integration URL. Use case names are users, groups, connections, license, exportCube, import, export, files, datasets, relationships, cubes, and workbooks, */
       "listing": true  /*true means option to show list panel should be available*/
   },
   "workbooks": { /* here comes the viewer workspace configuration, */
       "viewMode" : {  /* Defines the view mode of the viewer. This should be the read-only mode, any option set to true means that is available to user when viewer is loaded in this mode. */
           "showLinkedFilters":true,  /* whether the hyperlink filters, widget linking filters should be shown on dashboard*/
           "actionPanel":true,  /* whether the top panel containing save,setup etc. should be available */
           "update":true,  /* whether the update layout option should be available */
           "revert":true,  /* whether revert  should be available */
           "save":false,  /* whether save should be available */
           "share":false,  /* whether share should be available */
           "export":true,  /* whether export should be available */
           "showNotes":true, /* whether notes should be available */
           "showRelatedEntities":false, /* whether related entities option should be available */
           "openSemanticmodel":false, /* whether open semantic model in new window option should be available */
           "setup":false,  /* whether toggle setup option should be available */  
           "duplicate":false,  /* whether duplicate should be available */
           "rename":false,  /* whether rename should be available */
           "delete":false,  /* whether delete should be available */
           "notify":false, /* whether notify should be available */
           "actionContextMenu":true, /* whether the three dots for opening context menu should be available,if set to true, then it will always have “refresh” option */
           "copy": false, /* whether copy option should be available */
           "move": false, /* whether move option should be available */
           "addWorkbook": false, /* whether add workbook option in panel should be available */
           "addWorksheet": false, /* whether add worksheet in panel should be available */
           "openSheetInWindow":false, /* whether open source sheet for a dashboard widget should be available */
           "action":false /* option to enable hyperlink setup */
      "layoutMode": "view|edit" /* option to open worksheet in View or Edit mode */
      "shortcut":false  /* whether shortcut option should be available */
      "worksheetWorkspaceSetting" :false /* whether ‘workspace setting’ option should be available */
      "workbookParameter": /* whether workbookParameter option should be available */
      "renameCubeField": /* whether renameCubeField option should be available */
      "refresh":false /* whether refresh option should be available */
      "showData":false /* whether ‘Show Data’ option should be available */
      "hide":false /* whether hide option should be available */
"dashboard": { /* integration configuration for dashboard */
            "widget": { /* integration configuration for widgets*/
                  "showInfoIcon": false, /* whether show info for the widget */
                  "showWarningsIcon": false, /* whether show warnings info for the widget */
                  "showFilterAppliedIcon": false, /* whether show the filter applied info for the widget*/
                  "showActionMenu": {
                        "dataCard": true, /* whether to show the three dot option on the Data card widget */
                        "filterCard": true, /* whether to show the three dot option on the Filter card widget */
                        "htmlCard": true, /* whether to show the three dot option on the HTML card widget */
                        "urlCard": true, /* whether to show the three-dot option on the URL card widget */
                        "groupCard": false /* whether to show the three dot option on the Group card widget */
                  },
                  "actionMenu": { /* integration configuration for three dot menu */
                        "duplicate": false, /* whether to show duplicate option */
                        "linkCard": false, /* whether to show the link card option */
                        "move": true, /* whether to show the move option */
                        "moveToSubOptions": { /* integration configuration for move sub options */
                               "moveToNewGroup": false, /* whether to move the widget in “New Group” */
                               "moveToExistingGroup": true /* whether to move the widget in “Existing Group” */
                        },
                        "copy": false, /* whether to show the copy option*/
                        "removeFromGroup": false, /* whether to remove the widget from Group card */
                        "openSource": false, /* whether to open the source worksheet of the widget */
                        "rename": false /* whether to show rename option for a widget */
                  }
            },
            "dataCardDialog": { /* integration configuration for data card dialog */
                  "viewOptions": { /* intgeration config for View options in dialog */
                        "showLegend": true, /* whether to show the show legend option for the widget*/
                        "showTitle": true, /* whether to show the show legend option for the widget*/
                        "showMaximize": true /* whether to show the maximize widget option*/
                  },
                  "viewStyling": { /* integration configuration for View Styling options */
                        "fixWidgetPosition": false, /* whether to show the fix widget position option*/
                        "makeTransparentBackground": false, /* whether to show the option to make the widget background as transparent */
                        "hideScrollbar": false /* whether to show the hide scroll bar option for widget*/
                  },
                  "innerMargin": false, /* whether to show the inner margin option to set the margins for widget */
                  "cssSelectors": { /* integration configuration for CSS selectors */
                        "id": false, /* whether to show ID input to set custom id for the widget*/
                        "class": false /* whether to show CLASS input to set custom class for the widget*/
                  }
            },
            "filterCardDialog": { /* integration config for filter card dialog*/
                  "viewOptions": {
                        "allowEditing": true, /* whether to show the Allow filters editing option for filter cards*/
                        "allowFilterSuspension": true, /* whether to show the allow filter suspension option for filter card*/
                        "showDimensionFilters": true, /* whether to show the dimension filters option*/
                        "showMeasureFilters": true, /* whether to show the measure filters option */
                        "showTitle": true, /* whether to show the show legend option for the widget*/
                        "showMaximize": true /* whether to show the maximize widget option*/
                  },
                  "viewStyling": { /* integration configuration for View Styling options */
                        "fixWidgetPosition": false, /* whether to show the fix widget position option*/
                        "makeTransparentBackground": false, /* whether to show the option to make the widget background as transparent */
                        "hideScrollbar": false /* whether to show the hide scroll bar option for widget*/
                  },
                  "innerMargin": false, /* whether to show the inner margin option to set the margins for widget */
                  "cssSelectors": { /* integration configuration for CSS selectors */
                        "id": false, /* whether to show ID input to set custom id for the widget*/
                        "class": false /* whether to show CLASS input to set custom class for the widget*/
                  }
            },
            "htmlCardDialog": { /* integration config for html card dialog*/
                  "viewOptions": {
                         "showTitle": true, /* whether to show the show legend option for the widget*/
                       "showMaximize": true /* whether to show the maximize widget option*/
                  },
                  "viewStyling": { /* integration configuration for View Styling options */
                        "fixWidgetPosition": false, /* whether to show the fix widget position option*/
                        "makeTransparentBackground": false, /* whether to show the option to make the widget background as transparent */
                        "hideScrollbar": false /* whether to show the hide scroll bar option for widget*/
                  },
                  "innerMargin": false, /* whether to show the inner margin option to set the margins for widget */
                  "cssSelectors": { /* integration configuration for CSS selectors */
                        "id": false, /* whether to show ID input to set custom id for the widget*/
                        "class": false /* whether to show CLASS input to set custom class for the widget*/
                  }
            },
            "urlCardDialog": { /* integration config for url card dialog*/
                  "viewOptions": { /* integration config for view options */
                         "showTitle": true, /* whether to show the show legend option for the widget*/
                        "showMaximize": true /* whether to show the maximize widget option*/
                  },
                  "viewStyling": { /* integration configuration for View Styling options */
                        "fixWidgetPosition": false, /* whether to show the fix widget position option*/
                        "makeTransparentBackground": false, /* whether to show the option to make the widget background as transparent */
                        "hideScrollbar": false /* whether to show the hide scroll bar option for widget*/
                  },
                  "innerMargin": false, /* whether to show the inner margin option to set the margins for widget */
                  "cssSelectors": { /* integration configuration for CSS selectors */
                        "id": false, /* whether to show ID input to set custom id for the widget*/
                        "class": false /* whether to show CLASS input to set custom class for the widget*/
                  }
            }
      },
      "visualization": { /* integration config for visualization charts and table*/
            "chartContextMenu": { /* integration config for three dot menu on charts and tables*/
                  "showInfo": false, /* whether to show the info of the visualization */
                  "quickSort": false /* whether to show the quick sort option of the visualization*/
     }
  }
           },
              "defaultMode":"" /* Defines the default mode in which the viewer would always load a sheet/dashboard. Possible values are VIEW, EDIT, or “”. A blank value means that the integration has not defined any particular mode. Mode’s value should be defined by Kyvos viewer’s behavior, like when an existing entity is open then it should open in View mode but when an entity is newly added then the viewer should open in the EDIT mode.*/
   },
  "jsEvents" : { /*here comes the javascript Api’s & events configurations */
"apiTimeout": 30, /* time interval in seconds, till which Kyvos would wait to emit the event against the API executed by host application, if not provided its default value is 30 seconds. */
"sessionSyncInterval": 120 /* time interval in seconds, that Kyvos would wait since the last session sync event emitted to host application, if not provided its default value is 120 seconds. */
  }
}

To allow cross-site cookies, add the following line to the conf/context.xml in Kyvos web client’s Tomcat, to allow cookie handling in iFrame.
<CookieProcessor sameSiteCookies="None" />
Kyvos web client must be running in https (secure) mode.
To terminate the user session in Kyvos from integration mode, i.e., to log out from the current Kyvos session, the parent application should send the HTTP request to the following endpoint.
http://<hostname:hostport>/<kyvosApplicationName>/kyvosIntegration.jsp?REQUEST_FOR=LOGOUT

Examples for Integrating Kyvos Use cases

Integrating workbooks into host web application

Below are some sample use cases to integrate workbooks into the host web application.

Sample 1: Let’s assume Kyvos is running at http://<hostname:hostport>/kyvos/
This is called the BASE_URL. Kyvos worksheets or Dashboard are both referred to as worksheets in this topic.

Integrate a specific worksheet in the host web application.
Let's say the user wants to integrate a worksheet named SheetDemo of IntegrationTesting
Below are the steps to create an integration link.
Login in Kyvos Application through Rest API and get auth token.

Create a URL like:

BASE_URL/kyvosIntegration.jsp?page=workbooks&name=SheetDemo&workbookName=IntegrationTesting&sessionId={token}&EXT_AUTH_PARAMETER_VALUE_TYPE=sessionId

In Host Web Application set this URL in iframe source.

Sample 2: To open a worksheet named SheetDemo of IntegrationTesting workbook in the IntegrationFolder, add the folderName in the URL.

For this, create a URL like:

BASE_URL/kyvosIntegration.jsp?page=workbooks&name=SheetDemo&workbookName=IntegrationTesting&folderName=IntegrationFolder&sessionId={token}&EXT_AUTH_PARAMETER_VALUE_TYPE=sessionId

Sample 3: To open a worksheet with Id Sheet1258485424224452 of Workbook with id Workbook_4545461215454, create a URL like:

BASE_URL/kyvosIntegration.jsp?page=workbooks&workbookId=Workbook_4545461215454&id=Sheet1258485424224452&&sessionId={token}&EXT_AUTH_PARAMETER_VALUE_TYPE=sessionId

Sample 4: To open a sheet with Id Sheet1258485424224452 of Workbook with id Workbook_4545461215454 inside the folder Folder_121548454544444554, add folderId in URL.

For this, create a URL like:

BASE_URL/kyvosIntegration.jsp?page=workbooks&workbookId=Workbook_4545461215454&id=Sheet1258485424224452&folderId=Folder_121548454544444554&sessionId={token}&EXT_AUTH_PARAMETER_VALUE_TYPE=sessionId

Adding worksheets in a workbook in an integrated manner from the HOST web application

Below are some sample use cases to add a worksheet in a workbook in an integrated manner from the HOST web application.

Sample 1: To create a worksheet inside IntegrationTesting Workbook, which is present at Root.

Login to Kyvos Application through Rest API and get auth token.

Create a URL like:

BASE_URL/kyvosIntegration.jsp?page=workbooks&actionCode=ADD&workbookName=IntegrationTesting&sessionId={token}&EXT_AUTH_PARAMETER_VALUE_TYPE=sessionId.

In Parent Application, set this URL in the iframe source.

Sample 2: To create a worksheet inside IntegrationTesting Workbook, in the IntegrationFolder, add folderName in the URL.

For this, create a URL like:

BASE_URL/kyvosIntegration.jsp?page=workbooks&actionCode=ADD&workbookName=IntegrationTesting&folderName=IntegrationFolder&sessionId={token}&EXT_AUTH_PARAMETER_VALUE_TYPE=sessionId

Sample 3: To create a worksheet inside Workbook with id Workbook_4545461215454 in the Root folder, create a URL like:

BASE_URL/kyvosIntegration.jsp?page=workbooks&actionCode=ADD&workbookId=Workbook_4545461215454&sessionId={token}&EXT_AUTH_PARAMETER_VALUE_TYPE=sessionId

Sample 4: To create a worksheet inside Workbook with id Workbook_4545461215454 in folder Folder_121548454544444554, add folderId in the URL.

For this, create a URL like:

http://BASE_URL/kyvosIntegration.jsp?page=workbooks&actionCode=ADD&workbookId=Workbook_4545461215454&folderId=Folder_121548454544444554&sessionId={token}&EXT_AUTH_PARAMETER_VALUE_TYPE=sessionId

Opening a workbook from the parent application

Below are some sample use cases to open a workbook from the parent application.

Sample 1: To open a IntegrationTesting Workbook (opening a workbook means opening the first accessible sheet).

Log into Kyvos Application through Rest API and get auth token.

Create a URL like:

BASE_URL/kyvosIntegration.jsp?page=workbooks&workbookName=IntegrationTesting&sessionId={token}&EXT_AUTH_PARAMETER_VALUE_TYPE=sessionId

In Parent Application, set this URL in iframe source.

Sample 2: To open IntegrationTesting Workbook in an IntegrationFolder, add folderName in the URL.

For this, create a URL like:

BASE_URL/kyvosIntegration.jsp?page=workbooks&workbookName=IntegrationTesting&folderName=IntegrationFolder&sessionId={token}&EXT_AUTH_PARAMETER_VALUE_TYPE=sessionId

Sample 3: To open a workbook with id Workbook_4545461215454 which is available in the Root folder, create a URL like:

BASE_URL/kyvosIntegration.jsp?page=workbooks&workbookId=Workbook_4545461215454 &sessionId={token}&EXT_AUTH_PARAMETER_VALUE_TYPE=sessionId

Sample 4: To open Workbook with id Workbook_4545461215454 in the folder Folder_121548454544444554, add the folderId in the URL.

For this, create a URL like:

BASE_URL/kyvosIntegration.jsp?page=workbooks&workbookId=Workbook_4545461215454&folderId=Folder_121548454544444554&sessionId={token}&EXT_AUTH_PARAMETER_VALUE_TYPE=sessionId

Adding a workbook from the parent application

Below are some sample use cases to add a workbook from the parent application.

Sample 1: To create a Workbook inside the root Folder:

Log into the Kyvos Application through Rest API and get auth token.

Create a URL like:

BASE_URL/kyvosIntegration.jsp?page=workbooks&actionCode=addWorkbook&sessionId={token}&EXT_AUTH_PARAMETER_VALUE_TYPE=sessionId

In Parent Application, set this URL in the iframe source.

Sample 2: To create a workbook inside IntegrationFolder (inside folder), add folderName in the URL.

For this, create a URL like:

BASE_URL/kyvosIntegration.jsp?page=workbooks&actionCode=addWorkbook&folderName=IntegrationFolder&sessionId={token}&EXT_AUTH_PARAMETER_VALUE_TYPE=sessionId

Sample 3: Let’s say the user wants to create a workbook inside folder Folder_121548454544444554 , add folderId in the URL.

For this, create a URL like:

http://BASE_URL/kyvosIntegration.jsp?page=workbooks&actionCode=addWorkbook&folderId=Folder_121548454544444554&sessionId={token}&EXT_AUTH_PARAMETER_VALUE_TYPE=sessionId

You can also provide mode and overideConfig as a parameter in all the above URLs.

For example, to open a sheet with “openSheetMode” defined in integration.config.json, create a URL like:

BASE_URL/kyvosIntegration.jsp?page=workbooks&name=SheetDemo&workbookName=IntegrationTesting&mode=openSheetMode&sessionId={token}&EXT_AUTH_PARAMETER_VALUE_TYPE=sessionId

Adding filters to worksheets from the host application

To add filters from the host application to the Kyvos dashboard/sheets, append the filter details in the GET or POST request to the Kyvos page.

For this, use any of the following methods:

The simplest way to send filters is by using the name-value pairs in the request.
For example, use fieldName1 and fieldName2 parameters in the dashboard URL with fieldValue1 and fieldValue2 values, respectively. To delimit multiple name-value filter pairs, use a semicolon (;) as a delimiter. To use any other character as a delimiter, specify it in the fieldSeparator parameter.
Sample syntax:
```
http://<hostname:hostport>/kyvos/kyvosIntegration.jsp?page=workbooks&name=<dashboardName>&folderName=<folderName>&workbookName=<workbookName>& EXT_AUTH_PARAMETER_VALUE_TYPE=sessionId&<EXT_AUTH_HEADER_ID>=<token>&filters=”<fieldName1=fieldValue1;fieldName2=fieldValue2>”&filterSeparator=”;”
```
This approach applies all the filters as string filters and IN LIST as the default criteria.

You can also provide more control over the filters, using an array of filters in JSON format as POST parameters.
For example:

[{
"fieldName” : “”, /*Mandatory : Level/Attribute/Measure name to which this filter is to be applied*/
“fieldValue”: “”, /*Mandatory : value of the filter*/
“criteria”: “”, /*Optional : Provide criteria for this filter. Default value is “INLIST” */
“secondValue” : “” ,/*Optional : required if the criteria is “BETWEEN”. Default value is “” */
“dateFormat”: “”,/*Optional : required to specify the format of Date in filter values.*/
“compareWithField” :””,/*Optional : required for filtering by comparing two measures (e.g. filter for profit is greater than cost )  or applying TopN filters (e.g. filter for Countries  in Top 10 by profit. ).*/
“isQualifiedDateValue”:/*Possible values True/False, it expects true if dimension has predefined time hierarchy and fieldValue contains parent member also (It should be in sync with qualified name set on level in cube design) 
}]

Using parameterized userAuthenticationVerificationUrl

For Kyvos embedding (integration), userAuthenticationVerificationUrl can have one or more dynamic parameters. Those parameters will be replaced with the values of top-level corresponding keys in customData JSON.
Example:
customData : {“APP_NAME”: “integration”}
userAuthenticationVerificationUrl : “http://localhost:8081/Kyvos/<%APP_NAME%> /verifyLogin”
so the final URL for the reverse REST call will become: “http://localhost:8081/kyvos/integration/verifyLogin”

There can be multiple dynamic parameters in userAuthenticationVerificationUrl. Each parameter should have a corresponding top-level key available in customData.

Read more