CAP bound actions: Pass the entity context and test the service contract
A manufacturing approval application exposes a bound action, and its developer must establish which request instance the action targets.
START HERE · NO PRIOR TOPIC KNOWLEDGE NEEDED
What it is. Why it matters.
SAP CAP helps developers build business services. A bound action is an operation attached to an entity, so the request must identify which business record the action concerns.
Completely new to SAP?
Manufacturers use SAP to connect work such as buying components, recording inventory, planning production, shipping equipment and accounting for costs. SAP S/4HANA is an enterprise resource planning system: it connects these activities through shared business data.
ABAP is SAP’s programming language for business applications. A program reads data, applies rules and produces a result. Start with the objects involved before investigating code.
A transaction code, or t-code, is a shortcut to a task in classic SAP GUI. Fiori apps provide another way to work. Names and screens depend on the product and release; you do not need a live system to learn the concepts in this guide.

Scope and source-review notes
Scope and evidence
Source review by FAST SAP SOLUTIONS® editorial. This badge describes our editorial review; it does not represent SAP certification or independent endorsement.
CAP Node.js custom instance-bound operations with illustrative OData V4 requests; Java, collection-bound and older runtime contracts differ.
Primary documentation reviewed on 14 November 2026 using readable full text and official indexed excerpts. Relevant full-text CAP action and authorization sections and indexed request-API text reviewed. CDL, requests and transition algorithm are original illustrative material and were not executed; installed runtime behavior must be validated.
A MANUFACTURING EXAMPLE
Approve the intended plant request
Approve which record?
Read the example values
- Entity
- Orders
- Target key
- 1001
- Bound action
- Approve
- Required context
- The intended order
Words you’ll meet in this guide
- Program
- A set of instructions executed by a computer.
- Class
- A reusable unit that groups data with operations called methods.
- Database
- Organized information kept beyond one program execution.
- Internal table
- A list of rows held temporarily in an ABAP program’s memory.
- Key
- One or more fields used to identify or find a record.
- CDS
- Core Data Services: reusable definitions of business data and relationships.
- OData
- A standard for reading and updating data through a web API.
- HTTP
- The request-and-response protocol used by web applications and APIs.
Preview the practical steps
SEE THE CONNECTION
See it in a simple example.
A small example to make the idea concrete.
Approve the intended plant request
A manufacturing approval application exposes a bound action, and its developer must establish which request instance the action targets.
A bound action needs the entity identity as well as its own parameters
For an instance-bound CAP action, the entity key comes from the binding context.
Scope and prerequisites
The worked example uses CAP Node.js with contemporary request APIs and OData V4-style invocation.
Separate unbound, instance-bound and collection-bound operations
An unbound operation belongs to the service rather than one entity instance.
Approve the intended plant request
A manufacturing approval application exposes a bound action, and its developer must establish which request instance the action targets.
Check the service contract, entity key and authorization before treating an action call as approval of the item displayed on screen.
| Reader | Business question | Evidence to carry forward |
|---|---|---|
| SAP developers and application teams supporting manufacturers | Approve the intended plant request | Check the service contract, entity key and authorization before treating an action call as approval of the item displayed on screen. |
01 A bound action needs the entity identity as well as its own parameters
For an instance-bound CAP action, the entity key comes from the binding context. Declared action parameters carry additional inputs such as a reason or quantity. Putting an ID into an arbitrary body field is not automatically equivalent to invoking the action on that entity instance. [1]
Start with the exposed service model and OData metadata, then compare the request path, operation name and handler context. This tutorial implements a fictional approval action for one request, including missing-key, state and concurrent-change cases. It distinguishes the public service contract from a direct unit call that happens to pass convenient JavaScript arguments.
02 Scope and prerequisites
The worked example uses CAP Node.js with contemporary request APIs and OData V4-style invocation. CAP Java has different handler APIs, while protocol adapters can expose different invocation conventions. Record installed @sap/cds/compiler versions, protocol path and generated metadata. In particular, request parameter representation has evolved across CAP versions; inspect your installed documentation and runtime rather than relying on an old snippet.
You need a development CAP project, a persistence model and authorized test identities. The example assumes Requests has Integer key ID, status, reviewer and approvalReason. It is illustrative code, not a deployed or executed service. Production authorization, validation and persistence constraints must be completed for the actual business model.
03 Separate unbound, instance-bound and collection-bound operations
An unbound operation belongs to the service rather than one entity instance. An instance-bound operation acts in the context of one addressed entity. A collection-bound operation is associated with an entity collection and must define its own selection/creation semantics. Do not use the instance handler's key assumptions for a collection action. [1]
The binding parameter is implicit in the operation contract. The action's declared reason is additional input. The service metadata determines the qualified operation name and binding type. Use that contract when writing a client; CAP may support convenient abbreviated URLs, but a portable OData request should not depend on undocumented shortcuts.
04 Worked case: approve request 1001
Fictional request 1001 is SUBMITTED and assigned to reviewer alex. Request 1002 is DRAFT, also assigned to alex. Request 1003 is SUBMITTED but assigned to sam. The approve action should permit alex to approve 1001 with a meaningful reason, reject 1002 because its state is wrong and deny access to 1003 according to the application's data policy.
The same action name appears in all three attempts. The binding identity and current business state determine which outcome is valid. An implementation-only test that calls approve with reason alone cannot establish that the real OData path identifies 1001 correctly. Keep request context and action payload separate in both tests and diagnostics.
| ID | Status | Assigned reviewer | alex expected outcome |
|---|---|---|---|
| 1001 | SUBMITTED | alex | Approve with valid reason |
| 1002 | DRAFT | alex | Reject state transition |
| 1003 | SUBMITTED | sam | Deny according to data policy |
| 9999 | Absent | None | Not found or non-disclosing policy outcome |
05 Define and inspect the service contract
The CDL sketch shows an instance-bound action inside the exposed entity. Adapt projection syntax to your project and compile metadata before constructing the URL. Verify that approve is bound to Requests, accepts reason and returns the intended service type. A projection rename can change the external entity name even when the persistence entity remains unchanged.
The service-level Reviewer role below is only a coarse entry restriction for this teaching service. The handler also needs the assigned-record policy and status rule. Review which CRUD operations this role should receive in the complete application; the narrow sketch is not a complete authorization model.
using { demo as db } from '../db/schema';
@requires: 'Reviewer'
service ReviewService {
entity Requests as projection on db.Requests actions {
action approve(reason : String(200)) returns Requests;
};
}06 Send the key in the binding path
Assuming the generated service path is /odata/v4/review and metadata declares namespace ReviewService, the canonical illustrative request is POST to Requests(1001)/ReviewService.approve with JSON reason. Confirm these names from your metadata: CAP path derivation or explicit path annotations can change the prefix, and a different service name changes qualification.
If the handler receives reason but no expected key, compare the request path and binding metadata before adding an ID parameter to the action. Such a parameter changes the contract and can create two competing identities. If both path ID and body ID exist, a malicious or mistaken caller can supply different values; prefer one authoritative binding identity.
POST /odata/v4/review/Requests(1001)/ReviewService.approve HTTP/1.1
Content-Type: application/json
{"reason":"Budget and account assignment reviewed"}07 Read the actual handler context and enforce the transition
In contemporary CAP Node.js, req.params carries key objects for the addressed path. Read the key corresponding to the expected entity, and account for navigation paths if your endpoint supports them. req.subject is another documented way to address a single-row subject in supported requests; use the release-appropriate contract rather than mixing representations. [2]
The pseudocode below makes the state transition explicit. An unconditional update after an earlier read has a race: another request can change the status between those operations. A conditional update that still requires SUBMITTED detects that conflict. Include the assigned-reviewer predicate in the write boundary as well, so an assignment change does not silently permit approval.
ID = instance key from request binding context
reason = declared request parameter
validate ID and nonblank reason (maximum 200 characters)
read request ID within the managed request transaction
if unavailable: return policy-appropriate not-found/denied outcome
if assigned reviewer differs from current user: reject
if status is not SUBMITTED: reject transition
conditionally update where ID matches, status = SUBMITTED,
and reviewer = current user
set status = APPROVED and approvalReason = reason
if affected row count is not 1: report concurrent change
return the supported action result for that same ID08 Keep service authorization and business validation explicit
A hidden Approve button does not protect the endpoint. The backend must verify the role, assigned-record policy and allowed status. Use supported declarative restrictions where they express the rule, then implement additional state validation without assuming that every low-level persistence query automatically applies the service's instance policy. [3]
An approval reason is input, not authority. A caller cannot gain permission by supplying another reviewer name or changing a body ID. Derive identity from authenticated request context and the authoritative binding key. Keep error messages appropriate to the data policy: revealing that request 1003 exists may itself be undesirable for an unauthorized caller.
09 Troubleshoot path, dispatch and result separately
A 404 can mean a wrong service path, unknown entity, unknown action or missing entity instance. A 400 can reflect parameter shape. A successful HTTP response with the wrong displayed state can instead concern action result shape or UI refresh. Preserve the actual response body and metadata context before changing the handler.
| Observation | Check | Next step |
|---|---|---|
| Handler never called | Namespace, action binding and HTTP method | Compare generated metadata and canonical path |
| Reason present; key missing | Instance versus unbound/collection contract | Inspect req.params/subject and request path |
| Wrong request updated | Competing body/path identity or mapping | Use authoritative bound key |
| Second approval succeeds unexpectedly | State check and concurrent write predicate | Make transition conditional |
| Role allowed; other reviewer record changed | Missing instance policy in custom persistence | Enforce assigned-record scope |
| Backend changed; UI stale | Result metadata and refresh behavior | Inspect returned identity and dependent bindings |
10 Test through the exposed endpoint
For the positive case, call the real OData route for 1001 as alex and verify status APPROVED with the reason persisted for 1001 only. For the negative cases, test DRAFT 1002, another reviewer's 1003, unknown 9999 and a caller lacking Reviewer. Keep expected denial/not-found disclosure policy explicit.
Boundary checks include blank reason, overlength reason, a malformed key and two concurrent approval attempts. Exactly one should perform the valid transition under the chosen contract; the other should receive a controlled conflict or already-processed outcome. Also test a direct generic service call separately, because it may bypass URL construction while still exercising service dispatch. No such tests were executed by this article.
11 Review action results and client refresh
If the action returns an entity, ensure the returned identity and declared return type match the service contract. A body containing a message string cannot substitute for a modeled entity result. If the operation has no result, clients still need a supported way to refresh affected fields and show the actual outcome.
Avoid reporting approval solely because the button handler finished or the request was sent. Inspect the operation response, then verify persisted state through the supported read path. If a response is lost after execution, reconcile status before resubmission. A repeat action needs a defined business outcome rather than relying on the frontend to prevent every duplicate click.
12 Frequently asked questions
Can I put ID in the JSON body? Only if it is a declared parameter with a deliberate contract. It does not replace an instance binding automatically.
Must the qualified action name appear in the URL? The OData contract uses qualification; inspect the generated namespace. CAP convenience shortcuts should not be mistaken for the portable protocol form.
Does a passing unit handler test prove the endpoint works? No. Test metadata, routing, binding identity, authorization and result serialization through the public endpoint.
What should the incident record contain? Service and runtime versions, metadata action definition, sanitized request path/body, resolved key, current state, caller role and resulting state. That shows whether the defect is dispatch, identity, transition or presentation.
Related services and next steps
Primary sources
Found this useful?
Share this guide with your network, or leave a like.
Your like is saved in this browser.