Core Framework Service

This secured core service is responsible for managing all client requests to the framework. It needs to be setup with HTTPS and a valid certificate.

Minimum Requirements

Login to the server where you installed the Core Framework Service and ensure that this server meets the minimum system requirements of an Ometa Framework server.

Application Pool and IIS Site

• Ensure an application pool and an IIS site mapped to the %OMETA_INSTALLATION_MAP%/Services/Core Service directory.
• Ensure an HTTPS binding to the site with a port of your choice, a valid hostname and ensure that a valid SSL certificate is chosen.

• It is recommended to configure the user of the application pool to be an AD account. This account should also have read / write access to the Ometa Framework database, especially when trusted connections are used.

Setup obiz suite

A new application needs to be added on the Core Service Site. This application will be used to host standalone pages (close and reassign task,...).

• Open the Core Service Site Applications.

• Add a new Application.

Tip

The full Physical path should look like this: %OMETA_INSTALLATION_MAP%\Services\Core Service\wwwroot\assets\obiz-suite

• End result should look like the picture below.

Obiz Suite appsettings.json

Default location: C:\Program Files (x86)\Ometa BVBA\Ometa Software Suite\Services\Core Service\wwwroot\assets\obiz-suite\assets

Edit these appsettings, change https://core.ometa.net:50200 to the right Core Service Url.

Copy

{
  "coreServiceUrl": "https://core.ometa.net:50200"
}

Note

Make sure the IIS module 'URL Rewrite' is installed and enabled.

Configure Database Connection strings

Note

This section can be ignored from v5.0 as the connection strings will be automatically configured in the installer. However, this is still required for older versions, or when upgraded from an older version.

Setup the connection strings to the Ometa Framework and Ometa Dynamic Case System databases by opening up the appsettings.json in the %OMETA_INSTALLATION_MAP%/Services/Core Service map and adding/updating the value of ConnectionStrings.OmetaFrameworkDatabase and ConnectionStrings.OmetaDcsDatabase.

Copy

{
  // ...
  // Other JSON Settings
  // ...
  "ConnectionStrings": {
    "OmetaFrameworkDatabase": "Data Source=dbserver.ometa.net;database=framework database;trusted_connection=yes;",
    "OmetaDcsDatabase": "Data Source=dbserver.ometa.net;database=dcs database;trusted_connection=yes;"
  }
}

Warning

This is a JSON file. Any special characters in the connection strings should be escaped. The most common use case for escaping characters is named SQL instances. Normally you would write Data Source=myserver\mysqlinstance but as this is JSON, the backslash should be escaped: Data Source=myserver\\mysqlinstance.

Note

This connection string will be used by the Framework Core Service for both accessing and migrating (creating new tables) the database to the latest schema of the installed framework version. Make sure that the database name in the connection string is the same as the database name from the SQL server. Ensure that the user in the connection string has enough access rights to completely manage the database.

If you set trusted_connection to yes, the user of the application pool will be used for those actions.

Azure SQL Database connection strings

When using Azure SQL Database services for data storage, adapt the connection strings a bit:

Copy

{
  // ...
  // Other JSON Settings
  // ...
  "ConnectionStrings": {
    "OmetaFrameworkDatabase": "Data Source='tcp:your-azure-instance-sql.database.windows.net,1433';database=framework database;Uid=sqlaccount;Pwd=sqlpwd;Encrypt=yes;TrustServerCertificate=no;Connection Timeout=30;",
    "OmetaDcsDatabase": "Data Source='tcp:your-azure-instance-sql.database.windows.net,1433';database=dcs database;Uid=sqlaccount;Pwd=sqlpwd;Encrypt=yes;TrustServerCertificate=no;Connection Timeout=30;"
  }
}

Replace your-azure-instance-sql.database.windows.net, sqlaccount and sqlpwd with the proper corresponding values.

Framework BC Folder Configuration

The Core Web Service provides services to be able to access OPC UA servers more directly instead of via the OPC UA interface. But to provide that service, the Core Web service needs to know the connection information defined in the Framework profiles to be able to set up connections to OPC UA servers. This is done by setting the FrameworkBCFolder configuration to the correct path of the BC folder of the Framework installation.

Copy

{
  // ...
  // Other JSON Settings
  // ...
  "FrameworkBCFolder": "C:\\Program Files (x86)\\Ometa BVBA\\Ometa Software Suite\\TopDir\\BC",
  // ...
  // Other JSON Settings
  // ...
}

Warning

This is a JSON file. Any special characters in the connection strings should be escaped. The most common use case for escaping characters are backslashes between folder names. Normally you would write C:\Program Files (x86)\Ometa BVBA but as this is JSON, the backslashes should be escaped: C:\\Program Files (x86)\\Ometa BVBA.

Database Config Table

The Core Service has a discover endpoint that other services rely on. This discover endpoint processes its data via the config table in the Ometa Framework database (in older versions the name can also be Ometa Business Connector). You can identify this database as it has these tables pre-installed: Config, Operators, AuditTrail, Combiners, ... You need to ensure that the dbo.Config table has the following entries with valid values.

Tip

If you first try to test the service by navigating to https://ometa-core.example.com/odata/Discover, the required entries are created for you in the config table and you'll only have to set their values.

• Authority Service Url: the url where the Authority Service is or will be installed (including the port if not using a DNS record)
• Core Service Url: the url where the [Core Service] itself is or will be installed (including the port if not using a DNS record)
• Generic REST Service Url: the url where the Generic REST Service is or will be installed (including the port if not using a DNS record)
• Repository Server: the IP or hostname where the Framework Repository is installed (in the setup this is called 'Core Framework Components')
• The port where the Ometa Business Connector Listener service is listening for incoming requests (defaults to 2005)
• Environment: The current environment of the server. Eg. Development, Testing, Acceptance, Production

Example:

Name	Value
Authority Service Url	https://ometa-authority.example.com
Core Service Url	https://ometa-core.example.com
Generic REST Service Url	https://ometa-rest.example.com
Repository Server	services.ometa.net
Repository Port	2005
Environment	[Development, Testing, Acceptance, Production]

Environment statusbar

Setting the Environment value in the database will result in a visual change of the statusbar in the WpfGUI:

There is no value or an incorrect value in the database.

The WpfGui is disconnected. This will show the core service URL if it was previously connected.

Connected to a development environment.

Connected to a testing environment.

Connected to an acceptance environment.

Connected to a production environment.

SharePoint Legacy Redirect Settings

These are optional legacy settings. These settings are only used for SharePoint environments which have a global redirect and silent redirect url defined.

Name	Value
Redirect Url	The URL of the global redirect page in your SharePoint environment (e.g.: https://your.sharepoint/SitePages/obiz-redirect-page.aspx).
Silent Redirect Url	The URL of the global silent redirect page in your SharePoint environment (e.g.: https://your.sharepoint/SitePages/obiz-silent-redirect-page.aspx).

Configure Allowed Origins

Provide the allowed origins from which the core service may accept requests:

Copy

{
  // ...
  // Other JSON Settings
  // ...
  "AllowedOrigins": [ "https://example.sharepoint.com" ]
}

Note

You can pass multiple origins. You can also pass a wildcard for subdomains, for example: 'https://*.sharepoint.com'.

Test the Core Framework Service

Tip

Always restart the Core Service when changing settings in the appsettings.json file.

Test the Core Framework Service by navigating to https://your-site-binding:port/odata/Discover

This should succeed without a security warning from the browser and should contain the values you configured in the Config table of the database.

Logging

• If anything goes wrong when testing the service and you get an error page similar like the one below, your best bet is to check any log files in the BAM log directory, default directory %OMETA_INSTALLATION_MAP%/Log.
• If BAM is enabled on the directory where the logging takes place, it is also possible that BAM already processed the log file. In that case, you'll need to check the BAM portal. Look for a process with the name Ometa.Framework.Web.

When checking the log file, you'll need to search for a fatal error for example.

Copy

2019-02-07 10:04:23.2232398 [Fatal-1]: Application startup exception
    System.Data.SqlClient.SqlException (0x80131904): A network-related or instance-specific error occurred while establishing a connection to SQL Server.
    The server was not found or was not accessible.
    Verify that the instance name is correct and that SQL Server is configured to allow remote connections.
    (provider: Named Pipes Provider, error: 40 - Could not open a connection to SQL Server) ---> System.ComponentModel.Win32Exception (53): The network path was not found

Routing Multiple Service Instances

In some more advanced use cases where the Ometa framework has different data sources that cannot be accessed by the same Core service (like internal active directory), or providing data on multiple SharePoint environments, there can be a need to use multiple Core services originating from one framework installation.

This configuration is possible in the database ConfigDiscovery table. A new entry in this table can be created with the url of another Core service, generic REST or authority service.

Tip

Empty configurations will be ignored and use the default value from the Config table.

By creating and linking this entry to a ConditionSet, different conditions can be used to select a different service instance.

The following fields can be used to define the conditions on the discovery:

Name	FieldType	Description
Request.IsExternalUser	YesNo	Indicates if the user is from outside the organisation. This field can only be true on SharePoint Online environments external users. For example, this field can never be true when connecting the Ometa Business Connector.
Request.Url	Text	The target url of the request. This is the Ometa authority service itself.
Request.IpAddressV4	Text	The IP-address v4 of the user.
Request.IpAddressV6	Text	The IP-address v6 of the user.
Request.UserAgent	Text	The user agent of the user.
Request.Host	Text	The host of the url.
Request.Referer	Text	The original address the request came from. This can be used to determine the SharePoint environment.
Request.AcceptLanguage	Text	The languages client can understand, and which variant is preferred.

Tip

The available fields and their values can be validated in the logging of the core service upon discovery (either manual or by an ADM). The minimum log level for this is 'Information'.

Troubleshooting

HTTP 502.5 - ANCM Out-Of-Process Startup Failure

If you encounter a 'HTTP 502.5 - ANCM Out-Of-Process Startup Failure' error when testing the service, this is mostly caused by the fact that you just installed the .Net Core runtime and IIS is not yet restarted. Open up a command prompt as administrator and execute an iisreset.

Important

It is not enough to restart IIS via the management tool. You really have to execute an iisreset command. If that doesn't solve the issue, you can also try to completely reboot the server.

Make sure your settings in the appsettings.json file are correct and your application pool identity has enough access rights to the database if you use trusted connection in the connection string.

Tip

Most common causes for fatal errors:

• Invalid appsettings.json (remember that a backslash needs to be escaped by another backslash)
• Distinguished name misspelled or belongs to a certificate which cannot be found
• Invalid or missing connection string
• Invalid or missing log configuration
• Not enough access rights to the database
• Not enough access rights to the log directory

An Error Occurred While Starting The Application

If you encounter 'An error occured while starting the application'. Check that your IIS Application Pools and sites are configured correctly.

Buffer Size Error

An error is thrown when the OData query returns too many rows:

This means that the max buffer size for the Core Service has been reached. It is not recommended to return that many rows though, your query should only return what you really need. But if you do want to return many rows, you can set the following option in the appsettings.json of the Core Service and the error will be resolved:

Copy

{
  ...
  "ConnectionStrings": {
    "OmetaFrameworkDatabase": "Data Source=sqlserver.yourdomain.net;database=yourframeworkdatabase;trusted_connection=yes;",
    "OmetaDcsDatabase": "Data Source=sqlserver.yourdomain.net;database=yourdcsdatabase;trusted_connection=yes;"
  },
  "MaxRecordsBufferLimit": 50000000
}

In the picture above we set the maximum buffer size to 50 million records.

Note

Executing queries that return many rows won't be good for performance.

Other (fatal) errors

Some errors are thrown too early to be caught by the logging structures (ex: initializing the logging itself). In this case the only way to see those errors is to start the service outside of IIS (in-process) with the dotnet CLI.

1. Open up a command prompt as an administrator and navigate to the %OMETA_INSTALLATION_MAP%/Services/Core Service directory
2. Execute the command dotnet .\Ometa.Framework.Web.dll

Any errors within the startup sequence will be thrown to the console and can be investigated.

If the command above executes succesfully but browsing the service still returns 'HTTP 500.19 Internal Server' error, ensure that the .NET Core Runtime is explicitly installed.

Warning

Installation of the .NET Core SDK does not install all required modules to host the service on IIS.