In this article, you will find the steps to migrate from Stambia DI Runtime S17 versions to 2020 (S20).
The whole procedure is described with additional notes and information about the major modifications you should have in mind.
The migration procedure will guide you to migrate to the new version and also explains the first step to follow after the migration is done.
There are dedicated articles for migration and upgrade procedure for the different major versions.
There are all summarized in the following article.
Do not hesitate to have a look at it.
You want to know what have changed in Stambia DI Runtime 2020 (S20) major version?
You can have a look at the following release notes!
About migration
This article is dedicated to the migration from Stambia DI Runtime S17 versions to 2020 (S20).
There are major differences between those mostly on third party libraries installation and usage that require your attention.
If you are simply doing a minor version upgrade, please refer to the corresponding article which will guide you to do it.
All migration / upgrade articles are summarized in the following article.
Prerequisites
From Stambia DI 2020 (S20) and higher, Java 8 or Java 11 is required to run the application.
Upgrade procedure
Here are the steps to follow to upgrade Stambia DI Runtime.
Preparation and Backup
The first step is to prepare your old Runtime to the upgrade.
- Stop the Old Runtime if it is running
- Make a zip archive of it to avoid any loss in case of upgrade problem.
Installation - Stambia DI Runtime
After downloading the desired Runtime ZIP archive, proceed through the steps listed below.
We assume your current Runtime is installed into a directory named "stambiaRuntime".
- Install the new Runtime in a new directory, something like "stambiaRuntime_new"
- On UNIX/Linux systems make sure that all the stambiaRuntime_new/*.sh files are executable
- Apply the read / write permissions to the new folder as it was set on the old one
-
Copy the content of the following directories from the old Runtime to the new Runtime:
- stambiaRuntime\build\deliveries
- stambiaRuntime\build\packages
- stambiaRuntime\properties (if you have set some properties)
- stambiaRuntime\scheduler (if you are using the Runtime's scheduler)
- stambiaRuntime\sessions (if you use the Runtime's internal log database)
- Optionally: stambiaRuntime\temp (if your Processes store specific files intentionnally in this directory)
Installation - Libraries
Next step is to reinstall the additional libraries and third party libraries you installed in your Runtime, such as JDBC drivers, and more...
The major change of this version is the introduction of Modules which is now the main mechanism to handle additional libraries.
Modules can be managed and prepared directly from Stambia DI Manager through the different wizards available.
We highly suggest to read "Getting started with Modules" article to understand the concepts and what this will change.
When your Modules are ready, you can copy / paste them in the Runtime you want them to be used in.
Default location for Modules is stambiaRuntime/modules
On previous versions, all the libraries where copied under <Stambia Runtime>/lib folder.
From now, you should use Modules instead of manually copying libraries inside this Runtime folder which must not be used anymore.
About "default" Module
We advise to start using the new Module mechanism as it is now an important part of Stambia DI for managing libraries.
Note however that you can also put all your existing libraries inside the Module called "default" which is a fallback Module used when no Module is specified in Metadata.
If you put all the libraries you were copy / pasting in lib folder in previous versions inside this "default" Module, your existing Mappings should work without having to define a Module in all your Metadata.
As indicated, this "default" Module is a fallback module which is used when no Module is specified, so it will be used for all your Metadata if you do not specify a Module in.
Note that using "default" Module will not work for the following Components which requires to create and use a Module explicitly:
Salesforce, MongoDB, Hadoop, Google Cloud Platform, Google BigQuery, Kafka, Elasticsearch, SAP or Excel.
Reorganization of Runtime libraries:
The folder hierarchy in a Stambia DI Runtime installation folder has slightly changed for the arrival of Modules.
There is a new folder named "stambiaRuntime/modules" which will contain all user created Modules which the Runtime will be able to use.
The "stambiaRuntime/lib" now contains only Runtime's internal files, you must NOT anymore add files inside this folder.
All additional libraries are now handled through Modules.
Installation - log database
When you are using another log database than default one for the Runtime, you must copy the corresponding JDBC Driver inside "default" Module.
For instance if you are using Microsoft SQL Server as log database for the RUntime, copy Microsoft SQL Server JDBC driver inside stambiaRuntime/modules/default
Installation - scheduler
If you are using the Runtime's internal scheduler to schedule deliveries, and you changed the default database it uses to store it schedules in, you must copy the corresponding JDBC Driver inside "default" Module.
For instance if you are using Microsoft SQL Server as scheduler database for the Runtime scheduler, copy Microsoft SQL Server JDBC driver inside stambiaRuntime/modules/default
Configuration - RMIS
When you want to secure RMI through TLS, you have now the ability to specify your own certificate.
This is now mandatory to define your certificate to secure Runtime's RMI endpoint with TLS.
The previous internal certificate which were shipped and used automatically for RMIS has been removed for security and customization purposes.
Refer to this article to learn how to secure the various endpoints with TLS on Stambia DI 2020.
Refer to this article to learn how to configure the clients such as Designer, Analytics, or command line scripts to communicate with a Runtime which endpoints are secured with TLS.
Configuration - About SOAP Web Services Publication
Published Stambia Web Services are exposed under REST and SOAP Endpoints.
There are two SOAP endpoints, one standard wsi compliant endpoint, and one historical non-wsi compliant.
URLs to access those SOAP endpoints have changed in this version to address some issues and to have a more comprehensive behavior.
On versions prior to Stambia DI 2020, such as S17, S18, S19, the wsi and non-wsi compliant endpoints were exposed and reversed on the same endpoint which was the web services root endpoints.
This can cause confusion and is not working properly since Stambia DI 2020 because of the structural changes of this version.
We therefore decided to fix this to have two clear and distinct SOAP endpoints URLs from now.
As always, you can see the endpoints URLs at Runtime's startup in the console.
Here is an example of output
SOAP Endpoint: http://STAMBIA:42200/wsi/DeliverableService?WSDL
SOAP Legacy "Non WSI-Compliant" Endpoint: http://STAMBIA:42200/nonwsi/StambiaDeliveryService?WSDL
What do you need to do about this change?
The endpoint URLs having changed, you have to adapt the resources which are calling the Stambia published web services to use the new base URLs.
For instance, if you are calling the Stambia Published Web Services directly from Stambia, you'll have to update the URLs in your Web Services (wsdl) Metadata.
SOAP Endpoints have some issues in S20.0.0 which are fixed in S20.0.1
We advise to use S20.0.1 or higher if you are publishing SOAP Web Services.
Post Migration Steps
Once you have finished following the upgrade guide, make sure the Runtime is properly starting, and you can the start using your fresh new Stambia DI Runtime!
If the Runtime was installed as a Windows service, you must now remove and re-install the Windows service.
Finally, you can remove the old Runtime folder if everything is working properly.
Troubleshooting
If you encounter issues while performing the upgrade, double check you have followed properly all the steps, and make sure you had a look on the getting started articles related to this new version.
Moreover, feel free to ask questions on the forum or to the Support Team.