Configure App Server Configuration Database & App Manager Connection Strings

An App Server Configuration Database is a SQL Server database used to store configuration settings for an App Server and also to store information about apps which have been registered with the server, diagnostic and audit logs, usage statistics etc.

These configuration settings, app data, logs and usage statistics can be viewed and, where appropriate, edited and updated in the Configuration Database using App Manager. App Manager doesn't connect to an App Server; it only reads and updates the settings etc. stored in an App Server Configuration Database. An App Server reads its designated Configuration Database at regular intervals to pick up any changes you make and uses the specified database to record its app data, logs and usage statistics.

In order for App Manager and App Server to access the Configuration Database you want them to use, you need to supply the connection strings for your chosen database for each one.

The Configuration Database is normally created when you install Digitise Apps. By default, it is called ndlmetamx and is stored in an instance of SQL Server that you specify within the install wizard. In some circumstances, the install isn't able to create the database, e.g. because the SQL Server hasn't been installed yet or the machine running the SQL Server has the security protocols TLS 1.0 and 1.1 disabled, in which case you will need to create the database manually after the install has finished.

The settings which specify the connection details for the Configuration Database can be viewed and edited within App Manager, under the App Manager Configuration Options. There are separate options for App Manager and App Server - the Manager and Server options, respectively. If the install creates the database for you, both these options will automatically be set to use this database. If you have to manually create the database or you want to change the database in use, you will need to edit these options to specify the relevant connection details for the required database, which you can do at any time.

The options can be edited separately, which means you can change the database being used for one without having to change it for both at the same time.

For App Manager, you can specify a database located on the same machine as App Manager or on a remote machine elsewhere, providing App Manager can connect to the specified machine over a suitable network connection. This allows you to use a single copy of App Manager to view and edit multiple App Server Configuration Databases, if required. The database currently specified in the Manager option, is the database whose values you can view and edit in this copy of App Manager. If you want to see and change the settings etc. in another Configuration Database, you can simply change the database connection details for those of the new database.

For App Server, if you want to specify or change the Configuration Database to be used, you must run App Manager on the same machine as the App Server you want to configure; you cannot modify this option remotely. This is because App Manager stores the connection string locally on the machine it is running on and an App Server will look for its Configuration Database connection string locally as well. The value entered in the Server option tells the App Server which database has been designated for it to use as its Configuration Database. The value stored in the option must be the ADO database connection string required to connect to the relevant database. App Server will extract its configuration settings from this database and store information in it about its registered apps, diagnostic and audit logs, usage statistics etc.

 

