Minimum System Requirements

Make sure to meet the minimum system requirements of an Ometa Framework server.

Important

The installer will automatically set the compatibility level of the databases to SQL Server 2016 if the level is lower than 2016, except for SQL 2012 and 2014 installations.
Do note that support for SQL 2012 and 2014 will be removed starting from version 6.0.

Scripted PowerShell Installation

You can choose the easy way to install the Ometa Framework, or the hard way by installing the Ometa Framework manually by following the procedure below.

The Easy Install Framework Scripts are currently two scripts which must run in the following sequence:

1. install-framework.ps1
2. configure-iis.ps1

These scripts are located in the scripts folder of the Ometa Software Suite zip file.

Requirements

Before running the scripts make sure to:

• meet the minimum software requirements
• IIS is configured according to the minimum software requirements.
• a SSL certificate is available in the Personal Certificate Store of the Local Computer (Cert:\LocalMachine\My).

AutoInstall

The PowerShell scripts have an autoinstall parameter. If this is set, you can pass the passwords as parameter. This can be be useful for build actions or batch installation.
The installerPath parameter needs to be folder where the .exe is located. The script will look for the first .exe in that folder.

Example where a service account is used, with default trusted connections. Keep in mind that the service account needs db_owner permissions on the Ometa Database.

./install-framework.ps1 -autoInstall -installerPath "Some path to the setup"

./configure-iis.ps1 -autoInstall

Example where a normal account is used, with default trusted connections.

./install-framework.ps1 -autoInstall -bcosSecurePassword 'abc' -bcslSecurePassword 'abc' -installerPath "Some path to the setup"

./configure-iis.ps1 -autoInstall -appPoolSecurePassword 'abc'

Example where SQL Authentication is used, instead of trusted connections.

// install-framework-settings.json
"bamDbSqlUser": "ometa.setup",
"bamDbUseIntegratedSecurity": false,
"frameworkDbSqlUser": "ometa.setup",
"frameworkDbUseIntegratedSecurity": false,

// PowerShell Scripts
./install-framework.ps1 -autoInstall -fwDbSecurePassword 'abc' -bamDbSecurePassword 'abc' -installerPath "Some path to the setup"

// configure-iis-settings.json
"frameworkDbSqlUser": "ometa.setup",
"frameworkDbUseIntegratedSecurity": false,

// PowerShell Scripts
./configure-iis.ps1 -autoInstall -fwDbSecurePassword 'abc'

Folder Structure

Make sure the Ometa Software Suite executable file is in the setup folder. You should have the following directory structure:

> setup
	- Ometa Software Suite v5.0.0.exe
- configure-iis.ps1
- configure-iis-settings.json
- install-framework.ps1
- install-framework-settings.json

Passwords

All passwords will be asked during the execution of the script and are not stored.

When using SQL username and password for SQL authentication, the following characters are not allowed in the username or password: ', ", {, }, $. If this isn't possible, create a temporary SQL user to perform the installation, and switch to the intended SQL user afterwards by editing the appsettings.json once completed.

Note

The installation scripts offer support to use SQL Server Authentication by setting the frameworkDbUseIntegratedSecurity setting to false. However, Microsoft recommends using Integrated Security over SQL Logins. Refer to the following Microsoft article.

Install Framework Script

install-framework-settings.json

Update the install-framework-settings.json file.

Parameter	Description
applicationDirectory	The folder where the framework is installed. This must be JSON escaped with double slashes. Default value: c:\Program Files (x86)\Ometa BVBA\Ometa Software Suite
workingDirectory	Reflects to the applicationDirectory. This must be JSON escaped with double slashes. Default value: c:\Program Files (x86)\Ometa BVBA\Ometa Software Suite\WorkDir
bcosDomain	The domain of the provided user account (bcosUsername). Will be used for all Ometa Services except the BCSL service.
bcosUsername	The username for setting all Ometa Services except the BCSL service.
bcslDomain	The domain of the provided user account (bcslUsername). Will be used for the BCSL service.
bcslUsername	The username for setting the BCSL service.
bamDbSqlUser	The SQL user name to authenticate to the Ometa BAM database, only applicable when bamDbUseIntegratedSecurity is false.
bamDbUseIntegratedSecurity	Option to toggle integrated security for the framework database. When enabled the Windows user is used to authenticate to the SQL server. It is recommended to use Integrated Security.
bamSqlServer	The SQL server where the Ometa BAM database is located. This must be JSON escaped with double slashes.
bamDatabaseName	The name of the Ometa BAM database.
frameworkDbSqlUser	The SQL user name to authenticate to the Ometa Framework database, only applicable when frameworkDbUseIntegratedSecurity is false.
frameworkDbUseIntegratedSecurity	Option to toggle integrated security for the framework database. When enabled the Windows user is used to authenticate to the SQL server. It is recommended to use Integrated Security.
frameworkSqlServer	The SQL server where the Ometa Framework database is located. This must be JSON escaped with double slashes.
frameworkDatabaseName	The name of the Ometa Framework database.
installedFeatures	Set the features which needs to be installed to true.

