Categories: ADMIN GUIDE MAINTENANCE

Migration

Migration guidelines

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.

Just follow our tutorial example to redeploy your keywords with an explicit dependency in an uber jar.

.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):
nuget.png

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.

General migration process

Stop running instance

  • If you installed step component as service, just stop the services.
  • If not, make sure to kill the associated Java processes (1 for the controller, 1 per agent).

Database

Backup

Before any migration task, make sure to backup your database following this instructions.

Instance

Case 1 : new instance running instead of the old one

If your new step instance will replace the existing one, you have nothing to do regarding the database instance.

Case 2 : new instance running alongside the old one

If you new step instance will run alongside the existing one, you will have to start a new instance of **MongoDB **on a different port that the one used by the previous instance.

Follow below instruction in order to achieve this :

In …\step-controller-X.Y.Z\bin, edit the file startMongo.bat

  • Replace the line
%MONGO_PATH%mongod.exe -dbpath ..\data\mongodb > mongod_%mydate%.log 2>&1
  • With
%MONGO_PATH%mongod.exe --port PORT_NUMBER -dbpath ..\data\mongodb > mongod_%mydate%.log 2>&1 

Then use this modified script to start your new **MongoDB **instance 

Restore the data

Now that your new instance is running, you can restore your data into it by following this instructions.

Controller

Installation

Refer to the following page to install the step Controller.

Configuration review

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).

step.properties

Default path is : …\step-controller-X.Y.Z\conf\step.properties.

Rather than copying the old step.properties file to your new step installation, you should keep the new version of the file and adjust its settings according to your new setup.

Refer to the step properties section of the installation manual for more details.

Agents

Installation

Refer to the following page to install a step Agent.

Configuration review

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 Agents configuration).

AgentConf.json

Default path :  …\step-agent-X.Y.Z\conf\AgentConf.json

  • Compare the content of the old configuration file with the new one and adjust the necessary settings : (do not simply erase the new configuration file with the old one, you may loose any new settings introduced by the release)
  • If you new instance is running alongside the existing one, make sure to update the agents port used to connect to the controller Grid !!!
{
"gridHost":"http://localhost:CONTROLLER_GRID_PORT",
....
}

Refer to the AgentConf.json section of the installation manual for more details.

Binaries migrations

If you have installed any custom binaries in the Agent bin folder, make sure copy them to the new agents bin folder at  …\step-agent-X.Y.Z\bin

Keywords

Re-compilation

In order for your keyword to work in a newest version of step, you will have then to recompile them with the new version of the step Api.

  • 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

      1526479857654-525.png

    • 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 :
1525437178268-576.png
  • Update the keyword path and press the Save button
1525437239861-843.png

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.

See Also