“What is the best way to avoid breaking changes when updating a custom component?”
“How can we organise our library of components in a way that we can avoid app lifecycle strangling?”
“Can we have multiple versions of the same component spread in different modules?”
If you are an experienced OutSystems front-end developer, you will probably recognize some of these questions because someone asked them to you at a certain point in time.
And probably you didn’t have an answer to give them capable of satisfying all the required needs.
Well, all of this is true if we are talking about OutSystems 11, but what if we are talking about OutSystem’s newest cloud platform, ODC?
OutSystems ODC
OutSystems ODC is basically the natural evolution of OutSystems 11.
It’s the cloud-native “OS 11” version on steroids with a lot of features that OS developers have been asking for.
Just to name a few:
- A single portal with all the tools merged (Lifetime, Users, Forge, Service Center, AI Mentor and others);
- A new approach to app packaging, makes it easier and safer to deploy and manage;
- Easier to use deploy system;
- Easier to make platform and app configurations.
And the most anticipated feature of them all, is library versioning. This is what we are going to talk about in this article, the idea behind it and how to use it.
The Concept of Libraries
To understand how versioning works, let’s first understand the new approach from ODC to deliver applications into production.
To put it simply, to deliver an application in production, what OS is now doing is grabbing the application you are developing and the libraries you are using and isolating them in a closed container. That container is then sent to production completely isolated from the rest of the infrastructure.
The main advantage of this approach is that since the container will not have outer dependencies on other libraries, the god old breaking changes problems from OS 11, will not happen anymore.
The other advantage of this approach is that when we are creating a container, a version of the library will be used and stagnant inside the container which is the same as saying that if we make a change to the library (like adding a mandatory parameter to a component), the new version will not be applied until we “create” a new container.
So, if you are thinking “Well, this opens the door that will allow me to select what version of a library I want to include inside the container!”, you are correct. That is exactly what OutSystems is doing and in the next chapter, I will explain how to create a new library version and later on, how to use a specific version on an application and how to manage it.
Creating a Library
At this point, it’s easy to understand that a library is a new concept in ODC and has a specific purpose. Their purpose is to store logic, themes, reusable UI elements, and similars. They are not allowed to store and save persistent data. Libraries are designed to be producers of functionality.
This approach allows the reduction of complexity while promoting reusability and modularity.
To create a new library, in the ODC Studio, you just need to select “Library” in the “Create” popup.
Give it a name, and a description (select a color if desired) and hit the “Create library” button.
Next, we will create a very simple UI component named “CustomCard” with 3 placeholders (title, content, actions) and a container to host a “times” icon inside to serve as a closing action. We will also create an event (not mandatory) to be triggered when the user clicks on the “times” icon.
For the structure, we will use a container with a first container (with an icon inside and a click event) and the placeholders.
And to finalize, we give it a little CSS by creating a new CSS stylesheet.
Now that we have our first component, we can publish the library.
After publishing the first time, ODC Studio will prompt you if you want to use your new library in an application that you already may have in your cloud or in a new one. For now, let’s ignore this prompt by hitting “Cancel”.
After we first publish our new library, we need to create a new release. To do that we need to go to the menu on the top left corner saying “Master Class Library” and select the option “Release Library”.
By doing this, a new TAB on your browser will open with the ODC Portal requesting you to add the release information. Just follow the steps.
Start by selecting the version that you want to release. In our scenario, we want the second revision because it is the latest one.
In the second step, you will be prompted to set the version. The overall rules for choosing a version number are:
- Major: when there are big changes to the library that can break applications that are consuming it;
- Minor: when you make a change like adding a new component or changing something that does not affect or break consumers;
- Patch: when you made some bug fixes or performed some improvements with no impact on consumers.
At this point we already have a working library with a custom component that we can start using in our applications.
Using Libraries on Applications
It’s only possible to use a library in an application if it has at least one release.
Let’s start by creating a new application and on the ODC Studio top option “Add public elements” add a reference to the newly created custom component from our library.
If you go to the ODC Portal and open the library, you can now see that it’s being consumed by one application.
Updating a Library
To exemplify the workflow when a library is updated let’s use the same library and the same “CustomCard” component. The idea is to perform two different types of changes that would create an incompatibility on OS 11 but we will use it to understand how ODC now deals with the same problem.
On the “CustomCard” component let’s change the event from “Not Mandatory” to “Mandatory” and let’s add a new mandatory input parameter called “HideCloseButton”.
When done, we click the 1-Publish button to generate a new library version and what we need to do next is to create a new release.
The interesting thing here is that even if you add 2 breaking changes if you open the application consuming the library, it will be completely OK with no errors. That’s because the application is using a different library version where the changes haven’t made yet.
To generate a new release, open the ODC Portal open the library details page, and click on the “Release library” button.
On the screen, you will see the list of versions, you just need to select the last one and hit “Continue” to start the new release flow (the same has been explained before).
After you complete the release workflow, you should have something similar to this:
Now, if you open your application, you will get an information message stating that you have some updates available from the libraries you are using.
At this point, if we choose to ignore updating the changes, we could just publish our application and safely deliver it to production, mostly because as we said earlier, when we deliver an application in production, a closed container is created. Meaning that our app, in this scenario, would be packed alongside the current revision of the library (without errors).
But if we really want, we can update our library and fix issues. To do that, if you click on the review button, you will be presented with a prompt popup with all of the updates available and its details to assist you in deciding what to do. The good thing here is that we can see if there is any kind of breaking change. In our scenario, since we added 2 breaking changes, they will be highlighted for the developer to be careful.
If you are completely aware of the changes, just hit the “Update” button to fetch the changes.
After we update our application, we can publish it and send it to production.
Conclusions
As you can see, even though we added some breaking changes to our component in the first try, our application didn’t stop working. It was only after I deliberately updated the library that these changes were applied.
It’s a huge step forward from OS 11 where this kind of thing happens a lot resulting in us not being able to update a component the right way just because that would mean introducing a breaking change.
So now you know the basics of dealing with libraries, releases and updates.
