To report a found bug,
please select the text with the bug and click Report a Bug
or CTRL+ENTER.
Help
system 10.9 of 26/11/2025,
©
FORESIGHT
OpenMetabaseResult OpenMetabase(MbDef tDef, UserCreds tCreds, [OpenMetabaseArg tArg])
tDef. Description of the repository, the user is connecting to.
tCreds. User authentication parameters.
tArg. Connection parameters.
The OpenMetabase operation connects to the repository and returns the moniker of the repository connection.
The operation executes the following actions:
Connects to an existing repository and gets access to its objects.
Creates a new repository on DBMS server.
Connection to a repository can be established in various ways. To connect to a repository, specify the repository information and user authentication parameters. For specifying a repository to connect, the following variants are available:
In the tDef.id field specify repository description identifier. On operation executing the specified description is searched in the operating system registry of the server, where the BI server is located. If the description is not found, its settings will be used to connect to the repository.
In the tDef.logonData field specify the parameters of the security module that are used to connect to the repository (DBMS driver used for connection, server name or IP address, schema/database identifier). In this case an empty string should be set as an identifier of description in the tDef.id field.
A guest connection can also be created using the OpenMetabase operation. For details see the Using Guest Connection article.
To authenticate the user, use the following methods (a more detailed description is provided below):
With direct specification of credentials.
With domain user authentication.
Using OAuth protocol.
Using a digital signature.
Authentication parameters are specified in the tCreds field.
The operation results in the following objects:
The repository connection moniker (the id field).
The session key (the sessKey field).
The session identifier (the sessCookie field).
The repository version (the version field).
NOTE. Session parameters are stored in the BI server memory or at the state server if configuration defined a group of StateServer settings. If the StateServer group of settings is defined, the state server is disconnected, the session identifier is not generated.
The obtained moniker is further used in the following cases:
On executing various operations to specify the repository, within which the user is working.
In the id field when creating identifier of the object, with which the user is working.
On closing the repository connection by means of the CloseMetabase operation.
The sessKey session key can be used, for example, to work with access protocol to get a list of operations executed in the session.
The sessCookie identifier, unlike the moniker, is not used to work with the repository, and is used only to identify existing server sessions. If the obtained identifier is saved and on a new connection is further specified as a value of the tArg.sessCookie field, BI server checks if a session with the same identifier exists. If such a session exists, it is checked if it can be reused. The necessary conditions for reuse of the session:
Correct user login and password.
The list of active sessions still contains a session with the specified identifier.
The existing session was created only for the specified user.
Depending on the selected authentication type, different fields of the OpenMetabase operation will be used. One may also require to determine advanced settings given below.
In the registry/settings.xml file create the OAuth section, create a subsection inside it and determine the settings required for working with external authentication service via the OAuth 2.0 protocol.
In the Metabases.xml file create a section to connect to repository, set the Authentication attribute to 7. In the created section create the OAuthService subsection, in the Providers attribute enter authentication server name, which was specified in the registry/settings.xml file.
Connection is established in several steps with execution of additional operations:
Execute the GetOAuthSettings operation, in the tArg.svcKey field specify the -1 value. The operation results in the list of external services created in the OAuth subsection in the registry/settings.xml file. Each element of the list will have identifier, key, and icon that are determined in the id, key, and icon fields.
Execute the CreateOAuthState operation, in the tArg.svcKey field specify authentication service key, and in the tArg.redirectUri field specify path to the web application root that will be used as the address to return to the application after entering user credentials in external service. During operation execution the BI server generates the state parameter for protection against potential CSRF attacks during authorization code request. The operation results in the authentication service address that is specified in service settings in the registry/settings.xml file in the AuthUrl field that is appended with the return address from tArg.redirectUri and the generated state parameter. The address specified in tArg.redirectUri should be written in external authentication service settings. In the response the BI server uses the Set-Cookie header to set cookies in the browser with the value of the state parameter. Cookie's lifetime is 5 minutes, it has the HttpOnly and Secure attributes.
IMPORTANT. Cookies with the Secure attribute are sent only via HTTPS connection that is why interaction between the BI server and the web application should be set up to work via HTTPS, otherwise OAuth authentication will be impossible.
The web application should redirect the user by the obtained authUrl address. The user is authenticated in external service. If authentication was successful, the external service redirects the user back to the web application by the address specified in the CreateOAuthState.tArg.redirectUri field with specification of the code and state parameters.
Execute the GetOAuthToken operation, in the tArg.svcKey field specify the previously used authentication service key, and in the tArg.applicationUrl field specify path to the web application root that will be used as the address to return to the application. The value should be equal to the previously specified in CreateOAuthState.tArg.redirectUri. In the tArg.loginCode and tArg.state fields specify values of the obtained code and state parameters. During the request execution the BI server checks value of parameter for protection against potential CSRF attacks during authorization code request. In case of successful check, the system opens the external service to get tokens. The BI server returns key for using tokens. This key will be available in the oauth_token field of the operation execution result and can be sent to the OpenMetabase operation.
Execute the OpenMetabase operation, in the tCreds.oauth.oauth_token fields specify the obtained key for using tokens, in the tCreds.oauth.oauth_verifier field specify empty value, and in the tCreds.oauth.svcKey field specify the previously used authentication service key, and in the tCreds.pass field specify empty value. In the tDef.id field specify repository identifier.
If all operations are successfully executed, the repository connection is established.
The user needs to save an encrypted password to the registry. This password will be used to connect to the repository database. To do it, start the PP.Util utility with the /save_creds <ID of repository description> <user name> key. The utility is located in the folder with installed Foresight Analytics Platform. When started, the application requests password. Enter the password. After this the message "Password for metabase "repository description identifier" and login "user name" saved is displayed.
Save the certificate to the repository using the following command: PP.Util.exe /save_cert "path to the certificate" <repository description identifier> <user name>. After this the utility requires password of the specified user. The obtained credentials will be used to connect to the repository. In case of successful authorization and saving the certificate the message "Certificate from file "path to certificate" with identifier "certificate identifier" saved to metabase "repository description identifier" is displayed.
Save the private key in the registry using the command: PP.Util.exe /save_private_key "path to key" <certificate identifier> <encryption algorithm:= gos|pro, if it is not specified, then gos>. After the private key is successfully saved, the following message appears: "Certificate from file "path to the key" with identifier "certificate identifier" saved".
NOTE. If BI server is installed on IIS web server, the BI server pool should be started under the user who started the PP.Util utility.
Before connection execute the GetVerifierCode operation to get the data block the client must sign with the digital signature. In the tCreds.verifier.signature field specify the signed data, and in the tCreds.verifier.cookie field specify the random number that will also be obtained as the result of executing the GetVerifierCode operation. In the tCreds.verifier.user field specify the user who connects to the repository. This user may be unavailable in the repository DBMS or in the security manager.
NOTE. If the specified user does not exist anywhere, it is created in the security manager of the repository. If the tCreds.verifier.role field was defined, the user is included in the specified group and granted respective permissions. If the field is not set, the user will be included in the USERS built-in group. If required, permissions of the created user can be edited with the SetMbSec operation.
In the tCreds.verifier.mbUser field specify the user who will be used to connect to the repository database. This user must exist in the repository and have permissions to enter the repository. Also, in the tCreds.verifier.certificate field specify identifier of the certificate to be used to verify the digital signature. This certificate should be saved in the repository as described above. An empty string is set as the value of the tCreds.pass field, and this field is not used when connecting to the repository using a digital signature.
The handler of custom events that will handle actions executed from web service can be installed in the repository. To do it, set the following settings:
Set the IMetabaseDefinition.CheckCustomEvents property to True.
Set the special object MetabaseSpecialObject.MetabaseCustomEvents for repository, as the object specify the unit containing implementation of the IMetabaseCustomEvents interface.
When executing the OpenMetabase operation the following algorithm will be executed:
If IMetabaseDefinition.CheckCustomEvents = False, the connection opens according to sent credentials and returns the connection moniker.
If IMetabaseDefinition.CheckCustomEvents = True, the connection opens with credentials that should be saved by the PP.Util utility. If there is no saved data, an exception is thrown.
The special object that must be set in repository is launched. If it is not set or there is no implementation of the IMetabaseCustomEvents interface in it, an exception is thrown.
The OnBeforeLogon event receives the credentials that were sent to the OpenMetabase operation. Next, according to the application logic, any actions can be executed in the event handler. The output connection must be set in the ResultMetabase property of the event argument, the moniker of the connection will be returned as the operation result. If for any reasons in the event handler the AllowLogon property of the event argument was set to False, an exception is thrown after operation execution.
Various methods of using the operation are given in the following examples:
See also:
Common Operations | Using Guest Connection