Configuring Business Central Web Server Instances

Accessing Business Central from the Business Central Web client or App requires a Business Central Web Server instance on IIS. You create a Business Central Web Server instance for the Business Central Web Server by using the Business Central Setup to install the Business Central Web Server or by running the New-NAVWebServerInstance cmdlet. When you set up a web server instance, you are configuring the connection from the Business Central Web Server to the Business Central Server instance. The connection settings, along with several other configuration settings, are saved in a configuration file for the web server instance.

About the configuration file

The configuration file for the web server instances is a .json file type called navsettings.json. The navsettings.json file is a Java Script Object Notification file type that is similar to files that use the XML file format.

After installation, you can change the configuration by modifying the navsettings.json. There are two ways to modify this file: directly or using PowerShell.

Where to find the navsettings.json file

The navsettings.json file is stored in the physical path of the web server instance, which is by default is %systemroot%\inetpub\wwwroot\[WebServerInstanceName].

[WebServerInstanceName] corresponds to the name (alias) of the web server instance in IIS, for example, c:\inetpub\wwwroot\BC140.

Modify the navsettings.json file directly

  1. Open the navsettings.json in any text or code editor, such as Notepad or Visual Studio Code.

    Each setting is defined by a key-value pair.

    • In the navsettings.json file, a setting has the format:

      "keyname": "keyvalue",
      

    The keyname is the name of the configuration setting and the keyvalue is the value.

    For example, the configuration setting that specifies the Windows credential type for authenticating users is:

    "ClientServicesCredentialType":  "Windows",
    

    Include values in double quotes.

  2. Find the configuration settings that you want to change, and then change the values.

    See the Settings section for a description of each setting.

  3. When you are done making changes, save the file.

  4. Restart the Business Central Web Server instance for the changes to take effect.

    For example, in IIS Manager, in the Connections pane, select website node for Business Central Web Server, and then in the Actions pane, choose Restart. Or, from your desktop, run iisreset.

Modify the navsettings.json file by using the Set-NAVWebServerInstanceConfiguration cmdlet

The PowerShell script module NAVWebClientManagement.psm1 includes the Set-NAVWebServerInstanceConfiguration cmdlet that enables you to configure a web server instance.

  1. Depending on your installation, run the Dynamics NAV Development Shell or Windows PowerShell as an administrator.

    For more information, see Get started with the Business Central Web Server cmdlets.

  2. For each setting that you want to change, at the command prompt, run the following command:

    Set-NAVWebServerInstanceConfiguration -Server [MyComputer] -ServerInstance [ServerInstanceName] -WebServerInstance [MyBCWebServerInstance] -KeyName [Setting] -KeyValue [Value]
    

    Replace:

    • [MyComputer] with the name of the computer that is running the Business Central Server
    • [ServerInstanceName] with the name of the server instance, such as BC140.
    • [MyBCWebServerInstance]with the name of the web server instance for the Business Central Web Server.
    • [KeyName] with the name of the setting. Refer to the next section in this article.
    • [KeyValue] with the new value of the setting.

Settings in the navsettings.json

The navsettings.json has the following structure, where settings are included under one of two root elements: NAVWebSettings and ApplicationIdSettings:

{
  "NAVWebSettings": {
     "//ServerInstance":  "Name of the Business Central Server instance to connect to (for client) or listen on (for server).",
     "ServerInstance":  "BC140",
      [...more keys]
 },
  "ApplicationIdSettings": {
      "BlogLink": "https://myBCBlog.com",
      [...more keys]
  }
}

// indicates a comment that provides help for the setting, and has no affect on the Web Server instance.

The following table describes the settings that are available in the navsettings.json for each root element. If you do not see a setting in the file, this is because some settings are not automatically included as a key in the file. For these settings, you can add the key manually. If you do not add the key, the default value of the setting is used.

Important

If modifying the file directly, place values in double quotes "".

Setting/KeyName Description
AllowedFrameAncestors Specifies the host name of any web sites in which the Business Central Web client or parts of are embedded. By default, the Business Central Web Server will not allow a website to display it inside an iframe unless the website is hosted on the same web server. This value of this setting is a comma-separated list of host names (URIs). Wildcard names are accepted. For example: https:mysite.sharepoint.com, https:*.myportal.com

