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
This information is also available offline, see the Upgrade datasheet.
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 consider the new features, improvements, security, and bug fixes of that release:
You should also 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 your applications in the new version.
If you are upgrading from Platform Server 11.x to Platform Server 11.12.0 or later, after the Platform Server is upgraded, you can publish your applications gradually, following your teams' pace.
In the following upgrade scenarios, you must publish all your applications after the Platform Server is upgraded:
- Upgrading from Platform Server 10 or previous to Platform Server 11
- Upgrading from Platform Server 11.x to Platform Server 11.11 or earlier
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, we recommend 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.
You always have the freedom to choose the order that's most convenient for you. Sometimes, to best coordinate with the development teams and ongoing 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.
Choosing to do a Zero-Downtime Upgrade means that if you need to rollback, you will most certainly have data loss. To successfully perform a Zero-Downtime Upgrade, your environment requires multiple Front Ends in each OutSystems Zone. If you don’t have this feature enabled you cannot 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. Depending on your upgrade scenario, you might need to publish all your applications, or opt to publish your applications gradually, following your teams' pace. See the details below.
Step 1. Upgrade the Platform Server component
Depending on if your environment is in the OutSystems Cloud or in your datacenter (on-premises/private cloud), follow the relevant procedure below:
In the OutSystems Cloud, the process of upgrading the Platform Server is handled by OutSystems, coordinating with you in every step of the way. This guarantees a successful and painfree procedure as possible:
Make your upgrade request by opening a support ticket using any of the available mechanisms and provide the following:
- An infrastructure admin's approval. If you're an infrastructure admin, your request is authorized. If you're not an admin either ask your admin to submit the ticket or to leave a reply on the ticket stating the approval.
- What are the environments you want to upgrade and to what version. You can check OutSystems release notes for a list of available versions for Platform Server and LifeTime. We advise you to choose the latest version.
- Let us know when (date and time) you wish to upgrade each environment, make sure to refer the time zone. We advise to allow at least a day between the schedule of each environment to accommodate for testing. If you have any special needs, let us know.
OutSystems will promptly contact you to discuss the schedule and plan for the upgrade.
OutSystems proceeds with the upgrade of the environment on the agreed schedule. When upgrading the Development environment of your infrastructure to Platform Server 11.11 or earlier, OutSystems also installs the latest version of the following components:
If you are upgrading from Platform Server 11.x to Platform Server 11.12.0 or later, you receive an email indicating that the Platform Server has been upgraded in your environment, and OutSystems is now preparing your modules for the new version. This operation takes place outside your maintenance window as it doesn't require any downtime. Once the modules preparation step finishes, you are able to publish your applications in the new version, at your own pace.
OutSystems is responsible only for the Platform Server upgrade. Once the OutSystems software (System Components included) is updated in the environment, the customer is responsible for:
- Publishing your applications in the new version (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, you can contact OutSystems Support at any time for assistance.
While upgrading the Platform Server component, consider enabling maintenance mode in the environment to avoid unnecessary communication attempts from the LifeTime console.
The process is the following:
Download the latest version of the Platform Server installer.
Follow the Installation Checklist for the corresponding Platform Server version. In the Installation Checklist, select the corresponding upgrade option, and follow the instructions.
If you are upgrading from Platform Server 11.x to Platform Server 11.12.0 or later, the Platform Server installer starts preparing your modules for the new version.
When you click Apply and Exit in the Configuration Tool, as described in the Installation Checklist, you must confirm the execution of the following steps:
- Publish the latest version of Service Center
- Publish the latest version of System Components
- Start the modules preparation step
Pressing OK publishes the latest version of Service Center and System Components, and starts running the modules preparation step in the background. You can see the progress of the operation in the Configuration Tool window, or in the Service Center console.
Closing the Configuration Tool during the modules preparation step doesn't interrupt the operation.
Once the modules preparation step finishes, you are able to publish your applications in the new version, at your own pace.
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 you have your teams' availability to perform the needed code fixing resulting from possible breaking changes.
If you are upgrading from Platform Server 11.x to Platform Server 11.12.0 or later, after the upgrade, you can publish your applications gradually, following your teams' pace. You can only start publishing your applications after the modules preparation step finishes. Check the progress of the modules preparation step in Service Center. You can also opt to publish all your applications by this time, but it's not a mandatory step.
In the following upgrade scenarios, you must publish all your applications after the Platform Server is upgraded:
- From Platform Server 10 or previous to Platform Server 11
- From Platform Server 11.x to Platform Server 11.11 or earlier
See below for the possible approaches to publish all the applications in your upgraded 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 so it's an advisable practice that improves the end-user experience.
Publish all applications
Having the Platform Server upgraded in the environment, consider the following scenarios when publishing all the modules in the new version:
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.
Keep 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.
For Forge components, it's a good practice to take the opportunity to upgrade them if there are new versions. Not only you can benefit from any bug fix but also the component might already be adjusted to any new feature or breaking change, saving you the effort to adjust the component. Make sure to validate any changes in the Forge components.
After publishing your applications in the new version, 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 hasn't yet been 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.