From a5b8f493f4a9cfabd648096dcff6a81db17bf650 Mon Sep 17 00:00:00 2001 From: Eckart Liemke <eckart.liemke@sap.com> Date: Tue, 1 Apr 2025 13:55:11 +0200 Subject: [PATCH 1/9] 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` | <Beta/> `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`) | </div> @@ -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 <eckart.liemke@sap.com> Date: Fri, 4 Apr 2025 15:28:53 +0200 Subject: [PATCH 2/9] 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` | <beta/> Activation status ( `1` for draft, `2` for active, default is `2`) | </div> @@ -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 | </div> @@ -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: [] }_ <beta/> + +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_ <beta/> + +Activates extension draft `ID` and makes it publicly visible. + +#### HTTP Request Options + +| Request Header | Example Value | Description | +| ---------------- | -------------------------------------------------------|--------------| +| `prefer` | `respond-async` | Trigger asynchronous extension activation | + + +<div class="cols-2"> + +<div> + +#### 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) ) | + +</div> + +</div> + +#### Example Usage + +```http [Request] +POST /-/cds/extensibility/activate +Content-Type: application/json +Authorization: Basic carol: + +{ + "ID": "isbn-extension", + "level": 2 +} +``` + +### `discard` _(ID)_ <beta/> + +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 <eckart.liemke@sap.com> Date: Fri, 4 Apr 2025 16:11:29 +0200 Subject: [PATCH 3/9] 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_ <beta/> +### `activate` _(ID, level, options) → Jobs_ <beta/> {#activate-extension-draft} Activates extension draft `ID` and makes it publicly visible. From a75e5d2150d311fb009866a9013b6f92269db562 Mon Sep 17 00:00:00 2001 From: Eckart Liemke <eckart.liemke@sap.com> Date: Fri, 4 Apr 2025 16:20:07 +0200 Subject: [PATCH 4/9] 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_: From c6a0d872abd32e25b6b63f40d0e76a903dac255a Mon Sep 17 00:00:00 2001 From: Eckart Liemke <eckart.liemke@sap.com> Date: Tue, 1 Apr 2025 13:55:11 +0200 Subject: [PATCH 5/9] 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` | <Beta/> `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`) | </div> @@ -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 93e94e3fb94e7c2724a540a9c9990569eb5dd537 Mon Sep 17 00:00:00 2001 From: Eckart Liemke <eckart.liemke@sap.com> Date: Fri, 4 Apr 2025 15:28:53 +0200 Subject: [PATCH 6/9] 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` | <beta/> Activation status ( `1` for draft, `2` for active, default is `2`) | </div> @@ -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 | </div> @@ -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: [] }_ <beta/> + +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_ <beta/> + +Activates extension draft `ID` and makes it publicly visible. + +#### HTTP Request Options + +| Request Header | Example Value | Description | +| ---------------- | -------------------------------------------------------|--------------| +| `prefer` | `respond-async` | Trigger asynchronous extension activation | + + +<div class="cols-2"> + +<div> + +#### 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) ) | + +</div> + +</div> + +#### Example Usage + +```http [Request] +POST /-/cds/extensibility/activate +Content-Type: application/json +Authorization: Basic carol: + +{ + "ID": "isbn-extension", + "level": 2 +} +``` + +### `discard` _(ID)_ <beta/> + +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 cdbfd219309d7b5b607af7e6fe6c0563bf3db208 Mon Sep 17 00:00:00 2001 From: Eckart Liemke <eckart.liemke@sap.com> Date: Fri, 4 Apr 2025 16:11:29 +0200 Subject: [PATCH 7/9] 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_ <beta/> +### `activate` _(ID, level, options) → Jobs_ <beta/> {#activate-extension-draft} Activates extension draft `ID` and makes it publicly visible. From 15eebe85bade01efab2d17a075d57c269defca75 Mon Sep 17 00:00:00 2001 From: Eckart Liemke <eckart.liemke@sap.com> Date: Fri, 4 Apr 2025 16:20:07 +0200 Subject: [PATCH 8/9] next link fix --- guides/multitenancy/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/multitenancy/index.md b/guides/multitenancy/index.md index a183ac8d2..5b2b1e4d9 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 From 65f2c19d790d84bf1226f7b015d0fbcf9e37884b Mon Sep 17 00:00:00 2001 From: Eckart Liemke <eckart.liemke@sap.com> Date: Tue, 6 May 2025 09:03:58 +0200 Subject: [PATCH 9/9] rename level to status --- guides/multitenancy/mtxs.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/guides/multitenancy/mtxs.md b/guides/multitenancy/mtxs.md index 2615b1b76..1d1591f13 100644 --- a/guides/multitenancy/mtxs.md +++ b/guides/multitenancy/mtxs.md @@ -1107,8 +1107,8 @@ Activates extension draft `ID` and makes it publicly visible. | **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) ) | +| `status` (optional) | Target activation level, `1` or `2`, default is `2`, `1` is a no-op currently | +| `options` (optional) | Various options, including deployment options (similar to [upgrade in SaasProvisioningService](#upgrade-options) ) | </div> @@ -1122,8 +1122,7 @@ Content-Type: application/json Authorization: Basic carol: { - "ID": "isbn-extension", - "level": 2 + "ID": "isbn-extension" } ```