Upgrade MX to Digitise Apps

Whilst all new versions of our software are given extensive testing, every live environment is potentially different. It is therefore important that you test any existing Solutions with a new version in a test environment BEFORE you upgrade your live systems.

This topic provides information about upgrading existing versions of MX to the new Digitise Apps software and covers upgrading your App Server and development PCs. For details about upgrading MX Clients and Standalone Apps, see the additional topics listed at the end.

The Digitise Apps software is generally supplied as a download from our web site. Therefore, before you can upgrade to the latest version of Digitise Apps, you will need to download the latest version from the web site. You, or someone in your organisation, should have received an email, when the Software Licence was purchased or renewed, providing full details of how to download and unzip the software and giving details of your Software Licence.

Create a temporary folder on each machine (physical or virtual) on which you want to upgrade the software and copy the downloaded product zip file into this folder. Alternatively, create your temporary folder somewhere from which you can access and run the files from your other machines, e.g. on a network drive or USB stick. Unzip the file into the temporary folder, maintaining the original internal folder structure.

You will need to run the setup on each machine that currently runs a copy of the MX App Server software or MX development software that you want to upgrade. The remaining instructions will need to be repeated on each such machine.
Before you upgrade the software on a machine, stop the ndl-metascybe MX App Server service on that machine using the Windows Services applet.
Now run ndl-software_autorun.exe on that machine. You will find this in the root folder of the unzipped Product Download, and you can run it by double-clicking on it in Windows Explorer.

If you get a message asking if you want to allow the program to make changes to your computer, choose Yes.
- When installing Digitise Apps under Windows, if you experience problems during the install, you may need to run the setup as an administrator. Cancel the installation and then run ndl-software_autorun.exe again from the Product Download root folder by right-clicking on the file and choosing Run as administrator.
The Installation menu will load:
The Help items on the right of the menu provide links to this online help, which you might want to read before you perform the upgrade. The What's New link will take you to an overview of the new features in this release.

To upgrade the App Server or Developer software, choose Digitise Apps under Installs. This option allows you to install the full Digitise Apps software or choose which components you want to install and specify certain configuration settings, before installing your selected software.
The setup wizard will load.
A dialog box may appear telling you that you need to install one or more software packages which Digitise Apps requires in order to work, e.g. one or more Microsoft Visual C++ Redistributable packages.

Click on the Install button to install the listed components.

If, after the components have been installed, you are asked if you want to reboot now, click on Yes to perform the reboot – do not postpone it for later.

After the reboot, the install should automatically re-load and continue, but if not, you will need to reload the Installation menu and start the install again, as described above.
The Welcome screen will be displayed. Click Next > to continue.
The Licence Agreement is displayed. Read the licence terms and then select the radio button to accept the terms if you agree, and then click Next >.

If you don't agree with the Licence terms and don't wish to install the software, click Cancel instead to exit the setup.
When performing an upgrade, the setup should pick up your existing configuration settings and licence details for the remaining screens within the setup wizard, so you shouldn’t generally need to re-enter this information, unless you want to change anything.

The Customer Information screen should currently be displayed. Check that your name and organisation are filled in and click Next >.
A list of the Digitise Apps components will be displayed allowing you to choose which components you want to install.

For an App Server or development PC, we recommend you upgrade all the listed components.

You can tell whether a component was installed previously from the icon displayed to the left of the component in the list - the icon indicates an installed component and the icon indicates a component which wasn't installed. To change the status of a component, click on its icon to display a drop-down menu. Choose This feature will be installed on local hard drive. to add the component to the install or This feature will not be available. to remove it from the list of installed items. You can ignore the other options on the drop-down menu as they aren't relevant for Digitise Apps installations.

We recommend installing all components on an App Server or development PC. If you only select a sub-set of the components, the procedure is basically the same as described below but you will only be asked to enter information relevant to the components you selected and so you may not see all the setup screens described.

By default, the previous MX software was installed to:

32-bit Operating Systems:

C:\Program Files\ndl-metascybe\MX

64-bit Operating Systems:

C:\Program Files (x86)\ndl-metascybe\MX

but this folder could have been changed when the software was originally installed. You can see the current install folder displayed below the list of components and, unless you change it, the software will be upgraded and remain in this folder. If you want to install the new version to a different folder, choose the Change button to display the Change Current Destination Folder page. Browse for or enter your new location and then choose the OK button.

Click Next > to continue.
The Database Server screen appears.

This screen allows you to specify the instance of SQL Server to be used to hold your App Server Configuration Database, a name for the database and login credentials to access the database.

Generally we would recommend retaining the original database when you upgrade. You can specify a different database here if you want to but the data in your original database won't be moved over to the new one and would need to be moved manually after the upgrade, if you want to keep it.