GlobalEndPoints Specifies the comma-separated list of global endpoints that are allowed to call this website. The values must include http scheme and fully qualified domain name (FDQN), such as https://financials.microsoft.com.

Default value: none
LoadScriptsFromCdn Specifies whether to load scripts from Content Distribution Networks (CDNs). This only applies to scripts that are available from a CDN, like jQuery.

If set to false, scripts will be loaded from the Web server, which is useful in, for example, an intranet scenario where there is no internet access.
Default value: true
AllowNtlm Specifies whether NT LAN Manager (NTLM) fallback is permitted for authentication.

To require Kerberos authentication, set this value to false.

Values: true, false

Default value: true
ClientServicesChunkSize Sets the maximum size, in kilobytes, of a data chunk that is transmitted between Business Central Web Server and Business Central Server. Data that is transmitted between Business Central Web Server and Business Central Server is broken down into smaller units called chunks, and then reassembled when it reaches its destination.

Values: From 4 to 80.

Default value: 28
ClientServicesCompressionThreshold Sets the threshold in memory consumption at which Business Central Web Server starts compressing data sets. This limits amount of consumed memory. The value is in kilobytes.

Default value: 64
ClientServicesProtectionLevel Specifies the security services used to protect the data stream between the Business Central Web Server and Business Central Server. This value must match the value that is specified in the Business Central Server configuration file. For more information, see Configuring Business Central Server.

Values: EncryptAndSign, Sign, None

Default value: EncryptAndSign
Server Specifies the name of the computer that is running the Business Central Server.

Default value: localhost
ServerInstance Specifies the name of the Business Central Server instance that the Business Central Web Server connects to.

Default value: BC140
ClientServicesCredentialType Specifies the authorization mechanism that is used to authenticate users who try to connect to the Business Central Web Server. For more information, see Authentication and User Credential Type.

The credential type must match the credential type configured for the Business Central Server instance that the Business Central Web Server connects to. For information about how to set up the credential type on Business Central Server, see Configuring Business Central Server.

Values: Windows, UserName, NavUserPassword, AccessControlService

Default value: Windows
ClientServicesPort Specifies the TCP port for the Business Central Server. This is part of the Business Central Server’s URL.

Values: 1-65535

Default value: 7046
ManagementServicesPort The listening TCP port for the Business Central management endpoint.

Valid range: 1-65535
Default value: 7045
ServicePrincipalNameRequired If this parameter is set to true, then the Business Central Web Server can only connect to a Business Central Server instance that has been associated with a service principal name (SPN).

If this parameter is set to false, then the Business Central Web Server attempts to connect to the configured Business Central Server service, regardless of whether that service is associated with an SPN.

For more information about SPNs, see Configure Delegation.

Default: false
SessionTimeout Specifies the maximum time that a connection between the Business Central Web Server and the Business Central Server can remain idle before the session is stopped.

In the Business Central Web Server, this setting determines how long an open Business Central page or report can remain inactive before it closes. For example, when the SessionTimeout is set to 20 minutes, if a user does not take any action on a page within 20 minutes, then the page closes and it is replaced with the following message: The page has expired and the content cannot be displayed.

The time span has the format [dd.]hh:mm:ss[.ff]:

- dd is the number of days
- hh is the number of hours
- mm is the number of minutes
- ss is the number of seconds
- ff is fractions of a second

Default value: 00:20:00
RequireSsl Specifies whether SSL (https) is required. If the value is set to true all cookies will be marked with a \u0027secure\u0027 attribute. If SSl is enable on the Web server, you should set this to true.

Values: true, false
Default value: false
ShowPageSearch Specifies whether to show the Tell me what you want to do icon in the Role Center. The Tell me what you want to do lets users find Business Central objects, such as pages, reports, and actions.

If you do not want to the Tell me what you want to do icon available in the Business Central Web Server, then set the parameter to false.

Default value: true
UnknownSpnHint Specifies whether to use a server principal name when establishing the connection between the Business Central Web Server server and Business Central Server. This setting is used to authenticate the Business Central Server, and it prevents the Business Central Web Server server from restarting when it connects to Business Central Server for the first time. You set values that are based on the value of the ServicePrincipalNameRequired key.

