After upgrading Step to a new version, some additional tasks may be required.

General migration process

Before starting the migration

• Stop existing controller and agents
• Stop the related services if they were installed as such or terminate directly the corresponding Java processes otherwise.
• Backup
• Database: before any migration task, make sure to backup your database following this instructions.
• Controller: if you intend to reuse the same data folders of the step’s controller, we recommend to backup them as well. By default all of these folders are located under <CONTROLLER_DIR>/data, but you may have changed the related settings in step.properties.

Migration

Database migration

• Reusing the same database: in a typical case you will start the new version of the controller on the same database, migration are performed automatically. You should still read the sections at the bottom of this page for release specific migration tasks.
• Using a copy of the database: in case you’d like to keep your older database, and run a copy alongside the older one, you’ll have to:
• Start a new mongo instance using a different port (Using the option –port PORT_NUMBER, refer to mongo official documentation for more details)
• Import the data to the new mongo instance following this instructions
• Update the configuration of your new controller to connect to it.

Controller migration

• Installation of the new version: refer to the following page to install the Step Controller.
• Reapply your customized configuration: you will have to migrate the configurations entries from the old configurations files to the new ones (refer to the following page) for more details about the Step Controller configuration).
• Reimport your controller data and ressources:
  • if you’re using customized data folders and want to reuse the same folder, you are done (given that you did Reapply your customized configuration)
  • if you’re using the default data folders under <CONTROLLER_DIR>/data you will have to copy its content from the old to the new installation. Following are the main folders that you could only partially migrate depending on your needs:
    • resources
      • datasource: contains datasources files uploaded through the UI (i.e. CSV files for datasets…)
      • functions: contains jar, dll of keyword when loaded through the UI
    • scripts: contains keywords scripts files (for groovy, oryon…)
    • image_compare: contains image compare scenario/masks definition
    • pdftest: contains pdf compare scenario/masks definition

Agents migration

• Installation: refer to the following page to install a Step Agent.
• Reapply your customized configuration: migrate the configurations entries from the old configurations files to the new ones (refer to the following page for more details about the Step Agents configuration).

Keywords migration process

There is no migration task required for the keywords when upgrading step. Below describe the process whenever you want to upgrade the keyword to a newer version of the Step keyword api.

Re-compilation

In order for your keyword to use a newer version of the Step Api, you will have to recompile them.

• For Java, you can change the version of Step specified in your pom.xml
• For .NET, follow below steps :

  • Remove the dependencies of Newtonsoft.Json, ScriptDev and ScriptApi from your Visual Studio project

    

  • You will find the new version of these 3 DLLs in the bin folder of the new agent. You need to add them back to your Visual Studio project.

  • Rebuild your project and make sure the Keyword DLL is generated properly.

  • Go to next section “Re-deployment”

Re-deployment

Once your keyword have been recompiled, if the keyword location has changed you will have to update it using Step GUI :

• Click on the Keywords tab, search your keyword and click on the Configure button :

• Update the keyword path and press the Save button

Validation

Once you recompiled and redeployed your Keywords, we highly advise you to run a Smoke Test in order to make sure the migration completed successfully.

Release specific

3.18.x/3.19.x to 20.x

For most users there is not manual migrations tasks to be performed. Only specific customization will require manual updates

Groovy dynamic expressions

Groovy libraries and engine were upgraded to support java 17 from groovy 2.x to 3.x. While the majority of your dynamic expressions will remain compatible, we cannot exclude that some very specific custom code needs few adaptations. For instance follow type of code changes may be required:

- array declaration = ['a','b'] are not compiling, they have to be replaced by new String[] {'foo','bar'};
- the method *JsonStringImpl.toString* should be replaced by *JsonStringImpl.getString* to retrieve a valid Json string (for instance when used with a *JsonSlurper* object)

User defined screen inputs with custom HTML

Screen inputs with custom HTML are not supported since Step 20. A predefined set of UI components can however be used and could be extended via plugins; The screen input attributes is now named “Value Cell Renders”. For more information check Customization: Value Cell Renderers

Self developed plugins

The custom plugins that you developed will need to be updated and recompiled to be compatible with Step 20. The main reasons for this are the refactoring done to support Java 17 and migrate to Angular 2+. Below are the main points to consider:

