How to create One Single Generic Action to Override OutSystems REST Request?
In this article, I will explain the value, and benefits of creating encapsulated and generic actions.
When I started my career as a software developer, I remember how fascinated I was when I learned how to use in c# generics classes and polymorphisms (a common concept in an object-oriented language). After 8 years of working with OutSystems, shifting between roles, between a developer, tech-lead, architect, and working with teams around the world, I saw many failures in the coding of functions/actions which were not able to hold any good encapsulated logic that could be reusable throughout the application.
It seems there is hardly any effort to avoid creating duplicated code. The reason could be a lack of experience or misunderstood global vision of the project. However, the consequences of not taking care of this can lead to plenty of duplicated code, poor level of abstraction and losing scalability for the project. Supporting duplicated code wastes time because often in projects like these, once you solve a bug, you are likely to create another one. If you have worked on the maintenance code, you have probably faced this problem.
My thought always was driven to create everything to be reusable, easy to maintain and flexible. Even though OutSystems does not allow to have generics nor polymorphisms concepts, it does not mean we cannot apply a few concepts of “OO” (object-oriented) and find a way around. For example, having the variables with the identical type, help us to assign the right values and avoid overlooking errors. It is essential to try to take in these kinds of nuances and implement it. Also, give the actions their own life and think “how could this new action be reusable among my flows?”
We should think more about our structures
Creating a structure is simple and easy to go with. It is important to create awareness of the importance of keeping a pattern such as structure’ names, attributes’ names and attributes’ types. In the old days, to build an architecture in c#, we usually created a class diagram just the way we still do with ER model to draw the application. I do not really believe we need to create diagrams for structures in OutSystems, but we need to consider structures as an important key in the success of a good abstraction and maintainability.
For the next few paragraphs, I’d like to offer a helpful example of creating abstraction and taking the best of OutSystems structures to avoid duplicated code and keep a pattern. For doing that it’s important to understand the context of our application sample.
The requirement says to have the REST’s URL, Users and Passwords configurable by tenants.
For each web service REST we have created, we can add an event action called <OnBeforeRequest> and this action, is followed by two variables created automatically. These variables allow us to get the values before we effectively do the request. The parameters such as BaseURL, User and Password are by default introduced in the Service Center and they cannot be changed at runtime. To visualize that, look the parameters need to be overridden on the left, and on the right, the structures were created by OutSystems.
At this point, it looks like we could develop the whole logic inside the <OnBeforeRequest> action, it will work but perhaps it’s not the best approach. We need to think we could have many RESTs or we already have, so we need a simple solution to implement that faster and easy to change.
I believe the suitable method here would be to have one single action to manage which values should be used in the BaseURL, user and password parameters, this action would work overridden all initials values. Let’s imagine if a hand full of RESTs integration have the same header as well, we could use this solution for adding or removing the values in just one place, so it would not be necessary all that logic inside each REST action.
Creating a single point action
To support that, I created a new service module that could also be a normal one. Looking into that, I built an action called <RestBuilder> which holds all logic to override our REST parameters. It is not a public action, so it will not be exposed to consumers and to turn it even more generic, I will get the new configuration based on the current base URL parameter which provides a unique identifier that I need to fetch my “configuration” from the database. It means to have somewhere an entity to relate the old URL with the NEW ONE and all other parameters including the tenant. The “Site.TenantId” property is in the session context, so it can be used to determine which settings to get.
Besides that, the structures that I mentioned before, the ones were created automatically by OutSystems, I had to copy these structures and I renamed them as “Header”, “inRequest”, “outRequest” and “URLQueryParameter”.
Now it’s time to create a service action to encapsulate the <RestBuilder>. The reason why I created a service action is to reap the benefits such as weak dependency and immediate effect over the implementation changes, it’s completing our “generic concept”.
Implementation
Back to the <OnBeforeRequest>, we need to reference into that the action service newly created <RESTOverride>.
Do you remember what I said in the beginning about structures and patterns? You will notice since the structures are identical and at least have the same columns, OutSystems will automatically suggest which value it’s possible to use to assign the values. The parameter InRequest is the only one that OutSystems does not advise, however as soon as you map that record OutSystems will automatically fill up the columns.
Once I have mapped the input values, it is also necessary to map the output values and assign them to the “CustomizedRequest” variable with the values that have returned from <RESTOverride> action.
Furthermore, since the OutSystems REST structure does not change among the RESTs, and once you have implemented it for the first web service you just need to copy and paste this snippet code among all <OnBeforeRequest>RESTs action to override them by that output. No more changes will be required because keeping a pattern of structures and following this model, OutSystems automatically suits all variables since we have been using the same name.
To come to the point, this example enlightens us the importance of avoiding duplicated code, providing a solution for specific propose. However, it can be applied to many other requirements. In OutSystems make a copy and paste is a common behavior we do it all the time, despite I suggest to do that as well. We need to strive do not make a copy of the main process but only from its call.
