Work for TS 54 (Round 4)

reports/README.md

@@ -0,0 +1,165 @@
+# KillBill Analytics Reports Setup Script
+
+This script installs all necessary database DDLs and creates KillBill analytics reports for your KillBill environment.
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Prerequisites](#prerequisites)
+- [Usage](#usage)
+- [Environment Variables](#environment-variables)
+- [Script Behavior](#script-behavior)
+- [Examples](#examples)
+- [Reports List](#reports_list)
+
+
+---
+
+## Overview
+
+This Bash script performs the following tasks:
+
+1. Installs database DDL files (`.sql` or `.ddl`) into the configured MySQL database.
+2. Creates KillBill analytics reports via the KillBill Analytics plugin REST API.
+3. Supports optional dropping of existing reports before creation.
+
+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.
+
+---
+
+## Prerequisites
+
+- **Bash shell** (Linux, macOS, or Windows Git Bash)
+- **MySQL client** installed and accessible in PATH
+- KillBill server running with the KillBill Analytics plugin installed
+- Appropriate permissions for the MySQL database and KillBill API
+
+---
+
+## Usage
+
+Run the script from the directory containing your DDL files:
+
+```bash
+./setup_reports.sh
+```
+
+By default, the script installs DDLs and creates all reports.
+
+---
+
+## Environment Variables
+
+The script uses environment variables to configure MySQL and KillBill settings. Defaults are provided if variables are not set:
+
+| Variable                 | Default                  | Description                                                               |
+|--------------------------|--------------------------|---------------------------------------------------------------------------|
+| `KILLBILL_HTTP_PROTOCOL` | `http`                   | KillBill API protocol                                                     |
+| `KILLBILL_HOST`          | `127.0.0.1`              | KillBill host                                                             |
+| `KILLBILL_PORT`          | `8080`                   | KillBill port                                                             |
+| `KILLBILL_USER`          | `admin`                  | KillBill username                                                         |
+| `KILLBILL_PASSWORD`      | `password`               | KillBill password                                                         |
+| `KILLBILL_API_KEY`       | `bob`                    | KillBill API key                                                          |
+| `KILLBILL_API_SECRET`    | `lazar`                  | KillBill API secret                                                       |
+| `MYSQL_HOST`             | `127.0.0.1`              | MySQL host                                                                |
+| `MYSQL_USER`             | `root`                   | MySQL user                                                                |
+| `MYSQL_PASSWORD`         | `killbill`               | MySQL password                                                            |
+| `MYSQL_DATABASE`         | `killbill`               | MySQL database name                                                       |
+| `INSTALL_DDL`            | `true`                   | Whether to install DDL files (`true` or `false`)                          |
+| `DROP_EXISTING_REPORT`   | `true`                   | Whether to drop existing reports before creating them (`true` or `false`) |
+
+You can export environment variables before running the script to override defaults:
+
+```bash
+export KILLBILL_HOST=192.168.1.10
+export MYSQL_PASSWORD=mysecret
+export INSTALL_DDL=false
+
+./setup_reports.sh
+```
+
+---
+
+## Script Behavior
+
+1. **DDL Installation**
+    - Installs ddl from the `utils` directory first.
+    - Recursively installs DDLs from the other subdirectories:
+        - If `v_report_*.ddl` files exist, they are installed first, followed by `report_*.ddl`.
+        - If no `v_report_*.ddl` exists, all `.ddl` files in the folder are installed.
+
+2. **Report Creation**
+    - All reports defined in the `create_all_reports` function are created.
+    - If `DROP_EXISTING_REPORT=true`, existing reports are deleted before creation.
+    - Reports are created via the KillBill Analytics plugin REST API.
+
+---
+
+## Examples
+
+- **Run with default configuration:**
+
+```bash
+./setup_reports.sh
+```
+
+- **Skip DDL installation:**
+
+```bash
+export INSTALL_DDL=false
+./setup_reports.sh
+```
+
+- **Disable dropping existing reports:**
+
+```bash
+export DROP_EXISTING_REPORT=false
+./setup_reports.sh
+```
+
+- **Override KillBill host and MySQL password:**
+
+```bash
+export KILLBILL_HOST=192.168.1.10
+export MYSQL_PASSWORD=mysecret
+./setup_reports.sh
+```
+
+## Reports List
+
+The script creates the following reports:
+
+|Report Name| Underlying Report Table               |Report Description|
+|--|---------------------------------------|--|
+| [accounts_summary](accounts_summary/README.md) | report_accounts_summary               |Provides an account summary. Provides details like account balance, account status, currency, etc.|
+| [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.|
+| [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.|
+| [cancellations_daily](cancellations_daily/README.md) | report_cancellations_daily            |Compute the total number of cancellations per day per phase.|
+| [chargebacks_daily](chargebacks_daily/README.md) | report_chargebacks_daily              |Compute the total value (in the reference currency) of chargebacks per day per currency.|
+| [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.|
+| [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.|
+| [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.
+|
+| [invoice_credits_daily](invoice_credits_daily/README.md) | report_invoice_credits_daily          |Total of invoice credits per tenant, per currency and per day.|
+| [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.|
+| [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.|
+| [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.|
+| [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.|
+| [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.
+|
+| [invoices_daily](invoices_daily/README.md) | report_invoices_daily                |Compute the total invoice amount charged (in the reference currency) per day per currency.|
+| [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.|
+| [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.|
+| [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.|
+| [overdue-states-count-daily](overdue-states-count-daily/README.md) | report_overdue-states-count-daily                |Count of overdue states per tenant and per day.|
+| [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.|
+| [payments_summary](payments_summary/README.md) | report_payments_summary                |Provides payment summary. Provides details like payment_id, amount, etc.|
+| [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.|
+| [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.|
+| [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.|
+| [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.|
+| [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.|
+| [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.|
+

reports/accounts_summary/README.md

@@ -1,10 +1,10 @@
-# Accounts summary report
+# Accounts Summary Report
 
 Provides an account summary. Provides details like account balance, account status, currency, etc.
 
 The snapshot view is: `v_report_accounts_summary`
 
-## Pie chart configuration
+## Report Creation
 
 ```
 curl -v \
@@ -15,9 +15,15 @@ curl -v \
      -H 'Content-Type: application/json' \
      -d '{"reportName": "report_accounts_summary",
           "reportType": "TABLE",
-          "reportPrettyName": "Accounts summary",
+          "reportPrettyName": "Accounts Summary",
           "sourceTableName": "report_accounts_summary",
           "refreshProcedureName": "refresh_report_accounts_summary",
           "refreshFrequency": "HOURLY"}' \
      "http://127.0.0.1:8080/plugins/killbill-analytics/reports"
 ```
+
+## Report UI:
+
+![accounts-summary.png](accounts-summary.png)
+
+

src/main/resources/reports/active_by_product_term_monthly/README.md → reports/active_by_product_term_monthly/README.md

@@ -1,10 +1,10 @@
-# Monthly active subscriptions report
+# Monthly Active Subscriptions Report
 
 Compute (at the end of each month) the total number of active subscriptions per product and billing period.
 
 The snapshot view is: `v_report_active_by_product_term_monthly`
 
-## Timeline configuration
+## Report Creation
 
 ```
 curl -v \
@@ -18,9 +18,23 @@ curl -v \
           "reportPrettyName": "Monthly Active Subscriptions by Product Term",
           "sourceTableName": "report_active_by_product_term_monthly",
           "refreshProcedureName": "refresh_active_by_product_term_monthly",
-          "refreshFrequency": "DAILY"}' \
+          "refreshFrequency": "HOURLY"}' \
      "http://127.0.0.1:8080/plugins/killbill-analytics/reports"
 ```
+## Sample Data
+
+| tenant_record_id | day        | product_name | billing_period | count |
+|------------------|------------|--------------|----------------|-------|
+| 1                | 2025-08-31 | Gold         | MONTHLY        | 3     |
+| 2                | 2025-08-31 | Gold         | MONTHLY        | 1     |
+| 1                | 2025-08-31 | Gold         | ANNUAL         | 2     |
+| 2                | 2025-09-30 | Silver       | MONTHLY        | 4     |
+| 2                | 2025-09-30 | Gold         | QUARTERLY      | 1     |
+
+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.
+
+
+
 ## Report UI:
 
 ![monthly-active-subs-by-product-term.png](monthly-active-subs-by-product-term.png)

reports/bundles_summary/README.md

@@ -4,7 +4,7 @@ Provides a subscription bundle summary. Provides details like CTD, plan name, pr
 
 The snapshot view is: `v_report_bundles_summary`
 
-## Pie chart configuration
+## Report Creation
 
 ```
 curl -v \
@@ -15,9 +15,13 @@ curl -v \
      -H 'Content-Type: application/json' \
      -d '{"reportName": "report_bundles_summary",
           "reportType": "TABLE",
-          "reportPrettyName": "Bundles summary",
+          "reportPrettyName": "Bundles Summary",
           "sourceTableName": "report_bundles_summary",
           "refreshProcedureName": "refresh_report_bundles_summary",
           "refreshFrequency": "HOURLY"}' \
      "http://127.0.0.1:8080/plugins/killbill-analytics/reports"
 ```
+
+## Report UI:
+
+![bundles-summary.png](bundles-summary.png)

src/main/resources/reports/cancellations_daily/README.md → reports/cancellations_daily/README.md

@@ -1,10 +1,10 @@
-# Daily cancellations report
+# Daily Cancellations Report
 
 Compute the total number of cancellations per day per phase.
 
 The snapshot view is: `v_report_cancellations_daily`
 
-## Timeline configuration
+## Report Creation
 
 ```
 curl -v \
@@ -18,9 +18,22 @@ curl -v \
           "reportPrettyName": "Daily Cancellations",
           "sourceTableName": "report_cancellations_daily",
           "refreshProcedureName": "refresh_report_cancellations_daily",
-          "refreshFrequency": "DAILY"}' \
+          "refreshFrequency": "HOURLY"}' \
      "http://127.0.0.1:8080/plugins/killbill-analytics/reports"
 ```
+## Sample Data
+
+| tenant_record_id | phase     | day        | count |
+|------------------|-----------|------------|-------|
+| 1                | EVERGREEN | 2025-09-10 | 9     |
+| 1                | EVERGREEN | 2025-09-03 | 2     |
+| 1                | EVERGREEN | 2025-09-22 | 5     |
+| 2                | EVERGREEN | 2025-09-23 | 6     |
+| 2                | EVERGREEN | 2025-09-24 | 6     |
+| 1                | EVERGREEN | 2025-09-25 | 1     |
+
+The first row in the above table indicates that on `2025-09-10`, the `tenant_record_id=1` had 9 cancellations in `EVERGREEN` phase.
+
 ## Report UI:
 
 ![daily-cancellations.png](daily-cancellations.png)

reports/chargebacks_daily/README.md

@@ -0,0 +1,40 @@
+# Daily Chargebacks Report
+
+Compute the total value (in the reference currency) of chargebacks per day per currency.
+
+The snapshot view is: `v_report_chargebacks_daily`
+
+## Report Creation
+
+```
+curl -v \
+     -X POST \
+     -u admin:password \
+     -H "X-Killbill-ApiKey:bob" \
+     -H "X-Killbill-ApiSecret:lazar" \
+     -H 'Content-Type: application/json' \
+     -d '{"reportName": "report_chargebacks_daily",
+          "reportType": "TIMELINE",
+          "reportPrettyName": "Daily Chargebacks Value",
+          "sourceTableName": "report_chargebacks_daily",
+          "refreshProcedureName": "refresh_report_chargebacks_daily",
+          "refreshFrequency": "HOURLY"}' \
+     "http://127.0.0.1:8080/plugins/killbill-analytics/reports"
+```
+
+## Sample Data
+
+| tenant_record_id | day        | currency | count    |
+|------------------|------------|----------|----------|
+| 1                | 2025-09-18 | USD      | 100.0000 |
+| 1                | 2025-09-26 | USD      | 50.0000  |
+| 2                | 2025-09-11 | USD      | 100.0000 |
+
+The first row in the above table indicates that on `2025-09-18`, the `tenant_record_id=1` had a total chargeback value of `$100`
+
+
+## Report UI:
+
+![chargebacks-daily.png](chargebacks-daily.png)
+
+

src/main/resources/reports/chargebacks_daily/v_report_chargebacks_daily.ddl → reports/chargebacks_daily/v_report_chargebacks_daily.ddl

@@ -3,7 +3,7 @@ select
   ac.tenant_record_id
 , date_format(ac.created_date,'%Y-%m-%d') as day
 , ac.currency
-, sum(ac.converted_amount) as count
+, sum(ac.amount) as count
 from
   analytics_payment_chargebacks ac
 where 1=1

src/main/resources/reports/conversion-total-dollar-amount/README.md → reports/conversion-total-dollar-amount/README.md

@@ -4,7 +4,7 @@ Compute (monthly) the total revenue from subscriptions converting out of trial,
 
 The snapshot view is: `v_report_conversions_total_dollar_monthly`
 
-## Timeline configuration
+## Report Creation
 
 ```
 curl -v \
@@ -18,7 +18,7 @@ curl -v \
           "reportPrettyName": "Conversions Total Dollar Amount",
           "sourceTableName": "report_conversions_total_dollar_monthly",
           "refreshProcedureName": "refresh_report_conversions_total_dollar_monthly",
-          "refreshFrequency": "DAILY"}' \
+          "refreshFrequency": "HOURLY"}' \
      "http://127.0.0.1:8080/plugins/killbill-analytics/reports"
 ```
 
@@ -32,7 +32,7 @@ curl -v \
 |6| 2025-01-01 |ANNUAL|200|
 |1| 2025-04-01 |MONTHLY|30|
 
-Here day represents the first day of the month representing that subscription's conversion month. So if the subscription converts from TRIAL to EVERGREEN phase on `2025-04-15`, the day will be `2025-04-01`.
+Here `day` represents the first day of the month representing that subscription's conversion month. So if the subscription converts from TRIAL to EVERGREEN phase on `2025-04-15`, the `day` value will be `2025-04-01`. The first row in the above table indicates that in the month of June, a revenue of `$30` was generated when `WEEKLY` subscriptions moved out of `TRIAL` phase.
 
 ## Report UI:
 

src/main/resources/reports/invoice_aging/README.md → reports/invoice_aging/README.md

@@ -22,7 +22,7 @@ curl -v \
           "reportPrettyName": "Invoice Aging Report",
           "sourceTableName": "report_invoice_aging",
           "refreshProcedureName": "refresh_report_invoice_aging",
-          "refreshFrequency": "DAILY"}' \
+          "refreshFrequency": "HOURLY"}' \
      "http://127.0.0.1:8080/plugins/killbill-analytics/reports"
 ```
 

src/main/resources/reports/invoice_aging_no_payment/README.md → reports/invoice_aging_no_payment/README.md

@@ -22,7 +22,7 @@ curl -v \
           "reportPrettyName": "Invoice Aging No Payments Report",
           "sourceTableName": "report_invoice_aging_no_payment",
           "refreshProcedureName": "refresh_report_invoice_aging_no_payment",
-          "refreshFrequency": "DAILY"}' \
+          "refreshFrequency": "HOURLY"}' \
      "http://127.0.0.1:8080/plugins/killbill-analytics/reports"
 ```