Eclipse Scout: Migration Guide

Clone the following git repository and import it into an empty eclipse workspace: https://github.com/bsi-software/scout-10-migration-template. The workspace and git repository are only necessary temporarily and can be deleted again after the migration.

The migration app requires at least Java 8. Also make sure the migration project uses the same encoding as your source code files (a regular scout project uses UTF-8 by default). If you use a different encoding, adjust the property in the pom.xml and press Alt+F5 to reimport the changes:

  <properties>
    <maven.compiler.target>1.8</maven.compiler.target>
    <maven.compiler.source>1.8</maven.compiler.source>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>

The migration requires api files to properly generate the import statements. The api files for Scout are already placed in the folder api of the project. If your JavaScript code depends on other libraries built with Scout and not only org.eclipse.scout.rt.ui.html, then you need to include the api files from these libraries as well.

Adjust the methods in the Config class to configure the migration application to your local setup. Make sure to read the JavaDoc to understand what exactly you need to configure.

The migration application has some prerequisites that the code can be migrated. Ensure that these are met before launching:

If the above conditions are fulfilled the migration can be started using the launch config migrate.launch.

The migration is executed in two steps (which will result in two separate VCS commits):

Having two steps is necessary to preserve the VCS history. When the first step is finished, the migration app asks you to commit the changes and confirm. Do NOT commit and confirm yet.

Have a look at the output. If there is an error you should revise your configuration (maybe you didn’t copy all api files?) and your code (did you extract all JS classes into a separate file?, etc.). To fix the errors abort the migration, reset all files (e.g. use git reset --hard), fix the configuration and run the migration again.

If there are no errors anymore have a look at the the migrated files. You will notice that the files are not properly formatted yet. You can do it now, if you like to have a clean git history, or do it later after the migration.

If you are pleased with the files commit them. Make sure all files are committed.

Now it is time to proceed with the second step. Confirm the message.

The migrated files are now moved to theirs new location. When it’s done, commit all the files.

Please do the Automatic Migration first even if you don’t have any JS or CSS files in your project because it will also migrate your HTML files (e.g. index.html etc.).

In the pom.xml of your parent project change the version of the parent maven_rt_plugin_config-master to 3.12.7. Ensure that the values of all relativePath attributes in the parent group do not end with pom.xml. Additionally, update your Scout dependencies to the most recent Scout 10 version.

If you use Git, create a file (or open the existing one) named .gitignore in the .ui module and the .app module (if available) and add the following content:

node_modules
dist
test-results

If you only have a .ui module without an .app module (typical Scout Classic app), follow these steps. Otherwise skip this section and continue with the next step.

If you have a separate .app module you should have skipped the previous step. Instead do the following steps.

Copy the following file to the directory src/test/js of the .ui module: test-index.js

The migrator should have renamed yourapp-module.js to index.js, yourapp-module.less to index.less and migrated theirs contents. Check these files for TODOS and resolve them, maybe you need to adjust an import. Also, if you have multiple themes, there should be an additional index file for each theme (e.g. index-dark.less). Check these files too.

The migrator should also have renamed yourapp-macro.js to yourapp.js, yourapp-macro.less to yourapp-theme.less and moved them to the src folder. The former index.js is now included into yourapp.js. There should be a theme file for each theme (e.g. yourapp-theme-dark.less). If not, create them manually. Make sure that the theme files properly import the according index files (e.g. yourapp-theme-dark.less should include index-dark.less files if available).

Open your app file (the one that contains something like new App().init, e.g. src/main/js/yourapp.js) and remove the modelsUrl, if present.

Check your html files. The migrator should have removed obsolete style and script tags and added references to yourapp.js and yourapp-theme.js. If you had multiple custom *-macro.js or *-macro.less files there may still be references to an old *-macro.less file → Use the new matching *-theme.css file instead or maybe merge it with the regular yourapp-theme.css file.

If you have other html files than the migrated index.html, login.html etc. migrate them manually in the same way index.html has been migrated (adjust script, style and include tags).

Move all files and folders in src/main/resources/WebContent/res one folder up directly into WebContent and delete the empty res folder.

Search for all occurrences of /res within the .ui and .app modules and remove the res folder.