Value: The value has the following format.

(net.tcp://BCServer:Port/ServerInstance/Service)=NoSpn|SPN

- BCServer is the name of the computer that is running the Business Central Server.
- Port is the port number on which the Business Central Server is running.
- ServerInstance is the name of the Business Central Server instance.
- NoSpn|SPN specifies whether to use an SPN. If the ServicePrincipalNameRequired key is set to false, then set this value to NoSpn. If the ServicePrincipalNameRequired key is set to true, then set this value to Spn.

Default value: (net.tcp://localhost:7046/BC140/Service)=NoSpn

If you set this key to the incorrect value, then during startup, the Business Central Web Server will automatically determine a correct value. This will cause the Business Central Web Server to restart. Note: For most installations, you do not have to change this value. Unlike the Dynamics NAV Client connected to Business Central, this setting is not updated automatically. If you want to change the default value, then you must change it manually.
DnsIdentity Specifies the subject name or common name of the service certificate for Business Central Server.

This parameter is only relevant when the ClientServicesCredentialType is set to UserName, NavUserPassword, or AccessControlService, which requires that security certificates are used on the Business Central Web Server and Business Central Server to protect communication. Note: You can find the subject name by opening the certificate in the Certificates snap-in for Microsoft Management Console (MMC) on the computer that is running Business Central Web Server or Business Central Server.

For more information, see Authentication and User Credential Type.

Value: The subject name of the certificate.

Default value: none
AuthenticateServer Specifies whether to authenticate the server by enabling service identity checks on protocol between the Web server and the Business Central Server instance.

Values: true, false
Default value: true
HelpServer Specifies the name of the Business Central Help Server if the deployment uses Help Server. If the deployment uses an online library, remove this setting.

Default value: none
HelpServerPort Specifies the TCP port on the specified Business Central Help Server if the deployment uses Help Server. If the deployment uses an online library, remove this setting.

Default value: none
OfficeSuiteShellServiceClientTimeout Defines the time Business Central will wait for the Office Suite Shell Service to respond.

Important: This setting has been deprecated in Business Central, and it has no effect on the Web Server instance.

Default value: 10
UseAdditionalSearchTerms Specifies whether Tell me uses the additional search terms that are defined on pages and reports.

The additional search terms are specified by the AdditionalSearchTerms and AdditionalSearchTermsML properties.

If you set this to false the additional search terms are ignored.

Default value: true
DefaultRelativeHelpPath Specifies the default Help article to open if no other context-sensitive link is specified.

Default value: none
PersonalizationEnabled Specifies whether personalization is enabled in the Business Central Web client. Set to true to enable personalization.

For more information, see Managing Personalization.

ApplicationIdSettings element settings

Setting/KeyName Description
BaseHelpUrl Specifies the link to the online Help library that the deployment uses, such as https://mysite.com/{0}/mylibrary/.

Default value: none

For more information, see Configuring the Help Experience.
BlogLink Specifies the target of the blog link on the Help & Support page. Use this link to give users access to your end-user blog.

Value: a valid URL
Default value: https://go.microsoft.com/fwlink/?linkid=2076643|
ComingSoonLink Specifies the target of coming soon link on the Help & Support page. Use this link to give users access to information about your roadmap or any upcoming features and fixes.

Value: A valid URL.
Default value: https://go.microsoft.com/fwlink/?linkid=2047422
CommunityLink Specifies the URL to a community or resource for sharing information.

Value: a valid URL
Default value: http://go.microsoft.com/fwlink/?LinkId=287089|
ContactSalesLink Specifies the target of the contact sales link on the Help & Support page. Use this link to give users access to your sales-focused web page where users can engage with your sales process. Note This setting and link are not used for Business Central on-premises.
SigninHelpLink Specifies the URL to open if the user selects help on the sign in page box.

Value: a valid URL
Default value: none

See Also

Setting up Multiple Business Central Web Server Instances
Install Business Central Components
Business Central Web Server Overview
Configuring Business Central Server
Configuring the Help Experience