To-do List Query

Add search to the to-do list by creating a MongoDB Query, exposing it as an API through a Saga, and wiring the UI lister to use the query endpoint with a filter.

This exercise adds a simple search flow on top of the to-do list. You will:

• define a Query that filters todos by data.project

• expose it as an API using a Saga

• update the UI lister to call the query endpoint and show filtered results

Before you start

• You completed To-do List UI.

• You can access:

  • the Query screen in the Configuration app

  • the Saga screen in the Devops app

  • the Source and UI screens in the Design app

• You know your API base URL: https://[YOUR_ADMIN_API_DOMAIN].

Why use a Saga?

The todo-0001 runner is a CRUD runner. CRUD runners are designed for standard read/write operations.

For querying, you typically expose a dedicated RPC endpoint using a Saga (or an RPC runner).

What you’ll build

• Query ID: todo

  • Filters data.project = %%project%%

• Saga path: /SearchTodos

• API endpoint: GET https://[YOUR_ADMIN_API_DOMAIN]/api/request/rpc/SearchTodos?project=Personal

• Source update: add query -> request/rpc/SearchTodos

• UI update: switch lister to Query Table and add a project filter

1

Open the Query screen

Open the Query screen from the Configuration app.

Unless you changed routing, the UI is at https://[YOUR_ADMIN_UI_DOMAIN]/app/configuration/common/query.

Query Screen

2

Create the Query (todo)

Click CREATE NEW and set the Query ID:

• todo

Fill in the DEFINITION tab:

Query Definition Screen

• Query Name: Todo

• Query Status: ACTIVE

• Query Description (optional): Search todo list by project.

• Query Type: SIMPLE

• Query Platform: MONGODB

• Source Table: todo

3

Add a WHERE condition (project)

Open the WHERE tab.

Hover on the plus icon and select Simple.

Edit the new condition:

Query Condition Dialog

• Use a Function: false

• Expression: data.project

• Operator: EQUALS

• Value: %%project%%

Save the query.

%%project%% is a parameter placeholder. You’ll pass it at runtime through the API call.

4

Open the Saga screen

Open the Saga screen from the Devops app.

If you need a refresher on the basics, follow the structure in Exercise: Hello World API.

5

Create a Saga (SearchTodos)

Create a new saga and set:

Search Todos Saga Definition Screen

• Saga Name: Search Todos

• Status: ACTIVE

• Saga Path: /SearchTodos

• Version: 0

• Allowed On: saga

• Saga Domain: util

6

Add steps (Start → Event → Success)

Add Start, Event, and Success steps from the stencil.

Link them to form:

• Start → Event → Success

7

Configure the Start → Event link (local execution)

Edit the link from Start to Event:

Saga Link Definition Dialog

• Stream: local

local means the gateway executes the step without delegating to a remote runner.

8

Configure the Event step (GetQuery)

Edit the Event step:

Saga Event Definition Dialog

• DEFINITION

  • Step Name: Get Project Todos

• EVENT META

  • Event Version: 0

  • Event Action: GetQuery

  • Event Domain: master

  • Input Element: parameters

  • Output Element: $

  • Parameters Map

    • Key: queryId

    • Value: todo

This step executes GetQuery against the master system, using the Query ID todo.

It reads query parameters from parameters (so project=... becomes available as %%project%%).

9

Save the Saga

Click SAVE to activate the saga. Wait for the gateway/runner reload interval if your environment uses one.

10

Test the API endpoint

Call:

GET https://[YOUR_ADMIN_API_DOMAIN]/api/request/rpc/SearchTodos?project=Personal

Expected result:

• HTTP 200

• A list of todos where data.project equals Personal

11

Update the Source (add the query URL)

Open the todo Source in the Design app (.../app/design/common/source?id=todo).

Add a new URL row:

• Action: query

• URL: request/rpc/SearchTodos

Save the Source.

12

Update the UI lister (use Query Table + filter)

Open the todo UI in the Design app (.../app/design/common/ui?id=todo).

Update the LISTER tab:

UI Lister Screen

• Lister: Query Table

• List Columns

  • Title: Name, Path: data.name

  • Title: Project, Path: data.project

• Main Filters

  • Path: project, Widget: TextFilter, Properties: { "label": "Project" }

Save the UI.

13

Verify in the app

Open your Example app and go to the Todo screen.

You should now see a filter input for Project. Searching should call the saga endpoint and return filtered results.

Updated Todo Screen

Next step

You now have a complete end-to-end example: CRUD + gateway + UI + query + saga.

If you want to expand it, add:

• multiple filters (name contains, status, date range)

• pagination/sorting in the query lister

• authentication on the gateway channel

Troubleshooting

• Empty results: ensure you have at least one todo with data.project = "Personal".

• Saga returns an error about queryId: confirm the Query ID is exactly todo.

• Parameter not applied: confirm the saga reads from Input Element: parameters and you call ?project=....

• UI still does CRUD calls: confirm you added the Source URL for action query and changed the lister to Query Table.