Table of Contents

Class OpenBiApiClientSystemExtensions

Namespace
BiExcellence.OpenBi.Api.SystemInfo
Assembly
BiExcellence.OpenBi.Api.Client.dll

Extension methods for the /system REST API.

public static class OpenBiApiClientSystemExtensions
Inheritance
object
OpenBiApiClientSystemExtensions

Methods

DeleteSharedConfigurationSettingAsync(IOpenBiApiClient, string, CancellationToken)

Deletes one shared configuration setting (DELETE system/sharedconfiguration/{name}); each server then falls back to its own configuration. Deleting a setting that is not there is not an error.

public static Task DeleteSharedConfigurationSettingAsync(this IOpenBiApiClient client, string name, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient
name string
cancellationToken CancellationToken

Returns

Task

GetConfigurationAsync(IOpenBiApiClient, CancellationToken)

Reads the server settings from Configuration.xml (GET system/configuration). Reachable only on the dedicated configuration port, in addition to the normal permission check; on any other port the server answers 404 rather than 403, so this throws OpenBiApiException (404) there. Write the settings back with SetConfigurationAsync(IOpenBiApiClient, ConfigurationSetting[], CancellationToken).

public static Task<ServerSettings> GetConfigurationAsync(this IOpenBiApiClient client, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient
cancellationToken CancellationToken

Returns

Task<ServerSettings>

GetHealthLiveAsync(IOpenBiApiClient, CancellationToken)

Asks the anonymous liveness probe (/health/live, at the server root rather than under /openbi/api) whether the server process answers. It runs no check, so it says nothing about the database or anything else - only that the server is up. A server that does not answer throws, and one older than the probe answers 404, which throws OpenBiApiException.

public static Task<SystemHealthStatus> GetHealthLiveAsync(this IOpenBiApiClient client, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient
cancellationToken CancellationToken

Returns

Task<SystemHealthStatus>

GetHealthReadyAsync(IOpenBiApiClient, CancellationToken)

Asks the anonymous readiness probe (/health/ready, at the server root rather than under /openbi/api) for the overall status of the health checks - the worst of them, without saying which one, where GetSystemHealthAsync(IOpenBiApiClient, CancellationToken) returns each result but needs openbi.system.read. The probe answers an unhealthy server with a 503, which comes back here as Unhealthy rather than thrown. A server that does not answer throws, and one older than the probe answers 404, which throws OpenBiApiException.

public static Task<SystemHealthStatus> GetHealthReadyAsync(this IOpenBiApiClient client, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient
cancellationToken CancellationToken

Returns

Task<SystemHealthStatus>

GetLicenseComponentStatusAsync(IOpenBiApiClient, string, CancellationToken)

Asks whether the license includes one component and it has not expired (GET system/licenseinformation/components/{name}). Unlike GetLicenseInformationAsync(IOpenBiApiClient, CancellationToken) it needs no permission, only a login, so a client can check its own component for every user. A component the license does not include comes back with Licensed false; a server older than the route answers 404, which throws OpenBiApiException.

public static Task<LicenseComponentStatus> GetLicenseComponentStatusAsync(this IOpenBiApiClient client, string name, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient
name string
cancellationToken CancellationToken

Returns

Task<LicenseComponentStatus>

GetLicenseInformationAsync(IOpenBiApiClient, CancellationToken)

Reads what the installation is licensed for - the components, the user counts and the expiry (GET system/licenseinformation). Worth checking before offering a feature the license does not include.

public static Task<LicenseInformation> GetLicenseInformationAsync(this IOpenBiApiClient client, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient
cancellationToken CancellationToken

Returns

Task<LicenseInformation>

GetSharedConfigurationAsync(IOpenBiApiClient, CancellationToken)

Reads the shared configuration - the settings kept in the database and used by every server connected to it (GET system/sharedconfiguration). Secrets carry SecretPlaceholder instead of their value. Reachable only on the dedicated configuration port (404 elsewhere).

public static Task<SharedConfigurationSetting[]> GetSharedConfigurationAsync(this IOpenBiApiClient client, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient
cancellationToken CancellationToken

Returns

Task<SharedConfigurationSetting[]>

GetSystemErrorsAsync(IOpenBiApiClient, OpenBiListRequest?, CancellationToken)

Lists the exceptions the server recorded, newest first (GET system/errors). This is where a 500 explains itself: the response body of a failed call carries only a generic message on purpose, so the detail is here.

public static Task<OpenBiListResult<SystemErrorLog>> GetSystemErrorsAsync(this IOpenBiApiClient client, OpenBiListRequest? request = null, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient
request OpenBiListRequest
cancellationToken CancellationToken

Returns

Task<OpenBiListResult<SystemErrorLog>>

GetSystemHealthAsync(IOpenBiApiClient, CancellationToken)

Runs the server's health checks and returns each one's result (GET system/health) - the same checks the anonymous /health/ready probe runs, which answers with the overall status alone. Needs openbi.system.read (403 otherwise; GetHealthReadyAsync(IOpenBiApiClient, CancellationToken) needs nothing). The call succeeds whatever the status: an unhealthy server is reported in Status, not thrown.

public static Task<SystemHealth> GetSystemHealthAsync(this IOpenBiApiClient client, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient
cancellationToken CancellationToken

Returns

Task<SystemHealth>

SendSystemMailAsync(IOpenBiApiClient, SystemMailRequest, CancellationToken)

Sends a mail through the server's own SMTP configuration (POST system/mail). Doubles as a way to prove that configuration works before a batch job or an inquiry notification depends on it.

public static Task SendSystemMailAsync(this IOpenBiApiClient client, SystemMailRequest mail, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient
mail SystemMailRequest
cancellationToken CancellationToken

Returns

Task

SetConfigurationAsync(IOpenBiApiClient, ConfigurationSetting[], CancellationToken)

Replaces every server configuration setting and rewrites Configuration.xml (POST system/configuration). Settings left out are removed, so read them with GetConfigurationAsync(IOpenBiApiClient, CancellationToken) and post them back changed. Most settings are read at startup, so a restart is needed for them to take effect. Reachable only on the dedicated configuration port, in addition to the normal permission check (404 elsewhere); an invalid setting is a 400.

public static Task SetConfigurationAsync(this IOpenBiApiClient client, ConfigurationSetting[] parameters, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient
parameters ConfigurationSetting[]
cancellationToken CancellationToken

Returns

Task

SetSharedConfigurationAsync(IOpenBiApiClient, SharedConfigurationSetting[], CancellationToken)

Replaces every shared configuration setting (POST system/sharedconfiguration). Settings left out are removed, which needs openbi.configuration.delete as well (403 otherwise), so read them with GetSharedConfigurationAsync(IOpenBiApiClient, CancellationToken) and post them back changed. Only name and value are read.

public static Task SetSharedConfigurationAsync(this IOpenBiApiClient client, SharedConfigurationSetting[] settings, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient
settings SharedConfigurationSetting[]
cancellationToken CancellationToken

Returns

Task

SetSharedConfigurationSettingAsync(IOpenBiApiClient, string, string?, CancellationToken)

Creates or updates one shared configuration setting (POST system/sharedconfiguration/{name}). A setting that is read before the database is loaded (CONNECTION_STRING, the ports, ...) is refused with a 400; for a secret, SecretPlaceholder keeps the current value.

public static Task<SharedConfigurationSetting> SetSharedConfigurationSettingAsync(this IOpenBiApiClient client, string name, string? value, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient
name string
value string
cancellationToken CancellationToken

Returns

Task<SharedConfigurationSetting>