Example:

{
	"applicationDirectory": "c:\\Program Files (x86)\\Ometa BVBA\\Ometa Software Suite",
	"workingDirectory": "c:\\Program Files (x86)\\Ometa BVBA\\Ometa Software Suite\\WorkDir",
	"bcosDomain": "OMETA",
	"bcosUsername": "my-user",
	"bcslDomain": "OMETA",
	"bcslUsername": "my-user",
	"bamDbSqlUser": "",
	"bamDbUseIntegratedSecurity": true,
	"bamSqlServer": "server\\instance",
	"bamDatabaseName": "OmetaBAMLogging",
	"frameworkDbSqlUser": "",
	"frameworkDbUseIntegratedSecurity": true,
	"frameworkSqlServer": "server\\instance",
	"frameworkDatabaseName": "OmetaFramework",
	"installedFeatures": {
		"SharedComponentsFeature": true,
		"ClientFeature": true,
		"CoreFeature": true,
		"DCSFeature": true,
		"ArchiveSystemObjectsFeature": true,
		"AuthorityServiceFeature": true,
		"CoreServiceFeature": true,
		"GenericRESTFeature": true,
		"OPCUAServiceFeature": false,
		"BAMGlobalFeature": true,
		"BAMCoreFeature": true,
		"BAMWebPortalFeature": true,
		"PublishingFeature": false, 
		"ADFeature": true,
		"SAPFeature": true,
		"CMISFeature": false,
		"DAVInterfaceFeature": false,
		"DLL4Feature": true,
		"FileInterfaceFeature": true,
		"MAPICSFeature": false, 
		"MoveXFeature": false,
		"ODBCFeature": true,
		"ODataFeature": true,
		"OPCUAFeature": false,
		"OSFeature": true,
		"SharePointFeature": true,
		"XMLFeature": true, 
		"BaaNFeature": false,
		"RESTInterfaceFeature": true,
		"WebServiceFeature": true
	}
}

Execute

Run the PowerShell script by right-clicking and select Run With PowerShell.

Configure IIS Script

configure-iis-settings.json

Update the configure-iis-settings.json file.

Parameter	Description
authorityUrl	The URL of the authority service. Needs to be a valid URL format.
bamUrl	The URL of the BAM Portal. Needs to be a valid URL format.
coreUrl	The URL of the core service. Needs to be a valid URL format.
restUrl	The URL of the generic REST service. Needs to be a valid URL format.
servicesFolder	The folder where the services are installed. Always in the Ometa Software Suite folder. This must be JSON escaped with double slashes. Default value: C:\Program Files (x86)\Ometa BVBA\Ometa Software Suite\Services
rootFolder	The folder of to the Ometa Software Suite. Default value: C:\Program Files (x86)\Ometa BVBA\Ometa Software Suite
programFileFolder	The folder of the Ometa BVBA folder, needed to set modify permissions on. Default value: C:\Program Files (x86)\Ometa BVBA
appPoolUser	This username will be set on all application pool accounts. Should include the domain. For example: Ometa\OmetaService$
certificateDnsName	The correct certificate must be uploaded to the local machines' certificate store: Cert:\LocalMachine\My. A selection is made by the script on DnsName, this corresponds to the issuer column.
serverName	The name of the server. Used to set the Repository Server, BC Server config values in the database. Also used for configuring the service restart failures.
bamDatabaseName	The name of the Ometa BAM Database.
frameworkSqlServer	The SQL server where the Ometa Framework Database is located. This must be JSON escaped with double slashes.
frameworkDatabaseName	The name of the Ometa Framework Database.
setLocalSecurityPolicies	Sets the local security policies, modify folder permissions and performance monitor group according to the accounts article.
sharePointOnline.useSharePointOnline	If true, you can pass the sourceSharePointUrl and clientId parameters which are set in the config.SharePointAuthentication table.
sharePointOnline.sourceSharePointUrl	Set the Source SharePoint URL parameter, for instance: https://yourtenant.sharepoint.com
sharePointOnline.clientId	The client id for authentication purposes. The client secret will be asked while running the script, or when the autoInstall flag is set, the secureClientSecret should also be set.
sharePointOnPremise.useSharePointOnPremise	If true, you can pass the sourceSharePointUrl, domain and username parameters which are set in the config.SharePointAuthentication table.
sharePointOnPremise.sourceSharePointUrl	Set the Source SharePoint URL parameter, for instance: https://yourtenant.domain.com
sharePointOnPremise.domain	The domain of the specified username.
sharePointOnPremise.username	The username for authentication purposes. The password will be asked while running the script, or when the autoInstall flag is set, the genericRestSharePointPassword should also be set.

