Best Practices
This section addresses the fundamental guidelines for the use, modelling, and manipulation of data in Studio aligned with the specified pillars.
Applying best practices enable clearer, more consistent, and efficient token management throughout the solution. These recommendations seek to minimize errors, facilitate maintenance, and improve interoperability to promote consistent building across projects.
General best practices bring together cross-cutting recommendations for using tokens in Studio that have a direct impact on the clarity and organization of tokens when building an app. The aim is to avoid common errors, promote a coherent structure and facilitate maintenance.
Considerations:
Use alias functionality for global tokens (IDs < 1000), following variable naming best practices. Currently, along with the creation of the environment, several reserved tokens are specified.
Important
Aliases are declared at the environment level and affect all entities that use them (apps and modules).
Use reserved tokens only for their intended purpose. Reserved tokens have specific behavior within the platform. Using them for other purposes may result in unexpected behavior or errors that are difficult to track.
To represent structures with multiple attributes (such as an account, address, user, etc.), it is recommended to use arrays, assigning each attribute to a column. This approach simulates the behavior of a data structure, favors decoupling between entities, and allows information to be extended without breaking contracts, simply by adding new columns.
Correct token segmentation and management in Studio is key to ensuring application order, consistency, and scalability.
The strategy proposed in this section allows for anticipating conflicts, facilitating maintenance, ensuring consistency across projects, and aligning the data model with cross-cutting initiatives such as Lambda Front and States.
Considerations before using tokens:
Determine which segment it belongs to, depending on the type of information it will handle.
Verify that the token is not in use by:
Checking the Excel of token documentation.
In case of global tokens, checking the alias functionality.
In active environments, using the Used In option. Note that for global tokens, search across all apps and modules, both by alias and numeric ID.
Update the documentation, registering the new token in the corresponding Excel file.
Important
Tokens that can be reused in screens and flows (e.g. Presentation and Inline Lambda tokens) should be cleaned up after use to avoid interference or unwanted behavior.
The volume and manner in which data is manipulated can significantly impact application performance. Find a list of recommendations below:
Avoid large arrays: It is recommended to avoid using arrays with a large number of rows or columns in the channel. Although there is no exact technical limit, as a good practice one should not manipulate arrays with more than 150 rows or more than 15 columns , it can already negatively affect screen loading and user experience.
Paginate from transaction: Transactions returning arrays should be designed to support paging, allowing the number of records returned to be limited.
Avoid heavy calculations or filtering in the channel: Operations such as filtering and sorting should preferably be performed in the backend (transaction).
Initialize needed tokens: It is recommended to initialize only the tokens needed in each context. Loading unnecessary tokens from startup can slow down screen rendering or logic execution.
Clean up unused tokens: Clean up tokens that are no longer used, especially if they contain large data such as documents, images, or large arrays. Keeping these tokens in memory can affect the overall performance of the app.
While there is a document dedicated exclusively to security guidelines, it is important to highlight some general considerations that should be kept in mind when handling data within the platform.
It is strongly suggested to avoid storing sensitive data or data subject to regulation, whether international, national, or by customer policies, on the device or host (persistent tokens, cache, databases, etc.). This includes, but is not limited to:
personally identifiable information (PII);
financial data;
credentials;
authentication tokens; and/or
any data protected by confidentiality agreements.
In cases where it is strictly necessary to retain this type of information, appropriate encryption must be applied, and retention time and access mechanisms must also be evaluated.
When an entity (such as a module or a transaction) exposes an interface, a contract composed of input and output tokens is established. These contracts determine how other entities (such as Lambda processes and screens) can interact.
It is essential that these contracts be clear, stable and declarative. Poor design—for example, using a single token with a nested JSON object for multiple attributes—increases coupling and complicates both maintenance and evolution of the solution. This can also lead to hard-to-track errors when attributes are modified within those objects.
Additionally, any change to the contract impacts all invocations to that entity, which may require adjustments in multiple places in the solution (for example, adding a new input to a transaction requires modifications to all Lambda processes that invoke it).
Considerations:
Use explicit and declarative tokens in contracts. Avoid passing complex structures (such as JSON objects) in a single token. Instead, break down the information into individual tokens, clearly representing each expected field or parameter.
In transactions, any token that is to be updated and consequently returned must be explicitly declared as part of the output contract. This practice ensures clarity, predictability, and facilitates both the maintenance and validation of contracts. Although Studio technically allows you to set any token, informing the channel that made the invocation, this represents a bad practice.
Design stable and evolving contracts. Before submitting a contract, check that it covers current requirements without leaving any fields that are "temporary" or unclear. If new parameters need to be added in the future, consider controlled evolution strategies (e.g., maintaining backward compatibility if applicable).
Reuse common structures when it makes sense. For example, if multiple modules use the same combination of data (user, email, ID), consider encapsulating it in a reusable structure—while still maintaining the clarity of the individual fields exposed in the contract. Although structures do not exist, as previously mentioned, they can be emulated with arrays.