IBM i

IBM i 

A space for professionals working with IBM’s integrated OS for Power systems to exchange ideas, ask questions, and share expertise on topics like RPG and COBOL development, application modernization, open source integration, system administration, and business continuity.


#Power


#IBMi
#Power
#Operatingsystems
#Servers
 View Only

Thin Controllers, Strong Services: Where Orchestration Belongs on IBM i

By George Van Eaton posted 08/28/26 08:21 AM

  

Why the Boundary Matters

Modern IBM i integration discussions often focus on APIs, REST endpoints, JSON, and the systems consuming them. Those external boundaries matter, but they are only half of the architecture.

A stronger integration boundary exposes intentional business capabilities rather than requiring every consumer to understand tables, programs, commands, and internal processing rules. Examples include:

·         CreateOrder

·         GetCustomer

·         ReserveInventory

·         CalculatePrice

Those capabilities create a cleaner external boundary.

Eventually, though, the request crosses that boundary and reaches IBM i.

Then we have another question:

Where does the business work belong?

This is where modern applications can get into trouble surprisingly quickly. Once a controller starts making pricing decisions, updating multiple tables, calculating inventory, deciding whether an order is valid, and coordinating half a dozen downstream operations, it has stopped being a controller. It has become the application.

A team creates a REST endpoint. The endpoint receives JSON. The controller calls some SQL, performs a few calculations, updates a table, invokes another program, handles an exception, and returns a response.

Technically, we now have an API.

Architecturally, however, we may have simply moved the old coupling into a new place.

A cleaner internal boundary follows a different rule:

Controllers should coordinate. Services should decide.

That distinction is one of the most important boundaries in a maintainable application.

The Controller Is a Doorway

A controller sits at the edge of the application.

Its job is primarily translation and coordination.

For an API request, that usually means things such as:

·         receiving the request;

·         validating that the request is structurally usable;

·         identifying the requested operation;

·         translating transport-specific data into application input;

·         invoking the appropriate service;

·         translating the result into the expected response;

·         returning the appropriate status or error information.

Those responsibilities are already substantial.

It does not need to own the business rules too.

Consider an order API.

A controller might receive:

POST /orders

with customer, item, quantity, and shipping information.

The controller can translate that request into something the application understands and call:

CreateOrder

What it should not need to know is:

·         whether the customer is allowed to place the order;

·         how pricing is calculated;

·         whether inventory can be reserved;

·         which tables must be updated;

·         which historical records must be written;

·         whether a notification must be generated;

·         which internal program performs each step.

Those are application concerns.

Once the controller knows those details, we have begun exporting internal architecture again—this time into our own presentation layer.

Thin Does Not Mean Unimportant

“Thin controller” can sound like “simple controller.”

But “thin” does not mean trivial.

The controller has an important architectural responsibility because it protects the rest of the application from the delivery mechanism.

Today, the request may come from REST.

Tomorrow, the same business capability may be invoked from:

·         an RPG application;

·         a batch process;

·         a message queue;

·         an event handler;

·         another internal service;

·         a scheduled job;

·         an AI agent.

Changing the caller should not require rewriting the business capability.

That separation is why the boundary matters.

If CreateOrder contains the business behavior, multiple entry points can reuse it.

If the behavior lives inside OrderApiController, the API becomes the application.

Strong Services Do the Real Work

The service layer is where the use case becomes meaningful.

This is where orchestration belongs.

For CreateOrder, a service may need to coordinate several responsibilities:

1.      retrieve the customer;

2.      validate the customer's eligibility;

3.      calculate pricing;

4.      check or reserve inventory;

5.      create the order;

6.      write supporting records;

7.      commit the transaction;

8.      return the result.

The service does not necessarily perform every one of those operations itself.

That distinction matters.

A strong service is not a giant procedure containing every SQL statement and every business rule.

Its responsibility is to orchestrate the business operation.

It can delegate specific work to domain logic and data services.

Conceptually:

Controller
    ↓
CreateOrder Service
    ↓
Customer Rules
Pricing Service
Inventory Service
Order Data Service

The controller knows that it needs to create an order.

The CreateOrder service knows what creating an order requires.