Example:

{
	"authorityUrl": "https://my-auth.ometa.net",
	"bamUrl": "https://my-bam.ometa.net",
	"coreUrl": "https://my-core.ometa.net",
	"restUrl": "https://my-rest.ometa.net",
	"servicesFolder": "C:\\Program Files (x86)\\Ometa BVBA\\Ometa Software Suite\\Services",
	"rootFolder": "C:\\Program Files (x86)\\Ometa BVBA\\Ometa Software Suite",
	"programFileFolder": "C:\\Program Files (x86)\\Ometa BVBA",
	"appPoolUser": "svc_testing_server_a",
	"certificateDnsName": "my.ometa.net",
	"serverName": "localhost",
	"bamDatabaseName": "OmetaBAMLogging",
	"frameworkDbSqlUser": "",
	"frameworkDbUseIntegratedSecurity": true,
	"frameworkSqlServer": "server\\instance",
	"frameworkDatabaseName": "OmetaFramework",
	"setLocalSecurityPolicies": false,
	"sharePointOnline": {
		"useSharePointOnline": true,
		"sourceSharePointUrl": "",
		"clientId": ""
	},
	"sharePointOnPremise": {
		"useSharePointOnPremise": false,
		"sourceSharePointUrl": "",
		"domain": "",
		"username": ""
	}
}

Execute

Run the PowerShell script by right-clicking and select Run With PowerShell.

Run the Installer

This is the manual way to install the Ometa Framework, do consider the scripted PowerShell installation

Run the Ometa Software Suite executable to begin the installation procedure on an Ometa Framework server. Make sure to:

• run the setup with an administrator account which has db_owner permissions to the Ometa databases.
• don't run the setup in a personal folder such as Downloads, instead run in for example: c:\Temp.

• 1. Start Screen
• 2. Feature Selection
• 3. Core System
• 4. Core System Database
• 5. Business Activity Monitoring
• 6. Installation

The first screen doesn't tell a lot and you don't have many choices. Either cancel or click next to continue.

Troubleshooting

.NET 8 Required

If you get the following dialog, you haven't met the minimum system requirements. Install .NET v8.0.21 or higher and continue the setup.

SQL Security & Privileges

Several steps in the setup require you to choose an SQL Server instance and database names. You always have to choose between Windows Trusted Connection or SQL Server Login. The selected account information will be used during install and also at run-time of the framework. It will still be possible to change any account configuration for database access after the framework installation has been completed.

It is important that the installation user (or the SQL user if you choose that option) has owner privilege on its own database.

SQL/EF/Command Errors In Patcher

It can happen that the patcher, which is executed at the end of the installation, generates errors regarding SQL, Entity Framework or command definitions. This can be caused by the fact that we are transitioning from plain SQL scripts to Entity Framework Core Migrations to keep our databases up-to-date. The patcher assumes that the databases are always up-to-date, but sometimes this is not the case.

To solve this you'll need to:

• Invoke the discovery of the Core Framework Service by navigating to https://core-service-site-binding:port/odata/Discover
  • This ensures that any pending migrations will be executed

• Manually re-execute the patcher:
  • Open up your file explorer and navigate to %OMETA_INSTALL_ROOT%\Ometa Software Suite\TopDir\BC\Bin
  • Right-click the BCRPatcher.exe file
  • Click Run as administrator

The patcher will now execute successfully without any SQL errors.

Unblock the setup

Some environments have additional security on external applications. You can recognize this by Windows showing this pop-up when starting the setup:

To resolve this, the setup file must be unblocked manually. This can be done by opening the properties of the setup file (.exe), and clicking unblock.

Service failed to start

When you get the error: "Service [service name] failed to start. Verify that you have sufficient priviliges to start system services." you should take a look in the System and Application event logs.