To view or change the Configuration Database settings:

  1. If you want to edit the Server option, i.e. to set or change the connection string for an App Server, App Manager must be running in administrator mode. You can do this by right-clicking on the app in the start menu:

    Picture showing the Windows Start button. → NDL Software Digitise Apps → App Manager

    and choosing More → Run as administrator.

    If you forget to do this, and you change the Server option, App Manager will ask you if you want it to restart with elevated privileges. Click Continue to restart App Manager and update the Server setting's value.

    If you won't be changing this option, you can run App Manager without administrator privileges in the normal way, e.g. by choosing:

    Picture showing the Windows Start button. → NDL Software Digitise Apps → App Manager

    or using a desktop shortcut or app tile.

    Remember also, if you want to change the Server option, you must run App Manager on the same machine as the App Server you want the change to apply to.

    For anything else, as long as you won't be changing the Server option, it doesn't matter where you run App Manager relative to the App Server, as long as the App Manager can communicate with the Configuration Database, and you don't need to run App Manager as an administrator.

    In all cases, the SQL Server instance holding the Configuration Database can be on the same or a different machine than the App Manager and/or App Server.

  2. Click on File, in the top left-hand corner of the window.

  3. Choose Options… from the drop-down menu.

  4. The Database section of the Options dialog box includes two options:

    Manager

    Specifies the SQL connection string for App Manager to retrieve, display and update the values stored in an App Server Configuration Database.

    If this option is blank, you will need to specify the connection string required to connect to the Configuration Database containing the configuration settings and other data that you want to view and manage in this copy of App Manager.

    If this option contains a connection string, you can change the Configuration Database whose data can be accessed and modified by changing the connection string specified here to that required to connect to the new Configuration Database.

     

    Server

    Specifies the SQL connection string of the Configuration Database you want to the App Server running on this machine to use. The App Server will retrieve configuration settings stored in the specified database and use the database to record information about apps registered with the server, logging messages and usage statistics.

    Remember, in order to change this option, you must be running App Manager on the same server as the App Server whose Configuration Database you want to set or change, you cannot modify this option remotely.

     

  5. You will need to enter the connection string in both options. Use the Browse button, Picture showing the Browse button, to the right of each option to load the Data Link Properties dialog box and specify the required connection details. The user you specify to access the SQL database only needs to have read and write permissions; you don’t need a SQL administrator user once the database has been created.

    By default, App Manager connects to the App Server Configuration Database using a Microsoft OLE DB client. If the Configuration Database is hosted by an instance of SQL Server running on a machine which has the TLS 1.0 and 1.1 security protocols DISABLED, you will either need to update the OLE DB driver for SQL Server to the latest version, which supports TLS 1.2, or connect using a SQL Server Native Client driver instead. The choice is yours – contact your database administrator for advice.

    If you don’t know whether TLS 1.0 and 1.1 have been disabled or not, try using the default Microsoft OLE DB client first (see below) and if you are able to connect to the database, the TLS protocols are enabled and you can continue to use this driver. If, on the other hand, at any point you get SSL Security errors or cannot connect to the Configuration Database, the TLS protocols may be disabled and you should try using the updated OLE DB driver or SQL Server Native Client driver instead.

    If you decide to update the OLE DB driver, you will need to update it on any machines which will run the App Manager and/or App Server and which will connect to an instance of SQL Server running on a machine with TLS 1.0 and 1.1 disabled. At the time of writing, you can download the update, Microsoft OLE DB Driver 18 for SQL Server, from Microsoft’s web site:

     

    https://www.microsoft.com/en-us/download/details.aspx?id=56730

     

    After downloading the installer, you simply run it and select to install the ODBC Driver Client Components.

    • If you choose to update the OLE DB driver here, you will also need to update it on your development PCs, if you want to access the same database from these machines.

    If you decide to use the SQL Server Native Client instead, at the time of writing, you can download the latest version from Microsoft’s web site, if you need it:

     

    https://www.microsoft.com/en-us/download/details.aspx?id=50402

     

    Whichever driver you choose to use, if at any point during configuring the connection string you get an error message something like this:

    Picture showing Microsoft Data Link Error indicating problem with database driver.

    you will need to re-install the driver. You may need to uninstall the existing driver before reinstalling it.

    To specify the connection string:

    1. If you know the required connection string you can type it directly into the Manager and Server edit boxes.

      Alternatively, click on the Picture showing the Browse Button. button at the end of the Manager option to display the Data Link Properties dialog and enter the connection details for the App Manager to connect to the App Server Configuration Database using this dialog:

      Picture showing the Data Link Properties Dialog Box.

    2. If the machine on which you are running the SQL Server has TLS 1.0 and TLS 1.1 security protocols enabled, under the Provider tab select Microsoft OLE DB Provider for SQL Server.

      Where TLS 1.0 and 1.1 have been disabled, and you have upgraded the OLE DB driver, you should select Microsoft OLE DB Driver for SQL Server under the Provider tab.

      Alternatively, where TLS 1.0 and 1.1 have been disabled and you want to use the SQL Server Native Client, you can select SQL Server Native Client 11.0 under the Provider tab and use this provider instead of the OLE DB Driver.

      If you don’t know whether TLS 1.0 and 1.1 have been disabled or not, try using the Microsoft OLE DB Provider for SQL Server first and if you get SSL Security errors or cannot connect to the Configuration Database, either download the later OLE DB driver and reconfigure the connection string to use this driver or reconfigure the connection string to use the SQL Server Native Client 11.0 instead.

      • If your SQL Server is configured to use an availability group, for example, for backup/failover purposes, you should select Microsoft OLE DB Driver for SQL Server here. This will allow you to specify relevant initialisation properties under the All tab, if required.

    3. Once you have selected a Provider, click Picture showing the Next Button. or click on the Connection tab.

    4. The options available on the Connection tab vary depending upon the driver selected on the Provider tab:

      Picture showing the Data Link Properties dialog illustrating connection string options for SQL Server OLE DB Provider driver.

      In 1. type in the name of the relevant SQL Server instance or select it from the drop-down list.

      In 2. select the appropriate option depending upon whether you need to use Windows Authentication or SQL Authentication to log in to the Configuration Database. If you choose SQL Authentication (Use a specific user name and password), enter the required username and password and then make sure you select Allow saving password, otherwise you may not be able to connect to the database.

      In 3. enter the name of the database being used to store the App Server configuration and tracing data or select it from the drop-down list. The default name for the App Server Configuration Database is ndlmetamx.

      You may need to check the Advanced and All tabs to see whether you need to configure any of the options here - ask your SQL administrator for guidance, if you're not sure.

      Clicking on Picture showing the Test Connection Button. will attempt to connect to your specified SQL Server instance and if the connection attempt is successful this means that you have specified a valid authorisation method and credentials. It doesn’t connect to the actual database nor verify that you have entered the correct database name. If the wizard is able to connect to your database server, a message confirming that the test was successful will appear. Otherwise, if you get an error message you will need to look back over the details you entered and edit them before you try again.

      Click on OK to finish. Skip to step 6.

       

      Picture showing the Data Link Properties dialog illustrating connection string options for SQL Server OLE DB Driver.

      In 1. type in the name of the relevant SQL Server instance or select it from the drop-down list. If your SQL Server is configured to use an availability group, enter the Availability Group's DNS name here.

      In 2. select the appropriate option depending upon whether you need to use Windows Authentication or SQL Authentication to log in to the Configuration Database.

      If you choose Windows Authentication, you can enter a Server SPN, and select Use strong encryption for data and/or Trust server certificate if required. Your SQL Server administrator should be able to tell you which of these options you need.

      If you choose SQL Server Authentication, enter the required username and password and then make sure you select Allow saving password, otherwise you may not be able to connect to the database. If Blank Password is selected, click on it to deselect it before you enter your password. Your SQL Server administrator should be able to tell you whether you need to select either or both of the Use strong encryption for data and Trust server certificate options.

      In 3. make sure Select the database: is selected and then enter the name of the Configuration Database or select it from the drop-down list. The default name for the Configuration Database is ndlmetamx.

      You may need to check the Advanced and All tabs to see whether you need to configure any of the options here - ask your SQL administrator for guidance, if you're not sure.

      Clicking on Picture showing the Test Connection Button. will attempt to connect to your specified SQL Server instance and if the connection attempt is successful this means that you have specified a valid authorisation method and credentials. It doesn’t connect to the actual database nor verify that you have entered the correct database name. If the wizard is able to connect to your database server, a message confirming that the test was successful will appear. Otherwise, if you get an error message you will need to look back over the details you entered and edit them before you try again.

      Click on OK to finish. Skip to step 6.

       

    5. Picture showing the Data Link Properties dialog box illustrating connection string options available for SQL Server Native Client driver.

      In 1. type in the name of the relevant SQL Server instance or select it from the drop-down list.

      In 2. select the appropriate option depending upon whether you need to use Windows Authentication or SQL Authentication to log in to the App Server Configuration Database.

      If you choose Windows Authentication, enter the Server SPN if needed.

      If you choose SQL Authentication (Use a specific user name and password), enter the required user name, deselect the Blank password option and then enter the password. Select Allow saving password.

      In 3. select Select the database and then enter the name of the database being used to store the App Server configuration and tracing data or select it from the drop-down list. The default name for the Configuration Database is ndlmetamx.

      Next, click on the All tab and then find and double-click on the Persist Security Info option. Click on Picture showing the Reset Value Button. and then set the Property Value option to True. Click on the OK button and then click back on the Connection tab.

      Clicking on Picture showing the Test Connection Button. will attempt to connect to your specified SQL Server instance and if the connection attempt is successful this means that you have specified a valid authorisation method and credentials. It doesn’t connect to the actual database nor verify that you have entered the correct database name. If the wizard is able to connect to your database server, a message confirming that the test was successful will appear. Otherwise, if you get an error message you will need to look back over the details you entered and edit them before you try again.

      Click on OK to finish.

       

  1. Click on OK to close the Options dialog.

  2. If you have entered or changed the Configuration Database used by the App Server, you will need to restart the NDL Digitise App Server service in the Windows Services applet to make the change take effect. If you have only specified the Configuration Database to be accessed by an App Manager, you don't need to restart this service; the change will take effect immediately if App Manager is already connected to a database or the next time you connect App Manager to the Configuration Database.