Translated from Portuguese to English - www.onlinedoctranslator.

com

Outsystems Best Practices

(Quick Guidelines)
Introduction

This document is intended to summarize some typical guidelines and best practices
for any Outsystems project. It is organized according to Service Studio's own
interface (v9 used as a reference).

Timers and Processes (BPT)

Flows, Screens, WebBlocks, Variables,

Themes...

Actions, Roles, Exceptions, References...

Entities, Structures, Session Variables,

Site Properties, Resources...

1
processes

● In timers, it is good practice to create a site property “AllowExec” (eg

“Site.Timer_Shipment_List_AllowExec”) with the default value of “False” (depending on
the cases, the default value of “True” may be useful), so that to protect the timer from
running after passing to other environments, among other examples.

This siteproperty can also be used anywhere in the code several times (eg
in cycles), this so that the user has some control over the timer and if it
has problems or has a long execution, it can stop it.

two
● Using Audits at Start, End and different flow decisions can help to control the iterations
of a timer (eg knowing how many records were processed and how many records were
rejected). With Audits it is possible to register each iteration in the General Log (Service
Center) through a customized message in Service Studio.
note:the number of Audits is limited per run ("Themaximumnumber (3000) of allowed
Audits per request has been exceeded. No more Audit messages will be logged in
current request."). In these cases we can have a counter and an IF that decides to
audit after X iterations and not all.

3
In the audit action it is possible to write a personalized message and identify it through a
ModuleName for later identification and filtering in the General Log (Service Center). (for
example. message-"------Timer_Shipment_AcceptReject [START] ------ (12:30:01 7/5/2016)",
ModuleName- "Timer_AcceptReject"). The ModuleName must be short as it has a limited
number of characters. In this example we purposely set the same timestamp (saved in a
local variable as soon as the timer is started) to facilitate the filtering of events in the
General Log (this makes it easier to identify all the messages related to a given execution).

During the process there may be records of decisions (eg."Shipment with

SAPShipmentId=21345 has been synced for acceptance/rejection! (12:30:20 7/5/2016)").

It is also good practice in the timer exception flow to use an Audit for execution control since if there
is an exception it will not be noticeable to the user. (for example."There was an error in
Timer_Shipment_AcceptReject SAPShipmentId: 23456 - It has already been synchronized ! (12:30:40
05/07/2016)")")

Once the beginning of the process has been registered, it is necessary to register the end
of it using the audit (eg."------ Timer_Shipment_AcceptReject [END] ------ 30 Shipments
successfully synced and 2 were not synced! (12:31:10 7/5/2016)").

4
Interface

● Use pattern for screen names with same prefix as per entity. Ex: Customer_List,
Customer_Edit, Customer_Show. Names must remain singular. note:Since the version9 that
defaults to the platform's default is: listing screens as the name of the entity in the plural
(Customers, Projects, ...) and the remaining screens without underscore, entity in the singular
and camelcase (CustomerDetail, ...)
However, the important thing is to have a common pattern throughout the project.
If it is a new project, adopt the 2nd approach, otherwise, keep the existing
pattern in the project.
● To identify record, record list and parameters (eg use the entity name by removing the “_”:
“Customer_Invoice” -> “rCustomerInvoice” or “rlCustomerInvoice”)
● Assign names to ShowRecords, EditRecords and TableRecords (eg
“srCustomerInvoice”,“erCustomerInvoice”,”trCustomerInvoice”, )
● Assign name to “Id” (eg “CustomerId”)
● Booleans use expressions like “Has” or “Is” (eg IsLoading, HasRole)
● Fill in the example expressions.

Good practice bad practice

● Avoid putting CSS in webblocks or screens, put it in the theme (in order to avoid
creating several CSS files). The same applies to Javascript functions.
note:to obtain a better optimization of theCSS on Platform 9: https://

www.outsystems.com/forums/discussion/14708/amsterdam-css-optimization/

● Avoid using too many local variables on the screens and too many input parameters in order to
avoid too heavy a viewstate.
● Pay attention to what to put in the preparation (eg avoid very heavy queries, do not load
binaries - fetch only the id and fetch the binary in the download action)
● Always associate respective roles to the screens.

5
● Validate input parameters and permissions in the preparation of screens (included
in Pop-ups). Depending on the context of the project, sometimes it is also necessary to
validate the state of the process that may or may not be allowed on that screen. in the
URL, but we were also easily able to tamper with AJAX requests and form submission).

Good practice bad practice

● Use TOP1, in case you just want a record (eg fill in an Edit Record)

6
● In Advanced Queries, whenever you don't want to reuse all attributes of entities,
use structures.

Good practice bad practice

● Avoid circular references between eSpaces in order to avoid errors in publications of

eSpaces as well as the solution.
note:to delve deeper into this topic, it is important to take into account the architecture4
Layer Canvas:
https://success.outsystems.com/Support/Enterprise_Customers/Maintenance_and_Oper
ations/Designing_the_architecture_of_your_OutSystems_applications/Application_compo
sition/01_Applying_the_4_Layer_Canvas_to_applications

In addition, the applicationdiscoveryit is fundamental to detect cyclic references

between modules or applications:
https://www.outsystems.com/forge/component/409/discovery/

7
● If you intend to use test or debug screens, create a flow for that purpose. Create a site
property “AllowDebug” with the default value of “False” and protect all screens with a site property
no preparation (in addition to just associating the role administrator with the screen).

● Site Properties created with default values intended for the Production
environment. In development, later change in Service Center to the intended
value to test.
● Right-aligned exceptions.

● Query Optimization:
○ “EXISTS” instead of “IN”:

■ “EXISTS” must be used when the result of the sub-query has many
records.
■ “IN” must be used when the result of the sub-query is few records or
fixed.
○ Avoid “For Each”, if possible do everything in an Advanced Query.
○ Use SQL STUFF to get a comma-separated list of records (Ex:
1,2,45,34,56,67,87)

8
○ Auxiliary queries (WITH Table1 AS (QUERY))
The auxiliary table Table1 can be used in another query (in the
same advanced query), as if it were a real table.

9
● When a data base exception occurs, it is registered in the ServiceCenter through
the session variable. Since the message is always the same, for each situation it is
possible to test, using an IF, whether it is that exception that is being thrown and in this
way proceed with the treatment. (for example. "Index(Upper
(Session.ExceptionMessage),Upper("The DELETE statement conflicted with the
REFERENCE constraint")) <> -1)”).

10
logic

● Code and comments in English.

● Maintain vertical main flow and equal spacing and alignment between components.

Good practice bad practice

11
● If = True vertically (bottom), If =False horizontally (always possible to the right).

Good practice bad practice

● Leave comments when the code is not understandable or when it is complex.

12
● Always fill in Names and Descriptions (actions, assigns, site properties, etc...)

Good practice bad practice

● Always identify the elements (whether If's, msg feedback, for each, etc...)

Good practice bad practice

● Variables or parameters with inline SQL or to be used in queries include the “SQL”
expression (eg “SQLShipmentStatusIds”).
● Code cleanup, delete unused actions and reference. note:
from the latest versions of the platform:
○ 8.0.1.65;
○ 9.0.1.65;
○ 9.1.501.0;
○ 10;
there is a new feature in Service Studio to make it easier to
remove references that are not being used in eSpace.
http://www.outsystems.com/ideas/167/remove-all-unused-references (Outsystems-06-
07-2016: “Bytheway,wearealsoworkinginhavingwarningswhenyou have unused
actions, variables, inputs, etc!!”)
● Organization of actions by categories (creation of folders).

13
● Use TOP1, in case you just want a record (eg fill in an Edit Record)

14
● In Advanced Queries, whenever you don't want to reuse all attributes of entities,
use structures.

Good practice bad practice

● Right-aligned exceptions.

15
● Query Optimization:
○ “EXISTS” instead of “IN”:

■ “EXISTS” must be used when the result of the sub-query has many
records.
■ “IN” must be used when the result of the sub-query is few records or
fixed.
○ Avoid “For Each”, if possible do everything in an Advanced Query.
○ Use SQL STUFF to get a comma-separated list of records (Ex:
1,2,45,34,56,67,87)

○ Auxiliary queries (WITH Table1 AS (QUERY))

The auxiliary table Table1 can be used in another query (in the
same advanced query), as if it were a real table.

16
Date

● Check the DeleteRule of foreign keys in order to avoid errors with related records.
Choosing the “Delete” option causes related records to be deleted as well. (Cascade
DELETE).

● In each project it is important to define a set of messages that can be very reusable in
feedback messages and beyond. One of the ways to apply this definition is to create a set of
site properties in one of the CORE eSpaces to the project:

In order to be reused in other eSpaces, a structure can be created

and the respective action that will consume the messages

17
One of the most important examples of using this action will be the
“Msg_GeneralError“, as it will replace the untreated message generated by the application
(“Session.ExceptionMessage”), which would be presented to the end user. A message
that, in addition to being an “ugly” message, would be of little use to that user.

Good practice bad practice

18