From 74cbbc93b92283005f4bd28de1316f1ea1a92aff Mon Sep 17 00:00:00 2001 From: KBbitsP <75751774+KBbitsP@users.noreply.github.com> Date: Tue, 15 Sep 2026 14:19:29 +0530 Subject: [PATCH] https://github.com/killbill/technical-support/issues/300 Aviate Settings docs --- html5/_main_toc.html.slim | 3 + userguide/aviate/aviate-getting-started.adoc | 2 + userguide/aviate/aviate-tenant-settings.adoc | 172 +++++++++++++++++++ 3 files changed, 177 insertions(+) create mode 100644 userguide/aviate/aviate-tenant-settings.adoc diff --git a/html5/_main_toc.html.slim b/html5/_main_toc.html.slim index 5ec4392ce..f4554cc25 100644 --- a/html5/_main_toc.html.slim +++ b/html5/_main_toc.html.slim @@ -330,6 +330,9 @@ nav.sidebar-nav li a.nav-link href="/latest/how-to-install-the-aviate-plugin.html" | Aviate Plugin Installation + li + a.nav-link href="/latest/aviate-tenant-settings.html" + | Tenant Settings li a.nav-link href="/latest/aviate-database-migrations.html" | Database Migrations diff --git a/userguide/aviate/aviate-getting-started.adoc b/userguide/aviate/aviate-getting-started.adoc index b825b7420..304c9d089 100644 --- a/userguide/aviate/aviate-getting-started.adoc +++ b/userguide/aviate/aviate-getting-started.adoc @@ -47,6 +47,8 @@ For the purpose of this guide, use the following fictive company: ** United Kingdom (GBP) ** France (EUR) +For the full set of organization options-including logo and brand color-and how they interact with invoice and email templates, see the https://docs.killbill.io/latest/aviate-tenant-settings.html[Aviate Tenant Settings] guide. + The following demo shows how you can configure the organization settings via Aviate. :storylane-id: eykmjqwtc4vf diff --git a/userguide/aviate/aviate-tenant-settings.adoc b/userguide/aviate/aviate-tenant-settings.adoc new file mode 100644 index 000000000..106e4a6ab --- /dev/null +++ b/userguide/aviate/aviate-tenant-settings.adoc @@ -0,0 +1,172 @@ += Aviate Tenant Settings + +:card-badge: Premium +:card-title: Aviate +:card-link: https://aviate.killbill.io/ +:card-description: +include::{sourcedir}/includes/premium-card.adoc[] + +== Overview + +The *Settings* screen groups the configuration that applies to a single tenant. It is reached from *Configuration -> Settings* in the left navigation. + +Settings are scoped to the tenant of the currently selected deployment. Switching deployments reloads the screen with that tenant's values. + +The *Organization* tab holds your company details and branding, and is described in full below. The remaining tabs expose Kill Bill per-tenant configuration properties. + +== Organization + +The *Organization* tab defines who you are as a business. The values entered here apply by default to invoices, emails, and quotes, so that customer-facing documents carry consistent company details and branding. + +=== Company Information + +[cols="1,3", options="header"] +|=== +| Field | Description + +| Company name +| The legal or trading name of your business. + +| Company address +| Street address of your business. + +| City, province, postal code +| Remainder of the postal address, entered as a single line. + +| Company country +| Country of your business, selected from a list of ISO countries. + +| Company URL +| Your company website. If no protocol is entered, `https://` is added automatically when the value is saved. +|=== + +=== Logo and Brand Color + +The Organization tab also lets you upload a *company logo* and choose a *primary brand color*. The logo appears on invoice and email documents, and the brand color is used for styling elements such as invoice table headings. + +=== How These Values Are Used + +Organization settings act as the defaults for customer-facing documents. Individual invoice templates and email templates can define their own values, in which case those take precedence. + +The resolution order is: + +. The template-level override, if one is defined. +. The Organization setting. +. The built-in default. + +This means you can set your company details once on the Organization tab, and only override them where a specific template needs something different. + +=== Saving Changes + +*Save* becomes active as soon as you change a value. Company information, brand color, and logo are saved independently, so changing one does not rewrite the others. Use *Reset* to discard unsaved changes and restore the values currently stored. + +[NOTE] +On the first save, values still at their defaults are written as well, so that the stored configuration matches what the screen shows. + +=== Reading the Stored Values via the API + +Organization settings are stored as Kill Bill tenant key-values and can be read through the Kill Bill https://apidocs.killbill.io/tenant.html[Tenant API]. For example, to retrieve the saved company information: + +[source,bash] +---- +curl -u admin:password \ + -H "X-Killbill-ApiKey: my-tenant" \ + -H "X-Killbill-ApiSecret: my-secret" \ + "http://127.0.0.1:8080/1.0/kb/tenants/userKeyValue/COMPANY_INFO" +---- + +[NOTE] +The structure of these values is managed by Aviate. Use the Organization tab to change them rather than writing the keys directly. + +== Configuration Tabs + +The remaining tabs edit Kill Bill configuration properties for the selected tenant. Rather than repeating the property list here, each field on screen shows the underlying system key (for example `org.killbill.invoice.maxNumberOfMonthsInFuture`), which you can look up in the https://docs.killbill.io/latest/userguide_configuration.html[Kill Bill Configuration Guide] for its meaning, default value, and how else it can be set. + +=== Where a Value Comes From + +Kill Bill resolves a property from several layers. Each field carries a badge showing the layer the value currently in effect came from: + +[cols="1,3", options="header"] +|=== +| Badge | Meaning + +| Default +| The built-in Kill Bill default; nothing has overridden it. + +| Runtime +| The value comes from the runtime configuration. + +| Environment +| The value comes from an environment variable. + +| Tenant +| A per-tenant value has been set for this tenant. +|=== + +Saving a change on one of these tabs writes a per-tenant value, which takes precedence over the global configuration. + +=== System-Level Properties + +Not every Kill Bill property can be set per tenant. Properties that cannot are listed on the tab under *System-Level Properties* and are shown read-only: they are configured at the system level during deployment, through the Kill Bill properties file or environment variables. + +=== Available Tabs + +[cols="1,2", options="header"] +|=== +| Tab | Corresponding section of the Configuration Guide + +| Invoices +| Invoice Properties + +| Payments +| Payment Properties + +| Payment Retry +| Payment Properties (retry schedule) + +| Push Notifications +| Push Notifications Properties + +| Events +| Events Properties + +| Subscriptions +| Subscription Properties + +| Catalog +| Catalog Properties + +| JAX-RS +| Jax-rs Properties + +| Server +| Kill Bill Server Properties + +| Database +| Database Properties + +| Read-Only Database +| RO Database Properties + +| OSGI +| OSGi Properties + +| OSGI Database +| Plugin Database Properties + +| Security +| Security Properties +|=== + +=== Setting Per-Tenant Properties via the API + +Per-tenant properties can also be set outside the UI, using the https://apidocs.killbill.io/#tenant-add-a-per-tenant-system-properties-configuration[uploadPerTenantConfig] endpoint. Refer to the https://docs.killbill.io/latest/userguide_configuration.html[Kill Bill Configuration Guide] for details and for the full list of properties. + +[NOTE] +Each call to that endpoint overwrites the previous per-tenant properties, so the full list must be supplied every time. + +== Related + +* https://docs.killbill.io/latest/aviate-getting-started.html[Getting Started with Aviate and Kaui] - initial setup, including organization settings +* https://docs.killbill.io/latest/userguide_configuration.html[Kill Bill Configuration Guide] - all configuration properties and the ways they can be set +* https://apidocs.killbill.io/tenant.html[Tenant API] - read and write tenant configuration programmatically