Caution

Since version v3.0.0 the settings of this service are contained in the appsettings.json file. Do not use the web.config file for configuring Ometa settings. It will be overwritten after each upgrade.

Generic REST Service

The Generic REST service is used by the latest ADM components and the older Kendo ADM. It also contains the OData services for executing methods. Since this service is also part of the new security layers, it needs to be configured manually. It is no longer possible to use this service without a valid SSL certificate.

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 mapped to the %OMETA_INSTALLATION_MAP%/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.

Warning

The port of Generic REST Service Url in the database must match the port in IIS. If the ports don't match, update Generic REST Service Url of table dbo.Config from the Ometa Business Connector database (default name is Ometa Business Connector) to the correct port.

Service Settings

There are some required settings you need to configure in the appsettings.json file of the Generic REST Service. You can find this file in the %OMETA_INSTALLATION_MAP%/Services/Generic REST Service directory.

{
  "AppSettings": {
    "EnableCompression": true,
    "CoreServiceUrl": "https://ometa-core.example.com",
    "AuthorityUrl": "https://ometa-authority.example.com",
    "UseUnsafeUserContext": false,
    "SharePointAuthentications": [
        { 
            "Source": "http://yourintranet.yourdomain.com",
            "IsCloudEnvironment": false,
            "Domain": "yourdomain",
            "Username": "admin",
            "Password": "",
            "ClientId": "",
            "ClientSecret": ""
        },
        { 
            "Source": "https://yourcompany.sharepoint.com",
            "IsCloudEnvironment": true,
            "Domain": "",
            "Username": "admin@yourdomain.onmicrosoft.com",
            "Password": "",
            "ClientId": "",
            "ClientSecret": ""
        }
    ],
    "SharePointRewriteUrls": [
        {
            "FromUrl": "https://yourcompany.sharepoint.com",
            "ToUrl": "https://yourcompany-internal.sharepoint.com"
        }
    ] 
  },
  "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;"
  }
}

Setting Name	Description
EnableCompression [true, false]	Applies compression to the response data of the service. This should be true for production environments.
CoreServiceUrl	The URL of the Ometa Core Service. The Core Service will be used to discover other settings for the this service.

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 SharePointAuthentications:

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 in the cloud (Office 365). False if SharePoint is installed on-premise.
Domain	The domain name of the SharePoint administrator user. Not applicable for Office 365 environments.
Username	The username of the SharePoint administrator user. For Office 365 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.
ClientSecret	The client secret of the registered app in the Microsoft Azure portal. You have only one chance to copy this secret. This secret can be configured with an encrypted value (with a tool from Ometa) or the plain text value.

Warning

Modern authentication is only used when both the ClientId and ClientSecret are configured for this source, otherwise the Username, Password and Domain are used.

Because SharePointAuthentications is an array, you can specify multiple connections. 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.

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

Setting Name	Description
AuthorityUrl	The URL of the Ometa Authority Service.

Warning

The configuration for RedirectUrl and SilentRedirectUrl have been moved to the Core service since version 3.7.0.

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). You can remove this from the appsettings.json if you're not planning on using it.

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

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.

These are required connection strings you need to configure for the Generic REST service.

Setting Name	Description
OmetaFrameworkDatabase	The connection string to the Ometa Framework database.
OmetaDcsDatabase	The connection string to the Ometa Dynamic Case System database.

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

These connection strings will be used by the Generic REST Service for accessing the databases of the installed framework version. Make sure that the database names in the connection strings are the same as the database names in 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.

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

{
  // ...
  // 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.

Application Pool Identity

The application pool account of the Ometa Generic REST Service must have read and write access to its own WorkDir directory.

Test the Generic REST Service

Test the Generic REST Service by navigating to https://your-site-binding:port. This should succeed without a security warning from the browser.

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

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.
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.