From 8fde35d5c13de1718ee091607d02c5e32f637650 Mon Sep 17 00:00:00 2001 From: Robin de Silva Jayasinghe Date: Mon, 27 Apr 2026 11:16:26 +0200 Subject: [PATCH 1/7] Rename and promote CAP plugins menu item Moved "CAP plugins w/o CDS Model" from sub-item of Spring Boot Integration to top-level entry, renamed to "CAP Java plugins in Brownfields Apps". --- java/_menu.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/java/_menu.md b/java/_menu.md index 984673608..a681b0852 100644 --- a/java/_menu.md +++ b/java/_menu.md @@ -24,7 +24,7 @@ # [Multitenancy](multitenancy) # [Security](security) # [Spring Boot Integration](spring-boot-integration) -## [CAP plugins w/o CDS Model](cap-plugins-in-spring-boot-apps) +# [CAP Java plugins in Brownfields Apps](cap-plugins-in-spring-boot-apps) # [Developing Applications](developing-applications/) ## [Building](developing-applications/building) ## [Running](developing-applications/running) From d8a64444f9c0985675ab977175f893871ba808bd Mon Sep 17 00:00:00 2001 From: Robin de Silva Jayasinghe Date: Mon, 27 Apr 2026 11:17:24 +0200 Subject: [PATCH 2/7] Update document title to match menu item --- java/cap-plugins-in-spring-boot-apps.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/java/cap-plugins-in-spring-boot-apps.md b/java/cap-plugins-in-spring-boot-apps.md index cdd4e0ec7..bc2466b4d 100644 --- a/java/cap-plugins-in-spring-boot-apps.md +++ b/java/cap-plugins-in-spring-boot-apps.md @@ -4,7 +4,7 @@ synopsis: > status: released --- -# Use CAP Plugins in Spring Boot Applications without a CDS Model +# CAP Java plugins in Brownfields Apps + + + +{{ $frontmatter.synopsis }} + +CAP Java offers a [variety of plugins that integrate with SAP BTP services](../plugins/) and keep your application free of hard-coded service dependencies. In the CAP ecosystem, this approach is called [Calesi (CAP level service integration)](../get-started/concepts#the-calesi-pattern). The following sections describe plugins that complement the integrations already covered by the core capire documentation. + +In most cases, you add a CAP Java plugin by adding one or more dependencies to your application `pom.xml` and by adding configuration to `application.yaml` or another mechanism for [Spring Boot configuration](https://docs.spring.io/spring-boot/reference/features/external-config.html). + +## SAP Document Management Service + +The `sdm` plugin integrates CAP Java applications with the [SAP Document Management Service](https://help.sap.com/docs/document-management-service), Integration Option. It uses a CMIS-based repository to store and manage attachments, and is an alternative to the default database or object store backed [Attachments](../guides/attachments) feature. + +### Setup + +Add the plugin dependency to your `pom.xml`: + +```xml + + com.sap.cds + sdm + ${sdm.version} + +``` + +The `cds-maven-plugin` must also be configured to resolve the CDS model contributions from the plugin: + +```xml + + com.sap.cds + cds-maven-plugin + ${cds.services.version} + + + cds.resolve + resolve + + + +``` + +### CDS Model + +Extend your entities with the `Attachments` aspect provided by the plugin: + +```cds +using { sap.attachments.Attachments } from 'com.sap.cds/sdm'; + +extend entity Books with { + attachments : Composition of many Attachments; +} +``` + +### BTP Service Binding + +Bind an SAP Document Management Service instance (plan `standard`) to your application. In `mta.yaml`: + +```yaml +modules: + - name: bookshop-srv + type: java + path: srv + properties: + REPOSITORY_ID: + requires: + - name: sdm-di-instance + +resources: + - name: sdm-di-instance + type: org.cloudfoundry.managed-service + parameters: + service: sdm + service-plan: standard +``` + +The `REPOSITORY_ID` environment variable identifies the pre-onboarded Document Management repository that the plugin writes to. + +### Multitenancy + +For SaaS applications, the plugin integrates with the CAP Java multitenancy lifecycle. On tenant subscription, it onboards a dedicated repository; on unsubscription, it offboards it. No additional code is required beyond the standard CAP multitenancy setup. Learn more in the [plugin documentation](https://github.com/cap-java/sdm). + +## SAP Integration Suite, Advanced Event Mesh + +The `cds-feature-advanced-event-mesh` plugin adds support for [SAP Integration Suite, Advanced Event Mesh](https://help.sap.com/docs/sap-integration-suite-advanced-event-mesh) as a CAP messaging backend. It extends the standard CAP messaging abstraction with the `aem` kind, backed by a Solace-based broker. + +### Setup + +Add the plugin dependency: + +```xml + + com.sap.cds + cds-feature-advanced-event-mesh + ${aem.version} + +``` + +### Configuration + +Configure the messaging service in `application.yaml`: + +```yaml +cds: + messaging: + services: + - name: "my-messaging" + kind: "aem" +``` + +### Service Binding + +The plugin expects a Cloud Foundry user-provided service named `advanced-event-mesh` with the following credentials structure: + +```json +{ + "authentication-service": { + "tokenendpoint": "https:///oauth2/token", + "clientid": "", + "clientsecret": "" + }, + "endpoints": { + "advanced-event-mesh": { + "uri": "https://:", + "amqp_uri": "amqps://:" + } + }, + "vpn": "" +} +``` + +An additional `aem-validation-service` binding is required for broker provisioning validation. + +### Queue and Subscription Management + +By default, the plugin automatically creates and manages queues and topic subscriptions on the broker. You can disable this behavior per messaging service: + +```yaml +cds: + messaging: + services: + - name: "my-messaging" + kind: "aem" + connection: + properties: + skipManagement: true +``` + +For details on how to emit and receive events using the CAP messaging APIs, refer to the [Messaging documentation](./java/messaging). Learn more in the [plugin documentation](https://github.com/cap-java/cds-feature-advanced-event-mesh). + +## SAP Cloud Application Event Hub + +The `cds-feature-event-hub` plugin integrates CAP Java applications with [SAP Cloud Application Event Hub](https://help.sap.com/docs/sap-cloud-application-event-hub), enabling out-of-the-box consumption and emission of business events across applications. + +### Setup + +Add the plugin dependency: + +```xml + + com.sap.cds + cds-feature-event-hub + ${event-hub.version} + +``` + +Bind an SAP Cloud Application Event Hub service instance to your application and follow the [SAP Cloud Application Event Hub Service Guide](https://help.sap.com/docs/sap-cloud-application-event-hub) for the required service configuration. Learn more in the [plugin documentation](https://github.com/cap-java/cds-feature-event-hub). + +## SAP Audit Log Service NG + +The `cds-feature-auditlog-ng` plugin integrates with the next-generation [SAP Audit Log Service](https://help.sap.com/docs/btp/sap-business-technology-platform/audit-log-service). It emits standardized audit log events conforming to the Audit Log Event Catalog, and is distinct from the `cds-feature-auditlog-v2` plugin already covered in the [Audit Logging documentation](./java/auditlog). + +The plugin supports four event categories: Personal Data Access, Personal Data Modification, Configuration Change, and Security. + +### Setup + +Add the plugin dependency: + +```xml + + com.sap.cds + cds-feature-auditlog-ng + ${auditlog-ng.version} + +``` + +### Service Binding + +The plugin looks for a Cloud Foundry user-provided service named `auditlog-ng` with the tag `auditlog-ng`. For local testing, add the credentials to your `default-env.json`: + +```json +{ + "VCAP_SERVICES": { + "user-provided": [{ + "instance_name": "auditlog-ng", + "name": "auditlog-ng", + "tags": ["auditlog-ng"], + "credentials": { + "url": "", + "region": "", + "namespace": "", + "cert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----", + "key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----", + "passphrase": "" + } + }] + } +} +``` + +### Usage + +Inject the `AuditLogService` and use the typed event builders to emit audit events. You can override the registered namespace per event using the `auditlog.namespace` key on the event payload: + +```java +@Autowired +AuditLogService auditLogService; + +SecurityLog securityLog = SecurityLog.create(); +securityLog.put("auditlog.namespace", "my-custom-namespace"); +auditLogService.logSecurity(securityLog); +``` + +The namespace override is preserved through the [Transactional Outbox](./java/outbox), so audit events remain consistent even when emitted inside a transaction. Learn more in the [plugin documentation](https://github.com/cap-java/cds-feature-auditlog-ng). diff --git a/java/cap-plugins-in-spring-boot-apps.md b/plugins-in-spring-boot-apps.md similarity index 98% rename from java/cap-plugins-in-spring-boot-apps.md rename to plugins-in-spring-boot-apps.md index a3d3f2616..30e97e9a3 100644 --- a/java/cap-plugins-in-spring-boot-apps.md +++ b/plugins-in-spring-boot-apps.md @@ -4,7 +4,7 @@ synopsis: > status: released --- -# Using BTP Services in Brownfield Apps +# Integrate non-CAP Applications + +{{ $frontmatter.synopsis }} + +CAP Java offers a [variety of plugins that integrate with SAP BTP services](../plugins/). To use a plugin in your CAP Java application, add the corresponding Maven dependency to your `pom.xml`. Depending on the plugin, you may also need to add or modify your CDS model. Refer to the [plugin documentation](../plugins/#as-plugin-for-cap-java) for plugin-specific setup instructions. diff --git a/plugins-in-spring-boot-apps.md b/java/plugins-in-non-cap-apps.md similarity index 100% rename from plugins-in-spring-boot-apps.md rename to java/plugins-in-non-cap-apps.md diff --git a/plugins-in-cap-apps.md b/plugins-in-cap-apps.md deleted file mode 100644 index f4cab0ca2..000000000 --- a/plugins-in-cap-apps.md +++ /dev/null @@ -1,241 +0,0 @@ ---- -synopsis: > - This guide shows how CAP Java applications can integrate with SAP BTP services - using CAP plugins that are not yet part of the capire documentation. -status: released ---- - -# Integrate CAP Applications - - - - - -{{ $frontmatter.synopsis }} - -CAP Java offers a [variety of plugins that integrate with SAP BTP services](../plugins/) and keep your application free of hard-coded service dependencies. In the CAP ecosystem, this approach is called [Calesi (CAP level service integration)](../get-started/concepts#the-calesi-pattern). The following sections describe plugins that complement the integrations already covered by the core capire documentation. - -In most cases, you add a CAP Java plugin by adding one or more dependencies to your application `pom.xml` and by adding configuration to `application.yaml` or another mechanism for [Spring Boot configuration](https://docs.spring.io/spring-boot/reference/features/external-config.html). - -## SAP Document Management Service - -The `sdm` plugin integrates CAP Java applications with the [SAP Document Management Service](https://help.sap.com/docs/document-management-service), Integration Option. It uses a CMIS-based repository to store and manage attachments, and is an alternative to the default database or object store backed [Attachments](../guides/attachments) feature. - -### Setup - -Add the plugin dependency to your `pom.xml`: - -```xml - - com.sap.cds - sdm - ${sdm.version} - -``` - -The `cds-maven-plugin` must also be configured to resolve the CDS model contributions from the plugin: - -```xml - - com.sap.cds - cds-maven-plugin - ${cds.services.version} - - - cds.resolve - resolve - - - -``` - -### CDS Model - -Extend your entities with the `Attachments` aspect provided by the plugin: - -```cds -using { sap.attachments.Attachments } from 'com.sap.cds/sdm'; - -extend entity Books with { - attachments : Composition of many Attachments; -} -``` - -### BTP Service Binding - -Bind an SAP Document Management Service instance (plan `standard`) to your application. In `mta.yaml`: - -```yaml -modules: - - name: bookshop-srv - type: java - path: srv - properties: - REPOSITORY_ID: - requires: - - name: sdm-di-instance - -resources: - - name: sdm-di-instance - type: org.cloudfoundry.managed-service - parameters: - service: sdm - service-plan: standard -``` - -The `REPOSITORY_ID` environment variable identifies the pre-onboarded Document Management repository that the plugin writes to. - -### Multitenancy - -For SaaS applications, the plugin integrates with the CAP Java multitenancy lifecycle. On tenant subscription, it onboards a dedicated repository; on unsubscription, it offboards it. No additional code is required beyond the standard CAP multitenancy setup. Learn more in the [plugin documentation](https://github.com/cap-java/sdm). - -## SAP Integration Suite, Advanced Event Mesh - -The `cds-feature-advanced-event-mesh` plugin adds support for [SAP Integration Suite, Advanced Event Mesh](https://help.sap.com/docs/sap-integration-suite-advanced-event-mesh) as a CAP messaging backend. It extends the standard CAP messaging abstraction with the `aem` kind, backed by a Solace-based broker. - -### Setup - -Add the plugin dependency: - -```xml - - com.sap.cds - cds-feature-advanced-event-mesh - ${aem.version} - -``` - -### Configuration - -Configure the messaging service in `application.yaml`: - -```yaml -cds: - messaging: - services: - - name: "my-messaging" - kind: "aem" -``` - -### Service Binding - -The plugin expects a Cloud Foundry user-provided service named `advanced-event-mesh` with the following credentials structure: - -```json -{ - "authentication-service": { - "tokenendpoint": "https:///oauth2/token", - "clientid": "", - "clientsecret": "" - }, - "endpoints": { - "advanced-event-mesh": { - "uri": "https://:", - "amqp_uri": "amqps://:" - } - }, - "vpn": "" -} -``` - -An additional `aem-validation-service` binding is required for broker provisioning validation. - -### Queue and Subscription Management - -By default, the plugin automatically creates and manages queues and topic subscriptions on the broker. You can disable this behavior per messaging service: - -```yaml -cds: - messaging: - services: - - name: "my-messaging" - kind: "aem" - connection: - properties: - skipManagement: true -``` - -For details on how to emit and receive events using the CAP messaging APIs, refer to the [Messaging documentation](./java/messaging). Learn more in the [plugin documentation](https://github.com/cap-java/cds-feature-advanced-event-mesh). - -## SAP Cloud Application Event Hub - -The `cds-feature-event-hub` plugin integrates CAP Java applications with [SAP Cloud Application Event Hub](https://help.sap.com/docs/sap-cloud-application-event-hub), enabling out-of-the-box consumption and emission of business events across applications. - -### Setup - -Add the plugin dependency: - -```xml - - com.sap.cds - cds-feature-event-hub - ${event-hub.version} - -``` - -Bind an SAP Cloud Application Event Hub service instance to your application and follow the [SAP Cloud Application Event Hub Service Guide](https://help.sap.com/docs/sap-cloud-application-event-hub) for the required service configuration. Learn more in the [plugin documentation](https://github.com/cap-java/cds-feature-event-hub). - -## SAP Audit Log Service NG - -The `cds-feature-auditlog-ng` plugin integrates with the next-generation [SAP Audit Log Service](https://help.sap.com/docs/btp/sap-business-technology-platform/audit-log-service). It emits standardized audit log events conforming to the Audit Log Event Catalog, and is distinct from the `cds-feature-auditlog-v2` plugin already covered in the [Audit Logging documentation](./java/auditlog). - -The plugin supports four event categories: Personal Data Access, Personal Data Modification, Configuration Change, and Security. - -### Setup - -Add the plugin dependency: - -```xml - - com.sap.cds - cds-feature-auditlog-ng - ${auditlog-ng.version} - -``` - -### Service Binding - -The plugin looks for a Cloud Foundry user-provided service named `auditlog-ng` with the tag `auditlog-ng`. For local testing, add the credentials to your `default-env.json`: - -```json -{ - "VCAP_SERVICES": { - "user-provided": [{ - "instance_name": "auditlog-ng", - "name": "auditlog-ng", - "tags": ["auditlog-ng"], - "credentials": { - "url": "", - "region": "", - "namespace": "", - "cert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----", - "key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----", - "passphrase": "" - } - }] - } -} -``` - -### Usage - -Inject the `AuditLogService` and use the typed event builders to emit audit events. You can override the registered namespace per event using the `auditlog.namespace` key on the event payload: - -```java -@Autowired -AuditLogService auditLogService; - -SecurityLog securityLog = SecurityLog.create(); -securityLog.put("auditlog.namespace", "my-custom-namespace"); -auditLogService.logSecurity(securityLog); -``` - -The namespace override is preserved through the [Transactional Outbox](./java/outbox), so audit events remain consistent even when emitted inside a transaction. Learn more in the [plugin documentation](https://github.com/cap-java/cds-feature-auditlog-ng). From 2eba4db054018f06c03d74a45b2728c94e19428b Mon Sep 17 00:00:00 2001 From: Robin de Silva Jayasinghe Date: Wed, 29 Apr 2026 19:05:39 +0200 Subject: [PATCH 6/7] Rename cap-plugins-in docs to btp-services-in and update menu links --- java/_menu.md | 4 ++-- java/{plugins-in-cap-apps.md => btp-services-in-cap-apps.md} | 0 ...ins-in-non-cap-apps.md => btp-services-in-non-cap-apps.md} | 0 3 files changed, 2 insertions(+), 2 deletions(-) rename java/{plugins-in-cap-apps.md => btp-services-in-cap-apps.md} (100%) rename java/{plugins-in-non-cap-apps.md => btp-services-in-non-cap-apps.md} (100%) diff --git a/java/_menu.md b/java/_menu.md index 3c7dc96f3..1ae118400 100644 --- a/java/_menu.md +++ b/java/_menu.md @@ -37,6 +37,6 @@ # [Integrating Applications](../../java/integrating-applications/) ## [Unified Customer Landscape](../../java/integrating-applications/ucl) # [Building Plugins](building-plugins) -# [Integrating CAP apps](plugins-in-cap-apps) -# [Integrating non-CAP apps](plugins-in-non-cap-apps) +# [BTP Services in CAP apps](btp-services-in-cap-apps) +# [BTP Services in non-CAP apps](btp-services-in-non-cap-apps) # [Migration Guides](migration) diff --git a/java/plugins-in-cap-apps.md b/java/btp-services-in-cap-apps.md similarity index 100% rename from java/plugins-in-cap-apps.md rename to java/btp-services-in-cap-apps.md diff --git a/java/plugins-in-non-cap-apps.md b/java/btp-services-in-non-cap-apps.md similarity index 100% rename from java/plugins-in-non-cap-apps.md rename to java/btp-services-in-non-cap-apps.md From fca44c40945301ff95028393b6562b40b84b6288 Mon Sep 17 00:00:00 2001 From: Mahati Shankar <93712176+smahati@users.noreply.github.com> Date: Fri, 8 May 2026 10:33:24 +0200 Subject: [PATCH 7/7] cosmetics --- java/btp-services-in-cap-apps.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/java/btp-services-in-cap-apps.md b/java/btp-services-in-cap-apps.md index f64ba7f5a..ccfec92c8 100644 --- a/java/btp-services-in-cap-apps.md +++ b/java/btp-services-in-cap-apps.md @@ -14,4 +14,4 @@ status: released {{ $frontmatter.synopsis }} -CAP Java offers a [variety of plugins that integrate with SAP BTP services](../plugins/). To use a plugin in your CAP Java application, add the corresponding Maven dependency to your `pom.xml`. Depending on the plugin, you may also need to add or modify your CDS model. Refer to the [plugin documentation](../plugins/#as-plugin-for-cap-java) for plugin-specific setup instructions. +CAP Java offers a [variety of plugins that integrate with SAP BTP services](../plugins/). To use a plugin in your CAP Java application, add the corresponding Maven dependency to your `pom.xml`. Some plugins need you to update your CDS model. Refer to the [plugin documentation](../plugins/#as-plugin-for-cap-java) for plugin-specific setup instructions.