Appsettings.json Configuration

Below is an example of the updated BAM settings in a general appsettings.json file. Of course, any already existing appsettings.json file may have additional settings present not shown here. The default location of appsettings.json file is located in %OMETA_INSTALLATION_MAP%\Ometa Software Suite

Note

Same file name, different settings files

Keep in mind that the appsettings.json file described here is NOT the one in %OMETA_INSTALLATION_MAP%\Ometa Software Suite\Services\BAM Service. Although both files have the same name, the file described here, is located in the %OMETA_INSTALLATION_MAP%\Ometa Software Suite folder itself.

{
  "BamConfig": {
    "Enabled": true,
    "Destination": "File",
    "LogDirectory": "C:\\Program Files (x86)\\Ometa BVBA\\Log",
    "PortalUrl": "http://bam:65487/Portal/Dashboard-Health.aspx",
    "MaxPropertySize": 100,
    "MinimumLogLevel": "Information",
    "ProcessOverrides": [
      {
        "ProcessName": "BCS_ODBC",
        "Enabled": false
      },
      {
        "ProcessName": "BCS_OPCUA",
        "Enabled": true,
        "MinimumLogLevel": "Debug"
      }
    ]
  },
  "ConnectionStrings": {
    "OmetaBamDatabase": "Data Source=sqlserver.domain.net;database=OmetaBAMLogging;trusted_connection=yes;"
  }
}

General Logging Settings

Set the Enabled property to false to disable logging of the server. Obviously, setting it to true enables logging. Note: make sure the setting is present and set to true, otherwise the logging will be disabled by default.

Destination can either be File or Database.

  • File means writing to log files which are later processed for transfer to the BAM database.
  • Database means writing all logging directly to the BAM database.

When no destination is provided, the logging system will assume File being the default.

Note

Regardless of the defined destination, critical (= log level 'Critical') messages are also sent to the Windows Event Log.

Connection String

The connection string is used to process the files from the log directory and write them to a database, or writing logging directly to the database when the property Destination is set to Database. It is stored in the property OmetaBamDatabase of the section ConnectionStrings. This is a required setting.

An example showing a connection string for a default SQL setup (port 1433):

Data Source=sqlserver.domain.net;database=OmetaBAMLogging;trusted_connection=yes;

The following example shows a connection string for a SQL that is configured to receive connections on port 1500:

Data Source='serverName,1500\sqlInstance';database=OmetaBAMLogging;trusted_connection=yes;
Note

When using Trusted_Connection=yes in the OmetaBamDatabase connection string, ensure that the user of the BCSL service has sufficient permissions for reading and writing to the BAM logging database created during installation.

And be aware during initialisation the logging system checks whether the connection string is present and a connection can be set up to the database. If not, the system will fall back to file based logging, see Initialisation Fallback for more information.

BAM Portal Url

The BAM Portal URL is the URL used by the Ometa Business Connector to navigate to the BAM Portal website. It is stored in the property PortalUrl.

Important

Ensure that the BAMPortalUrl has a direct reference to the Portal/Dashboard-Health.aspx page. Another possibility is to set the index page of the BAM IIS site to this page.

Max Property Size

Stored in the property MaxPropertySize.

The amount of characters before it is cut of. This is only applied for properties in the formatted message of log events of the levels Error and Fatal. For more information about the log levels, see here.

If no value is provided or the defined value is lower than 100, the logging handler will reset the value to 100.

max property size example

Log Directory

The property LogDirectory contains the path name of the folder used to store the log files. This is a required setting when the Destination is set to File.

Within that log directory several subdirectories exist: Failed, Processing and Successful. Items in these directories stay there for seven days and are removed by the Process BAM Files method job.

That Process BAM Files method job is responsible to process all log files and writes them to the Ometa BAM Logging database. Even if the property Destination is set to Database, the method job will still check for the presence of any files. When a particular file could not be processed properly, the entire file will be placed in the Failed subdirectory.

Note

Keep in mind that during initialisation the logging system checks whether the log directory is defined and exists. If not, the system will fall back to Windows Event Log based logging, see Initialisation Fallback for more information.

Log Levels

The current BAM implementation uses log levels for filtering. Every log line gets a severity or "state of importance". Depending on that severity, the BAM processes will decide to write the log line to the files (or directly to the database), or not at all. Additionally, it is possible to define additional minimum log level requirements for each of the separate processes of the framework. The default minimum log level is Trace, or logging of all information.

All available log levels, sorted from lowest to highest level:

Level Description
Trace Trace is the noisiest level, rarely (if ever) enabled for a production app.
Debug Debug is used for internal system events that are not necessarily observable from the outside, but useful when determining how something happened.
Information Information events describe things happening in the system that correspond to its responsibilities and functions. Generally these are the observable actions the system can perform.
Warning When service is degraded, endangered, or may be behaving outside of its expected parameters, Warning level events are used.
Error When functionality is unavailable or expectations broken, an Error event is used.
Critical The most critical level, critical or fatal events demand immediate attention.

With the help of the property MinimumLogLevel is it possible to tell BAM which log lines must be written. When the property is set to Information, all log lines with severities Information, Warning, Error and Critical will be logged. Log lines with severities Trace and Debug will be dropped. Another example: setting the property value to Error, will result that only log lines with severities Error and Critical are processed. Any other log lines are not.

Note

The minimum log level filter will only be applied at the moment of writing the log line to either a file or directly in the database. The Process BAM Files method job processing log files for transferring them over into the BAM database will ignore the value of this property to avoid losing logging data unknowingly.

Important

It is important to note the old log category Verbose is mapped to the new log level Debug. This mapping is decided because the old Verbose level had the exact same meaning.

Process Filtering

The property MinimumLogLevel sets the log level for all framework processes. However, as stated before it is possible to define separate settings for individual processes. Those definitions have precedence over the general setting.

An example:

{
  "ProcessOverrides": [
    {
      "ProcessName": "BCS_ODBC",
      "Enabled": false
    },
    {
      "ProcessName": "BCS_OPCUA",
      "Enabled": true,
      "MinimumLogLevel": "Debug"
    }
  ]
}

In the example above, the 2 possible types of definitions are shown:

  • either disabling the logging for a process entirely (Enabled set to false for the process "BCS_ODBC"),
  • or defining a different minimum log level (MinimumLogLevel set to Debug for the process "BCS_OPCUA").

Make sure the setting Enabled is set to true otherwise the logging system will assume the process being set as disabled from logging.

The minimum log level can deviate from the general level in both directions. Setting a lower level will generate more logging for that process, and setting a higher one will generate less logging.

Following process names can be used:

  • BCA
  • BCJS
  • BCM
  • BCS_BaaN
  • BCS_OPCUA
  • BCS_AD
  • BCS_CMIS
  • BCS_DAV
  • BCS_DLL 4
  • BCS_File
  • BCS_MAPICS
  • BCS_MoveX
  • BCS_OData
  • BCS_ODBC
  • BCS_OS
  • BCS_REST
  • BCS_SAP
  • BCS_SharePoint
  • BCS_WebService
  • BCS_XML
  • BCSL
  • BCSP
  • Ometa.Framework.Authority
  • Ometa.Framework.Services.Bam
  • Ometa.Framework.Services.OpcUa
  • Ometa.Framework.Web (= Core web service)
  • Ometa.Services.Web (= Generic REST)
  • WpfGUI

Best For Production Environments

Ometa recommends to set the MinimumLogLevel to at least Information in production environments. Define separate log level filters for specific processes if extra logging is needed.