Skip to content

Commit 1509014

Browse files
pierrepierre
authored
Merge pull request #173 from reshmabidikar/work-for-ts-54-2
Work for TS 54 (Round 4)
2 parents b1b1147 + 553010b commit 1509014

127 files changed

Lines changed: 915 additions & 540 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎reports/README.md‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
# KillBill Analytics Reports Setup Script
2+
3+
This script installs all necessary database DDLs and creates KillBill analytics reports for your KillBill environment.
4+
5+
---
6+
7+
## Table of Contents
8+
9+
- [Overview](#overview)
10+
- [Prerequisites](#prerequisites)
11+
- [Usage](#usage)
12+
- [Environment Variables](#environment-variables)
13+
- [Script Behavior](#script-behavior)
14+
- [Examples](#examples)
15+
- [Reports List](#reports_list)
16+
17+
18+
---
19+
20+
## Overview
21+
22+
This Bash script performs the following tasks:
23+
24+
1. Installs database DDL files (`.sql` or `.ddl`) into the configured MySQL database.
25+
2. Creates KillBill analytics reports via the KillBill Analytics plugin REST API.
26+
3. Supports optional dropping of existing reports before creation.
27+
28+
The script recursively installs DDL files, ensuring `v_report_*.ddl` files are installed before corresponding `report_*.ddl` files. If no `v_report_*.ddl` exists in a folder, all `.ddl` files in that folder are installed.
29+
30+
---
31+
32+
## Prerequisites
33+
34+
- **Bash shell** (Linux, macOS, or Windows Git Bash)
35+
- **MySQL client** installed and accessible in PATH
36+
- KillBill server running with the KillBill Analytics plugin installed
37+
- Appropriate permissions for the MySQL database and KillBill API
38+
39+
---
40+
41+
## Usage
42+
43+
Run the script from the directory containing your DDL files:
44+
45+
```bash
46+
./setup_reports.sh
47+
```
48+
49+
By default, the script installs DDLs and creates all reports.
50+
51+
---
52+
53+
## Environment Variables
54+
55+
The script uses environment variables to configure MySQL and KillBill settings. Defaults are provided if variables are not set:
56+
57+
| Variable | Default | Description |
58+
|--------------------------|--------------------------|---------------------------------------------------------------------------|
59+
| `KILLBILL_HTTP_PROTOCOL` | `http` | KillBill API protocol |
60+
| `KILLBILL_HOST` | `127.0.0.1` | KillBill host |
61+
| `KILLBILL_PORT` | `8080` | KillBill port |
62+
| `KILLBILL_USER` | `admin` | KillBill username |
63+
| `KILLBILL_PASSWORD` | `password` | KillBill password |
64+
| `KILLBILL_API_KEY` | `bob` | KillBill API key |
65+
| `KILLBILL_API_SECRET` | `lazar` | KillBill API secret |
66+
| `MYSQL_HOST` | `127.0.0.1` | MySQL host |
67+
| `MYSQL_USER` | `root` | MySQL user |
68+
| `MYSQL_PASSWORD` | `killbill` | MySQL password |
69+
| `MYSQL_DATABASE` | `killbill` | MySQL database name |
70+
| `INSTALL_DDL` | `true` | Whether to install DDL files (`true` or `false`) |
71+
| `DROP_EXISTING_REPORT` | `true` | Whether to drop existing reports before creating them (`true` or `false`) |
72+
73+
You can export environment variables before running the script to override defaults:
74+
75+
```bash
76+
export KILLBILL_HOST=192.168.1.10
77+
export MYSQL_PASSWORD=mysecret
78+
export INSTALL_DDL=false
79+
80+
./setup_reports.sh
81+
```
82+
83+
---
84+
85+
## Script Behavior
86+
87+
1. **DDL Installation**
88+
- Installs ddl from the `utils` directory first.
89+
- Recursively installs DDLs from the other subdirectories:
90+
- If `v_report_*.ddl` files exist, they are installed first, followed by `report_*.ddl`.
91+
- If no `v_report_*.ddl` exists, all `.ddl` files in the folder are installed.
92+
93+
2. **Report Creation**
94+
- All reports defined in the `create_all_reports` function are created.
95+
- If `DROP_EXISTING_REPORT=true`, existing reports are deleted before creation.
96+
- Reports are created via the KillBill Analytics plugin REST API.
97+
98+
---
99+
100+
## Examples
101+
102+
- **Run with default configuration:**
103+
104+
```bash
105+
./setup_reports.sh
106+
```
107+
108+
- **Skip DDL installation:**
109+
110+
```bash
111+
export INSTALL_DDL=false
112+
./setup_reports.sh
113+
```
114+
115+
- **Disable dropping existing reports:**
116+
117+
```bash
118+
export DROP_EXISTING_REPORT=false
119+
./setup_reports.sh
120+
```
121+
122+
- **Override KillBill host and MySQL password:**
123+
124+
```bash
125+
export KILLBILL_HOST=192.168.1.10
126+
export MYSQL_PASSWORD=mysecret
127+
./setup_reports.sh
128+
```
129+
130+
## Reports List
131+
132+
The script creates the following reports:
133+
134+
|Report Name| Underlying Report Table |Report Description|
135+
|--|---------------------------------------|--|
136+
| [accounts_summary](accounts_summary/README.md) | report_accounts_summary |Provides an account summary. Provides details like account balance, account status, currency, etc.|
137+
| [active_by_product_term_monthly](active_by_product_term_monthly/README.md) | report_active_by_product_term_monthly |Compute (at the end of each month) the total number of active subscriptions per product and billing period.|
138+
| [bundles_summary](bundles_summary/README.md) | report_bundles_summary |Provides a subscription bundle summary. Provides details like CTD, plan name, price, for the base subscription in a bundle.|
139+
| [cancellations_daily](cancellations_daily/README.md) | report_cancellations_daily |Compute the total number of cancellations per day per phase.|
140+
| [chargebacks_daily](chargebacks_daily/README.md) | report_chargebacks_daily |Compute the total value (in the reference currency) of chargebacks per day per currency.|
141+
| [conversion-total-dollar-amount](conversion-total-dollar-amount/README.md) | report_conversion-total-dollar-amount |Compute (monthly) the total revenue from subscriptions converting out of trial, grouped by tenant and billing period.|
142+
| [invoice_aging](invoice_aging/README.md) | report_invoice_aging |This report lists all customer invoice aging with remaining balances, breaking them into standard aging buckets and converting amounts to USD for easy comparison.|
143+
| [invoice_aging_no_payment](invoice_aging_no_payment/README.md) | report_invoice_aging_no_payment |This report lists all customer invoices with no payments recorded, categorizing outstanding amounts into standard aging buckets and converting balances into USD for comparison.
144+
|
145+
| [invoice_credits_daily](invoice_credits_daily/README.md) | report_invoice_credits_daily |Total of invoice credits per tenant, per currency and per day.|
146+
| [invoice_credits_monthly](invoice_credits_monthly/README.md) | report_invoice_credits_monthly |Report of all invoice credits from the previous month, showing amounts in both original currency and USD equivalents.|
147+
| [invoice_item_adjustments_daily](invoice_item_adjustments_daily/README.md) | report_invoice_item_adjustments_daily |Total of invoice item adjustments per tenant, per currency and per day.|
148+
| [invoice_item_adjustments_monthly](invoice_item_adjustments_monthly/README.md) | report_invoice_item_adjustments_monthly |Report of all invoice item adjustments from the previous month, showing amounts in both original currency and USD equivalents.|
149+
| [invoice_items_monthly](invoice_items_monthly/README.md) | report_invoice_items_monthly |Report of all invoice items from the previous month, showing amounts in both original currency and USD equivalents.|
150+
| [invoices_balance_daily](invoices_balance_daily/README.md) | report_invoices_balance_daily |Compute the total sum of invoices balance (in the reference currency) per invoice created day.
151+
|
152+
| [invoices_daily](invoices_daily/README.md) | report_invoices_daily |Compute the total invoice amount charged (in the reference currency) per day per currency.|
153+
| [invoices_monthly](invoices_monthly/README.md) | report_invoices_monthly |Report of all invoices from the previous month, showing amounts in both original currency and USD equivalents.|
154+
| [mrr_daily](mrr_daily/README.md) | report_mrr_daily |Computes the total active MRR (monthly recurring revenue), broken down both by product and as a tenant-wide total (ALL) for each tenant and each day.|
155+
| [new_accounts_daily](new_accounts_daily/README.md) | report_new_accounts_daily |Compute the total amount of new accounts created per day for each tenant.|
156+
| [overdue-states-count-daily](overdue-states-count-daily/README.md) | report_overdue-states-count-daily |Count of overdue states per tenant and per day.|
157+
| [payments_monthly](payments_monthly/README.md) | report_payments_monthly |Report of all payments from the previous month, showing amounts in both original currency and USD equivalents.|
158+
| [payments_summary](payments_summary/README.md) | report_payments_summary |Provides payment summary. Provides details like payment_id, amount, etc.|
159+
| [payments_total_daily](payments_total_daily/README.md) | report_payments_total_daily |Compute the total value (in the reference currency) of payments per day per currency.|
160+
| [refunds-monthly](refunds-monthly/README.md) | report_refunds-monthly |Report of all refunds from the previous month, showing amounts in both original currency and USD equivalents.|
161+
| [refunds_total_daily](refunds_total_daily/README.md) | report_refunds_total_daily |Compute the total value (in the reference currency) of refunds per day per currency for each tenant.|
162+
| [subscribers-vs-non-subscribers](subscribers-vs-non-subscribers/README.md) | report_subscribers-vs-non-subscribers |Compute the total number of active (i.e. with at least one active subscription) and non-active accounts per tenant.|
163+
| [trial-starts-count-daily](trial-starts-count-daily/README.md) | report_trial-starts-count-daily |Count of new trial subscriptions per tenant, per day and per product.|
164+
| [trial-to-no-trial-conversions_daily](trial-to-no-trial-conversions_daily/README.md) | report_trial-to-no-trial-conversions_daily |Count of subscriptions converting from trial to non-trial per tenant per day.|
165+

‎reports/accounts_summary/README.md‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
1-
# Accounts summary report
1+
# Accounts Summary Report
22

33
Provides an account summary. Provides details like account balance, account status, currency, etc.
44

55
The snapshot view is: `v_report_accounts_summary`
66

7-
## Pie chart configuration
7+
## Report Creation
88

99
```
1010
curl -v \
@@ -15,9 +15,15 @@ curl -v \
1515
-H 'Content-Type: application/json' \
1616
-d '{"reportName": "report_accounts_summary",
1717
"reportType": "TABLE",
18-
"reportPrettyName": "Accounts summary",
18+
"reportPrettyName": "Accounts Summary",
1919
"sourceTableName": "report_accounts_summary",
2020
"refreshProcedureName": "refresh_report_accounts_summary",
2121
"refreshFrequency": "HOURLY"}' \
2222
"http://127.0.0.1:8080/plugins/killbill-analytics/reports"
2323
```
24+
25+
## Report UI:
26+
27+
![accounts-summary.png](accounts-summary.png)
28+
29+

‎reports/accounts_summary/accounts-summary.png‎

273 KB
Loading

reports/accounts_summary/v_report_account_summary.ddl renamed to reports/accounts_summary/v_report_accounts_summary.ddl

File renamed without changes.

src/main/resources/reports/active_by_product_term_monthly/README.md renamed to reports/active_by_product_term_monthly/README.md

Lines changed: 17 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
1-
# Monthly active subscriptions report
1+
# Monthly Active Subscriptions Report
22

33
Compute (at the end of each month) the total number of active subscriptions per product and billing period.
44

55
The snapshot view is: `v_report_active_by_product_term_monthly`
66

7-
## Timeline configuration
7+
## Report Creation
88

99
```
1010
curl -v \
@@ -18,9 +18,23 @@ curl -v \
1818
"reportPrettyName": "Monthly Active Subscriptions by Product Term",
1919
"sourceTableName": "report_active_by_product_term_monthly",
2020
"refreshProcedureName": "refresh_active_by_product_term_monthly",
21-
"refreshFrequency": "DAILY"}' \
21+
"refreshFrequency": "HOURLY"}' \
2222
"http://127.0.0.1:8080/plugins/killbill-analytics/reports"
2323
```
24+
## Sample Data
25+
26+
| tenant_record_id | day | product_name | billing_period | count |
27+
|------------------|------------|--------------|----------------|-------|
28+
| 1 | 2025-08-31 | Gold | MONTHLY | 3 |
29+
| 2 | 2025-08-31 | Gold | MONTHLY | 1 |
30+
| 1 | 2025-08-31 | Gold | ANNUAL | 2 |
31+
| 2 | 2025-09-30 | Silver | MONTHLY | 4 |
32+
| 2 | 2025-09-30 | Gold | QUARTERLY | 1 |
33+
34+
The first row in the above table indicates that on `2025-08-31` the `tenant_record_id=1` had 3 Monthly subscriptions for the `Gold` product.
35+
36+
37+
2438
## Report UI:
2539

2640
![monthly-active-subs-by-product-term.png](monthly-active-subs-by-product-term.png)

src/main/resources/reports/active_by_product_term_monthly/monthly-active-subs-by-product-term.png renamed to reports/active_by_product_term_monthly/monthly-active-subs-by-product-term.png

File renamed without changes.

src/main/resources/reports/active_by_product_term_monthly/report_active_by_product_term_monthly.ddl renamed to reports/active_by_product_term_monthly/report_active_by_product_term_monthly.ddl

File renamed without changes.

src/main/resources/reports/active_by_product_term_monthly/v_report_active_by_product_term_monthly.ddl renamed to reports/active_by_product_term_monthly/v_report_active_by_product_term_monthly.ddl

File renamed without changes.

‎reports/bundles_summary/README.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ Provides a subscription bundle summary. Provides details like CTD, plan name, pr
44

55
The snapshot view is: `v_report_bundles_summary`
66

7-
## Pie chart configuration
7+
## Report Creation
88

99
```
1010
curl -v \
@@ -15,9 +15,13 @@ curl -v \
1515
-H 'Content-Type: application/json' \
1616
-d '{"reportName": "report_bundles_summary",
1717
"reportType": "TABLE",
18-
"reportPrettyName": "Bundles summary",
18+
"reportPrettyName": "Bundles Summary",
1919
"sourceTableName": "report_bundles_summary",
2020
"refreshProcedureName": "refresh_report_bundles_summary",
2121
"refreshFrequency": "HOURLY"}' \
2222
"http://127.0.0.1:8080/plugins/killbill-analytics/reports"
2323
```
24+
25+
## Report UI:
26+
27+
![bundles-summary.png](bundles-summary.png)

‎reports/bundles_summary/bundles-summary.png‎

398 KB
Loading

0 commit comments

Comments
 (0)