-
-
Notifications
You must be signed in to change notification settings - Fork 82
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Work for aviate catalog plugin #575
Merged
reshmabidikar
merged 6 commits into
killbill:v3
from
reshmabidikar:work-for-aviate-catalog-plugin
Nov 27, 2024
Merged
Changes from all commits
Commits
Show all changes
6 commits
Select commit
Hold shift + click to select a range
7775436
Initial commit
reshmabidikar f2d33a7
Move plugin installation to separate doc and other minor corrections
reshmabidikar c6400da
More corrections
reshmabidikar 57b4e9e
Fix review comments
reshmabidikar 732e9e5
Fix URLs
reshmabidikar 268c117
Added link to left nav and renamed aviate-catalog doc
reshmabidikar File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,65 @@ | ||
= Aviate Catalog Plugin | ||
|
||
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/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://apidocs.killbill.io/catalog#upload-a-catalog-as-xml[here]. | ||
|
||
== 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 https://docs.killbill.io/latest/how-to-install-the-aviate-plugin.html[How to Install the Aviate Plugin] doc. | ||
|
||
=== Enabling Catalog APIs | ||
|
||
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 | ||
---- | ||
|
||
=== 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://apidocs.killbill.io/aviate-catalog-apis[slate docs]. | ||
|
||
== 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: | ||
|
||
[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 | ||
|
||
*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://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?* | ||
|
||
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 | ||
|
||
|
||
|
||
|
||
|
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 | ||
|
||
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: | ||
|
||
[source,bash] | ||
---- | ||
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": "<version>" | ||
}, | ||
{ | ||
"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/<token>/killbill/aviate/maven/com/kill-bill/billing/plugin/java/aviate-plugin/<version>/aviate-plugin-<version>.jar" | ||
} | ||
], | ||
"nodeCommandType": "INSTALL_PLUGIN", | ||
"isSystemCommandType": "true" | ||
}' \ | ||
"http://127.0.0.1:8080/1.0/kb/nodesInfo" | ||
---- | ||
|
||
Replace `<token>` with your cloudsmith token. Replace `<version>` 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: | ||
|
||
[source,bash] | ||
---- | ||
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: | ||
|
||
[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", | ||
"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 | ||
|
||
|
||
|
||
|
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes, they should. We should explain how the flyway migration process works and also share the DDL somewhere (https://docs.killbill.io/latest/aviate-mysql.ddl ?)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'll gather more information about this and address this in a subsequent PR.