From 777543656ca7b2ac4ceb207783d221ddd8226d16 Mon Sep 17 00:00:00 2001 From: reshmabidikar Date: Tue, 26 Nov 2024 09:57:23 +0530 Subject: [PATCH 1/6] Initial commit --- userguide/aviate/aviate-catalog.adoc | 158 +++++++++++++++++++++++++++ 1 file changed, 158 insertions(+) diff --git a/userguide/aviate/aviate-catalog.adoc b/userguide/aviate/aviate-catalog.adoc index 98739fada..07097de7f 100644 --- a/userguide/aviate/aviate-catalog.adoc +++ b/userguide/aviate/aviate-catalog.adoc @@ -3,3 +3,161 @@ include::{sourcedir}/aviate/includes/aviate-card.adoc[] == Introduction + +The Aviate plugin can be used as a catalog plugin. The Aviate catalog plugin serves as an alternative to the XML catalog managed within Kill Bill core. It provides APIs that operate at the plan level, offering greater flexibility and granularity compared to the catalog version level. These APIs enable users to create individual catalog entries such as plans, products, and pricelists without the need to manage entire catalog versions. The catalog data created through the plugin is stored in tables managed by the Aviate plugin. + +When the aviate catalog plugin is enabled, it takes priority over any _existing catalog entries_ created from regular KB catalog APIs (`/1.0/kb/catalog`) documented https://killbill.github.io/slate/catalog.html#upload-a-catalog-as-xml[here]. + +== Installing the Plugin + +This section lists the steps to be followed for the aviate plugin installation. + +//TODO - Steps to create the DB tables are not mentioned here, I'm assuming that com.killbill.billing.plugin.aviate.enableMigrations=true will automatically create the tables? + +Step 1 - Install Plugin + +The aviate plugin can be installed by running the following curl command: + +``` +curl -v \ + -u admin:password \ + -H "Content-Type: application/json" \ + -H 'X-Killbill-CreatedBy: admin' \ + -X POST \ + --data-binary '{ + "nodeCommandProperties": [ + { + "key": "pluginKey", + "value": "aviate" + }, + { + "key": "pluginVersion", + "value": "" + }, + { + "key": "pluginArtifactId", + "value": "aviate-plugin" + }, + { + "key": "pluginGroupId", + "value": "com.kill-bill.billing.plugin.java" + }, + { + "key": "pluginType", + "value": "java" + }, + { + "key": "pluginUri", + "value": "https://dl.cloudsmith.io//killbill/aviate/maven/com/kill-bill/billing/plugin/java/aviate-plugin//aviate-plugin-.jar" + } + ], + "nodeCommandType": "INSTALL_PLUGIN", + "isSystemCommandType": "true" + }' \ + "http://127.0.0.1:8080/1.0/kb/nodesInfo" +``` + +Replace `` with your cloudsmith token. Replace `` with the plugin version to be installed. This should be something like `1.0.12`. + +Step 2 - Start the Plugin + +In order to start the plugin, run the following `curl` command: + +``` +curl -v \ + -u admin:password \ + -H "Content-Type: application/json" \ + -H 'X-Killbill-CreatedBy: admin' \ + -X POST \ + --data-binary '{ + "nodeCommandProperties": [ + { + "key": "pluginKey", + "value": "aviate" + } + ], + "nodeCommandType": "START_PLUGIN", + "isSystemCommandType": true + }' \ + "http://127.0.0.1:8080/1.0/kb/nodesInfo" + + +``` + +Step 3 - Verify that the plugin is running + +Run the following `curl` command: + +``` +curl -v \ +-u admin:password \ +http://127.0.0.1:8080/1.0/kb/nodesInfo +``` + +The output should contain an entry similar to the following: + +``` + { + "bundleSymbolicName": "com.kill-bill.billing.plugin.java.aviate-plugin", + "pluginKey": "aviate-plugin", + "pluginName": "aviate-plugin", + "version": "1.0.12-SNAPSHOT", + "state": "RUNNING", + "isSelectedForStart": true, + "services": [ + { + "serviceTypeName": "javax.servlet.Servlet", + "registrationName": "aviate-plugin" + }, + { + "serviceTypeName": "org.killbill.billing.catalog.plugin.api.CatalogPluginApi", + "registrationName": "aviate-plugin" + }, + { + "serviceTypeName": "org.killbill.billing.osgi.api.Healthcheck", + "registrationName": "aviate-plugin" + } + ] + } +``` +Alternatively, you can verify this via Kaui. To do this, click on the plug icon and the kpm link. Verify that the Aviate plugin is displayed in green color in RUNNING status. + +== Enabling Catalog APIs + +To use the Catalog API capabilities provided by the Aviate plugin, ensure that KB is started with the following properties: + +``` +com.killbill.billing.plugin.aviate.enableCatalogApis=true +com.killbill.billing.plugin.aviate.enableHealthReporter=false //TODO is this required? +``` + +== Catalog APIs + +As mentioned earlier, the aviate catalog plugin exposes endpoints that operate at a plan/product/pricelist level. These endpoints allow plan/product/pricelist creation/modification and deletion. At the time of writing, only plan-level endpoints are supported. The catalog API endpoints are documented in our Slate docs here. + +Note that at the time of writing, the aviate catalog plugin does not expose any endpoints for catalog retrieval. Instead, the catalog can be retrieved via the https://killbill.github.io/slate/catalog.html#catalog-2[KB Catalog APIs]. + +== KB Catalog APIs + +When the Aviate catalog plugin is enabled, the catalog state is managed by the Aviate plugin. So, while it is possible to use the `GET` https://killbill.github.io/slate/catalog.html#catalog-2[KB Catalog APIs] for catalog retrieval, it is not possible to use the upload/delete https://killbill.github.io/slate/catalog.html#catalog-2[KB Catalog APIs] endpoints. + +== Catalog Versioning + +Since the Kill Bill system internally manages catalog versions, the plugin will construct such multi-version catalog based on the entries that need to be returned. Each plan stored within the Aviate catalog plugn has an associated `effectiveDate`. The catalog versions and what they each include is based on the `plan#effectiveDate`: A new version will be created every time there is a set of changes associated with an existing Plan (e.g. price change). When this happens, a new version is created, which also includes all the previous Plans. + +Assuming we have the following plans, Pa, Pb, Pc, and we create those at different times and modify those to allow for price changes, we get the following: + +``` +* T1: Create Pa -> 1 catalog version v1={Pa} +* T2: Create Pb -> 1 catalog version v1={Pa, Pb} +* T3: Modify Pa -> 2 catalog versions v1={Pa, Pb}, v2={Pa', Pb} // Pa' with the new price +* T4: Create Pc -> 2 catalog versions v1={Pa, Pb}, v2={Pa', Pb, Pc} // Pa' with the new price +* T5: Modify Pb -> 3 catalog versions v1={Pa, Pb}, v2={Pa', Pb, Pc}, v3={Pa', Pb', Pc} // Pa' and Pb' with the new price +... +``` + + +== Further Reading + + + From f2d33a7f0dccbe272b993faebaed1c3d2221387b Mon Sep 17 00:00:00 2001 From: reshmabidikar Date: Tue, 26 Nov 2024 10:28:35 +0530 Subject: [PATCH 2/6] Move plugin installation to separate doc and other minor corrections --- userguide/aviate/aviate-catalog.adoc | 127 ++-------------- .../how-to-install-the-aviate-plugin.adoc | 136 ++++++++++++++++++ 2 files changed, 145 insertions(+), 118 deletions(-) create mode 100644 userguide/aviate/how-to-install-the-aviate-plugin.adoc diff --git a/userguide/aviate/aviate-catalog.adoc b/userguide/aviate/aviate-catalog.adoc index 07097de7f..02ae36470 100644 --- a/userguide/aviate/aviate-catalog.adoc +++ b/userguide/aviate/aviate-catalog.adoc @@ -6,121 +6,11 @@ include::{sourcedir}/aviate/includes/aviate-card.adoc[] The Aviate plugin can be used as a catalog plugin. The Aviate catalog plugin serves as an alternative to the XML catalog managed within Kill Bill core. It provides APIs that operate at the plan level, offering greater flexibility and granularity compared to the catalog version level. These APIs enable users to create individual catalog entries such as plans, products, and pricelists without the need to manage entire catalog versions. The catalog data created through the plugin is stored in tables managed by the Aviate plugin. -When the aviate catalog plugin is enabled, it takes priority over any _existing catalog entries_ created from regular KB catalog APIs (`/1.0/kb/catalog`) documented https://killbill.github.io/slate/catalog.html#upload-a-catalog-as-xml[here]. +When the aviate catalog plugin features are enabled, enabled, the plugin takes priority over any _existing catalog entries_ created from regular KB catalog APIs (`/1.0/kb/catalog`) documented https://killbill.github.io/slate/catalog.html#upload-a-catalog-as-xml[here]. == Installing the Plugin -This section lists the steps to be followed for the aviate plugin installation. - -//TODO - Steps to create the DB tables are not mentioned here, I'm assuming that com.killbill.billing.plugin.aviate.enableMigrations=true will automatically create the tables? - -Step 1 - Install Plugin - -The aviate plugin can be installed by running the following curl command: - -``` -curl -v \ - -u admin:password \ - -H "Content-Type: application/json" \ - -H 'X-Killbill-CreatedBy: admin' \ - -X POST \ - --data-binary '{ - "nodeCommandProperties": [ - { - "key": "pluginKey", - "value": "aviate" - }, - { - "key": "pluginVersion", - "value": "" - }, - { - "key": "pluginArtifactId", - "value": "aviate-plugin" - }, - { - "key": "pluginGroupId", - "value": "com.kill-bill.billing.plugin.java" - }, - { - "key": "pluginType", - "value": "java" - }, - { - "key": "pluginUri", - "value": "https://dl.cloudsmith.io//killbill/aviate/maven/com/kill-bill/billing/plugin/java/aviate-plugin//aviate-plugin-.jar" - } - ], - "nodeCommandType": "INSTALL_PLUGIN", - "isSystemCommandType": "true" - }' \ - "http://127.0.0.1:8080/1.0/kb/nodesInfo" -``` - -Replace `` with your cloudsmith token. Replace `` with the plugin version to be installed. This should be something like `1.0.12`. - -Step 2 - Start the Plugin - -In order to start the plugin, run the following `curl` command: - -``` -curl -v \ - -u admin:password \ - -H "Content-Type: application/json" \ - -H 'X-Killbill-CreatedBy: admin' \ - -X POST \ - --data-binary '{ - "nodeCommandProperties": [ - { - "key": "pluginKey", - "value": "aviate" - } - ], - "nodeCommandType": "START_PLUGIN", - "isSystemCommandType": true - }' \ - "http://127.0.0.1:8080/1.0/kb/nodesInfo" - - -``` - -Step 3 - Verify that the plugin is running - -Run the following `curl` command: - -``` -curl -v \ --u admin:password \ -http://127.0.0.1:8080/1.0/kb/nodesInfo -``` - -The output should contain an entry similar to the following: - -``` - { - "bundleSymbolicName": "com.kill-bill.billing.plugin.java.aviate-plugin", - "pluginKey": "aviate-plugin", - "pluginName": "aviate-plugin", - "version": "1.0.12-SNAPSHOT", - "state": "RUNNING", - "isSelectedForStart": true, - "services": [ - { - "serviceTypeName": "javax.servlet.Servlet", - "registrationName": "aviate-plugin" - }, - { - "serviceTypeName": "org.killbill.billing.catalog.plugin.api.CatalogPluginApi", - "registrationName": "aviate-plugin" - }, - { - "serviceTypeName": "org.killbill.billing.osgi.api.Healthcheck", - "registrationName": "aviate-plugin" - } - ] - } -``` -Alternatively, you can verify this via Kaui. To do this, click on the plug icon and the kpm link. Verify that the Aviate plugin is displayed in green color in RUNNING status. +The Aviate plugin can be installed as documented in the [How to Install the Aviate Plugin] doc. == Enabling Catalog APIs @@ -129,21 +19,24 @@ To use the Catalog API capabilities provided by the Aviate plugin, ensure that K ``` com.killbill.billing.plugin.aviate.enableCatalogApis=true com.killbill.billing.plugin.aviate.enableHealthReporter=false //TODO is this required? +com.killbill.billing.plugin.aviate.enableMigrations=true //TODO - is this required? ``` == Catalog APIs -As mentioned earlier, the aviate catalog plugin exposes endpoints that operate at a plan/product/pricelist level. These endpoints allow plan/product/pricelist creation/modification and deletion. At the time of writing, only plan-level endpoints are supported. The catalog API endpoints are documented in our Slate docs here. +=== Aviate Catalog Plugin APIs -Note that at the time of writing, the aviate catalog plugin does not expose any endpoints for catalog retrieval. Instead, the catalog can be retrieved via the https://killbill.github.io/slate/catalog.html#catalog-2[KB Catalog APIs]. +As mentioned earlier, the Aviate catalog plugin exposes endpoints that operate at a plan/product/pricelist level. These endpoints allow plan/product/pricelist creation/modification and deletion. At the time of writing, only plan-level endpoints are supported. The catalog API endpoints are documented in our Slate docs here. -== KB Catalog APIs +=== KB Catalog APIs When the Aviate catalog plugin is enabled, the catalog state is managed by the Aviate plugin. So, while it is possible to use the `GET` https://killbill.github.io/slate/catalog.html#catalog-2[KB Catalog APIs] for catalog retrieval, it is not possible to use the upload/delete https://killbill.github.io/slate/catalog.html#catalog-2[KB Catalog APIs] endpoints. == Catalog Versioning -Since the Kill Bill system internally manages catalog versions, the plugin will construct such multi-version catalog based on the entries that need to be returned. Each plan stored within the Aviate catalog plugn has an associated `effectiveDate`. The catalog versions and what they each include is based on the `plan#effectiveDate`: A new version will be created every time there is a set of changes associated with an existing Plan (e.g. price change). When this happens, a new version is created, which also includes all the previous Plans. +Since the Kill Bill system internally manages catalog versions, the plugin will construct such multi-version catalog based on the entries that need to be returned. + +Each plan stored within the Aviate catalog plugn has an associated `effectiveDate`. The catalog versions and what they each include is based on the `plan#effectiveDate`: A new version will be created every time there is a set of changes associated with an existing Plan (e.g. price change). When this happens, a new version is created, which also includes all the previous Plans. Assuming we have the following plans, Pa, Pb, Pc, and we create those at different times and modify those to allow for price changes, we get the following: @@ -157,7 +50,5 @@ Assuming we have the following plans, Pa, Pb, Pc, and we create those at differe ``` -== Further Reading - diff --git a/userguide/aviate/how-to-install-the-aviate-plugin.adoc b/userguide/aviate/how-to-install-the-aviate-plugin.adoc new file mode 100644 index 000000000..0a25e54e4 --- /dev/null +++ b/userguide/aviate/how-to-install-the-aviate-plugin.adoc @@ -0,0 +1,136 @@ += How to Install the Aviate Plugin + +include::{sourcedir}/aviate/includes/aviate-card.adoc[] + +//TODO - Add some introduction about Aviate plugin + +== Prerequisites + +* Ensure that you have Kill Bill, Kaui, and the database set up as explained in the https://docs.killbill.io/latest/getting_started.html[__Getting Started Guide__]. + +* Ensure that you have https://curl.haxx.se/[_cURL_] installed. If you are on Windows, we recommend that you use https://git-scm.com/download/win[_Git Bash_] to run the `cURL` commands. + +== Plugin Installation + +The Aviate plugin is not an open-sourced plugin and hence cannot be installed using the standard https://docs.killbill.io/latest/plugin_installation#_plugin_installation[__plugin installation steps__]. + +This section lists the steps to be followed for the Aviate plugin installation. + +//TODO - Steps to create the DB tables are not mentioned here, I'm assuming that com.killbill.billing.plugin.aviate.enableMigrations=true will automatically create the tables? + +*Step 1 - Install Plugin* + +The aviate plugin can be installed by running the following curl command: + +``` +curl -v \ + -u admin:password \ + -H "Content-Type: application/json" \ + -H 'X-Killbill-CreatedBy: admin' \ + -X POST \ + --data-binary '{ + "nodeCommandProperties": [ + { + "key": "pluginKey", + "value": "aviate" + }, + { + "key": "pluginVersion", + "value": "" + }, + { + "key": "pluginArtifactId", + "value": "aviate-plugin" + }, + { + "key": "pluginGroupId", + "value": "com.kill-bill.billing.plugin.java" + }, + { + "key": "pluginType", + "value": "java" + }, + { + "key": "pluginUri", + "value": "https://dl.cloudsmith.io//killbill/aviate/maven/com/kill-bill/billing/plugin/java/aviate-plugin//aviate-plugin-.jar" + } + ], + "nodeCommandType": "INSTALL_PLUGIN", + "isSystemCommandType": "true" + }' \ + "http://127.0.0.1:8080/1.0/kb/nodesInfo" +``` + +Replace `` with your cloudsmith token. Replace `` with the plugin version to be installed. This should be something like `1.0.12`. + +*Step 2 - Start the Plugin* + +In order to start the plugin, run the following `curl` command: + +``` +curl -v \ + -u admin:password \ + -H "Content-Type: application/json" \ + -H 'X-Killbill-CreatedBy: admin' \ + -X POST \ + --data-binary '{ + "nodeCommandProperties": [ + { + "key": "pluginKey", + "value": "aviate" + } + ], + "nodeCommandType": "START_PLUGIN", + "isSystemCommandType": true + }' \ + "http://127.0.0.1:8080/1.0/kb/nodesInfo" + + +``` + +*Step 3 - Verify that the plugin is running* + +Run the following `curl` command: + +``` +curl -v \ +-u admin:password \ +http://127.0.0.1:8080/1.0/kb/nodesInfo +``` + +The output should contain an entry similar to the following: + +``` + { + "bundleSymbolicName": "com.kill-bill.billing.plugin.java.aviate-plugin", + "pluginKey": "aviate-plugin", + "pluginName": "aviate-plugin", + "version": "1.0.12-SNAPSHOT", + "state": "RUNNING", + "isSelectedForStart": true, + "services": [ + { + "serviceTypeName": "javax.servlet.Servlet", + "registrationName": "aviate-plugin" + }, + { + "serviceTypeName": "org.killbill.billing.catalog.plugin.api.CatalogPluginApi", + "registrationName": "aviate-plugin" + }, + { + "serviceTypeName": "org.killbill.billing.osgi.api.Healthcheck", + "registrationName": "aviate-plugin" + } + ] + } +``` +Alternatively, you can verify this via Kaui. To do this, click on the plug icon and the kpm link. Verify that the Aviate plugin is displayed in green color in RUNNING status. + +== Further Reading + +* Aviate Overview +* Aviate Catalog Plugin + + + + From c6400da322fe7e7d6e165828925e6e74d70353b3 Mon Sep 17 00:00:00 2001 From: reshmabidikar Date: Tue, 26 Nov 2024 14:26:17 +0530 Subject: [PATCH 3/6] More corrections --- userguide/aviate/aviate-catalog.adoc | 33 +++++++++++++++++----------- 1 file changed, 20 insertions(+), 13 deletions(-) diff --git a/userguide/aviate/aviate-catalog.adoc b/userguide/aviate/aviate-catalog.adoc index 02ae36470..1d5043791 100644 --- a/userguide/aviate/aviate-catalog.adoc +++ b/userguide/aviate/aviate-catalog.adoc @@ -4,17 +4,21 @@ include::{sourcedir}/aviate/includes/aviate-card.adoc[] == Introduction -The Aviate plugin can be used as a catalog plugin. The Aviate catalog plugin serves as an alternative to the XML catalog managed within Kill Bill core. It provides APIs that operate at the plan level, offering greater flexibility and granularity compared to the catalog version level. These APIs enable users to create individual catalog entries such as plans, products, and pricelists without the need to manage entire catalog versions. The catalog data created through the plugin is stored in tables managed by the Aviate plugin. +The Aviate plugin can be used as a catalog plugin. The Aviate catalog plugin serves as an alternative to the XML catalog managed within Kill Bill core. It provides APIs that operate at the plan/product/pricelist level, offering greater flexibility and granularity compared to the catalog version level. These APIs enable users to create individual catalog entries such as plans, products, and pricelists without the need to manage entire catalog versions. The catalog data created through the plugin is stored in tables managed by the Aviate plugin. -When the aviate catalog plugin features are enabled, enabled, the plugin takes priority over any _existing catalog entries_ created from regular KB catalog APIs (`/1.0/kb/catalog`) documented https://killbill.github.io/slate/catalog.html#upload-a-catalog-as-xml[here]. +When the aviate catalog plugin features are enabled, the catalog served by the plugin takes priority over any _existing catalog entries_ created from regular KB catalog APIs (`/1.0/kb/catalog`) documented https://killbill.github.io/slate/catalog.html#upload-a-catalog-as-xml[here]. -== Installing the Plugin +== Getting Started with the Aviate Catalog Plugin + +This section provides a step-by-step approach to get started with the Aviate Catalog plugin. + +=== Installing the Plugin The Aviate plugin can be installed as documented in the [How to Install the Aviate Plugin] doc. -== Enabling Catalog APIs +=== Enabling Catalog APIs -To use the Catalog API capabilities provided by the Aviate plugin, ensure that KB is started with the following properties: +To use the catalog API capabilities provided by the Aviate plugin, ensure that KB is started with the following properties: ``` com.killbill.billing.plugin.aviate.enableCatalogApis=true @@ -22,15 +26,9 @@ com.killbill.billing.plugin.aviate.enableHealthReporter=false //TODO is this req com.killbill.billing.plugin.aviate.enableMigrations=true //TODO - is this required? ``` -== Catalog APIs - -=== Aviate Catalog Plugin APIs +=== Using Catalog Plugin APIs -As mentioned earlier, the Aviate catalog plugin exposes endpoints that operate at a plan/product/pricelist level. These endpoints allow plan/product/pricelist creation/modification and deletion. At the time of writing, only plan-level endpoints are supported. The catalog API endpoints are documented in our Slate docs here. - -=== KB Catalog APIs - -When the Aviate catalog plugin is enabled, the catalog state is managed by the Aviate plugin. So, while it is possible to use the `GET` https://killbill.github.io/slate/catalog.html#catalog-2[KB Catalog APIs] for catalog retrieval, it is not possible to use the upload/delete https://killbill.github.io/slate/catalog.html#catalog-2[KB Catalog APIs] endpoints. +Once the plugin is installed and enabled, you can start using the Catalog Plugin APIs. As mentioned earlier, the Aviate catalog plugin exposes endpoints that operate at a plan/product/pricelist level. These endpoints allow plan/product/pricelist creation/modification and deletion. At the time of writing, only plan-level endpoints are supported. The catalog API endpoints are documented in our https://killbill.github.io/slate/aviate-catalog-apis.html[slate docs]. == Catalog Versioning @@ -49,6 +47,15 @@ Assuming we have the following plans, Pa, Pb, Pc, and we create those at differe ... ``` +== FAQ + +*Is it possible to use the KB catalog APIs when the Aviate catalog plugin is enabled?* + +When the Aviate catalog plugin is enabled, the catalog state is managed by the Aviate plugin. So, while it is possible to use the `GET` https://killbill.github.io/slate/catalog.html#catalog-2[KB Catalog APIs] for catalog retrieval, it is not possible to use the upload/delete https://killbill.github.io/slate/catalog.html#catalog-2[KB Catalog APIs] endpoints. + +*Is it possible to use the KB price overrides feature when the Aviate catalog plugin is enabled?* + +Yes, it is possible to use the KB price overrides feature. In other words, even if the Aviate catalog plugin is enabled, it is still possible to create a subscription with price overrides. From 57b4e9e9f4173a306d24e464e7a56dd67ae25fa9 Mon Sep 17 00:00:00 2001 From: reshmabidikar Date: Tue, 26 Nov 2024 18:12:30 +0530 Subject: [PATCH 4/6] Fix review comments --- userguide/aviate/aviate-catalog.adoc | 18 ++++++++------ .../how-to-install-the-aviate-plugin.adoc | 24 +++++++++---------- 2 files changed, 23 insertions(+), 19 deletions(-) diff --git a/userguide/aviate/aviate-catalog.adoc b/userguide/aviate/aviate-catalog.adoc index 1d5043791..b505d24b7 100644 --- a/userguide/aviate/aviate-catalog.adoc +++ b/userguide/aviate/aviate-catalog.adoc @@ -20,15 +20,14 @@ The Aviate plugin can be installed as documented in the [How to Install the Avia To use the catalog API capabilities provided by the Aviate plugin, ensure that KB is started with the following properties: -``` +[source,bash] +---- com.killbill.billing.plugin.aviate.enableCatalogApis=true -com.killbill.billing.plugin.aviate.enableHealthReporter=false //TODO is this required? -com.killbill.billing.plugin.aviate.enableMigrations=true //TODO - is this required? -``` +---- === Using Catalog Plugin APIs -Once the plugin is installed and enabled, you can start using the Catalog Plugin APIs. As mentioned earlier, the Aviate catalog plugin exposes endpoints that operate at a plan/product/pricelist level. These endpoints allow plan/product/pricelist creation/modification and deletion. At the time of writing, only plan-level endpoints are supported. The catalog API endpoints are documented in our https://killbill.github.io/slate/aviate-catalog-apis.html[slate docs]. +Once the plugin is installed and enabled, you can start using the Catalog Plugin APIs. As mentioned earlier, the Aviate catalog plugin exposes endpoints that operate at a plan/product/pricelist level. These endpoints allow plan/product/pricelist creation/modification and deletion. At the time of writing, only plan-level endpoints are supported. The catalog API endpoints are documented in our https://apidocs.killbill.io/aviate-catalog-apis[slate docs]. == Catalog Versioning @@ -38,14 +37,15 @@ Each plan stored within the Aviate catalog plugn has an associated `effectiveDat Assuming we have the following plans, Pa, Pb, Pc, and we create those at different times and modify those to allow for price changes, we get the following: -``` +[source,bash] +---- * T1: Create Pa -> 1 catalog version v1={Pa} * T2: Create Pb -> 1 catalog version v1={Pa, Pb} * T3: Modify Pa -> 2 catalog versions v1={Pa, Pb}, v2={Pa', Pb} // Pa' with the new price * T4: Create Pc -> 2 catalog versions v1={Pa, Pb}, v2={Pa', Pb, Pc} // Pa' with the new price * T5: Modify Pb -> 3 catalog versions v1={Pa, Pb}, v2={Pa', Pb, Pc}, v3={Pa', Pb', Pc} // Pa' and Pb' with the new price ... -``` +---- == FAQ @@ -57,5 +57,9 @@ When the Aviate catalog plugin is enabled, the catalog state is managed by the A Yes, it is possible to use the KB price overrides feature. In other words, even if the Aviate catalog plugin is enabled, it is still possible to create a subscription with price overrides. +// TODO - Add Further Reading section once we have more documentation on Aviate plugin + + + diff --git a/userguide/aviate/how-to-install-the-aviate-plugin.adoc b/userguide/aviate/how-to-install-the-aviate-plugin.adoc index 0a25e54e4..88cba6da0 100644 --- a/userguide/aviate/how-to-install-the-aviate-plugin.adoc +++ b/userguide/aviate/how-to-install-the-aviate-plugin.adoc @@ -12,8 +12,6 @@ include::{sourcedir}/aviate/includes/aviate-card.adoc[] == Plugin Installation -The Aviate plugin is not an open-sourced plugin and hence cannot be installed using the standard https://docs.killbill.io/latest/plugin_installation#_plugin_installation[__plugin installation steps__]. - This section lists the steps to be followed for the Aviate plugin installation. //TODO - Steps to create the DB tables are not mentioned here, I'm assuming that com.killbill.billing.plugin.aviate.enableMigrations=true will automatically create the tables? @@ -22,7 +20,8 @@ This section lists the steps to be followed for the Aviate plugin installation. The aviate plugin can be installed by running the following curl command: -``` +[source,bash] +---- curl -v \ -u admin:password \ -H "Content-Type: application/json" \ @@ -59,7 +58,7 @@ curl -v \ "isSystemCommandType": "true" }' \ "http://127.0.0.1:8080/1.0/kb/nodesInfo" -``` +---- Replace `` with your cloudsmith token. Replace `` with the plugin version to be installed. This should be something like `1.0.12`. @@ -67,7 +66,8 @@ Replace `` with your cloudsmith token. Replace `` with the plugi In order to start the plugin, run the following `curl` command: -``` +[source,bash] +---- curl -v \ -u admin:password \ -H "Content-Type: application/json" \ @@ -84,23 +84,23 @@ curl -v \ "isSystemCommandType": true }' \ "http://127.0.0.1:8080/1.0/kb/nodesInfo" - - -``` +---- *Step 3 - Verify that the plugin is running* Run the following `curl` command: -``` +[source,bash] +---- curl -v \ -u admin:password \ http://127.0.0.1:8080/1.0/kb/nodesInfo -``` +---- The output should contain an entry similar to the following: -``` +[source,bash] +---- { "bundleSymbolicName": "com.kill-bill.billing.plugin.java.aviate-plugin", "pluginKey": "aviate-plugin", @@ -123,7 +123,7 @@ The output should contain an entry similar to the following: } ] } -``` +---- Alternatively, you can verify this via Kaui. To do this, click on the plug icon and the kpm link. Verify that the Aviate plugin is displayed in green color in RUNNING status. == Further Reading From 732e9e52cc72ac69c6b9fe2f9b135d0341de4d62 Mon Sep 17 00:00:00 2001 From: reshmabidikar Date: Tue, 26 Nov 2024 18:19:21 +0530 Subject: [PATCH 5/6] Fix URLs --- userguide/aviate/aviate-catalog.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/userguide/aviate/aviate-catalog.adoc b/userguide/aviate/aviate-catalog.adoc index b505d24b7..8f9abab1c 100644 --- a/userguide/aviate/aviate-catalog.adoc +++ b/userguide/aviate/aviate-catalog.adoc @@ -6,7 +6,7 @@ include::{sourcedir}/aviate/includes/aviate-card.adoc[] The Aviate plugin can be used as a catalog plugin. The Aviate catalog plugin serves as an alternative to the XML catalog managed within Kill Bill core. It provides APIs that operate at the plan/product/pricelist level, offering greater flexibility and granularity compared to the catalog version level. These APIs enable users to create individual catalog entries such as plans, products, and pricelists without the need to manage entire catalog versions. The catalog data created through the plugin is stored in tables managed by the Aviate plugin. -When the aviate catalog plugin features are enabled, the catalog served by the plugin takes priority over any _existing catalog entries_ created from regular KB catalog APIs (`/1.0/kb/catalog`) documented https://killbill.github.io/slate/catalog.html#upload-a-catalog-as-xml[here]. +When the Aviate catalog plugin features are enabled, the catalog served by the plugin takes priority over any _existing catalog entries_ created from regular KB catalog APIs (`/1.0/kb/catalog`) documented https://apidocs.killbill.io/catalog#upload-a-catalog-as-xml[here]. == Getting Started with the Aviate Catalog Plugin @@ -14,7 +14,7 @@ This section provides a step-by-step approach to get started with the Aviate Cat === Installing the Plugin -The Aviate plugin can be installed as documented in the [How to Install the Aviate Plugin] doc. +The Aviate plugin can be installed as documented in the https://docs.killbill.io/latest/how-to-install-the-aviate-plugin.html[How to Install the Aviate Plugin] doc. === Enabling Catalog APIs @@ -51,7 +51,7 @@ Assuming we have the following plans, Pa, Pb, Pc, and we create those at differe *Is it possible to use the KB catalog APIs when the Aviate catalog plugin is enabled?* -When the Aviate catalog plugin is enabled, the catalog state is managed by the Aviate plugin. So, while it is possible to use the `GET` https://killbill.github.io/slate/catalog.html#catalog-2[KB Catalog APIs] for catalog retrieval, it is not possible to use the upload/delete https://killbill.github.io/slate/catalog.html#catalog-2[KB Catalog APIs] endpoints. +When the Aviate catalog plugin is enabled, the catalog state is managed by the Aviate plugin. So, while it is possible to use the `GET` https://apidocs.killbill.io/catalog[KB Catalog APIs] for catalog retrieval, it is not possible to use the upload/delete https://apidocs.killbill.io/catalog[KB Catalog APIs] endpoints. *Is it possible to use the KB price overrides feature when the Aviate catalog plugin is enabled?* From 268c1179e680029e1903a490fb91e923cca94306 Mon Sep 17 00:00:00 2001 From: reshmabidikar Date: Wed, 27 Nov 2024 19:19:43 +0530 Subject: [PATCH 6/6] Added link to left nav and renamed aviate-catalog doc --- html5/_main_toc.html.slim | 13 +++++++++++++ ...iate-catalog.adoc => aviate-catalog-plugin.adoc} | 2 +- 2 files changed, 14 insertions(+), 1 deletion(-) rename userguide/aviate/{aviate-catalog.adoc => aviate-catalog-plugin.adoc} (99%) diff --git a/html5/_main_toc.html.slim b/html5/_main_toc.html.slim index b717263ce..dca03ea7a 100644 --- a/html5/_main_toc.html.slim +++ b/html5/_main_toc.html.slim @@ -104,6 +104,19 @@ nav.sidebar-nav li a.nav-link href="/latest/errors-sentry.html" | Error Tracking with Sentry + li + .icon-title + a.bd-toc-link.main-link role="button" Aviate + + + + ul.nav.navbar-nav + li.bd-sidenav-active + a.nav-link href="/latest/aviate-catalog-plugin.html" + | Aviate Catalog Plugin + li.bd-sidenav-active + a.nav-link href="/latest/how-to-install-the-aviate-plugin.html" + | Aviate Plugin Installation li .icon-title a.bd-toc-link.main-link role="button" Manuals diff --git a/userguide/aviate/aviate-catalog.adoc b/userguide/aviate/aviate-catalog-plugin.adoc similarity index 99% rename from userguide/aviate/aviate-catalog.adoc rename to userguide/aviate/aviate-catalog-plugin.adoc index 8f9abab1c..0f7a27f58 100644 --- a/userguide/aviate/aviate-catalog.adoc +++ b/userguide/aviate/aviate-catalog-plugin.adoc @@ -1,4 +1,4 @@ -= Aviate Catalog += Aviate Catalog Plugin include::{sourcedir}/aviate/includes/aviate-card.adoc[]