The pricing component knows how pricing works.

The data service knows how orders are persisted.

Each layer knows what it needs to know—and ideally little more.

Orchestration Is Not the Same as Business Logic

This distinction is easy to blur.

Suppose creating an order requires checking whether a customer is on credit hold.

The service might ask:

CustomerCanOrder(customer)

The service owns the sequence:

Before creating the order, verify that the customer can order.

But the rules determining whether that customer is eligible may belong somewhere else.

For example:

CanCustomerPlaceOrder()

That rule could consider:

·         account status;

·         credit status;

·         customer type;

·         contractual restrictions;

·         other business conditions.

The application service coordinates the use case.

The domain logic makes the business decision.

That separation becomes increasingly valuable as applications grow.

The IBM i Version of the Fat Controller

This problem is not unique to web frameworks.

IBM i applications have been combining responsibilities for decades.

A traditional program may handle:

·         display-file processing;

·         user input;

·         validation;

·         calculations;

·         database access;

·         calls to other programs;

·         commitment control;

·         error handling;

·         workflow decisions.

That architecture made sense in many environments where a program effectively was the application boundary.

But when we begin exposing those capabilities through APIs, web interfaces, mobile applications, automation, or agents, those responsibilities become harder to reuse.

One modernization temptation is to wrap the existing program and stop there.

Sometimes that is exactly the right first step.

A wrapper can create a useful boundary without forcing a risky rewrite.

But it should not automatically become the final architecture.

The important question is:

Where does the reusable business capability actually live?

If it is buried inside a display program or endpoint-specific controller, future consumers remain tied to that delivery mechanism.

Before and After: Extract the Capability, Not Just the Endpoint

The difference becomes easier to see in code. Consider a simplified order-entry path shown in RPG-style pseudocode. The examples intentionally omit declarations, prototypes, detailed SQL diagnostics, and other production plumbing so the focus stays on architectural responsibility. The exact procedure names will vary by application; the important part is which layer owns each responsibility.

Before: the endpoint owns everything

A first API implementation might put request handling, business rules, SQL, orchestration, and the response in one procedure:

dcl-proc CreateOrderController;
   request = ParseOrderRequest();

   exec sql
      select CREDIT_STATUS into :creditStatus
        from CUSTOMER
       where CUSTOMER_ID = :request.customerId;

   if creditStatus = 'H';
      return MapError('CUSTOMER_ON_HOLD');
   endif;

   exec sql
      select PRICE into :unitPrice
        from ITEM_PRICE
       where ITEM_ID = :request.itemId;

   exec sql insert into ORDER_HEADER (...);
   exec sql insert into ORDER_DETAIL (...);
   ReserveInventory(request.itemId : request.quantity);
   exec sql commit;

   return MapSuccess(orderId);
end-proc;

This can work. It may even be a sensible first wrapper around an existing process. But the controller now knows the customer table, the pricing table, the order schema, the inventory operation, the transaction boundary, and the HTTP-facing result.

Every additional consumer either calls this controller or rebuilds part of the same behavior somewhere else.

After: the controller delegates to a business capability

Now move the use case behind a service boundary:

dcl-proc CreateOrderController;
   request = ParseOrderRequest();
   result  = CreateOrder(request);
   return MapOrderResponse(result);
end-proc;

The controller still matters. It owns the transport boundary: parsing the request and mapping the result. But it no longer owns the order process.

The application service can coordinate that process:

dcl-proc CreateOrder;
   customerResult = GetCustomer(request.customerId);

   if not customerResult.ok;
      return CustomerLookupFailedResult();
   endif;

   if not CanCustomerPlaceOrder(customerResult.customer);
      return CustomerOnHoldResult();
   endif;

   priceResult = CalculatePrice(
                   request.customerId
                 : request.itemId
                 : request.quantity);

   if not priceResult.ok;
      return PricingFailedResult();
   endif;

   headerResult = CreateOrderHeader(request : priceResult.price);
   if not headerResult.ok;
      exec sql rollback;
      return OrderFailedResult();
   endif;

   detailResult = CreateOrderDetail(
                     headerResult.orderId
                   : request
                   : priceResult.price);
   if not detailResult.ok;
      exec sql rollback;
      return OrderFailedResult();
   endif;

   inventoryResult = ReserveInventory(
                        request.itemId
                      : request.quantity);
   if not inventoryResult.ok;
      exec sql rollback;
      return InventoryFailedResult();
   endif;

   exec sql commit;
   return OrderCreatedResult(headerResult.orderId);
