How to use List built-in functions in Outsystems?

If you have been working with OutSystems for a while, you might already be familiar with some of its built-in functions. If you are new to OutSystems, it can be extremely helpful to learn how to use these built-in List functions. You can find the official documentation for the List functions here.

Prerequisite
- A table with various values to test the functions on your own.

What will be covered
1. ListFilter / ListSort

2. ListAll / ListAny

3. ListAppend / ListAppendAll

4. ListClear / ListDuplicate

5. ListIndexOf / ListInsert / ListRemove

6. How to use it in real case scenarios?

Some of the built-in functions are grouped into categories. For each function, you will see the input and output variables, which will help you understand how to use them effectively.

Let’s get started!

Add List functions to your application

If you have never used List functions in your applications, you can add them by going to “Manage Dependencies”, selecting the “System” dependency, and searching for “List”.

From the screen above, you can see that List functions can be used for both Client and Server Actions. The functionality remains the same in both cases; the difference lies in which action you are using them.

For this demo, I will select all of the List functions from Server Actions.

To add List functions to your actions, search for “List” using the search bar at the top right, then drag and drop the needed function into your flow.

That completes the preparation of your development environment. Now, let’s test each function to understand how we can maximize our productivity.

ListFilter / ListSort

Let’s start with the most commonly used functions: ListFilter and ListSort.

First, drag and drop your table that you want to sort or filter.

Configure List Settings:

• For the List setting, add the selected list.
• For the By setting, add the sorting criteria.
• Additionally, you can specify if you want your list results in Ascending or Descending order.

As you can see in the result below, table was sorted based on value in Ascending order.

The next function is ListFilter.

In the image below, you can see that I added a static comparison for the condition. However, you can easily make this condition dynamic based on the scope of your requirements.

And as you can see in before-after, ListFilter function filter out needed condition.

ListAll / ListAny

The ListAny function returns a boolean variable, either True or False. The main idea of ListAny is to check if any element in the list satisfies a given condition. If at least one element meets the condition, it will return True; otherwise, it will return False.

Look at the result with two different conditions

ListAll follows the same logic as ListAny, returning a boolean variable (True or False) based on a given condition. The main difference is that ListAll returns True only if all items in the list satisfy the condition; otherwise, it returns False.

In the image below, you can see I added the same logic. Let’s check the result of this comparison.

As you can see it returned False, because not all items in the Value column has given number

ListAppend / ListAppendAll

ListAppend adds a single item to the list. You can use it within a loop with a specific condition for sorting. The result will be the item appended to the list.

ListAppendAll follows the same logic as ListAppend, but instead of adding a single item, it adds an entire additional list to the existing list.

ListClear / ListDuplicate

ListClear has a straightforward task: it clears all items from the list. This function can be used when you need to clean up values or reset your temporary list for the next action.

ListDuplicate duplicates all elements of a list into another list, and the output is the duplicated list containing all the elements from the original list.

ListIndexOf / ListInsert / ListRemove

ListIndexOf returns the index (position) of the first occurrence of a value in a list that satisfies a given condition. It identifies and returns the row index where the item meets the specified condition.

Following ListIndexOf, you can use ListRemove to remove a specific item from the list. You provide the index (position) of the item as input, and this function will remove the item at that particular index from the list. This allows you to manipulate the contents of the list by selectively removing items based on their positions.

How to use them in real case scenarios?

Let’s examine how all these functions can be integrated into a single workflow:

1. Get Table: Start by retrieving the table that you want to manipulate.
2. Duplicate List: Duplicate the original list so that you have two separate lists to work with.
3. Filter List Values: Apply a filter to one of the lists to retain only those values that are less than 100.
4. Find Index: Use ListIndexOf to find the index of a particular item in the duplicated list, based on a given condition.
5. Remove Item: Utilize ListRemove to remove the item from the duplicated list, using the index found in the previous step.

This sequence allows you to manipulate data efficiently within your application flow, demonstrating the practical application of various list functions in OutSystems.

Here are a few examples and best-case solutions where List functions in OutSystems can be applied:

Example 1: Filtering and Sorting User Data

Scenario: You have a list of users and you want to filter and sort them based on specific criteria.

1. Get Users List: Retrieve a list of users from your database.
2. Filter Users: Use ListFilter to filter users based on conditions such as age, location, or status. For example, filter users who are active and under the age of 30.
3. Sort Users: Apply ListSort to sort the filtered list of users based on attributes such as name, age, or registration date in ascending or descending order.
4. Display Result: Assign the filtered and sorted list as the output, which can be displayed in a table or used further in your application.

Example 2: Dynamic Form Submission Handling

Scenario: You have a form where users can dynamically add or remove entries, and you need to handle these submissions efficiently.

1. Manage Dynamic Entries: Use ListAppend and ListRemove to manage entries dynamically as users add or remove items from the form.
2. Validation: Apply ListAny or ListAll to validate form entries against specific criteria before submission. For instance, ensure all required fields are filled or certain conditions are met.
3. Submission Handling: Use ListDuplicate to create a duplicate of the list of entries before submission. This allows you to retain the original data set while processing the submission.
4. Cleanup: Utilize ListClear to reset the form entries after successful submission or upon canceling the operation.

Let me know about your solutions and best case examples =)