Generic REST Service

Minimum Requirements

Login to the server where you installed the Generic REST 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 Generic REST Service) mapped to the %OMETA_INSTALL_ROOT%\Ometa Software Suite\Services\Generic REST 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

	Advanced Settings	Value
(General)	Preload Enabled	True

Apply the following Advanced Settings to 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) read / write access 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.

Application Pool Identity

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

Service Settings

Database Connection String

The connection information to the Ometa Framework database must be configured correctly. Please consult the article Check Database Connection Configuration for more information.

General Service and SharePoint Settings

Depending on the type of setting, some values will have to be set in the dbo.Config table and other will have to be set in specific config.SharePointAuthentications or config.SharePointRewriteUrls tables.

These settings have to modified in the dbo.Config table.

Setting Name	Description
Generic REST Service Enable Compression [true, false]	Applies compression to the response data of the service. This should be true for production environments.
Core Service Url	The URL of the Ometa Core Service. The Core Service will be used to discover other settings for the this service.
Authority Service Url	The URL where the Authority 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.
Repository Port	The port where the Ometa Business Connector Listener service is listening for incoming requests (defaults to 2005).

If you're working with ADM's, CM's and/or Remote Event Receivers through the Ometa Framework, the service needs administrator access to that SharePoint environment for fetching context data and processing events. In that case you'll need to configure the following properties in the config.SharePointAuthentications table. The Source name must be unique.

Setting Name	Description
Source	The SharePoint installation calls might be going to. Keep these as short as possible but able to distinguish different SharePoint sources.
IsCloudEnvironment [true, false]	`true` if you're using SharePoint Online. `false` if SharePoint Server (on-premise) is used.
Domain	The domain name of the SharePoint administrator user. Not applicable for SharePoint Online environments.
Username	The username of the SharePoint administrator user. For SharePoint Online this will be an email address.
Password	The password of the SharePoint administrator user. This password can be configured with an encrypted value (with a tool from Ometa) or the plain text value.
ClientId	The client ID of the registered app in the Microsoft Azure Portal. Required for SharePoint Online when using username and password.
SharePointOnlineAzureAdCertificate	The subject of the certificate linked to the registered app in the Microsoft Azure portal.
SharePointOnlineTenant	The SharePoint online tenant.

You can specify multiple connections in the config.SharePointAuthentications table. This allows a single Generic REST service instance to be used by multiple SharePoint installations and even hybrid solutions using both SharePoint OnPremise and SharePoint Online.

Authentication Methods

The Ometa framework offers several authentication methods towards SharePoint. Below is an ordered list of the authentication methods that the framework will use. The first method that is configured in the profile will be used.

Name	Necessary Appsettings Fields	Where to use?
Azure AD Certificate	ClientID SharePointOnlineAzureADCertificate SharePointOnlineTenant	Preferred to use for SharePoint Online
Username Password	ClientID (only for SharePoint online) Username Password Domain (only for SharePoint On-Premise)	SharePoint On-Premise SharePoint Online (not recommended)
Default Network Credentials	None It is likely an authorization error will occur.

To configure any of the modern authentication methods using a Certificate or ClientID, refer to this article for a guide.

/** 
 *  SQL script to update or insert the client id and certificate for the specified source.
 *  SharePoint Online: preferred authentication.
 *  Update the following 4 parameters: Source, ClientId and SharePointOnlineAzureAdCertificate and SharePointOnlineTenant
 */
DECLARE @Source NVARCHAR(255) = 'https://yourtenant.sharepoint.com';
DECLARE @ClientId NVARCHAR(255) = 'YourClientIdValue';
DECLARE @SharePointOnlineAzureAdCertificate NVARCHAR(255) = 'YourCertificateName';
DECLARE @SharePointOnlineTenant NVARCHAR(255) = 'YourTenantId'; -- U may use also the DNS entry, for example: yourtenant-admin.sharepoint.com

MERGE INTO [config].[SharePointAuthentications] AS target
USING (VALUES (@Source, @ClientId, @SharePointOnlineAzureAdCertificate, @SharePointOnlineTenant)) AS source (Source, ClientId, SharePointOnlineAzureAdCertificate, SharePointOnlineTenant)
ON target.Source = source.Source
WHEN MATCHED THEN
    UPDATE SET
		target.ClientId = source.ClientId,
        target.SharePointOnlineAzureAdCertificate = source.SharePointOnlineAzureAdCertificate,
        target.SharePointOnlineTenant = source.SharePointOnlineTenant,
		target.IsCloudEnvironment = 1,
		target.LastModified = SYSDATETIMEOFFSET(),
		target.Domain = NULL,
		target.Username = NULL,
		target.[Password] = NULL
