OpenMetabase

Syntax

OpenMetabaseResult OpenMetabase(MbDef tDef, UserCreds tCreds, [OpenMetabaseArg tArg])

Parameters

tDef. Description of the repository, the user is connecting to.

tCreds. User authentication parameters.

tArg. Connection parameters.

Description

The OpenMetabase operation connects to the repository and returns the moniker of the repository connection.

Comments

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.

To authenticate the user, use the following methods (a more detailed description is provided below):

With direct indication 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.

Authentication Methods

Direct Indication of Credentials

The credentials are specified in the tCreds.user and tCreds.pass fields.

Connection Using Digital Signature

To connect to repository using a digital signature, prepare the repository in the following way:

The user needs to save an encrypted password to the registry. This password will be further 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. After the successful startup the password for entering the repository is requested. Enter the password. The following message appears: Password for metabase “Repository description identifier” and login “user name” saved.
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 entered account data is used to connect to the repository. If the authentication is successful and the certificate has been saved, the following message appears: Certificate from file "path to certificate" with identifier "certificate identifier" saved to metabase "repository description identifier".
Save the private key to the registry using the following command: PP.Util.exe /save_private_key "path to the key" <certificate identifier> <encryption algorithm := gos|pro, if not specified, then pro>. 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 the BI server is deployed on the IIS web server, the BI server pool must be started using credentials of the same user who started the PP.Util.exe 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 not available 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 this field is not defined, the user is included into the Built-in Users Group. If required, permissions of the created user can be edited with the SetMbSec operation.

In the tCreds.verifier.mbUser field specify the user whose credentials will be used for actual connection 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 must be saved to 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.

Integrated Domain Authentication

To use integrated domain user authentication, do not specify the tCreds.user field, and in the tCreds.pass field specify empty value. In this case the current operating system user credentials are sent for connection.

Monitoring Events

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 are no saved data, then exclusive situation is generated.
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, the exclusive situation is generated.
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, the exception is thrown after operation execution.

Example

Various methods of using the operation are given in the following examples:

Example name

Connecting to Repository with Direct Passing of Credentials

Connecting to Repository Using Digital Signature

Connecting to Repository Using Integrated Domain Authentication