end-proc;

The SQL has not disappeared. It has moved behind data-oriented procedures whose job is persistence. A customer lookup, for example, can live behind a data service:

dcl-proc GetCustomer;
   exec sql
      select CUSTOMER_ID, CREDIT_STATUS, CUSTOMER_TYPE
        into :customer.id, :customer.creditStatus, :customer.customerType
        from CUSTOMER
       where CUSTOMER_ID = :customerId;

   // Production code maps SQLSTATE/SQLCODE into an
   // explicit result: success, not found, or SQL error.
   return result;
end-proc;

Implementation note: These examples are intentionally pseudocode. In production RPG, each embedded SQL operation must evaluate SQLSTATE/SQLCODE, or an equivalent result returned by the data-access procedure. RPG MONITOR handles RPG/ILE exceptions; it is not a substitute for SQL diagnostics. The transaction example also assumes commitment control is active, the affected tables/files are journaled as required, and the participating database changes use the same commitment definition.

Notice what changed. The language did not change. Db2 for i did not change. The business capability did not have to move off IBM i.

What changed was ownership.

The controller owns the request and response. The application service owns the use case and defines the intended transaction boundary. Domain logic owns business decisions. Data services own persistence.

On IBM i, that architectural boundary does not create a private transaction automatically. COMMIT and ROLLBACK affect only changes participating in the applicable commitment definition, so the work that must succeed or fail together has to participate in the same unit of work.

Modernization here is not a rewrite. It is the deliberate extraction of responsibility.

That gives the same CreateOrder capability somewhere stable to live whether the next caller is REST, an RPG program, a batch job, or an AI agent.

Service Programs Give IBM i a Natural Tool

IBM i already has a strong mechanism for separating reusable behavior: service programs.

That does not mean every procedure should become a service program, or that creating one automatically produces good architecture.

The architectural value comes from deliberately defining responsibilities.

A service program can expose procedures representing meaningful application operations.

For example:

CreateOrder()
CancelOrder()
ReserveInventory()
CalculatePrice()

Those procedures can then be called by different consumers without duplicating the business behavior.

An API controller can call them.

An RPG program can call them.

A batch process can call them.

Another service can call them.

The technology is familiar.

The modernization comes from the boundary.

Keep SQL Out of the Wrong Layer

One of the easiest shortcuts is also one of the most expensive over time.

A controller needs some information, so it executes SQL directly.

Then it needs another record.

Then an update.

Then another update.

Soon the controller understands the database schema almost as well as the application itself.

That creates several problems.

Database changes can break the controller.

Business rules can become duplicated between controllers.

Testing becomes harder because transport logic and persistence logic are intertwined.

And future developers must understand several layers simultaneously just to change one behavior.

In a layered IBM i architecture, database access should normally sit behind a data-service boundary.

Instead of:

Controller → SQL

prefer:

Controller
    ↓
Application Service
    ↓
Data Service
    ↓
Db2 for i

The data service understands persistence.

The application service understands the use case.

The controller understands the request.

Those are different responsibilities.

Transactions Need an Owner

Multi-step business operations introduce another question:

Who owns the transaction?

Suppose CreateOrder must:

·         create the order header;

·         create detail records;

·         reserve inventory;

·         update customer activity.

Those operations may need to succeed or fail together.

The transaction boundary should therefore correspond to the business operation—not whichever procedure happened to execute the first SQL statement.

In many designs, the application service coordinating the use case is the natural place to control that boundary.

It knows when the operation begins.

It knows when all required work has completed.

It knows whether the overall use case succeeded.

The individual data services should understand how to persist their data.

They should not independently decide whether the entire business process has succeeded.

That decision belongs at a higher level.

