From a5b8f493f4a9cfabd648096dcff6a81db17bf650 Mon Sep 17 00:00:00 2001 From: Eckart Liemke Date: Tue, 1 Apr 2025 13:55:11 +0200 Subject: [PATCH 1/4] first scetch of extension draft api --- guides/multitenancy/mtxs.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/guides/multitenancy/mtxs.md b/guides/multitenancy/mtxs.md index 1c96b8c0c..00cbe419b 100644 --- a/guides/multitenancy/mtxs.md +++ b/guides/multitenancy/mtxs.md @@ -685,14 +685,15 @@ The _ModelProviderService_ serves model variants, which may include tenant-speci - `in-sidecar` — provides defaults for usage in sidecars - `from-sidecar` — shortcut for `{ "kind": "rest" }` -### `getCsn` _(tenant, toggles) → CSN_ +### `getCsn` _(tenant, toggles) → CSN_ {#modelprovider-get-csn} Returns the application's effective CSN document for the given tenant + feature toggles vector. CAP runtimes call that method to obtain the effective models to serve. -| Arguments | Description | -| --------- | ----------------------------------------------------------- | -| `tenant` | A string identifying the tenant | -| `toggles` | An array listing toggled features; `['*']` for all features | +| Arguments | Description | +| ----------- | ----------------------------------------------------------- | +| `tenant` | A string identifying the tenant | +| `toggles` | An array listing toggled features; `['*']` for all features | +| `activated` | `false` to include also extension drafts, default is `true` | #### Example Usage {#example-get-csn } @@ -893,6 +894,11 @@ Content-Type: application/json Creates a new tenant-specific extension. +Extensions can be created as draft. In that case, the extensions need to be activate using action [`activate`](#activate-extension-draft) to get visible for everyone. + +To get the full model including draft extensions, the [Model Provider Service](#modelprovider-get-csn) has to be called accordingly. + + #### HTTP Request Options | Request Header | Example Value | Description | @@ -911,6 +917,7 @@ Creates a new tenant-specific extension. | **Body** | `csn` | Array of extension CDL or CSN to apply | | `i18n` | Texts and translations | +| `status` | Activation status ( `1` for draft, `2` for active, default is `2`) | @@ -1044,6 +1051,8 @@ The response is similar to the following: The job and task status can take on the values `QUEUED`, `RUNNING`, `FINISHED` and `FAILED`. +### Activate extension draft + ## DeploymentService The _DeploymentService_ handles `subscribe`, `unsubscribe`, and `upgrade` events for single tenants and single apps or micro services. Actual implementation is provided through internal plugins, for example, for SAP HANA and SQLite. From 1b0c9d5e38b50a85d03e17e55a8fcf4ac00f0636 Mon Sep 17 00:00:00 2001 From: Eckart Liemke Date: Fri, 4 Apr 2025 15:28:53 +0200 Subject: [PATCH 2/4] continue on draft api --- guides/multitenancy/mtxs.md | 107 ++++++++++++++++++++++++++++++++++-- 1 file changed, 102 insertions(+), 5 deletions(-) diff --git a/guides/multitenancy/mtxs.md b/guides/multitenancy/mtxs.md index 00cbe419b..f3af6dfd3 100644 --- a/guides/multitenancy/mtxs.md +++ b/guides/multitenancy/mtxs.md @@ -917,7 +917,7 @@ To get the full model including draft extensions, the [Model Provider Service](# | **Body** | `csn` | Array of extension CDL or CSN to apply | | `i18n` | Texts and translations | -| `status` | Activation status ( `1` for draft, `2` for active, default is `2`) | +| `status` | Activation status ( `1` for draft, `2` for active, default is `2`) | @@ -1019,6 +1019,9 @@ Deletes a tenant-specific extension. | **Parameters** | Description | | - | - | | `ID` | String uniquely identifying the extension | +| - | - | +| **Query parameters** | Description | +| `status` | `status` of the deletion. `2` for active deletion (default), `1` for deletion as draft | @@ -1027,11 +1030,19 @@ Deletes a tenant-specific extension. #### Example Usage ```http [Request] -DELETE /-/cds/extensibility/Extensions/isbn-extension HTTP/1.1 +DELETE /-/cds/extensibility/Extensions/isbn-extension?status=1 HTTP/1.1 Content-Type: application/json ``` -The request can also be triggered asynchronously by setting the `Prefer: respond-async` header. +Using query parameter `?status=1`, the extension with `ID` `isbn-extension` is deleted as draft. If the extension exists as draft, the draft will be discarded (similar to [discard](#discard-id)). +If the extension is active, the deletion is stored as draft and requires an [activation](#activate-id-level-options--jobs) to be deployed to the database. + +::: warning Deployment of extension deletions +The deployment of extension deletions only works for the SAP HANA Database, it it is configured accordingly. + +::: + +The `DELETE` request can also be triggered asynchronously by setting the `Prefer: respond-async` header. You can use the URL returned in the `Location` response header to poll the job status. In addition, you can poll the status for individual tenants using its individual task ID: @@ -1051,7 +1062,93 @@ The response is similar to the following: The job and task status can take on the values `QUEUED`, `RUNNING`, `FINISHED` and `FAILED`. -### Activate extension draft +### `validate` _(ID)_ _→ { errors: [], messages: [] }_ + +Validates extension draft `ID`. The validation checks the syntax and the permissions of an extension. + +Returns errors and messages in case if the validation fails. + +#### Request Format + +| **Parameters** | Description | +| - | - | +| `ID` | String uniquely identifying the extension | + + +#### Example Usage + +```http [Request] +POST /-/cds/extensibility/validate +Content-Type: application/json +Authorization: Basic carol: + +{ + "ID": "isbn-extension" +} +``` + +### `activate` _(ID, level, options) → Jobs_ + +Activates extension draft `ID` and makes it publicly visible. + +#### HTTP Request Options + +| Request Header | Example Value | Description | +| ---------------- | -------------------------------------------------------|--------------| +| `prefer` | `respond-async` | Trigger asynchronous extension activation | + + +
+ +
+ +#### Request Format + +| **Parameters** | Description | +| - | - | +| `ID` | String uniquely identifying the extension | +| `level` | Target activation level, `1` or `2`, default is `2`, `1` is a no-op currently | +| `options` | Various options, including deployment options (similar to [upgrade in SaasProvisioningService](#upgrade-options) ) | + +
+ +
+ +#### Example Usage + +```http [Request] +POST /-/cds/extensibility/activate +Content-Type: application/json +Authorization: Basic carol: + +{ + "ID": "isbn-extension", + "level": 2 +} +``` + +### `discard` _(ID)_ + +Discards extension draft `ID`. + +#### Request Format + +| **Parameters** | Description | +| - | - | +| `ID` | String uniquely identifying the extension | + + +#### Example Usage + +```http [Request] +POST /-/cds/extensibility/discard +Content-Type: application/json +Authorization: Basic carol: + +{ + "ID": "isbn-extension" +} +``` ## DeploymentService @@ -1298,7 +1395,7 @@ Returns configured SAP BTP SaaS Provisioning service dependencies. [Learn how to configure SaaS dependencies](./#saas-dependencies){.learn-more} -### `upgrade` _[tenants] → Jobs_ +### `upgrade` _[tenants] → Jobs_ {#upgrade-options} Use the `upgrade` endpoint to upgrade tenant base models. From 32fac940121f06031e66cd86fde12107cb38603e Mon Sep 17 00:00:00 2001 From: Eckart Liemke Date: Fri, 4 Apr 2025 16:11:29 +0200 Subject: [PATCH 3/4] fix internal links --- guides/multitenancy/mtxs.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guides/multitenancy/mtxs.md b/guides/multitenancy/mtxs.md index f3af6dfd3..2615b1b76 100644 --- a/guides/multitenancy/mtxs.md +++ b/guides/multitenancy/mtxs.md @@ -1035,7 +1035,7 @@ Content-Type: application/json ``` Using query parameter `?status=1`, the extension with `ID` `isbn-extension` is deleted as draft. If the extension exists as draft, the draft will be discarded (similar to [discard](#discard-id)). -If the extension is active, the deletion is stored as draft and requires an [activation](#activate-id-level-options--jobs) to be deployed to the database. +If the extension is active, the deletion is stored as draft and requires an [activation](#activate-extension-draft) to be deployed to the database. ::: warning Deployment of extension deletions The deployment of extension deletions only works for the SAP HANA Database, it it is configured accordingly. @@ -1087,7 +1087,7 @@ Authorization: Basic carol: } ``` -### `activate` _(ID, level, options) → Jobs_ +### `activate` _(ID, level, options) → Jobs_ {#activate-extension-draft} Activates extension draft `ID` and makes it publicly visible. From a75e5d2150d311fb009866a9013b6f92269db562 Mon Sep 17 00:00:00 2001 From: Eckart Liemke Date: Fri, 4 Apr 2025 16:20:07 +0200 Subject: [PATCH 4/4] next link fix --- guides/multitenancy/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/guides/multitenancy/index.md b/guides/multitenancy/index.md index d97fc95c1..3b4fb94e0 100644 --- a/guides/multitenancy/index.md +++ b/guides/multitenancy/index.md @@ -888,7 +888,7 @@ There are several ways to run the update of the database schema. #### MTX Sidecar API -Please check the [Upgrade API](./mtxs#upgrade-tenants-→-jobs) to see how the database schema update can be run for single or all tenants using the API endpoint. +Please check the [Upgrade API](./mtxs#upgrade-options) to see how the database schema update can be run for single or all tenants using the API endpoint. #### `cds-mtx upgrade` Command @@ -993,14 +993,14 @@ cds watch --profile dev ## SaaS Dependencies {#saas-dependencies} Some of the xsuaa-based services your application consumes need to be registered as _reuse services_ to work in multitenant environments. This holds true for the usage of both the SaaS Registry service and the Subscription Manager Service (SMS). -CAP Java as well as `@sap/cds-mtxs`, each offer an easy way to integrate these dependencies. They support some services out of the box and also provide a simple API for applications. Most notably, you need such dependencies for the following SAP BTP services: [Audit Log](https://discovery-center.cloud.sap/serviceCatalog/audit-log-service), [Event Mesh](https://discovery-center.cloud.sap/serviceCatalog/event-mesh), [Destination](https://discovery-center.cloud.sap/serviceCatalog/destination), [HTML5 Application Repository](https://discovery-center.cloud.sap/serviceCatalog/html5-application-repository-service), and [Cloud Portal](https://discovery-center.cloud.sap/serviceCatalog/cloud-portal-service). +CAP Java as well as `@sap/cds-mtxs`, each offer an easy way to integrate these dependencies. They support some services out of the box and also provide a simple API for applications. Most notably, you need such dependencies for the following SAP BTP services: [Audit Log](https://discovery-center.cloud.sap/serviceCatalog/audit-log-service), [Event Mesh](https://discovery-center.cloud.sap/serviceCatalog/event-mesh), [Destination](https://discovery-center.cloud.sap/serviceCatalog/destination), [HTML5 Application Repository](https://discovery-center.cloud.sap/serviceCatalog/html5-application-repository-service), and [Cloud Portal](https://discovery-center.cloud.sap/serviceCatalog/cloud-portal-service). For CAP Java, all these services are supported natively and SaaS dependencies are automatically created if such a service instance is bound to the CAP Java application, that is, the `srv` module. :::tip Explicitly activate the Destination service SaaS dependency for Destination service needs to be activated explicitly in the `application.yaml` due to security reasons. SaaS dependencies for some of the other services can be **de**activated by setting the corresponding property to `false` in the `application.yaml`. -Refer to the `cds.multiTenancy.dependencies` section in the [CDS properties](/java/developing-applications/properties#cds-properties). +Refer to the `cds.multiTenancy.dependencies` section in the [CDS properties](/java/developing-applications/properties#cds-properties). ::: For CAP Node.js, all these services are supported natively and can be activated individually by providing configuration in `cds.requires`. In the most common case, you simply activate service dependencies like so: @@ -1049,7 +1049,7 @@ The Boolean values in the _mtx/sidecar/package.json_ activate the default config ### Additional Services -If your CAP Java application uses a service that isn't supported out of the box, you can add a custom dependency by providing a custom handler. Refer to [Define Dependent Services](../../java/multitenancy#define-dependent-services) for details. +If your CAP Java application uses a service that isn't supported out of the box, you can add a custom dependency by providing a custom handler. Refer to [Define Dependent Services](../../java/multitenancy#define-dependent-services) for details. In Node.js, you can use the `subscriptionDependency` setting to provide a dependency configuration similar to the standard configuration shown before. Use your application's or CAP plugin's _package.json_: