<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Ivo Gonçalves on Medium]]></title>
        <description><![CDATA[Stories by Ivo Gonçalves on Medium]]></description>
        <link>https://medium.com/@ivogoncalves?source=rss-afb33469c210------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*x0SLF5sLYpQedCSncCKEiw.png</url>
            <title>Stories by Ivo Gonçalves on Medium</title>
            <link>https://medium.com/@ivogoncalves?source=rss-afb33469c210------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Thu, 19 Nov 2026 01:32:27 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@ivogoncalves/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Unveiling SEO Strategies for OutSystems Reactive Apps — Part 2 — 404 Pages]]></title>
            <link>https://blog.product-league.com/unveiling-seo-strategies-for-outsystems-reactive-apps-part-2-404-pages-d03e41acbd0e?source=rss-afb33469c210------2</link>
            <guid isPermaLink="false">https://medium.com/p/d03e41acbd0e</guid>
            <category><![CDATA[404-not-found]]></category>
            <category><![CDATA[outsystems]]></category>
            <category><![CDATA[outsystems-reactive]]></category>
            <category><![CDATA[seo]]></category>
            <dc:creator><![CDATA[Ivo Gonçalves]]></dc:creator>
            <pubDate>Wed, 26 Jun 2024 09:02:37 GMT</pubDate>
            <atom:updated>2024-08-16T08:49:18.633Z</atom:updated>
            <content:encoded><![CDATA[<h3>Unveiling SEO Strategies for OutSystems Reactive Apps — Part 2 — 404 Pages</h3><p>Following my <a href="https://blog.product-league.com/unveiling-seo-strategies-for-outsystems-reactive-apps-part-1-f5e9687cbaac">previous article</a>, where I discussed making OutSystems Reactive apps visible to crawlers, here I present you part 2 of this series.</p><p>This time, I’ll delve into the topic of 404 error pages — those special pages that appear when the content you’re looking for cannot be found. 404 pages can be further classified into two specific types:</p><ol><li><strong>Regular 404 page</strong></li><li><strong>Soft 404 page</strong></li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*4NuD3WvjWWUlFKCWqYBRuQ.jpeg" /></figure><h4>Regular 404 page</h4><p>A regular 404 page occurs when the HTTP response status code is set to 404.</p><p>In an OutSystems Reactive app, if a user tries to access a screen that doesn’t exist, the app displays an error page with the corresponding 404 status code</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/663/1*FQOHGwBGxnRM8sW2b6ALQw.png" /><figcaption>Default IIS 404 page</figcaption></figure><p>We all have seen this one — IIS beautiful default 404 page.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*KTo81Hs-d7xKWdxrZF3Sig.png" /><figcaption>Response status code</figcaption></figure><p>And by inspecting the response, we can see the HTTP status code set as 404.</p><h4>Soft 404 page</h4><p>A soft 404 page occurs when a page returns an HTTP status code 200, even though the requested content does not exist. In the context of OutSystems Reactive apps, a common pattern for delivering a soft 404 can be exemplified as follows:</p><ol><li>The user attempts to access a product detail page (using the product SKU as an input parameter).</li><li>Data fetching begins.</li><li>Data fetch does not find the product.</li><li>As a result, the user is either redirected to a 404 page or shown a not found message on the current screen. Despite the product not existing, the server responds with a 200 HTTP status code</li></ol><h3>But why does it matter?</h3><p>404 errors are a common occurrence on websites. If you’re running one, you’ll inevitably encounter them. That’s why custom 404 error pages are crucial. SEO experts will tell that, a proper 404 error meets the following criteria:</p><ol><li><strong>Provide relevant information to keep users engaged</strong> — including a friendly message explaining the error, links to popular or related content and a search bar to help users find what they’re looking for.</li><li><strong>Consistent Look and Feel</strong>: Maintaining consistency across your website is essential. Your 404 page should match the overall design and branding. This ensures a seamless user experience even when encountering an error.</li></ol><p>A well-crafted 404 page can turn a frustrating moment into an opportunity to engage users and guide them toward relevant content. Needless to say that IIS default 404 page meets none of this criteria.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*9_1xA3rvwuDfW2g5IVxmKA.png" /><figcaption>Medium’s 404 page</figcaption></figure><p>Displayed above is Medium’s 404 error page, which appears significantly more appealing than the default page provided by IIS, don’t you think? Here you can clearly see what was previously mentioned:</p><ul><li>Friendly message and links to relevant content.</li><li>Consistent look &amp; feel.</li></ul><h3>Custom 404 pages, pretty straight forward, right?</h3><p>We thought so, however we stumbled upon two challenges — bear in mind that we run on OS PaaS, where infrastructure access is limited:</p><ul><li><strong>Customizing the default IIS page: </strong>using a screen defined inside an OS Reactive application is not as simple as it seems at first sight.</li><li><strong>Crawlers:</strong> must get soft 404 pages served with HTTP status code 404 (instead 200).</li></ul><p>OutSystems recommends using Factory Configuration to customize 404 error pages. There’s an <a href="https://www.outsystems.com/forums/discussion/5484/creating-custom-error-pages-with-the-outsystems-agile-platform-4-1/#">old forum post</a> where this workaround is highlighted. Even though this works fine for Traditional web apps we cannot say the same for OutSystems Reactive apps. This won’t work.</p><p>As for why crawlers need to be served 404 pages with the proper HTTP status code, thus making soft 404 pages not an option, there are a few reasons:</p><ul><li><strong>Crawling budget: </strong>wasted budget on an error page.</li><li><strong>Indexing errors:</strong> If a crawler interprets a soft 404 as a valid page, it may index it. This is undesirable, especially when the page points to an error.</li></ul><h3>Setting custom 404 pages defined inside Reactive apps</h3><p>When we discussed the issue with OutSystems regarding customizing the 404 page for Reactive apps, they recommended creating a 404 error page using a Traditional web app. Although this was a known workaround at the time, we decided to explore alternative solutions. Using a Traditional web app for the error page would have certain implications:</p><ul><li><strong>Dual Runtimes:</strong> Managing two runtimes (Reactive and Traditional) would require maintaining duplicate themes, blocks, and other components.</li><li><strong>Risk of Propagation Errors:</strong> Forgetting to propagate changes from one runtime to another could impact the user experience.</li><li><strong>User Disruption:</strong> Switching between apps in different runtimes might trigger repeated initial loads in the OutSystems Reactive app.</li></ul><p>After some research we found out a simpler solution, allowing us to use Factory Configuration to configure a 404 page defined inside an OutSystems Reactive app. The thought process was:</p><ul><li>Q: What can we configure, as 404 error page, using Factory Configuration?</li><li>A: Screens inside Traditional web apps.</li><li>Q: Anything else?</li><li>A: Maybe we can point to resources (e.g. a resource inside a module).</li></ul><p>And this was the trick. It happens that we can leverage a resource, inside a module, to customize our 404 error page defined inside a Reactive app. How?</p><ul><li>Create a notfound.html file with an embedded iframe</li><li>The embedded iframe points to the not found page inside the Reactive app</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/800/1*FkDkD-NSCSBLI4qAzYB2Pw.png" /><figcaption>Iframe configuration, pointing to the not found page</figcaption></figure><ul><li>Deploy the notfound.html file to the target directory</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/333/1*lxkizcwkaEjQBODCSru95A.png" /><figcaption>Resource configuration</figcaption></figure><ul><li>Configure Factory Configuration to serve the embedded resource as 404 error page</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/964/1*ss-nQuS2vsfLMkPEX9l9NQ.png" /><figcaption>Factory configuration configuration</figcaption></figure><ul><li>Finally, we need to break out of the iframe when the page is loaded via the resource file</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*x60zBaHaK4nKPgV9ioUW2Q.png" /><figcaption>JS code to break out of the iframe</figcaption></figure><p>If you want to abstract some of this complexity, you can use this forge <a href="https://www.outsystems.com/forge/component-overview/15534/custom-404-plugin-o11">component</a>. It is a more polished solution to address the issue. It uses the same principle I have just described, but abstracts some complexity away from you.</p><h3>Serving soft 404 pages to crawlers</h3><p>At this point we have a custom 404 page, which is defined inside our Reactive app. This page is served as regular 404 page (e.g. URL does not exist), and also as a soft 404 page (e.g. product not found).</p><p>While for end users this works just fine, crawlers are a different situation. As I have already mentioned, we must serve them 404 error pages always with HTTP status code 404.</p><p>Lucky for us, the solution we picked for pre-rendering (mentioned in the <a href="https://blog.product-league.com/unveiling-seo-strategies-for-outsystems-reactive-apps-part-1-f5e9687cbaac">previous article</a>), has a very simple way to do this. You can inject a meta tag stating which status code you want your page to be served, named <strong>prerender-status-code. </strong>All you have to do is inject this header in the 404 page:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*u4aBDaR8ez8UoSXfJgjOHQ.png" /><figcaption>Header injection inside OnReady</figcaption></figure><p>You can use this <a href="https://www.outsystems.com/forge/component-overview/9576/seo-utils-on-steroids-o11">component</a> to inject the header.</p><p>When you access the page it should look like this:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/412/1*raniAJPg-f5KxVIjuw3gTA.png" /><figcaption>Pre-render header being injected</figcaption></figure><p>Finally, injecte the header into the previously created notfound.html resource. This acts as a fail-safe measure, since pre-render should always serve the page after the JavaScript, which breaks out of the iframe, has executed.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*blxciitIuOCJAn-QvmCFvA.png" /><figcaption>Pre-render header inside notfound.html</figcaption></figure><h3>Recap</h3><p><strong>Understanding the Significance of Properly Handling 404 Errors:</strong> During this article, we emphasized the importance of effectively managing 404 errors. We delved into two specific challenges we encountered and the solutions we adopted.</p><p><strong>Unique Challenges in Our Environment:</strong> Given that our application runs on the OutSystems PaaS, and uses the Reactive runtime, we face additional complexities. However, as demonstrated, there are viable workarounds to address these challenges.</p><h3>Next series</h3><p>We have seen already how to make Reactive apps visible to crawlers and how to serve 404 error pages. But there’s more coming up:</p><ul><li>Part 3 — Linking patterns that crawlers can see</li><li>Part 4 — Crawler friendly infinite scroll pattern</li><li>Part 5 — Automatic sitemap generation</li></ul><p>Click here to read more about our services: <a href="https://product-league.com/services/ecommerce">https://product-league.com/services</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=d03e41acbd0e" width="1" height="1" alt=""><hr><p><a href="https://blog.product-league.com/unveiling-seo-strategies-for-outsystems-reactive-apps-part-2-404-pages-d03e41acbd0e">Unveiling SEO Strategies for OutSystems Reactive Apps — Part 2 — 404 Pages</a> was originally published in <a href="https://blog.product-league.com/">ProductLeague</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Unveiling SEO Strategies for OutSystems Reactive Apps — Part 1 — Pre-Rendering]]></title>
            <link>https://blog.product-league.com/unveiling-seo-strategies-for-outsystems-reactive-apps-part-1-f5e9687cbaac?source=rss-afb33469c210------2</link>
            <guid isPermaLink="false">https://medium.com/p/f5e9687cbaac</guid>
            <category><![CDATA[prerender]]></category>
            <category><![CDATA[outsystems-reactive]]></category>
            <category><![CDATA[single-page-applications]]></category>
            <category><![CDATA[outsystems]]></category>
            <category><![CDATA[seo]]></category>
            <dc:creator><![CDATA[Ivo Gonçalves]]></dc:creator>
            <pubDate>Wed, 03 Apr 2024 09:38:45 GMT</pubDate>
            <atom:updated>2024-06-06T13:21:04.181Z</atom:updated>
            <content:encoded><![CDATA[<p>Recently I developed from scratch (together with a brilliant group of individuals) a large ecommerce solution using OutSystems Reactive, where SEO was a major concern. Before this project, SEO sat deep down in my list of priorities. I was asked a few times before to add a few metatags here and there. And that was it.</p><p>It happens that SEO is way more than just adding metatags, it is a whole league on its own. Additionally, OutSystems Reactive being a Single Page Application (SPA for short), poses some technical challenges.</p><p>Throughout this series, I’ll discuss some challenges I encountered and explore how they were tackled.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*_KPxMNLHjNpQ5GROrAcWHA.jpeg" /></figure><h3>First things first</h3><p>What do you mean with SEO?</p><p>According to moz.com <a href="https://moz.com/learn/seo/what-is-seo">article</a>, we can briefly define SEO as:</p><blockquote>SEO stands for search engine optimization. SEO practitioners optimize websites, web pages and content for the purposes of ranking higher in search engines, like Google. SEO is a set of practices designed to improve the appearance, positioning, and usefulness of multiple types of content in the organic search results. This content can include web pages, video media, images, local business listings, and other assets. Because organic search is the top method via which people discover and access online content, utilizing SEO best practices is essential for ensuring that the digital content you publish can be found and chosen by the public, increasing your website’s organic traffic.</blockquote><p>Organic search results emerge from search engines searching and categorizing internet content to deliver the most relevant results to your search queries. This procedure unfolds in three distinct stages:</p><ul><li><strong>Crawling </strong>— Search the internet to discover content</li><li><strong>Indexing </strong>— Save and categorize the content gathered during crawling</li><li><strong>Ranking — </strong>Rank the content that has been indexed</li></ul><h3>How do you crawl what you don’t see?</h3><p>If you work with OutSystems you already know this, but OutSystems Reactive compiles into React, which means it is a Single Page Application.</p><p>With Single Page Applications when the user requests the page, it is served with a basic HTML document. Content wise, this initial document has nothing. It comes with links for JavaScript files, that when loaded will start requesting data from the server and painting the page with content.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Vy6OxExveDE6oIHsy1Ta-w.png" /><figcaption>Rendering SPAs</figcaption></figure><p>We can see this by looking at the HTML document we get as response from an OutSystems Reactive app.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/927/1*D3JC4b8639hBvCYj4Nk_hA.png" /><figcaption>OutSystems Reactive HTML document response</figcaption></figure><p>Most crawlers will see this same empty page and won’t wait for the JS to kick in and load its content. So, they are effectively unaware what your page is all about. How will they index and rank your website if they know nothing about it?</p><h3>Making content visible to crawlers</h3><p>The issue mentioned before is not OutSystems-specific. It’s transversal to all Single Page Applications. And being a known issue means there are solutions out there. I won’t deep dive into all available options, instead I’ll focus in our use case.</p><p>For us, running our apps in OutSystems PaaS infrastructure limited our scope to just one possible approach.</p><h4>Pre-rendering to the rescue</h4><p>We did some research and ended up implementing a pre-rendering solution. The basic idea is that, for each page in your OutSystems reactive app, you have a pre-rendered version of it ready to be served to crawlers.</p><ul><li>When a human requests the page, it is served the SPA version of the page</li><li>When a crawler requests the page, it is served with a pre-rendered version instead</li></ul><p>A pre-rendered page represents the finalized version of the webpage, where the JavaScript has completed loading the content. This ensures that crawlers can access the fully loaded content rather than encountering an empty page.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/776/0*RJ54OQjRCKcDFIGn" /><figcaption>Serving requests based on source type</figcaption></figure><p>If you want to explore this yourself, checkout <a href="https://prerender.io/">prerender.io</a>, which was the chosen pre-render solution.</p><p>Setting pre-render infrastructure is a challenge on its own. If you run on OutSystems PaaS, you need to deploy a reverse proxy before OutSystems load balancer, so requests can be redirected accordingly. If you run on-premises, you can simply follow <a href="https://docs.prerender.io/docs/18-integrate-with-iis">pre-render’s instructions.</a></p><p>Also, quite important to consider:</p><ul><li><strong>How should the pages be pre-rendered for the first time (e.g. a new screen added to your app)? </strong>This is important, because if the crawler requests a page that is not pre-rendered yet, it needs to wait for the pre-render server to do its job. Since this takes time, the crawler might timeout. Also, you will get penalized by search engines, and rank lower, the longer your page takes to load. You want your pages to rank higher in search engines’ results page, thus you need to serve them as fast as possible.</li><li><strong>How often should pre-rendered pages be re-cached?</strong> If the content of the page changes often, it is important to have a pre-rendered page up to date. Otherwise, search engines might show outdated information.</li></ul><p>We have automated these two things using <a href="https://docs.prerender.io/docs/6-api">pre-render APIs</a> and automatic sitemaps generation.</p><h3>Checking how crawlers see your page</h3><p>Now that you have pre-render in place, how do you validate crawlers get served the right page? If the configuration was done properly, crawlers should see a fully rendered page.</p><h4>Using dev tools to pose as a crawler</h4><p>In chrome you can go to <strong>Network Conditions -&gt; User Agent -&gt; Set the bot user agent </strong>and fake being a crawler.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/715/1*VFgifY5LTQERy-f8d4_PvQ.png" /><figcaption>Setting user agent on Chrome dev tools</figcaption></figure><p>The user agent is used to decide which page is served. By faking your user agent, and pose as a crawler, you’ll see what the crawler sees.</p><p><strong>Search consoles</strong></p><p>Search engines have dedicated consoles where you can play around and test multiple metrics of your pages. Link below for the two biggest search engines:</p><ul><li><a href="https://search.google.com/search-console/about">Google Search Console</a></li><li><a href="https://www.bing.com/webmasters/about">Bing Webmaster Tools</a></li></ul><p>You’ll need to prove the ownership of the domain you want to test, but the process is quite straight forward. Afterwards, you have the ability to deep dive and perform various tests on the pages you want to validate.</p><p>This is the most reliable method, because you are actually using the crawler, not pretending to be one.</p><h3>Next series</h3><p>Now that crawlers can see your page, it is time to move on and handle other funny challenges.</p><p>I’ll talk more about that in upcoming articles:</p><ul><li>Part 2 — Implementing custom 404 pages (soft and hard)</li><li>Part 3 — Linking patterns that crawlers can see</li><li>Part 4 — Crawler friendly infinite scroll pattern</li><li>Part 5 — Automatic sitemap generation</li></ul><h3>Final notes</h3><ul><li>Some crawlers (cough cough googlebot cough cough) may be able to view the SPA page content. Yet, as mentioned before, you want your page to be served as fast as possible to crawlers, so you don’t get penalized by search engines. From the tests I did, even though googlebot can see your SPA page, it takes too long to load. For deterministic results pre-render is a must.</li><li>Sharing in social media also triggers crawlers to visit your website, so it can generate those fancy tiles you are used to see when links are shared. Without the prerender all that is shared is the link, no tile.</li><li>Using pre-render adds extra costs to the to the ecommerce solution. You need to account for that. Costs increase the more pages you have and how often you re-cache them. Also, it is one more tool to maintain and integrate with, thus operational costs also increase.</li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=f5e9687cbaac" width="1" height="1" alt=""><hr><p><a href="https://blog.product-league.com/unveiling-seo-strategies-for-outsystems-reactive-apps-part-1-f5e9687cbaac">Unveiling SEO Strategies for OutSystems Reactive Apps — Part 1 — Pre-Rendering</a> was originally published in <a href="https://blog.product-league.com/">ProductLeague</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Failing on our own way]]></title>
            <link>https://blog.product-league.com/failing-on-our-own-way-92a0b1450659?source=rss-afb33469c210------2</link>
            <guid isPermaLink="false">https://medium.com/p/92a0b1450659</guid>
            <category><![CDATA[exception-handling]]></category>
            <category><![CDATA[outsystems]]></category>
            <category><![CDATA[outsystems-development]]></category>
            <dc:creator><![CDATA[Ivo Gonçalves]]></dc:creator>
            <pubDate>Tue, 19 Oct 2021 10:12:45 GMT</pubDate>
            <atom:updated>2021-10-19T10:47:22.509Z</atom:updated>
            <content:encoded><![CDATA[<p>One of these days I was talking with <a href="https://www.linkedin.com/in/rucoutinho/">Rui Coutinho</a> when the conversation drifted towards the question “how do you learn?”.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/220/0*s0xJuIG_4lPj1-zA.gif" /><figcaption>Oh man, this is hard</figcaption></figure><p>Rui told me he really enjoys reading personal experiences, not only the nitty gritty details, but also the perspective of who’s on the other side: what was the problem, how was the solution reached, what other solutions were considered, etc. You get the point.</p><p>Inspired by this conversation I decided to share one personal experience. As you might have guessed by the title (not really), this story is about exceptions in the wonderful world of OutSystems. Hopefully it will help others that might come across the same problem.</p><h3>The beginning</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/200/0*w-frkM1nnw-pIhLk" /></figure><p>In this particular project, that I’m using as reference, we have adopted the standard <a href="https://success.outsystems.com/Support/Enterprise_Customers/Maintenance_and_Operations/Designing_the_Architecture_of_Your_OutSystems_Applications/The_Architecture_Canvas">OutSystems architecture guidelines</a>. So far so good, nothing fancy here.</p><p>In our core services we enforce the concept rules. Some examples of enforced rules could be:</p><ul><li>Creation date cannot be in the future;</li><li>Id cannot be null;</li><li>Username and password cannot be the same;</li><li>GUID is unique;</li><li>…</li></ul><p>The question now is, what do we do when something goes wrong?</p><ul><li>Do we throw an exception?</li><li>Do we use error codes? If yes, which error codes do we support?</li><li>Do we use a boolean output parameter to inform if the action executed successfully?</li></ul><p>We all have been there done that, am I right?</p><h3>Initial Approach</h3><p>It was decided that core services would always have, at least, 2 output parameters:</p><ul><li>Result — boolean indication if the action executed successfully or not</li><li>ErrorMessage — detailed error message in case of error</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/462/1*zbohewVLO6t_dxrI66INRg.png" /><figcaption>Example of a core service enforcing the concept rules</figcaption></figure><p>Then is up to the consumers to validate the output parameters and decide what to do:</p><ul><li>handle the error</li><li>throw an exception</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/457/1*Oa2kr_niPulzMjC704-uZA.png" /><figcaption>Example of how core service validation is handled</figcaption></figure><h3>Does it really work?</h3><p>Most of you should be familiar with this pattern, from my experience this is a fairly common approach. Implementation is simple, easy to understand, no shenanigans involved, so we should be fine, right? Yeah, it works, but does it really work?</p><h4><strong>Does it do anything?</strong></h4><p>Looking at the code I noticed that most of the times, the error was not being handled at all. Consumers were just throwing an exception if <strong>Result = False </strong>until eventually the exception reached the global exception handler and failed gracefully. Global exception handler is the real champion here, no one else cares about exceptions.</p><h4><strong>Oh boy it gets more complex</strong></h4><p>As the code became more complex, validations started to add even more complexity. Hypothetically, if you have an action calling 5 different actions from core services, you need 5 if statements to validate the result of each one of them. Instead of an action with a begin/end and 5 calls to core service actions, you end up with 5 additional if statements and 5 additional exception throws. The more action calls you add the more complex it gets. Complex actions required some next level skills to accommodate so many validations.</p><h4><strong>Is this a bug?</strong></h4><p>Once I got a report of a bug that I immediately dismissed: after all that kind of behavior should break the application, which we would see in the logs. “Typical service desk, you should do a better job finding the root cause of the problem”, I said to myself.</p><p>The incident escalated, more people started complaining about the problem, no more excuses, time to hit the debugger.</p><p>After many hours of debugging (I’m serious, it was hours), the problem was due to an unhandled exception. One core service action was called but the output parameter, the Result, was not being validated. And that folks, is how an exception managed to go unnoticed for a few weeks (some might say months).</p><p>Needless to say we had more incidents related with missing validations. In one of them, the bug was within the core service action. The Result parameter was not being set to false in case of an exception. No false, no exception.</p><h3>What lead us here?</h3><p>Since OutSystems does not support <a href="https://www.outsystems.com/ideas/100/allow-custom-exceptions-to-be-public-and-referenced-from-other-espaces/">public exceptions</a>, it becomes tricky whenever you have a valid use case to handle one. With this approach you can decide what to do with the exception by looking at the output parameter Result.</p><h4><strong>Things become more interesting</strong></h4><p>One day we got a request that would require us to rethink our exception mechanics inside the core services. We had one core service that could throw multiple exceptions and we wanted to handle just one of them. But how could we understand the underlying exception?</p><h3>Next steps</h3><p>We though of multiple things, I don’t recollect all the details anymore, but one of the things we thought about was extending our implementation, maybe add an additional parameter with the error code. This way one could simply look at the code and handle those that made sense.</p><h4><strong>Is this really where we wanna go?</strong></h4><p>Extending our logic to handle exceptions would not rid us of the other issues I mentioned before. If anything, it would add even more complexity.</p><h4><strong>Let’s ask some basic questions</strong></h4><p><strong>Q:</strong> How would you address this if there were no limitations on the platform?</p><p><strong>A: </strong>I would make exceptions public and trap the exception type I needed.</p><p>Won’t work, next!</p><p><strong>Q:</strong> How would you do it in another language?</p><p><strong>A:</strong> I would throw a certain exception and trap it if needed.</p><p>Dammit, I see no future here. One more question.</p><p><strong>Q:</strong> Can we typify exceptions so we can handle them?</p><p><strong>A:</strong> Hmm, I don’t know, can we?</p><h3>This is how we do it</h3><p>After some reflection we found a way to typify exceptions, we made a <a href="https://www.outsystems.com/forge/component-overview/10608/exception-handling-extended">component</a> out of it, and we have been using it with success.</p><p>We created a LIB module, with a public API for some common generic exceptions.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/399/1*LCTMqXHDhwuEZRFUEBGf-Q.png" /><figcaption>Generic exceptions</figcaption></figure><p>Each generic exception has 2 actions, one for throwing the exception and another one to validate if an exception is of that type.</p><p>In the core services we call the correspondent throw exception action.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/407/1*Qp5yXT8xTu1PpIEmS77R9A.png" /><figcaption>Input validation</figcaption></figure><p>No need to assign the output variables, just throw the desired exception. This way you won’t force consumers to validate the output, if they don’t care about the exception it will end up in the global exception handler and fail gracefully. Remember the previous example of the action with the 5 core actions inside? That’s what you get, an action with 5 calls to core service actions, no more need to have if statements.</p><h4>If I want to trap the exception</h4><p>Consumers can then trap all exceptions, validate its type and react accordingly.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/390/1*8KH7juhMBB0NF5_uFRy7CQ.png" /><figcaption>Exception type being handled</figcaption></figure><p>You still have to re-throw the exception if it is not the type you wanna handle, it sucks, but we could not find a better way.</p><h4>But I need other exception types, this won’t suit me</h4><p>We faced this same dilemma. We needed some business exceptions and we wanted to avoid adding them to this LIB. We wanted this LIB to be as stable as possible, we wanted to minimize the impact on other domains.</p><p>We have added 2 actions that you can use create your business/domain exceptions:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/242/1*ZyNY3VGvWxrt6cXE-jSz3A.png" /><figcaption>Application defined exception API</figcaption></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/339/1*aaNGYxJCq1is5AyFrmPAmQ.png" /><figcaption>Domain exceptions implementation</figcaption></figure><p>Unfortunately forge does not allow to bundle different applications in one component. We built a template so you can start defining your own exceptions. You just have to create a new module, pick the template and then you have the boiler plate code to customize your business/domain exceptions. Easy peasy.</p><h3>What’s next</h3><p>Hopefully in due time this <a href="https://www.outsystems.com/forge/component-overview/10608/exception-handling-extended">component</a> will be thrown away, meaning that we either find a better approach or OutSystems releases a new version allowing public exceptions. In the meantime, we’ll keep using this approach: despite its flaws, it is something that works for us.</p><p>I’d love to hear from you, how have you been dealing with exceptions in the wild? How many approaches have you seen?</p><p>This is one of these topics we deal within pretty much every single project, however I’ve never seen a consensus regarding it.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=92a0b1450659" width="1" height="1" alt=""><hr><p><a href="https://blog.product-league.com/failing-on-our-own-way-92a0b1450659">Failing on our own way</a> was originally published in <a href="https://blog.product-league.com/">ProductLeague</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[A tale of trust…]]></title>
            <link>https://blog.product-league.com/a-tale-of-trust-6590d9d013ff?source=rss-afb33469c210------2</link>
            <guid isPermaLink="false">https://medium.com/p/6590d9d013ff</guid>
            <dc:creator><![CDATA[Ivo Gonçalves]]></dc:creator>
            <pubDate>Wed, 21 Oct 2020 07:03:10 GMT</pubDate>
            <atom:updated>2020-10-21T09:17:32.413Z</atom:updated>
            <content:encoded><![CDATA[<p>And how your weekend gets ruined.</p><p>If you have ever worked with the OutSystems PaaS [<a href="https://www.outsystems.com/evaluation-guide/outsystems-cloud-services-overview/">1</a>], the chances are, at some point in time you had to deploy a new SSL certificate for your domain. Deploying a new SSL certificate, in the OutSystems cloud, is a mundane task [<a href="https://success.outsystems.com/Support/Enterprise_Customers/Installation/Use_your_SSL_domain_in_OutSystems_Cloud">2</a>]. The OutSystems console is straightforward and does all the heavy lifting for you. With the power of a few clicks you can deploy a new certificate in just a few minutes.</p><p>A few days ago I got a request to update the SSL certificate in order to support a new domain. Easy-peasy I thought. Fast forward to Friday, I finally got the new certificate.</p><h4>Easier than taking candy from a baby</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/480/0*fvSJSsiIOBRtqI2A" /></figure><p>It’s almost weekend time. Before I could formally finish my work day I still had one more task to do, deploy the new certificate. In a matter of minutes I managed to:</p><ol><li>Deploy the new certificate;</li><li>Smoke test a few applications;</li><li>Validate the certificate.</li></ol><p><strong>All my checks passed. Time for a beer.</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/188/1*wBbCuwmGzUUwS1Gyp1-jAA.png" /></figure><h3>Things go south</h3><p>By now we we have established 3 things:</p><ol><li>I like The Simpsons;</li><li>I like beer;</li><li>I was cocky.</li></ol><p>Sunday evening I opened my mailbox to have a sneak peak of how my Monday would look like. To my surprise I noticed a bunch of incidents that have been created during the weekend. All of them seemed to be related and have a common denominator: mobile applications were not working. Users were getting a generic error while opening the app and not being able to move on.</p><p>Immediately had a gut feeling the problem was somehow related to my Friday’s change — the cockiness backfired.</p><p>As soon as I spotted the problem I spammed the dev team Slack channel. In a matter of minutes I got a reply with the root error message: “<strong><em>Trust anchor for certification path not found</em></strong>”. By now even a kid would know what to do, rollback the change was done immediately and surprise, surprise, the problem was gone.</p><h3>Root cause analysis</h3><p>As I mentioned earlier I did some checks after deploying the certificate. So how on earth did mobile applications break? The error message already points towards the root cause, which is the chain of trust [<a href="https://www.ssl.com/faqs/what-is-a-chain-of-trust/">3</a>]. I won’t go into details about what a chain of trust is, the article I referenced does it very well, but in a nutshell a chain of trust indicates how your certificate is linked to trusted CA (certificate authority).</p><p>The certificate I was given to deploy had a standard chain of trust structure:</p><ol><li>Root certificate;</li><li>Intermediate certificate;</li><li>My domain certificate.</li></ol><p>Additionally, I also knew that:</p><ol><li>Certificate was valid on my machine;</li><li>Certificate’s chain of trust was invalid in mobile devices.</li></ol><h3>Time to validate the chain of trust</h3><p>I found online a few websites that allow you to validate your certificate’s chain of trust [<a href="https://tools.keycdn.com/ssl">4</a>]. The site in question can validate a certificate in a PEM format.</p><p>I had with me a certificate in a PFX format, so I used OpenSSL to convert the format to PEM:</p><p>“<strong><em>openssl pkcs12 -in &lt;pfc_certificate&gt; -out &lt;cert_name&gt;.pem -nodes</em></strong>”</p><p>Having the PEM certificate I edited the file and removed everything except the BEGIN CERTIFICATE &amp; END CERTIFICATE tags. (<strong>NOTE</strong>: pay special attention to the PRIVATE KEY tag, you do not want this to be shared anywhere since it will compromise your certificate).</p><p>Unsurprisingly, while validating my certificate, I was presented with the following message:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*J2b6RDEUPMDj95ua" /></figure><h3>The missing intermediate certificate</h3><p>A certificate can be prepared to include the whole chain. When the certificate chain is incomplete (e.g. missing the intermediate certificate) it might be a problem. In case of a missing intermediate certificate, most likely, your device will try to complete the incomplete chain using their own certificate store. If the missing certificate exists on your machine you probably won’t have any problem.</p><p>I did some digging on my computer certificate store and I could find the intermediate certificate. So, how do I check mobile devices (Android &amp; iOS)? Luckily that information can be found online:</p><ul><li>Android [<a href="https://android.googlesource.com/platform/system/ca-certificates/+/master/files/">5</a>]</li><li>iOS [<a href="https://support.apple.com/en-us/HT209144">6</a>]</li></ul><p>In those lists I could not find the intermediate certificate. Unless the device user had it manually installed, it would not be possible to validate the chain of trust on my domain certificate. At this point the solution is pretty obvious, I’ll need to install a new certificate that includes the intermediate certificate.</p><p>Just to make sure I was looking at this the right way, I executed the same chain of trust validation for the old certificate. That certificate included the intermediate certificate and therefore posed no problem at all.</p><h3>Lessons learned</h3><p>While doing a post-mortem, I immediately realized a few things to improve in order to prevent this from happening again:</p><ol><li>Before deploying the certificate validate it on your machine;</li><li>Make sure the chain of trust is valid;</li><li>Smoke test all types of applications (traditional, reactive and mobile);</li><li>Proactively monitor your environment;</li></ol><p>And above all, don’t be cocky.</p><h3>Reference</h3><p>[1] OutSystems Cloud Services Overview OutSystems, <a href="https://www.outsystems.com/evaluation-guide/outsystems-cloud-services-overview/">https://www.outsystems.com/evaluation-guide/outsystems-cloud-services-overview/</a></p><p>[2] Use your SSL domain in OutSystems Cloud, OutSystems, <a href="https://success.outsystems.com/Support/Enterprise_Customers/Installation/Use_your_SSL_domain_in_OutSystems_Cloud">https://success.outsystems.com/Support/Enterprise_Customers/Installation/Use_your_SSL_domain_in_OutSystems_Cloud</a></p><p>[3] What is a chain of trust, ssl.com, <a href="https://www.ssl.com/faqs/what-is-a-chain-of-trust/">https://www.ssl.com/faqs/what-is-a-chain-of-trust/</a></p><p>[4] Certificate Checker, keycdn, <a href="https://tools.keycdn.com/ssl">https://tools.keycdn.com/ssl</a></p><p>[5] Android certificate store list, Google, <a href="https://android.googlesource.com/platform/system/ca-certificates/+/master/files/">https://android.googlesource.com/platform/system/ca-certificates/+/master/files/</a></p><p>[6] List of available trusted root certificates in iOS, Apple, <a href="https://support.apple.com/en-us/HT209144">https://support.apple.com/en-us/HT209144</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=6590d9d013ff" width="1" height="1" alt=""><hr><p><a href="https://blog.product-league.com/a-tale-of-trust-6590d9d013ff">A tale of trust…</a> was originally published in <a href="https://blog.product-league.com/">ProductLeague</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[OutSystems Platform Upgrade 101]]></title>
            <link>https://blog.product-league.com/outsystems-platform-upgrade-101-455881babad3?source=rss-afb33469c210------2</link>
            <guid isPermaLink="false">https://medium.com/p/455881babad3</guid>
            <category><![CDATA[outsystems]]></category>
            <category><![CDATA[software-testing]]></category>
            <category><![CDATA[outsystems-development]]></category>
            <category><![CDATA[software-architecture]]></category>
            <dc:creator><![CDATA[Ivo Gonçalves]]></dc:creator>
            <pubDate>Tue, 14 Jul 2020 07:10:53 GMT</pubDate>
            <atom:updated>2020-07-14T07:10:53.227Z</atom:updated>
            <content:encoded><![CDATA[<p>When it comes to upgrading your software, tools and programs, the OutSystems platform is no different. New and improved versions are released and, at some point, you want to make sure you are using the latest version so you can fully leverage its power.</p><p>On the 31st of December, OutSystems will no longer support any older version of the platform. But what does this mean?</p><p>According to OutSystems itself:</p><p>“<em>OutSystems technical support team will continue to help you when you submit support requests. If technical support identifies Urgent or High issues in the product with no acceptable workaround during the extended support phase, the resolution may still include bug fixes in O10. After that period, if a bug is the problem, technical support’s response will not include a bug fix. In this scenario, problem-solving will only include advice and workarounds. To avoid this situation, we recommend that upgrades happen before the scheduled end of mainstream support.</em>” — <a href="https://success.outsystems.com/Support/Enterprise_Customers/OutSystems_Support/End_of_Mainstream_Support_for_OutSystems_Platform_10">link</a> [1].</p><p>This article is not going to guide you through a complete OutSystems upgrade — that would require detailed analysis and knowledge about how your company is using the platform and your release cycles. Instead, this article’s intention is to share some personal experience and concerns while executing an OutSystems upgrade — in the hope to create some awareness, and that you know at least where to start.</p><h3>Upgrading is not a minor action</h3><p>Unfortunately, there is no one-click upgrade button for a simple upgrade, especially when it comes to upgrading a platform. Besides new and cool functionality, new product releases may introduce breaking changes, as existing interfaces may need to change, in order for the product to evolve.</p><p>When we are talking about the OutSystems platform, we are talking about a product that allows you to build new products. So you want to make sure that the upgrade does not impact your application portfolio, and consequently, your customers… Even when no breaking changes are documented, you still want to ensure business goes on as usual, and there is no unforeseen side effect to your software.</p><p>Ok, so now you must be feeling worried… Great!</p><p>Awareness is the first step of a successful upgrade. The second step is to transform those worries into a plan. Planning allows you to do impact analysis, risk assessment, and determine when and how to upgrade your platform with minimal impact to your business.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/813/0*8CAWGMearoOav4eA.png" /><figcaption>OutSystems infrastructure overview</figcaption></figure><h3>When should I upgrade?</h3><p>Some organizations always want to be on the cutting edge and are always on the latest version — trading stability (of the old version) for innovation (of the new version). These companies are always looking for the new release and join OutSystems early access programs.</p><p>Others are more conservative and are one (or more) versions behind the latest. This ensures a more stable version but may be missing the innovation that may differentiate their business from the competitors. Unfortunately, these customers may also miss important security upgrades, exposing their applications to new vulnerabilities.</p><p>My recommendation is to be at least on the latest major version (keeping up with all the revisions may be excessive), so you can fully leverage the platform’s capabilities. Experience tells me that, the further behind you are, the more complex and risky the upgrade will be, so you want to avoid that scenario by keeping your OutSystems platform up to date. As mentioned before, remember that OutSystems will no longer support older platform versions after the 31st of December.</p><h3>Upgrade Process</h3><p>OutSystems understands the risks behind an upgrade, so it guides her customers to make this process as simple as possible — there is extensive online <a href="https://success.outsystems.com/Support/Enterprise_Customers/Upgrading/01_Upgrade_OutSystems_Platform">documentation</a> [2] on this topic.</p><p>You can break down your upgrade into a 4 step approach — this approach combines the OutSystems guidelines and personal experience:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*VLrTsMUYX_yNIShT.png" /><figcaption>4 step upgrade approach</figcaption></figure><h4>A. Upgrade Assessment</h4><p>Keep in mind that upgrade complexity increases mostly with two factors:</p><p><strong><em>Assess your current landscape</em></strong><em>:</em></p><ul><li>What is your current platform version?</li><li>What is your Infrastructure? Are you in the cloud or on-premise?</li><li>How many applications do you have? Which ones are mission critical?</li><li>Any third-party integrations?</li></ul><p><strong><em>Define where you wanna go and what is impacted:</em></strong></p><ul><li>What is the target platform version?</li><li>How documented breaking changes may affect your current applications?</li><li>Does the upgrade imply new infrastructure requirements?</li></ul><p><strong><em>Identify your upgrade window</em>:</strong></p><ul><li>Do you have any mandatory release cycles?</li><li>How will the upgrade timeline impact your ongoing projects?</li><li>Can you have downtime, when and for how long?</li></ul><h4>B. Upgrade Strategy</h4><p>After the initial assessment, it is time to define your upgrade strategy.</p><p>The main goal of this step is to make the decisions that allows you to mitigate the upgrade risks and reduce related costs. For example, you need to decide:</p><ul><li>Environment upgrade sequence: typical upgrade sequence (LifeTime, Development, Test, Pre-Production and Production) vs. a custom sequence;</li><li>Upgrade applications: how do you upgrade your applications? There are multiple ways to do it, from upgrading all applications in each one of the environments, to doing it just once (Dev) and staging it further;</li><li>Production Release Strategy: Zero downtime vs. downtime approach;</li><li>Breaking changes: some breaking changes can be solved in the current version, should you plan for that to happen before the upgrade starts?;</li><li>Development freeze: which applications stop first and for how long? Will the teams also be frozen or will they contribute, for example, by solving the breaking changes?;</li><li>Define which teams are working on the upgrade, and their responsibilities: Infrastructure team, development team, operations team, testing team, etc;</li><li>Deal with the unexpected: how to handle critical production issues during the upgrade?</li></ul><h4>C. Plan Definition</h4><p>The upgrade plan is the instantiation of your upgrade assessment and strategy. At the end of this step, you have a clear high-level overview of the entire upgrade. Make sure your plan is as detailed as possible:</p><ul><li>Split the upgrade into smaller, actionable upgrade moments. Each moment must have a clear goal and a deliverable. E.g: Solve breaking changes for application A, upgrade Development, Test application B, etc.</li><li>Create checklists for the critical steps inside a moment. Include all details for the necessary steps to execute the upgrade. It’s the best way to make your plan actionable: everyone knows what to do and when.</li><li>Upgrade timeline. Define dates for the complete upgrade and for each upgrade moment. Everyone involved must know the target date and how long the entire upgrade will take.</li><li>Define ownership and accountability. Put the names of the teams and their members in the plan, to ensure responsibilities are clear.</li><li>Identify team dependencies. Examples: In a multi-project software factory, it’s fundamental that all the PO’s agree on a timeline to minimize the impact of the release cycles; The testing phase cannot start before the breaking changes are executed by the delivery team, etc.</li><li>Plan regular status meetings. To promote alignment and discuss eventual adjustments.</li></ul><h4>D. Plan Execution</h4><p>The final step is, of course, the execution. The more complete your plan is, the smoother the execution will be. A plan with a lot of variables tends to be a lot more unpredictable, opening the door for failure.</p><p>If something goes wrong, do not panic — regroup and revamp your plan. Of course, now you are running against the clock… so it’s always better to invest more time in the preparation phase.</p><h3>Wrap-up</h3><p>Hopefully this article will help you not to oversimplify the platform upgrade but provide you with insights and attention points for a successful upgrade! There’s much more detail to add in each one of the steps that we mentioned. For those we advise you to take your time and analyse the best upgrade option considering your landscape.</p><p>For you to be successful, planning is fundamental. Even if you have a simple landscape, you should not skip writing an upgrade plan. As long as you invest the proper time and resources, the platform upgrade should be just another side project.</p><p>As final note, we at <a href="https://product-league.com/">Product League</a> have an Expert Services portfolio that supports our customers in multiple areas, including a specific Platform Upgrade Program, where we combine the OutSystems guidelines with our field experience. Should you need hands-on help on this process, feel free to reach out to us.</p><h3><strong>Authors’ Contributions</strong></h3><p>This article was jointly written with <a href="https://www.linkedin.com/in/rucoutinho/">Rui Coutinho</a>.</p><h3>References</h3><p>[1] End of Mainstream Support for OutSystems Platform 10, OutSystems, <a href="https://success.outsystems.com/Support/Enterprise_Customers/OutSystems_Support/End_of_Mainstream_Support_for_OutSystems_Platform_10">https://success.outsystems.com/Support/Enterprise_Customers/OutSystems_Support/End_of_Mainstream_Support_for_OutSystems_Platform_10</a></p><p>[2] Upgrade OutSystems Platform, OutSystems, <a href="https://success.outsystems.com/Support/Enterprise_Customers/Upgrading/01_Upgrade_OutSystems_Platform">https://success.outsystems.com/Support/Enterprise_Customers/Upgrading/01_Upgrade_OutSystems_Platform</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=455881babad3" width="1" height="1" alt=""><hr><p><a href="https://blog.product-league.com/outsystems-platform-upgrade-101-455881babad3">OutSystems Platform Upgrade 101</a> was originally published in <a href="https://blog.product-league.com/">ProductLeague</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
    </channel>
</rss>