On IBM i, this is architectural ownership of the unit of work, not an isolated transaction created simply because a service procedure is in control. Commitment control still determines which database changes participate, and COMMIT or ROLLBACK only affects work within the applicable commitment definition.

Error Handling Becomes Cleaner Too

Layering also changes how we think about errors.

A database service may discover:

Customer not found

A domain rule may determine:

Customer cannot place orders

An inventory service may return:

Insufficient inventory

Those are application outcomes.

The controller then decides how those outcomes should appear to its consumer.

For REST, that might become an HTTP response.

For an RPG interface, it might become an application message.

For a batch process, it might become a logged exception or rejected transaction.

The business layer should not need to understand HTTP merely because one caller happens to be a REST API.

A clean separation here is another sign that the boundary is working.

Testability Is a Side Effect of Better Boundaries

One of the best outcomes of this architecture is easier testing.

If pricing logic is buried inside an API endpoint, testing pricing may require constructing an HTTP request.

If order processing is buried inside an interactive RPG program, testing it may require navigating a display.

But if the capability is exposed through a service procedure:

CalculatePrice()

or:

CreateOrder()

we can test the behavior directly.

That lets us ask much more useful questions:

·         Does the pricing rule work?

·         Does an invalid customer get rejected?

·         Does inventory remain unchanged when order creation fails?

·         Does the transaction roll back correctly?

·         Does the service return the expected business outcome?

We are testing the business capability rather than the interface around it.

This Is Also an AI Architecture Decision

AI makes this separation even more important.

An agent may eventually invoke a capability such as:

CreateOrder

An agent should not be given an implementation recipe such as:

Call program X
Update file Y
Set field Z
Run SQL statement Q
Then execute command R

Those steps describe implementation mechanics, not a business capability.

They expose internal decisions the consumer should never need to understand.

The more internal knowledge we give the consumer, the more fragile the integration becomes.

An agent should be able to understand:

Create an order for this customer using these items.

The application should understand how that operation works.

The same architectural principle applies whether the consumer is:

·         a mobile application;

·         another enterprise system;

·         a web interface;

·         or an AI agent.

A Practical Modernization Path

None of this requires rewriting an application.

Start with one capability.

Choose something meaningful, such as:

CalculatePrice

or:

GetCustomer

Then trace what happens today.

Ask:

·         What is the entry point?

·         Where are the business decisions made?

·         Where is the SQL?

·         Which procedures are reusable?

·         Which logic exists only because of the current interface?

·         Where should the transaction boundary live?

Then begin separating those responsibilities.

You may initially keep most of the existing implementation.

Modernization does not require changing everything at once.

It requires improving the boundary deliberately.

The Architecture Begins to Appear

At this point, the pieces of the architecture start coming together.

Externally, we have a business capability exposed through a deliberate contract.

Internally, a controller accepts the request.

The controller delegates to a service.

The service orchestrates the use case.

Domain logic makes business decisions.

Data services interact with Db2 for i.

Conceptually:

Consumer
    ↓
API / Interface
    ↓
Controller
    ↓
Domain / Application Services
    ↓
Data Services
    ↓
Db2 for i

This structure provides a practical layered architecture for IBM i applications.

The result is a design that can evolve as interfaces, integration technologies, and consumers change around it.

Final Thoughts

A modern endpoint sitting in front of old code can be useful.

But the endpoint itself is not the modernization.

The important work happens when we begin establishing clear responsibility inside the application.

The controller should understand the request.

The service should understand the operation.

The domain should understand the rules.

The data layer should understand persistence.

And consumers should not need to understand any more of that internal structure than necessary.

Thin controllers are not about writing less code. They are about putting code where it belongs.

Putting each responsibility in the right place gives us applications that can evolve as interfaces, integration technologies, and consumers change around them.

For IBM i teams, the practical question is not whether every application should adopt the same layering overnight. It is whether responsibilities are clear enough that business behavior can be reused without dragging presentation and persistence details with it.

I would be interested in how other IBM i teams are handling this boundary. Do your controllers still own business logic and SQL, or have you moved orchestration into reusable service procedures? Where do you draw the transaction boundary?

Share your experience in the comments.

0 comments
2 views

Permalink