Sometimes it appears that the underlying stack of technologies used for an application is no longer appropriate for further software development and support. It may happen for a big variety of reasons: used technology is old and not supported anymore; legacy application doesn't meet new technical or customer requirements, that are hardly implementable using the old stack; or, finally, you have to support an application developed by a third-party company, but don't have enough experience and confidence in the used technology.
So, what if you got to the point when your legacy application should be migrated? We decided to provide a step by step guide and show how to modernize a legacy application with minimum efforts, taking the LightSwitch platform as an example, which has officially been abandoned by Microsoft. CUBA Studio comes along with its migration tool, which streamlines the migration process and makes it very straightforward and transparent. To demonstrate how it works in practice we moved the Vision Clinic LightSwitch sample application to CUBA Platform and described all steps on the official platform GitHub. Below you can see the old LightSwitch and new CUBA screenshots of the same screen, used in the Vision Clinic application.
So, if you are interested in modernizing a legacy application, you are welcome to evaluate the migration facilities of Studio by following the instructions, which we'll also dive into right now!
Migrating a Legacy App
We will use CUBA Studio — a specialized rapid application development tool for CUBA applications. Its built-in migration tool utilizes the well known reverse engineering approach. During the migration, meta-information extracted from the legacy application database will be used to complete the following steps automatically:
Generate a data model, mapped to the legacy DB.
Update the database to match the CUBA Platform requirements.
Generate standard CRUD UI.
As a result, most routine operations will be handled by CUBA Studio. However, business logic along with specific screens design will be transferred to the new application manually.
If you are interested only in the resulting application, scroll down to the How to Launch the Application without MSSQL section.
Legacy Application Overview
Let's have a short overview of the “victim” application we are going migrate. We have picked the official sample project for a fictional vision clinic published on the Microsoft website. The application is based on the Microsoft Lightswitch, which was officially abandoned by Microsoft a few months ago.
The sample is a standard three-tier application. It demonstrates the major features of LightSwitch: creating data model, screens scaffolding and calculated attributes in entities. The Vision Clinic example stores data in two different databases, linking data between them. For simplicity, we will merge the two databases with the application tables into one.
CUBA system tables will be created in the same database as well. As these changes will not affect the tables used by the LightSwitch application, the old LS app will retain the ability to run on the same database. Database schema
Note: It is also possible to attach a legacy database as an additional datastore to a CUBA application. Thus the legacy database will remain completely unmodified, CUBA-related tables will be stored separately.
Let's have a look at the user interface of the Lightswitch application, taking its most sophisticated screen, Products, as an example:
The application has a classic layout for enterprise software: the main menu of the application is on top of the main screen; screens are opened as tabs in the same window.
If you are curious about how to develop it yourself follow the guide or simply download it. However, we will only need its database. The database setup procedure is listed below in the corresponding section.
Looking ahead, let me announce the result we are going to achieve. We will create a fully functional Java based 3-tier application with a rich web client, that replicates the business logic and the user interface of the LightSwitch application. As it has already been mentioned, the application will not change the structure of the existing tables, so both CUBA and LightSwitch applications will be able to work simultaneously using the same database instance.
In the picture below you can see how the abovementioned Products screen will look in the CUBA application, so you can compare them:
Step 1: Environment Installation and Database Setup
Follow the Installation and Setup section of the CUBA Platform documentation.
Download and install MS SQL Server 2012+ from the official website. Skip this step if you already have it installed
Run the create-db.sql script on your MS SQL DB instance to create the VisionClinic database
Run the insert-data.sql script for the newly created VisionClinic database to fill it up with test data
Enable the SQL Server and Windows Authentication mode and sa user to login as it is shown here. Remember the password for sa, it will be used for connecting to the database from our CUBA application
Step 2: CUBA Project Setup
Launch the CUBA Studio server (1) and open Studio in the browser (2).
Create a new project (1), input vision-clinic as a project name (2) and press OK.
Open Project properties for editing to set up the connection to the VisionClinic database and fill the following fields:
Database type: Microsoft SQL Server 2012, or whatever you have installed (1).
Database URL: localhost, or domain name/IP of the machine with SQL Server installed (2).
Database name: visionclinic, which was created by executing the create-db.sql script in step 1, item 3 (3).
Database user and Database password: use your SQL server credentials for the sa, or your specific admin user (4).
Click Test connection (1) to check if Studio can reach the database. If you get the Connection successful (2) message, click OK (3) to save the changes Test connection
Step 3: Migration Tool: Data Model and CRUD UI Generation
In this section, we will generate a data model (entities) based on the database structure with a simple user interface for data manipulation.
Switch to the DATA MODEL tab and click the Generate model link.
CUBA Studio will ask you to update the database in order to create new tables required for the generic platform functionality, such as security management, audit, dynamic attributes and so on. Confirm the update.
Now the GENERATE MODEL FROM DATABASE window comes up. Here we will configure the mapping of the database tables and their columns to entities and their fields
Click the Settings button on the top panel to configure the global mapping options. In our example both frameworks track who and when created or updated records in the database, so map the predefined CUBA fields createTs, createdBy, updateTs, updatedBy to the corresponding system columns in the existing database, which exist in most tables: Created (1), CreatedBy (2), Modified (3), ModifiedBy (4). RowVersion (5) is another system column used by LightSwitch for optimistic locking. Unfortunately, it cannot be mapped to the version column, used by the platform for the same purpose, because the types of those fields do not match. We could add another field to support optimistic locking for the CUBA application, but as we have decided to avoid changing the structure of the existing tables, we will globally exclude this column from mapping. Click OK.
Click the Show tables button on the top panel to select tables that should be mapped to the entities in your application. Click the Select all button and remove sysdiagrams from the selection (1), as this table is a MS SQL service table, containing information about the database diagram, so it does not have any value for our application. Click Next (2):
At this stage, we can make a fine-grained mapping tune on the level of separate entities and their fields. For example, by a convention all entities in CUBA should be named in singular form, mainly because Studio auto-generates default strings used in the User Interface: for example in menu items and screen names. So, we will modify entities to be called in the singular form. Select the Appointments table, click the Edit mapping button, edit the class name: Appointment, and Click OK:
Repeat the previous action for the rest entities named in plural: InvoiceDetails, Invoices, and Patients.
Another thing we can adjust at this stage is Instance Name — this is a string representation of an entity (record), that will be displayed in UI, for example, in a table cell or a dropdown list. Select the Product table - click Edit mapping - select the ProductName field in the Instance name column combobox - OK Instance name
We will be able to modify everything later on, so no worries if we have forgotten anything or did anything wrong. Click Next.
At this stage we can automatically generate CRUD screens for the entities to be able to manipulate with data. Currently CUBA offers the following standard screen templates:
Browser is a screen for viewing a list of records from a database, it includes data filter and supports paging by default;
Editor is a screen for viewing or editing an individual record;
Browser and Editor just means that both screens will be generated;
Single screen embeds editor in a browser screen, so you see a list of records on the left and details of the selected record on the right.
Note: Studio will support custom screen templates since the new release coming in January 2017. It is also worth mentioning that you can modify any generated screen later in Studio and IDE.
Configure your screens in the following way and click Next Standard screens:
No update scripts have been generated for the existing tables, just as planned. Click Save to proceed and wait until the model and CRUD screens will be generated
From this stage we can already see the working application with auto-generated standard UI.
Step 4: First Launch
At this stage we already can launch the CUBA application. Click Run - Start application server in the main menu:
Use the Web client link in the bottom left corner of the Studio. The application will be opened in a new tab of your browser:
The default login and password is admin/admin, submit the credentials and open the application:
Screens we have created can be accessed from the Application menu on top of the app:
Open the Products screen to see how it looks with the default single screen layout:
Of course, it will take some time to transfer the business logic and adjust the user interface, but at this stage we already have the first version of a cross-platform web application, fully based on an open source stack.
Now you have the full freedom to enhance your application further. CUBA Platform doesn't restrict modifications of the generated source code and even the source code of the platform. You can also integrate any third-party technology existing in the vast Java universe.
For example, as you may see, the Product screen is missing the rebates, similar products tables and the product image. With CUBA Platform and Studio we can easily polish it up to look similarly to the original screen from the LightSwitch application.
The source code of the modified Product entity and the Product screen descriptor can be found in the GitHub project. Note that all the modifications of the entity declaration and the screen descriptor have been generated by the CUBA Studio visual designer.
CUBA Studio screen editor
All the hand-coded changes are documented in the screen controller. An example of the autocalculated attributes can also be found in the source code of the Product entity (see the Product#getCurrentPrice method).
How to Launch the Application without MSSQL
By default, when you clone the application from the GitHub repo, it is configured to use the lightweight HyperSQL Database. So, right after сlonning the application you can start it and the Studio will create the required database. However, the database will be empty, so will need to fill it up manually, using the application user interface.
If you would like to change the underlying database, CUBA Studio makes migration between different DBMS trivial: Open the Project Properties section, then Edit, pick the desired database type from the list. The studio will generate new scripts to create the database, so you can launch your application on the selected DB.
Feel free to explore the final version of the migrated application! We are also open for your feedback and ideas of how it can be improved; post your thoughts and questions on the support forum.