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

24.1-3 to 24.4+

An “anonymous” user was wrongly created from version Step 24.1 to Step 24.3. While this has no functional nor security impact, it consumes one user from the license. This is solved with Step 24.4, but the user should be manually removed.

23.x to 24.x

For most users and setup upgrading from Step 23, no manual migration tasks are required, but the following should be considered.

Step maven plugin

The existing maven plugins have been refactored into a single open source plugin compatible with all Step editions: step-maven-plugin.

As part of this change

• The existing goals run-packaged-automation-packages-(os|ee) have been removed in favor of the new goal execute-automation-package
• The existing goals upload-keywords-package-(os||ee) have been refactored to the single upload-keywords-package goal. Keywords packages are deprecated, it can already be replaced by the new deploy-automation-package goal.

Step runner

The Java Junit Step runner has been refactored for Step automation packages which implies some changes of behaviour:

• A test class annotated with the Step runner will not only execute plans defined with the @Plans and @Plan annotations in the same class, but it will execute all plans available in the context (class loader) including the ones defined in the automation package yaml descriptor
• The list of plans to be tested can be reduced by using the new annotations @AutomationPackagePlans
• The path of the plain text plans referenced with the @Plans annotation changed and are not related to the java package anymore. In other words, the plan referenced in below example must be localed at the root of the package.

Example:

@RunWith(Step.class)
@Plans({"testAutomation.plan"})
@AutomationPackagePlans({"testAutomation.plan"})
public class StepAutomationPackagesPlanAnnotation {}

Analytics

Response times and other measurements are now project aware, due to the general high volume of data no migration tasks were implemented. This means that for former executions, the analytic view may show only partial data and should rather be opened within the “All” tenant context.

22.x to 23.x

Keyword outputs in plans

With Step 23, access to keyword output fields in plans has been greatly simplified, see the section keyword outputs for more details. To avoid most compatibility issues, the output variable itself still implements the methods of jakarta.json.JsonObject however the values of the output object fields does not. Concretely, the following expression is still valid output.getString("myStringField"), but the following output.myStringField.getString() is not.

In case you have too many special expressions in your plans and do not want to migrate, you may revert to the old output JsonObject type by adding following property to the controller step.properties

keywords.output.legacy=true

API keys

With the Introduction of the API key revocations, exiting API keys are rendered invalid and must be renewed.

Other migration tasks

There are no other manual migration tasks from Step 22 to Step 23.

21.x to 22.x

Licenses

The new license files consist of a license configuration file (step-enterprise.licenseconfig.json), as well as (usually) one or more actual license files (license*.json). Please contact us to obtain the relevant files for your organization.

Do not attempt to modify the content of these files, as they are digitally signed, and any change will render the signature invalid.

The simplest way to install these files is to place all of them in a folder called licenses/

• A) in the controller root installation directory (besides the bin/, conf/ etc. folders). This is the recommended approach.
• or B) under the bin/ subdirectory.

Examples: If you have installed Step in D:\Step, you could create the licenses folder either in D:\Step\licenses (option A, recommended) or D:\Step\bin\licenses (option B). For Linux, examples would be /opt/exense/step-controller/licenses or /opt/exense/step-controller/bin/licenses .

If you follow these recommendations, you will not need to change the relevant settings in the step.properties file.

If you do need to place the files somewhere else, you can change the settings in step.properties accordingly, for example:

licenseconfig.file=/data/step-licenses/step-enterprise.licenseconfig.json

However, this is discouraged, and in this case, you will also need to request a customized licenseconfig.json file, which you can obtain by contacting us and letting us know the full path where your actual license files are to be searched.

Other migration tasks

There are no other manual migration tasks from Step 21 to Step 22.

System monitoring

Since the pre-populated system project has been deprecated and removed, the internal system monitoring has been removed as well. To set it up from Step 22 onward, you must use the open source keyword libraries. The keyword package is available on maven central and can be uploaded in Step using following maven snippet:

<dependency>
    <groupId>ch.exense.step.library</groupId>
    <artifactId>step-library-kw-monitoring-system</artifactId>
    <version>1.0.18</version>
</dependency>

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.