In the file src/main/webapp/WEB-INF/web.xml files of the .ui.html.app.dev and .ui.html.app.war modules change the filter-exclude list of the AuthFilter declaration to the following and replace ${simpleArtifactName} with your application name (if your application uses the Scout LoginApp). The AuthFilter may also be called UiServletFilter or YourAppNameUiServletFilter.

/favicon/*
/fonts/*
/logo.png
/jquery*.js
/login*.js
/logout*.js
/${simpleArtifactName}-theme*.css
/eclipse-scout*.js

If you have a Repository.js change the global object holding the repositories from ${yourAppNamespace}.repositories = {}; to static repositories = {}; and change all references in this file from ${yourAppNamespace}.repositories to Repository.repositories.

If you have Jasmine specs, follow these steps. Otherwise you can skip it and continue with the next step.

If your .ui and .app modules are separated, in the pom.xml of the .ui module add the .following properties:

Remove the following properties from all your config.properties files: scout.ui.prebuild, scout.ui.prebuild.files, scout.dev.scriptfile.rebuild, scout.dev.scriptfile.persist.key.

If you use pnpm, create a file called pnpm-workspace.yaml in the parent folder of your modules (which is most likely the root of your git repository) and include your npm modules (.ui, .app).

Open a terminal in the folder of the .ui module and run the command npm install (or pnpm install, if you use pnpm). This installs all dependencies that are required by the .ui module.

Open a terminal in the folder of the .app module and run the command npm install (or pnpm install, if you use pnpm). This installs all dependencies that are required by the .app module (including the .ui module of your project).

In the terminal of the .app module run the following command: npm run build:dev. This triggers the transpiler that creates the JavaScript build output in the dist folder of the .app module. Only after this command has been executed the server can find the web resources to deliver them to the browser.

If there are any build errors, fix them manually. The migration application might not fix every possible code correctly.

In the terminal of the .ui module run the following command: npm run testserver:start. This executes the Jasmine Specs in a Chrome browser (Chrome must be installed locally, the same applies to ChromeHeadless if running the build in a CI environment, see Build / Continuous Integration).

Now it is time to start your app!
Since you already ran npm run build:dev all the required JS and CSS files should be created and you can start the UI server using your existing launch file. If you now use IntelliJ you need to create a run configuration that uses JettyServer as main class (have a look at your Eclipse launch file for details).

If you like, you can create a launch group that start the JS build and the UI server together. Have a look at the Scout archetype for an example (the new Scout Project wizard in Eclipse uses the archetype).

Test all your html files (index.html, login.html, logout.html etc.) and all your themes (dark, custom). If everything looks fine, you are done. If not, have a look at the Troubleshooting section.

After starting the server the page in the browser stays blank.
This most likely happens when your created bundles don’t match the bundles required by the HTML files. Check the Network tab in your browser’s DevTools. Which files are being loaded? Are there 404 requests? Check your dist folder. What files are there? To fix it, adjust your HTML files or the entrypoints and chunks in webpack.config.js.

I am not sure if I missed something.
You can always create a new Scout app based on the arche type and compare it with your code. The easiest way is to use Eclipse and create a new Scout Project. Make sure you choose the correct application type (Java for Scout Classic apps, JavaScript for Scout JS apps).

I don’t understand why I had to do this and what it is for.
Have a look at the Build Stack chapter in the Technical Guide.

I did everything you said but it still does not work.
Ask at Stack Overflow or the Forum, we are happy to help you out.

Node is installed automatically during maven build when the module contains a package.json. So there is no need to install node on the build server. Nothing to do here for you.

To run JavaScript specs Scout now uses ChromeHeadless instead of PhantomJS. If you have JS specs you need to make sure there is a Chrome installed on your build server. The following installation guide worked for our linux servers: https://gist.github.com/ipepe/94389528e2263486e53645fa0e65578b#gistcomment-2379515.

In order to display the test results you need to add the new test-results dir in your job configuration (e.g. */test-results/*/test-*.xml)

You only have to do this step if you want to share your npm packages between different applications.
If you want to deploy npm artifacts to a custom npm repository (e.g. Artifactory), you need to add .npmrc file to the home directory of your build user on the build server (similar to the .settings.xml of maven). In order to deploy the artifacts you can use the official npm cli interface (npm publish). If you want to publish snapshots you can use the following command.

cd your.app.ui
./target/node/node ./target/node/node_modules/npm/bin/npm-cli.js publish --tag=snapshot