If you are using a personal environment and you would like to upgrade it to the latest version, refer to the article Upgrade a personal environment to the latest version.
The OutSystems ecosystem is divided into components with different release cycles: Platform Server, Development Environment (Service Studio and Integration Studio) and LifeTime Management Console. This article focuses on the upgrade of the core server part of OutSystems product, the Platform Server.
Upgrading your OutSystems environments to a new Platform Server version is a four-step process that requires preparation, as it may impact your applications (all your applications will have a new version after the upgrade). The steps for this process are:
- Analysis and Preparation
If you want to take this information offline, see the Upgrade datasheet that describes the overall procedure detailed in this article.
Up to version OutSystems 10, upgrading OutSystems to a new major version means upgrading all the infrastructure - LifeTime management console and the application environments.
From version OutSystems 11 onwards, LifeTime is distributed independently from the Platform Server, which enables both components to have different upgrading paces. For further details on the LifeTime upgrade process, see this article.
When upgrading your infrastructure, make sure that LifeTime is the most up-to-date environment. If you’re running OutSystems 11, LifeTime's continuous release cycle enables you to benefit quicker from the latest features and fixes. If you are running OutSystems 10 or previous, first you must upgrade your LifeTime Management console to the latest version.
Starting on version 11, LifeTime is only supported when installed in a dedicated environment. If you still have it installed in an application environment, see how to reinstall LifeTime in a dedicated environment.
Analysis and preparation
Before you start the upgrade of your OutSystems infrastructure, you should always learn more about the specific release. Start by understanding what are the new features, improvements, and security and bug fixes:
Then, it’s important to assess the impact that the upgrade may have in your applications, checking the Side Effects and Breaking Changes documents:
- Side Effects and Breaking Changes in OutSystems 11
- Side Effects and Breaking Changes in OutSystems 10
Be sure to read all the documents that might impact your upgrade. For example, if you're upgrading from OutSystems platform 9.1 to 11, read the breaking changes for versions 10 and 11.
The second phase is the planning. Based on the breaking changes identified on the previous step, you should estimate how long it will take to perform the needed code fixing, and to publish all the applications to the new version.
Make sure you involve your teams (you will need your development and test teams) and plan ahead to align the upgrade with your release cycle.
An upgrade sprint should never break a development sprint!
An upgrade should always happen between development sprints (if you have teams at a different speed, make the necessary adjustments).
Validate the best time to upgrade the Production environment and plan the remaining environment upgrades from there.
When upgrading your OutSystems environments, OutSystems recommendation is that you follow the staging lifecycle of the applications in the infrastructure. This is the order you push your developments to production, for example, Development > Testing > Pre-Production > Production. For this, you should prepare your applications for a full staging from development all the way to production.
You always have the freedom to choose the order that's most convenient for you. Sometimes, to best coordinate with the development teams and on-going projects, you can start with another non-production environment (for example, Pre-Production) to fully validate the applications upgrade, and then upgrade the Production environment. Only after, upgrade the Development environment according to the development teams delivery sprints. Bottom line is, you should always upgrade and test your applications in a non-production environment before proceeding to the Production environment.
Go live strategies
When upgrading the Platform Server you should consider that the environment is literally under maintenance. Therefore, if you already have live applications, this process may impact them and, as such, you should define a strategy for the upgrade of your Production environment, based on the priority of your applications.
A Downtime approach is the safest way to perform an upgrade and advised when there are no business requirements for zero-downtime. By stopping the Production environment and preventing end-users access, the Upgrade process consistency is guaranteed, and a rollback can happen with no data loss.
A Zero-Downtime Upgrade is like changing a car engine without stopping the car itself. Which means that if you need to rollback, you will most certainly have data loss. To perform a Zero-Downtime Upgrade, with success, your environment requires multiple Front Ends in each OutSystems Zone. If you don’t have this feature enabled you can’t proceed with this solution. The Upgrade process is done by:
- Disabling the Front-end servers in Service Center.
- Upgrade the platform in the controller node.
- In the load balancer disconnect half of front-end servers in each zone.
- Upgrade those servers and then enable them in Service Center
- Switch the active Front-End servers in the Load Balancer to the upgraded ones
- Upgrade the remaining Front-End servers.
- Finally, reconnect all servers to the Load Balancer.
Once you have your upgrade plan defined, and the development and test teams allocated, you can proceed with the upgrade execution.
For each environment, the upgrade consists in the following steps:
Upgrade the Platform Server component
Upgrade the development tools of the developers publishing applications in that environment
Upgrade the applications to the new version
Step 1. Upgrade the Platform Server component
Check below the procedure to upgrade the Platform Server in your environment, depending if your environment is in OutSystems Cloud or it's on-premises.
In the OutSystems Cloud, the process of upgrading the Platform Server is handled by OutSystems, coordinating with you in every step of the way, to guarantee a successful and as effortless as possible procedure:
You request the upgrade of your OutSystems Cloud environment to a supported upper version, by opening a Support Case using any of the available mechanisms.
OutSystems will promptly contact you to schedule and plan the Platform Server upgrade.
OutSystems proceeds with the upgrade of the Platform Server component on the environment on the agreed schedule.
OutSystems is only responsible for the Platform Server upgrade. Once the OutSystems software (System Components included) is updated in the environment, the customer is responsible for:
- Re-deploying applications (Upgrade Applications to the new version)
- Resolving any breaking changes
Self-managed (private cloud / on-premises)
If the environment is self-managed (running in your own private cloud or on-premises) the upgrade process is fully managed by you, without the direct involvement of OutSystems. However, at any time you can ask OutSystems Support for assistance if you have any questions or get any errors in the process.
The process is the following:
Step 2. Upgrade the development tools
If you haven't already, download and install the correspondent version of the Development Environment (Service Studio and Integration Studio) in the workstations of the developers publishing applications in the environment.
Step 3. Upgrade applications to the new version
At this stage, it's important your teams' availability to perform the needed code fixing (solving breaking changes) and testing.
Having the Platform Server upgraded in the environment, you should upgrade your applications, republishing all the modules to the new version, according to the following scenarios:
On the Development environment, the fastest way to upgrade all your applications is by creating a Solution with all modules and publish the "Current Running Version". If you get any errors publishing the solution, use the appropriate development tool to open the correspondent module and fix the problems. In the end, you can publish the whole solution again to make sure all issues and dependencies are properly resolved.
For all non-development environments (for example, Testing, Production, etc.), it’s recommended to stage the application modules from a previously upgraded environment. Using Service Center (
https://YOUR_ENVIRONMENT/ServiceCenter), download the solution and publish it in the new environment, ensuring you don't overwrite the System Components. You can also use the LifeTime management console to stage upgraded applications, when the lifecycle of the applications is perfectly aligned with the upgrade.
Have in mind that this approach for non-development environments is only applicable when the version of the applications on the previous environment is stable and ready to be staged to the next environment (upgrade must be aligned with your release cycle). If that’s not the case, you should perform a code-based upgrade, doing all the fixing and testing directly in each environment.
For mobile apps, upon a Platform Server version upgrade in your Production environment, it's expected that many of the mobile app resources carry differences, which will trigger over-the-air (OTA) upgrades to all the end users. Generating and distributing a new build eliminates the need for OTA upgrades and it's an advisable practice that improves the end-user experience.
Finally, you should create and run tests to ensure that your applications hot-points aren't affected by the upgrade. Test your applications (screens, workflows, operations, etc.), and check for application errors or background issues in Service Center's Error Log, to guarantee that all applications are running as expected.
Doing maintenance while upgrading environments
While upgrading, if you need to do some bug fixing in an application that's running on an environment that hasn't been upgraded, you'll need to do it on that environment. It won't be possible to go through the usual development-production pipeline, because you can't stage applications between environments in different versions.
The solution is to make the fix directly in the environment that's not yet upgraded.
As an example, imagine that you already upgraded Development and Test environments. There are still Pre-Production and Production environments to upgrade. You have to do a critical fix on an application in Production. In this case, use the development tools in Pre-Production to do the fix, publish, and test. Then, move the application to Production. Don't forget to backport the fix to the other environments.