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 (Ometa Core Service) mapped to the %OMETA_INSTALL_ROOT%\Ometa Software Suite\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.

  

• Apply the following Advanced Settings on the website:

  	Advanced Settings	Value
  (General)	Preload Enabled	True

• Apply the following Advanced Settings on the application pool:

  	Advanced Settings	Value
  (General)	Start Mode	AlwaysRunning
  Process Model	Identity	* User which has access to %OMETA_INSTALL_ROOT%. * When using trusted connections (integrated security) db_owner to the Ometa Framework database.
  	Idle Time-out (minutes)	0
  Recycling	Regular Time Interval (minutes)	Recommended daily (night time) when there is no or less network traffic. Refer to the recycling article for more background information.

  

Identity

When using a domain service account, make sure to include the Domain, otherwise the application pool will not start and give the following error in the System Event Viewer.

The identity of application pool Ometa Core Service is invalid. The user name or password that is specified for the identity may be incorrect, or the user may not have batch logon rights.  
If the identity is not corrected, the application pool will be disabled when the application pool receives its first request.  
If batch logon rights are causing the problem, the identity in the IIS configuration store must be changed after rights have been granted before Windows Process Activation Service (WAS) can retry the logon.  
If the identity remains invalid after the first request for the application pool is processed, the application pool will be disabled. The data field contains the error number.

Setup Obiz Suite

A new application needs to be added on the Core Service Site. This application will be used to host the Obiz Suite.

1. Go to the website of the Ometa Core Service.

2. In the right menu, click on View Applications.

   

3. In the right menu, click on Add Application.

   Setting	Value
   Alias	obiz-suite
   Application pool	Must be the application pool of the Ometa Core Service.
   Pysical path	%OMETA_INSTALL_ROOT%\Ometa Software Suite\Services\Core Service\wwwroot\assets\obiz-suite

   

4. End result should look like the picture below, except to the replace the %OMETA_INSTALL_ROOT% by the actual value.

   

   Obiz Suite appsettings.json

5. Click once or double click on the /obiz-suite application.

6. In the right menu, click on Explore to open the corresponding directory. Navigate to the assets folder.

7. Update the coreServiceUrl key in the appsettings.json located in %OMETA_INSTALL_ROOT%\Ometa Software Suite\Services\Core Service\wwwroot\assets\obiz-suite\assets.

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

Note

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

Logging

• Change the default IIS logging location. The default location is the system drive. When this drive runs out of disk space, it can severely impact the overall operation of the Ometa Framework.

  1. Open IIS Manager.
  2. In the Connections pane, click on the server name to select the server level.
  3. In the **Features View **pane, double-click Logging.
  4. In the Logging window, click Browse next to the Directory field and select the new location on the separate disk.
  5. Click Apply to save the changes.
  6. It is also advisable to clean the logs after X days. Follow the Microsoft documentation and configure a scheduled task: Delete old log files by script

Database Config Table

1. Go to the Ometa Framework database with SQL Management Studio.
2. Update the following values in the dbo.config table.

MERGE INTO [OmetaFramework].[dbo].[Config] AS Target
USING (VALUES
	('Authority Service Url', 'https://'),
	('Core Service Url', 'https://'),
	('Generic REST Service Url', 'https://'),
	('Repository Server', 'hostname'),
  ('Repository Port', '2005'),
	('Environment', 'Development, Testing, Acceptance, Production')
) AS Source ([Key], [Value])
ON Target.[Key] = Source.[Key]
WHEN MATCHED THEN
	UPDATE SET [Value] = Source.[Value]
WHEN NOT MATCHED THEN
	INSERT ([Key], [Value])
	VALUES (source.[Key], source.[Value]);

Key	Description	Possible Value
Authority Service Url	The URL of the Ometa Authority Service (including the port if not using a DNS record).	https://ometa-authority.example.com
Core Service Url	The URL of the Ometa Core Service (including the port if not using a DNS record).	https://ometa-core.example.com
Generic REST Service Url	The URL of the Ometa Generic REST Service (including the port if not using a DNS record).	https://ometa-rest.example.com
Repository Server	The IP or hostname where the Framework Repository is installed (in the setup this is called 'Core Framework Components')	services.ometa.net
Repository Port	The port of the BCA service. Defaults to 2005	2005
Environment	The current environment of the server. Possible values: Development, Testing, Acceptance, Production	[Development, Testing, Acceptance, Production]

Environment Status Bar

Setting the Environment value in the database will result in a visual change of the status bar in the Ometa Business Connector:

State	Description	Result
Connected	There is no value or an incorrect value in the database.
Disconnected	The Ometa Business Connector is disconnected. This will show the core service URL if it was previously connected.
Development	Connected to a development environment.
Testing	Connected to a testing environment.
Acceptance	Connected to a acceptance environment.
Production	Connected to a production environment.

Test the Core Framework Service

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.

Below topics are more advanced configuration settings and the troubleshooting guide in case of problems.

Proceed with configuring the Ometa Authority Service, if the settings below are not relevant to you.

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

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_INSTALL_ROOT%\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.

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

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 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 and the error will be resolved:

{
  ...
  "ConnectionStrings": {
    "OmetaFrameworkDatabase": "Data Source=sqlserver.yourdomain.net;database=yourframeworkdatabase;trusted_connection=yes;TrustServerCertificate=True;",
    "OmetaDcsDatabase": "Data Source=sqlserver.yourdomain.net;database=yourdcsdatabase;trusted_connection=yes;TrustServerCertificate=True;"
  },
  "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_INSTALL_ROOT%\Ometa Software Suite\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 successfully but browsing the service still returns 'HTTP 500.19 Internal Server' error, ensure that the correct .NET Runtime is explicitly installed.

Warning

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