cap-plugins

name	cap-plugins
description	Use when adding SAP CAP first-party plugins to a project: @cap-js/change-tracking, @cap-js/audit-logging, @cap-js/attachments, @cap-js/notifications, @cap-js/telemetry, @cap-js/graphql, @cap-js/data-inspector, @cap-js/data-privacy, @cap-js/ai, WebSocket, OData V2 adapter, or the ORD (Open Resource Discovery) plugin. Covers setup, annotations, and configuration.
metadata	{"version":"1.1.0","keywords":["@cap-js/change-tracking","@cap-js/audit-logging","@cap-js/attachments","@cap-js/notifications","@cap-js/data-inspector","@cap-js/data-privacy","@cap-js/ai","CAP plugin","cds plugin","built-in plugin"],"related":{"cds-modeling":"annotate entities for plugin activation","btp-deployment":"plugin service bindings in mta.yaml","observability-telemetry":"audit logging as observability"}}

CAP Plugins — Setup & Best Practices

Primary reference: https://cap.cloud.sap/docs/plugins/

All first-party CAP plugins follow the same install pattern:

npm install @cap-js/<plugin-name>
# → auto-activated by CAP's plugin mechanism — no cds.requires entry needed

---

Change Tracking (@cap-js/change-tracking)

Automatically records field-level changes to annotated entities.

npm install @cap-js/change-tracking

// Annotate the entity you want to track
annotate Orders with @changelog: [
  { target: 'status' },
  { target: 'amount' },
  { target: 'assignedTo.name' }  // associations supported
];

A Changes composition is added to the entity. Expose it in the service:

service AdminService {
  entity Orders as projection on db.Orders {
    ...,
    changes : redirected to ChangeView
  }
}

Multitenancy: Supported since April 2025 with MTX-S sidecar.

⚠️ Version 2 (April 2026): @cap-js/change-tracking v2 uses native database triggers (SQLite, HANA, PostgreSQL) instead of service-level tracking. This brings up to 50× faster performance for bulk operations. It introduces breaking schema changes — the ChangeLog table was removed and merged into Changes. A database migration is required when upgrading from v1. The @changelog annotation syntax is unchanged.

---

Audit Logging (@cap-js/audit-logging)

Logs sensitive data access and modifications to SAP Audit Log Service.

npm install @cap-js/audit-logging

// Mark entities with sensitive personal data
entity Persons : cuid, managed {
  @PersonalData.IsPotentiallySensitive
  socialSecurityNumber : String;

  @PersonalData.FieldSemantics: 'DataSubjectID'
  personID : String;
}

// package.json — bind to SAP Audit Log Service in production
{
  "cds": {
    "requires": {
      "audit-log": {
        "[production]": {
          "kind": "audit-log-service",
          "credentials": { "destination": "AUDIT_LOG" }
        },
        "[development]": {
          "kind": "audit-log-to-console"  // log to console locally
        }
      }
    }
  }
}

---

Attachments (@cap-js/attachments / cds-feature-attachments)

Stores file attachments — in DB (default) or Object Store (AWS S3, Azure Blob, GCS).

npm install @cap-js/attachments

using { Attachments } from '@cap-js/attachments';

entity Incidents : cuid {
  title       : String;
  attachments : Composition of many Attachments;
}

Switch to Object Store (all hyper-scalers supported since Nov 2025):

{
  "cds": {
    "requires": {
      "attachments": {
        "kind": "standard"  // auto-detects S3, Azure, or GCP from binding
      }
    }
  }
}

Bind the Object Store service in mta.yaml:

- name: my-app-oss
  type: org.cloudfoundry.managed-service
  parameters:
    service: objectstore
    service-plan: s3-standard  # or azure-standard, gcs-standard

Hide the UI section conditionally:

@UI.Hidden : (status = #canceled ? true : false)
attachments : Composition of many Attachments;

Note: Malware scanning is included — files over 400 MB show "Scanning failed".

---

Notifications (@cap-js/notifications)

Send SAP BTP notifications to Launchpad / Work Zone.

npm install @cap-js/notifications

const alert = await cds.connect.to('notifications')

await alert.notify({
  recipients: [req.user.id],
  priority: 'HIGH',
  title: 'Order {0} requires approval',
  description: 'Amount: {1} {2}',
  parameters: [orderId, amount, currency],
  targetParameters: [{
    parameterName: 'objectID',
    parameterValue: orderId
  }]
})

---

Telemetry / Observability (@cap-js/telemetry)

Exports traces, metrics, and logs to OpenTelemetry-compatible backends (Dynatrace, Cloud Logging, Jaeger).

npm install @cap-js/telemetry

Auto-activated. For production, bind a Cloud Logging or Dynatrace instance and configure:

{
  "cds": {
    "requires": {
      "telemetry": {
        "kind": "to-cloud-logging"
      }
    }
  }
}

In mta.yaml, bind cloud-logging service:

- name: my-app-logging
  type: org.cloudfoundry.managed-service
  parameters:
    service: cloud-logging
    service-plan: standard

---

GraphQL Adapter (@cap-js/graphql)

Expose CAP services as GraphQL APIs alongside OData.

npm install @cap-js/graphql

@graphql service CatalogService { ... }

Access at: http://localhost:4004/graphql

---

WebSocket (@cap-js-community/websocket)

Real-time events over WebSocket or Socket.IO.

@protocol: 'websocket'
service ChatService {
  function message(text: String) returns String;
  event received { text: String; }
}

---

Data Inspector (@cap-js/data-inspector)

Intelligent query execution analysis and database inspection with UI.

npm install @cap-js/data-inspector

Provides debug insights into CQL queries, generated SQL, and execution plans.

---

Data Privacy (@cap-js/data-privacy) — Beta

Out-of-the-box integration with SAP Data Privacy Integration (DPI) service.

npm install @cap-js/data-privacy

Automatically exposes DPI endpoints for data subject requests and deletion workflows.

---

AI Plugin (@cap-js/ai)

Automatic UI field recommendations powered by SAP RPT-1, plus SAP AI Core integration using the Calesi pattern.

npm install @cap-js/ai

Fields annotated with @Common.ValueList automatically receive AI-powered recommendations in Fiori draft-enabled UIs — no custom handler needed:

annotate Books with {
  genre @Common.ValueList: {
    CollectionPath: 'Genres',
    Parameters: [{ $Type: 'Common.ValueListParameterInOut',
      ValueListProperty: 'code', LocalDataProperty: genre_code }]
  }
}

The plugin also embeds SAP AI Core as a standard CAP service with automatic service binding resolution, managed resource groups, and tenant-aware access.

---

MCP Protocol Adapter (@cap-js/mcp)

Exposes existing CAP services to AI agents and LLM-powered tools as an MCP (Model Context Protocol) endpoint — just another protocol alongside OData, REST, and HCQL.

npm install @cap-js/mcp

// Annotate services you want to expose via MCP
annotate CatalogService with @mcp;

The adapter auto-generates three MCP tools:

• describe — returns entity/element information
• query — reads data via CQL translation
• call_action — invokes custom actions/functions

All standard CAP features (auth, authorization, constraints) work automatically. During cds watch, the adapter auto-wires client configurations for Claude Code and OpenCode.

Note: @cap-js/mcp is the protocol adapter (exposes CAP services to AI agents). @sap/cds-mcp is the separate development tool (gives AI agents access to CAP docs and your project model).

---

Print Service (@cap-js/print)

Provides print service features through integration with SAP Print Service.

npm install @cap-js/print

---

SAP Document Management Service (@cap-js/sdm)

Stores attachments in an SAP Document Management Service repository instead of the database.

npm install @cap-js/sdm

Uses the same Attachments aspect as @cap-js/attachments.

---

SAP Cloud Application Event Hub (@cap-js/event-broker)

Consumes events from SAP Cloud Application Event Hub — for example events emitted by SAP S/4HANA Cloud.

npm install @cap-js/event-broker

const S4Bupa = await cds.connect.to('API_BUSINESS_PARTNER')
S4Bupa.on('BusinessPartner.Changed', msg => { /* ... */ })

---

Common mistakes to avoid

• ❌ Adding cds.requires entries for auto-activated plugins — not needed, causes confusion
• ❌ Using @attachments.disable_facet — deprecated since Nov 2025, use @UI.Hidden
• ❌ Enabling Object Store attachments in multitenant apps without per-tenant Object Store bindings
• ❌ Using audit-log-to-console in production — it doesn't write to the Audit Log Service
• ❌ Forgetting to bind the actual BTP service for notifications/audit/telemetry in mta.yaml
• ❌ Using kind: s3 hardcoded when kind: standard auto-detects the hyper-scaler