Service Account Does Not Have Correct Rights

If you get the following error in the System event log, you need to follow the next procedure.

  The BCSL.exe service was unable to log on as [user] with the currently configured password due to the following error: 
  Logon failure: the user has not been granted the requested logon type at this computer.
  
  Service: BCSL.exe  
  Domain and account: [user]
  
  This service account does not have the required user right "Log on as a service."

Configuration Issue With Appsettings.json

When the following error message appears in the Application event log:

An error has occurred during the startup of the process, please verify your configuration.

Error details: 'd' is invalid after a value. Expected either ',', '}', or ']'. LineNumber: 36 | BytePositionInLine: 167.
System.Text.Json.JsonReaderException: 'd' is invalid after a value. Expected either ',', '}', or ']'. LineNumber: 36 | BytePositionInLine: 167.
   at System.Text.Json.ThrowHelper.ThrowJsonReaderException(Utf8JsonReader& json, ExceptionResource resource, Byte nextByte, ReadOnlySpan`1 bytes)
   at System.Text.Json.Utf8JsonReader.ConsumeNextTokenUntilAfterAllCommentsAreSkipped(Byte marker)
   at System.Text.Json.Utf8JsonReader.ConsumeNextToken(Byte marker)
   at System.Text.Json.Utf8JsonReader.ConsumeNextTokenOrRollback(Byte marker)
   at System.Text.Json.Utf8JsonReader.ReadSingleSegment()
   at System.Text.Json.Utf8JsonReader.Read()
   at System.Text.Json.JsonDocument.Parse(ReadOnlySpan`1 utf8JsonSpan, JsonReaderOptions readerOptions, MetadataDb& database, StackRowStack& stack)
   at System.Text.Json.JsonDocument.Parse(ReadOnlyMemory`1 utf8Json, JsonReaderOptions readerOptions, Byte[] extraRentedArrayPoolBytes, PooledByteBufferWriter extraPooledByteBufferWriter)
   at System.Text.Json.JsonDocument.Parse(ReadOnlyMemory`1 json, JsonDocumentOptions options)
   at System.Text.Json.JsonDocument.Parse(String json, JsonDocumentOptions options)
   at Microsoft.Extensions.Configuration.Json.JsonConfigurationFileParser.ParseStream(Stream input)
   at Microsoft.Extensions.Configuration.Json.JsonConfigurationProvider.Load(Stream stream)

There is an issue with the appsettings.json file. This could be caused by a double '\' (backslash) were only 1 is needed. The installer looks through the appsettings.json file to fix potential issues with backslashes. However, it does so without much checks on context. This can happen especially during an upgrade when the appsettings.json file has been modified already during a previous configuration.

Please check JSON structure and try executing the installer again. If needed, contact Ometa support for assistance.

There is a problem with tis Windows Installer package

When you encounter the error message "There is a problem with this Windows Installer package. A script required for this install to complete could not be run. Contact your support personnel or package vendor." after clicking NEXT on the feature selection screen, it is most likely caused by running the setup from a personal folder, such as the Downloads folder.

To resolve this issue, copy the setup file to a different location, such as C:\Temp, and run the setup with administrator privileges.

Setup log file

It is possible to create a log file of all actions executed by the setup during install time.

Start the installer from a command line window to provide additional logging options, an example:

Each log option starts with /L and then a file name. The file name can be a relative path but a full path is also possible. Right added next to the /L option, at least one parameter must be used to filter exactly what data should be logged.

• i - Status messages
• w - Nonfatal warnings
• e - All error messages
• a - Start up of actions
• r - Action-specific records
• u - User requests
• c - Initial UI parameters
• m - Out-of-memory or fatal exit information
• o - Out-of-disk-space messages
• p - Terminal properties
• v - Verbose output
• x - Extra debugging information
• + - Append to existing log file
• ! - Flush each line to the log
• * - Log all information, except for v and x options

Some examples

Creates a log file (logs everything) with the name install.log in the current directory:

"Ometa Software Suite v4.0.0.exe" /L*vx install.log

Creates a log file in the folder c:\temp and logs only error messages:

"Ometa Software Suite v4.0.0.exe" /Le c:\temp\install.log

Several parameters can be used at the same time as well:

"Ometa Software Suite v4.0.0.exe" /Lie+ install.log

The command in the screenshot of the command line above will log to a local file install.log and logs all information including verbose output.

Other Issues

Contact Ometa Support if you encounter any other issues which are unclear.