- Migration from *javax* to *jakarta* packages and internal package refactoring
- Methods of the abstract class "AbstractControllerPlugin" were renamed
- AbstractControllerPlugin.registerWebapp method has been removed and is not required anymore. Your must however make sure that web resources (HTML and javascript files) are available under the path *resources/webapp*
- ExportTasksManager has been refactored to AsyncTaskManager, see example in [github for Table services](https://github.com/exense/step/blob/master/step-controller/step-controller-base-plugins/src/main/java/step/plugins/table/TableService.java)

3.17.x to 3.18.x

There is no manual migration tasks to be performed, but please read out the following 2 sections.

Keywords changes

• Keyword packages: before the release 3.18 it was possible to modify the configuration of single keywords deployed with a keyword package in a Step instance and to update the underlying package keeping the local modified configuration. From now on, the keyword package is enforced as the leading keyword management system, updating the package will overwrite any local changes.
• Keyword resolution: starting with 3.18, the keywords are referenced and resolved by attributes (name, project, custom attributes) instead of IDs. All migrations are done automatically when first starting the 3.18 version of the Step controller. Keep in mind, that keywords must stay uniquely identifiable, in case of multiple matches, the first match will be chosen.

Project management changes

For the enterprise edition, the use of projects is now enforced meaning that it is not possible to deactivate the multitenancy plugin or to create entities outside the scope of a specific project. In case you were not yet using projects with the previous Step version, a notification will be displayed on the GUI if any unassigned entities are detected. Following the easy wizard you will be able to assign them to either an existing project or to a new one.

3.15.x to 3.16.x

System requirements

Starting with the version 3.16, Step’s controller and agent require Java version 11, so make sure to update the version installed on your systems accordingly.

Browser Support

The support of internet explorer has been dropped.

Agent configuration

For this release, the agent configuration was migrated to the YAML format. The older json format is still supported, you can change the configuration file used in the agent start script.

3.13.x to 3.14.x

There is no manual migration tasks to be performed, but please read out the following 2 sections.

All Step editions

-> how to back up my data

Activation script evaluator changed from nashorn (javascript) to groovy

Nashorn engine used to evaluate Javascript expressions and execute javascript (but not nodejs) keywords is deprecated starting with Step 3.14. Support of nashorn will be removed in a future release of step, in 3.14:

• The engine used to evaluate the “Activation script” of parameters and screen templates has changed to groovy
  • For now you may still revert to nashorn if required by changing the following property in ‘step.properties’ and restarting the controller: tec.activator.scriptEngine=nashorn
• Likewise keywords of type script and using javascript as language are deprecated

3.12.x to 3.13.x

All Step editions

-> how to back up my data

Artefacts collection migration

The artefacts collection will be migrated automatically during the first startup of 3.13.X controller to a new one called “plans”.

This migration is performed in order to use a more efficient data model for the Step plans (each plan is now a unique collection entry containing all its children, where in the past the plans children were stored as distinct entries and referenced by their respective parent entry).

API backward compatibility

• Although a new version of the keyword API has been released, backward compatibility is guaranteed and you don’t have to update dependencies.
• REST paths have been modified and as a consequence, any custom integration work done at HTTP level might break, we encourage users affected by this problem to either migrate to our java-based STEPClient tool or contact us if they wish to maintain their custom integration code.
• Other APIs remain unaffected

3.11.x to 3.12.x

All Step editions

Keyword API

Although backward compatibility has been preserved with step-api “1.0.0”, users wanting to benefit from the new annotation-based features released with Step 3.12.0 will have to migrate their keyword’s dependencies to step-api “1.1.0”.

Scheduler Task

A new column used to fix the search filter has been added to the list in the Scheduler view. Existing tasks won’t have a name but recreating these tasks (or any new task) will properly populate the name field, allowing for searches.

Enterprise edition

License file

The step-enterprise license called “license.step” file needs to be manually renamed to “step-enterprise.license”.

Project management

Upon starting the controller in 3.12.0, all existing projects will be displayed under the “Global” project. For users migrating from 3.11.X, we recommend either deleting or migrating the existing housekeeping Plan, Keywords and Scheduler Task manually, so that the new executions can take place under the “system” project.

Users who do not wish to create custom projects can just work directly in the “Global” project.

In order to assign existing assets to custom projects, just use the migration workflow described in the documentation of the Project Management plugin.

Function packages

For clients wishing to use Keyword Packages with paths in conjunction with multi-versioning, we’ve documented the recommended approach here.

3.10.x to 3.11.x

Keyword API

Starting from v3.11.0 and onwards, the keyword API dependency has been decoupled from Step itself (including the controller packages). This will allow users to upgrade their Step instances without necessarily updating the API dependency in their keyword projects, unless they wish to benefit from new feature or when compatibility is broken.

In this early stage, the compatibility matrix is simple: Step 3.11 is compatible with step-api “1.0.0” and compatibility with older API versions has been broken to enable this change. By default, backward compatibilty will be guaranteed in the future. If backward compatibilty is broken, the release notes or migration guidelines of the corresponding release will indicate so.

Selenium Keyword Type

Selenium now has to be deployed via uber jar or as an explicit keyword dependency. The Selenium keyword type is not supported anymore as users tend to prefer to manage their dependency version personally. It also avoids confusion and mismatches between a project’s dependency and the platform’s library version.

.NET

If you’re planning on using the Keyword Package functionality, a new FunctionDiscovery service will be used. This service relyies on a new port (8099) which needs to be opened on the controller using the following command:

netsh http add urlacl url=http://+:8099/ sddl=D:(A;;GX;;;S-1-1-0)

The following points have to be taken in consideration when upgrading the API:

• .NET Framework version >= 4.6 is required
• .NET naming standards have been enforced: most API methods now start with a capital letter
• ScriptRunner has been renamed to KeywordRunner and ExecutionContext is now to be retrieved from the static method KeywordRunner.GetExecutionContext
• AttachmentBuilder has been renamed to AttachmentHelper
• New NuGet packages are provided and need to be added to the keyword project(s):

3.9.x to 3.10.x

• The attachments (saved in the folder configured with the property ‘attachmentdir’ until 3.9.x) are now managed by the new ResourceManager and will be saved in the resource directory (configured with the property ‘resources.dir’).
• Remote-Client API: The class step.client.ControllerClient of the remote API has been renamed step.client.StepClient. This should be changed accordingly in the code using this API. If you don’t use the Remote-Client API, you’re not concerned by this change.

3.8.x to 3.9.x

• The configuration file ScreenTemplates.js as been removed and migrated to the DB. It can now to be configured in the GUI, via REST or (not recommended) directly in the DB. When using the GUI, the entries of the old configuration file ScreenTemplate.js have to be entered under “Admin > Settings > Screens”.

• The Keyword API slightly changed : the KeywordRunner run() method of the now returns an instance of step.functions.io.Output instead of step.grid.io.OutputMessage and throws exceptions. See this link for an example.