By default, Digitise Apps connects to the SQL Server using a Microsoft OLE DB client, which requires the security protocols TLS 1.0 and TLS 1.1 to be enabled. If the machine running the SQL Server has these protocols disabled, either because the current machine's configuration is being changed or because you are moving to a different machine, which has them disabled, the install will not be able to connect to the SQL Server instance and make any changes required to the Configuration Database tables.

If you don’t know whether TLS 1.0 and 1.1 have been disabled or not, enter the connection details as you would if TLS 1.0 and 1.1 are not disabled (see below) and then click Next >. If the next page of the install displays, the install can connect to the SQL Server and TLS 1.0 and 1.1 are not disabled. If, on the other hand, you get an SSL Security error displayed, TLS 1.0 and 1.1 have been disabled – click OK to dismiss the message to return to the Data connection details page and then follow the instruction for TLS 1.0 and 1.1 disabled below.

TLS 1.0 and 1.1 have been Disabled

Leave the Database Server field blank (delete the contents if it has a value) and then click Next >. This will perform the upgrade without attempting to setup the Configuration Database. Once the install has completed, you will need to manually upgrade the Configuration Database and, if necessary, update the connection strings pointing App Manager and App Server to it. See Manually Create the App Server Configuration Database for more information. Please contact the NDL Helpdesk if you need assistance with this process.
TLS 1.0 and 1.1 have NOT been Disabled
The setup should have picked up your previous values and automatically populated the fields on this screen. If not, or you want to change the database, you will need to complete the required fields.

Specify the SQL Server instance to use to host the database in the Database Server field. Type the name of the SQL Server, select it from the drop-down list or browse for it using the Browse button.

The Database Catalog field specifies the name of the database. By default, MX used a database called ndlmetamx and we recommended using that name but you could change the name if you wanted to. We recommend using the same name for your Digitise Apps software, so if you are not sure what name the previous software used, try specifying ndlmetamx in the Database Catalog field.

Under Connect using: you specify the login authentication method you want App Server to use when connecting to the SQL Server - select Windows authentication ... to use the current user’s Windows credentials, i.e. the user under which you are installing Digitise Apps, or Server authentication ... to enter a specific SQL Server username and password to be used ("SQL authentication"). In either case, remember that the user you specify MUST have SQL administrator rights to the database.
- If you choose to use SQL authentication, be aware that the username and password you specify are included in the connection string, in plain unencrypted text. You will also need to configure your SQL Server to allow SQL authentication.
  
  If you choose to use Windows authentication to log in to a SQL Server which is running on a separate PC to your App Server, be aware that because the App Server runs under the System Account, the account has no username/password with which to be authenticated. Therefore, if your SQL Server is running on a separate machine to that on which you are installing the App Server, you will need to configure your SQL Server to specify the machine name of the server running your App Server as the SQL login.
  If you want to use Windows authentication to access a SQL Server which is running on the same PC as your App Server, you will need to configure the relevant permissions within SQL Server for the System Account.
  
  For more information about configuring SQL Server in both these cases, see the Frequently Asked Questions (FAQs) page.
Click Next > to continue.
The Licence screen is displayed.

Your existing licence details should be displayed.

Click Next >.
The Ready to Install screen appears. You can alter any of your choices by choosing the < Back button until you reach the appropriate screen and then continuing back through the installation wizard as before, re-entering any options you want to change.
When you are ready, click on the Install button to install the software.
When the installation is complete, click on the Finish button to end the install.
To close the Installation menu, click on the Close button in the Title bar, .
If you are upgrading a development machine and you will want to send data to or retrieve data from remote Web API data sources, you will need to install the Connect Wizard Extension before you will be able to add a Web API as a Data Source within a Digitise app. The wizard is available from the same Product Download page on our web site as the Digitise Apps software. To install the Extension:
1. Download the Extension zip file and copy it to the same temporary folder as you used for the Digitise Apps software. Unzip the file and then load the setup, for example, by double-clicking on the file ConnectWizardExtensionSetup.exe in Windows File Explorer.
2. The setup will load and display the Software Licence page. Read the licence terms and then select the check box to accept the terms if you agree.
3. If you want to specify the install folder to be used for the Extension software, or check which folder is used by default, choose the Options button. You can then enter the full path of the folder you want to use in the Install location field or use the Browse button to locate and select the required folder. If you type in the path the folder must already exist. If you use the Browse button, you can create the folder if you need to.
  
  Click on the OK button to retain any changes, close the Setup Options page and return to the Software Licence page or click Cancel to abandon any changes.
4. Click Install to install the software or Close to exit without installing the software.
5. If you choose Install, click on the Yes button in response to the UAC message displayed asking you if you want to allow the setup to make changes to your computer.
6. The software will be installed and then a message will be displayed saying the install was successful. Click on the Close button to end the install.
  - If you don't have the Connect Wizard Extension installed and you attempt to create a new Web API Data Source within App Studio, the following error will be displayed:

After upgrading to Digitise Apps, the App Server service will have changed from being called ndl-metascybe MX App Server in the Services applet to NDL Digitise App Server.