diff --git a/docs/api-guide/cs-admin-rest-api/get-domain-settings.md b/docs/api-guide/cs-admin-rest-api/get-domain-settings.md deleted file mode 100644 index 7dfb3e23dc..0000000000 --- a/docs/api-guide/cs-admin-rest-api/get-domain-settings.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -sidebar_position: 8 ---- - -# Get Domain Settings - -### Description - -*Added in CloudShell 2024.1.* - -Gets all settings for a specific domain. Domain settings control per-domain behavior such as email notification timing. - -### URL - -`http://{Admin API IP}:{port#}/api/v1/domains/{id}/settings` - -| Parameter | Description/Comments | -| --- | --- | -| ID | (string) Domain's ID. Can be retrieved via [Get all domains](./get-all-domains.md). | - -### HTTP method - -`GET` - -### Request - -
-Headers - -Example header format: - -`Authorization: Basic ` - -`Content-Type: application/json` - -
- -### Response - -
-Response example - -```javascript -[ - { - "Name": "NotificationMinutesBeforeEnd", - "Value": "10" - } -] -``` -
- -
-Response code - -```javascript -200 OK -``` -
diff --git a/docs/api-guide/cs-admin-rest-api/index.md b/docs/api-guide/cs-admin-rest-api/index.md index dcdfcc9ef9..95a2310e13 100644 --- a/docs/api-guide/cs-admin-rest-api/index.md +++ b/docs/api-guide/cs-admin-rest-api/index.md @@ -18,13 +18,6 @@ Manage CloudShell domains. - [Edit domain](./edit-domain.md) - [Delete domain](./delete-domain.md) -**DomainSettings:** - -Manage per-domain settings (e.g., notification preferences). - -- [Get domain settings](./get-domain-settings.md) -- [Update domain setting](./update-domain-setting.md) - **DomainBlueprints:** Manage a domain's blueprints. diff --git a/docs/api-guide/cs-admin-rest-api/update-domain-setting.md b/docs/api-guide/cs-admin-rest-api/update-domain-setting.md deleted file mode 100644 index 1ea7daa149..0000000000 --- a/docs/api-guide/cs-admin-rest-api/update-domain-setting.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -sidebar_position: 9 ---- - -# Update Domain Setting - -### Description - -*Added in CloudShell 2024.1.* - -Updates a specific setting for a domain. Use this to configure per-domain behavior such as email notification timing. - -### URL - -`http://{Admin API IP}:{port#}/api/v1/domains/{id}/settings` - -| Parameter | Description/Comments | -| --- | --- | -| ID | (string) Domain's ID. Can be retrieved via [Get all domains](./get-all-domains.md). | - -### HTTP method - -`PUT` - -### Request - -
-Headers - -Example header format: - -`Authorization: Basic ` - -`Content-Type: application/json` - -
- -
-Request body - -| Parameter | Description/Comments | -| --- | --- | -| `Name` | The name of the domain setting to update. `(string)` | -| `Value` | The new value for the setting. `(string)` | - -
- -
-Request example - -```javascript -{ - "Name": "NotificationMinutesBeforeEnd", - "Value": "15" -} -``` -
- -### Response - -
-Response code - -```javascript -200 OK -``` -
- -### Available Domain Settings - -| Setting Name | Description | -| --- | --- | -| `NotificationMinutesBeforeEnd` | Number of minutes before sandbox end time to send an email notification to the sandbox owner. | diff --git a/docs/devguide/available-cs-api/useful-cs-api-examples/per-domain-email-notification-defaults.md b/docs/devguide/available-cs-api/useful-cs-api-examples/per-domain-email-notification-defaults.md new file mode 100644 index 0000000000..a21e2f1e6a --- /dev/null +++ b/docs/devguide/available-cs-api/useful-cs-api-examples/per-domain-email-notification-defaults.md @@ -0,0 +1,87 @@ +--- +sidebar_position: 11 +--- + +# Setting Email Notification Defaults per Domain + +By default, the sandbox email notification defaults (for example, how many minutes before the sandbox ends the **Before end** notification is sent) are set globally for the whole CloudShell deployment, using the `ReservationEmail.*` keys in the Quali Server's `customer.config` file. For details, see [Email Notifications Overview](../../../intro/features/email-notifications.md). + +You can override these defaults for a specific domain using the `UpdateDomainSetting` and `GetDomainSettings` Automation API methods. For example, the **Before end** notification can default to 60 minutes before the end in `Domain1` and 24 hours before the end in `Domain2`. + +*Available in CloudShell 2024.1.0.2686 and later, 2025.1 and 2026.1. To use these methods from Python, use `cloudshell-automation-api` 2026.1 or later.* + +## How it works + +- **These values are defaults only.** They determine the values that are pre-filled in the **Email Notifications** section of the **Reserve** form when a user reserves a sandbox while working in that domain. As with the global defaults, users can change them per sandbox, unless the domain disables this with `NonAdminCanChangeNotifications`. +- **Settings you don't set fall back to the global value.** Each domain stores only the settings you set for it. Any setting not set for the domain uses the global `customer.config` value, and a domain with no settings behaves exactly as before. +- **They apply to the domain the user is working in.** The defaults come from the user's current domain at the time they open the **Reserve** form. +- **The Automation API isn't affected.** Sandboxes created through the Automation API (for example, `CreateImmediateTopologyReservation`) use the notification values passed by the caller, not these defaults. + +## Available settings + +The setting names are the names of the global `ReservationEmail.*` keys, without the `ReservationEmail.` prefix. Names are case-sensitive. + +| Setting name | Value | Default for | +| --- | --- | --- | +| `SendNotificationBeforeEnd` | `True`/`False` | Whether the **Before end** notification is selected | +| `NotificationMinutesBeforeEnd` | Number of minutes | How long before the sandbox ends (before its teardown starts) the **Before end** notification is sent | +| `SendNotificationOnStart` | `True`/`False` | Whether the **On start** notification is selected | +| `SendNotificationOnSetupComplete` | `True`/`False` | Whether the **On setup complete** notification is selected | +| `SendNotificationOnEnd` | `True`/`False` | Whether the **On end** notification is selected | +| `NonAdminCanChangeNotifications` | `True`/`False` | Whether regular users can change the notification selections in the **Reserve** form (admins and domain admins always can) | + +The other `ReservationEmail.*` keys (such as `NotifySystemAdmins`, `NotifyDomainAdmins`, `RecipientsToNotify`, `SendNotificationOnReschedule` and the `Override*` keys) control who receives the emails and when they're sent, not the **Reserve** form defaults. They are always global, and setting them per domain has no effect. + +:::note +Setting names and values aren't validated. A misspelled name or a value that isn't a valid number or `True`/`False` is saved but ignored, and the global value is used instead. Use `GetDomainSettings` to check what is stored for a domain. +::: + +## API methods + +| Method | Parameters | Description | +| --- | --- | --- | +| `UpdateDomainSetting` | `domainName`, `name`, `value` (all strings) | Creates or updates a single setting for the domain. Only admins can call it. | +| `GetDomainSettings` | `domainName` | Returns the settings stored for the domain, as a list of `Key`/`Value` items. It doesn't include the global values for settings that aren't set for the domain. | + +There is no method that deletes a setting. To return a domain to the global behavior for a setting, set it to the same value as the global key. + +## Example + +The following script sends the **Before end** notification by default 60 minutes before the end in `Domain1` and 24 hours (1440 minutes) before the end in `Domain2`: + +```python +from cloudshell.api.cloudshell_api import CloudShellAPISession + +api = CloudShellAPISession(host='', username='admin', password='', domain='Global') + +domain_defaults = { + 'Domain1': {'SendNotificationBeforeEnd': 'True', 'NotificationMinutesBeforeEnd': '60'}, + 'Domain2': {'SendNotificationBeforeEnd': 'True', 'NotificationMinutesBeforeEnd': '1440'}, +} + +for domain_name, settings in domain_defaults.items(): + for name, value in settings.items(): + api.UpdateDomainSetting(domainName=domain_name, name=name, value=value) + +for domain_name in domain_defaults: + stored = api.GetDomainSettings(domainName=domain_name) + print(domain_name, {item.Key: item.Value for item in stored.Settings}) +``` + +Output: + +``` +Domain1 {'SendNotificationBeforeEnd': 'True', 'NotificationMinutesBeforeEnd': '60'} +Domain2 {'SendNotificationBeforeEnd': 'True', 'NotificationMinutesBeforeEnd': '1440'} +``` + +New sandboxes reserved from the Portal in these domains will now have the **Before end** notification selected, set to 60 minutes and 24 hours before the end respectively. Sandboxes reserved in other domains keep using the global `ReservationEmail.NotificationMinutesBeforeEnd` value. + +:::note +The `SendNotificationBeforeEnd` setting is included because the minutes value only matters if the **Before end** notification is selected. If the global `ReservationEmail.SendNotificationBeforeEnd` key is already `True`, setting `NotificationMinutesBeforeEnd` alone is enough. +::: + +## Related topics + +- [Email Notifications Overview](../../../intro/features/email-notifications.md) +- [Advanced CloudShell Customizations](../../../admin/setting-up-cloudshell/cloudshell-configuration-options/advanced-cloudshell-customizations.md) diff --git a/docs/intro/features/email-notifications.md b/docs/intro/features/email-notifications.md index 3b94fb2c35..abb7a28792 100644 --- a/docs/intro/features/email-notifications.md +++ b/docs/intro/features/email-notifications.md @@ -51,6 +51,10 @@ Note that the sandbox end-user can change the defaults in the **Email Notificati ![](/Images/CloudShell-Portal/Lab-Management/Reservations/ReservePaneEmailNotificaions.png) +#### Per-domain defaults + +You can override these defaults for specific domains. For example, the **Before end** notification can default to 60 minutes in one domain and 24 hours in another. Domains without their own values use the keys above. Per-domain defaults are set using the `UpdateDomainSetting` Automation API method. For details, see [Setting Email Notification Defaults per Domain](../../devguide/available-cs-api/useful-cs-api-examples/per-domain-email-notification-defaults.md). + ### Admin override keys **Email notifications for all sandbox events to admins/domain admins:**