WHEN NOT MATCHED THEN
    INSERT (Source, ClientId, SharePointOnlineAzureAdCertificate, SharePointOnlineTenant, IsCloudEnvironment, CreatedByDisplayName, CreatedByIdentifier, LastModified, LastModifiedByDisplayName, LastModifiedByIdentifier)
    VALUES (source.Source, source.ClientId, source.SharePointOnlineAzureAdCertificate, source.SharePointOnlineTenant, 1, 'Internal System', 'Internal System', SYSDATETIMEOFFSET(), 'Internal System', 'Internal System');


/** 
 *  SQL script to update or insert the domain, username and password for the specified source.
 *  SharePoint Server (on-premise)
 *  Update the following 4 parameters: Source, Domain, Username and Password
 */
DECLARE @Source NVARCHAR(255) = 'https://yourtenant.onmicrosoft.com';
DECLARE @Domain NVARCHAR(255) = 'YourDomain';
DECLARE @Username NVARCHAR(255) = 'YourUsername';
DECLARE @Password NVARCHAR(255) = 'YourPassword';

MERGE INTO [config].[SharePointAuthentications] AS target
USING (VALUES (@Source, @Domain, @Username, @Password)) AS source (Source, Domain, Username, [Password])
ON target.Source = source.Source
WHEN MATCHED THEN
    UPDATE SET
        target.Domain = source.Domain,
        target.Username = source.Username,
		target.[Password] = source.[Password],
		target.IsCloudEnvironment = 0,
		target.LastModified = SYSDATETIMEOFFSET(),
		target.ClientId = NULL
WHEN NOT MATCHED THEN
    INSERT (Source, Domain, Username, [Password], IsCloudEnvironment, CreatedByDisplayName, CreatedByIdentifier, LastModified, LastModifiedByDisplayName, LastModifiedByIdentifier)
    VALUES (source.Source, source.Domain, source.Username, source.[Password], 0, 'Internal System', 'Internal System', SYSDATETIMEOFFSET(), 'Internal System', 'Internal System');

These settings are used to support authentication to a specific SharePoint site to retrieve the context (calls that are made by the REST service to SharePoint). Every rewrite will have to defined by a record in the table config.SharePointRewriteUrls. The FromUrl value must be unique.

Setting Name	Description
FromUrl	The URL to replace.
ToUrl	The URL to replace the FromUrl with.

Test the Generic REST Service

Test the Generic REST Service by navigating to https://*your-site-binding:port*.

If you get the following error message, make sure to start the Ometa Business Connector Service also known as the BCM service. All Ometa Services should be running.

Server Error in '/' Application.

No connection could be made because the target machine actively refused it 10.10.1.1:2005

BCM Service is stopped

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

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

If anything goes wrong when testing the service and you get an error page, your best bet is to check the event viewer.

Tip

Most common causes for startup errors:

Invalid Core Service URL
Certificate errors (invalid)
Wrong value for UseUnsafeUserContext in appsettings.json
Invalid json data in appsettings.json

Access to the Path is Denied

Make sure the account running the application pool has full control privileges on the %OMETA_INSTALL_ROOT% folder.

Access to the path is denied

No connection could be made because the target machine actively refused it [IP Address]

Make sure the Ometa Business Connector Service also known as the BCM service is running.
Open Task Manager and navigate to the Services tab.
Make sure all Ometa services and especially the BCM service is started.

BCM Service is stopped

401 - Unauthorised

If navigating to the Generic REST Service gives a 401 - Unauthorised error code, this is probably because the default anonymous user does not have access to the files of the website.

In IIS click on the related site and click on Authentication.
Make sure Anonymous access is enabled.
If enabled and the issue still occurs, click on Edit... in the actions panel on the right.
Make sure that the selected account has read, write and folder creation permissions.

Anonymous user

If the error still occurs, try setting the Connect As acccount by updating the Basic Settings of the site. This will ensure that the folder structure of the site is accessed by the selected account. Make sure that the account has read, write and folder creation permissions.

Specific connect as user

Table of Contents