0.18.2

@sbrossie sbrossie released this Jan 3, 2017 · 17 commits to master since this release

Installation and Upgrade Notes

What's New

Catalog

Added validation (which may cause existing catalog to fail). The system property org.killbill.xmlloader.disable.validation=true can be used to disable catalog validation (but this should be used as a temporary measure, and catalog should be modified to pass validation). See #610, #678

Invoice

Invoice code generation has been modified to allow for the following (See #664):

  • Add new Preconditions to detect invalid state and automatically park the account (no more invoicing will happen until state has been fixed)
  • Add new apis in AdminResource to display such accounts
  • Trigerring a new invoice on such an account would automatically move it to its normal invoiceable state if such invoice succeeds. There is no API
    to move such account outside of that parked state (the only way is to fix the state, and then re-trigger an invoice)

API changes:

JAXRS (HTTP API):

  • Subscription json body has been enhanced to return the catalog plan name. See #673
  • New apis for retrieving (past or) present bus event/notifications on per account or per tenant level
  • New api to trigger invoice generation for all parked accounts.

Events:

  • Subscription Bus event have a new metadata field to include the bundle externalKey. See #679

DB Changes

N/A

Downloads

0.18.1

@sbrossie sbrossie released this Nov 21, 2016 · 115 commits to master since this release

Installation and Upgrade Notes

Also fixes the missing guava dependency for the catalog loader.

What's New

N/A

DB Changes

N/A

Downloads

0.18.0

@sbrossie sbrossie released this Nov 14, 2016 · 126 commits to master since this release

Overview

Those release notes are provided to help with the transition from the latest 0.16.x release (currently latest at this time of writing is 0.16.12) to the latest 0.18.x release (currently latest at this time of writing is 0.18.0). One should first upgrade any system to latest 0.16.x prior moving to 0.18.x. Also, it is not necessary to use any of the 0.17.x releases, as those were development releases, created for the sake of releasing 0.18.x.

There are quite a few things that have changed from 0.16.x -> 0.18.0 and so please use great caution when making the transition to a live production system (as a matter of fact we recommend to first make the transition to a test system, run some tests, and spend time verifying everything works as expected).

Those release notes are targeted to the Kill Bill core system and do not take into consideration changes made to plugins, KAUI, or any tooling (e.g KPM).

What's New?

Here is a brief summary diff of the things that have changed in the repos:

New Features

Account Notes #72

Ability to set notes on a given Account.

Api changes:

  • HTTP api: Account model : new field notes
  • Java api: MutableAccountData#setNotes

Catalog Apis and Performance

New apis to retrieve catalog as xml or json.

Ability to add new (simple) plan definitions to the current version where the plans have limitations and only support one recurring phase with or without a trial: The ability to upload a full xml catalog version with more complex plans, rules,... is still in use, but this is useful for simpler use cases or when there is a need to add dynamic entries to an existing catalog version.

Ability to create plans using just a planName (instead of triplet {product, billingPeriod, priceList}), removing the limitation where only one plan of a given shape could belong to a given priceList. #303

Ability to specify how instances of a given AO subscriptions can be created for a given BP subscription #609, #545

Catalog performance to support at least 10K plans.

Api changes:

  • HTTP api:
    • Catalog model return full catalog json including usage sections
    • GET /1.0/kb/catalog Accept: application/json, application/xml
    • POST 1.0/kb/catalog/simplePlan to add new SimplePlan
  • Java api:
    • CatalogUserApi#addSimplePlan

Hierarchical Account

This is a new feature which allows to attach children accounts to a parent account, in such a way that subscriptions and matching invoices appear at the child level, but with the ability to delegate the payments to the parent account. A daily summary invoice is created for the parent at the end of the day which contains one invoice item per child invoice.

Api changes:

  • HTTP api:
    • Account model : New atttributes parentAccountId, isPaymentDelegatedToParent
    • Invoice model : New atttributes status, isParentInvoice
    • InvoiceItem model : New atttributes childAccountId, childItems
    • GET /1.0/kb/accounts/account_id/children
  • Java api:
    • AccountData, ImmutableAccountData, MutableAccountData (new fields)
    • Invoice: new fields status, isParentInvoice
    • InvoiceItem: new field childAccountId
    • InvoiceItemType new value PARENT_SUMMARY
    • AccountUserApi#getChildrenAccounts
    • InvoiceUserApi#transferChildCreditToParent, InvoiceUserApi#getInvoiceItemsByParentInvoice

Blocking State Abstraction #259, #493, #431

Ability to modify the stream of events attached to an Account, Bundle or Subscription. See blog post

Api changes:

  • HTTP api:
    • GET /1.0/kb/accounts/account_id/block
    • PUT /1.0/kb/accounts/account_id/block
    • GET /1.0/kb/bundles/bundle_id/block
    • PUT /1.0/kb/bundles/bundle_id/block
    • GET /1.0/kb/subscriptions/subscription_id/block
    • PUT /1.0/kb/subscriptions/subscription_id/block
  • Java api:
    • SubscriptionApi#addBlockingState, SubscriptionApi#getBlockingStates

External refunds #255

Ability to create external refunds when the original credit card has been deleted and the merchant wants to issue a refund by check.
Note that the behavior of the system has changed: We used to allow to do a refund with a payment method that has been deleted and this is not supported anymore.

Api changes:

  • HTTP api:
    • Api GET/1.0/kb/invoicePayments/payment_id/refunds takes a new query param externalPayment(false)

Shopping Card Apis

Add ability to create multiple subscriptions and bundles in one call #219

The feature is in Beta mode and there is already an open task for potential performance improvements #661

BillingPeriod

Added new possible values: DAILY, WEEKLY, BIWEEKLY, THIRTY_DAYS, BIENNIAL

Migration Apis #376, #495, #497

Ability to set a migration flag for resources like Account, Subscription, Invoice. The flag is there for info purpose and ignored by the system except for invoices where the system will ignore such invoices (e.g such invoices are static). See migration guide

Api changes:

  • HTTP api:
    • POST /1.0/kb/subscriptions and POST /1.0/kb/subscriptions/createEntitlementWithAddOns takes a new query param migrated
    • New api POST /1.0/kb/invoices/migration/account_id
  • Java api:
    • EntitlementApi#createBaseEntitlement,createBaseEntitlementWithAddOns,addEntitlement take an additional isMigrated boolean
    • New api InvoiceUserApi#createMigrationInvoice

BCD Change #546

Ability to programmatically change the BCD (date at which a specific subscription gets billed) associated to a given subscription: Prior to this change, a given subscription BCD was static and driven by the catalog's rules (ACCOUNT, BUNDLE, or SUBSCRIPTION level). The new feature allows to modify the BCD with a new value starting at a specific effective date.

Api changes:

  • HTTP api:
    • POST /1.0/kb/subscriptions and POST /1.0/kb/subscriptions/createEntitlementWithAddOns takes a new query param bcd
    • New api PUT /1.0/kb/subscriptions/subscription_id/bcd
  • Java api:
    • New api EntitlementApi#updateBCD

Improvements/Rework/Bug Fixes

Export endpoint/script

  • Add ability to export bus/notification tables and account_history
  • Harden script

Time Management #484, #487, #488

Subscription and Invoice apis will now only accept LocalDate and not fully qualified DateTime:

  • If no date has been specified, this is interpreted as NOW by the system
  • If a date has been specified, it is interpreted as being in the account TZ (any event that requires a fully specified DateTime would be computed by using a reference time proper to the Account)

Account

  • Support for accounts with no PM #163

Catalog

  • Catalog Fix typo: effectiveDateForExistingSubscriptons -> effectiveDateForExistingSubscriptions #481
  • Fix error code when a Plan is not found

Entitlement/Subscription

  • Subscription base cleanup : Removed events (requested_date) #465 and subscription active_version #499
  • Ability to start subscription in the future #492
  • Add new EntitlementState#PENDING for when the entitlement is created in the future #466
  • Ability to update external key (new api SubscriptionApi#updateExternalKey)
  • Entitlement plugin API rework #469

    Requested and effective events map to same external event #557

Invoice

  • WRITTEN_OFF tag semantics change #590
  • New Invoice item description field #86 #114
  • New InvoiceItemType#TAX item
  • New event INVOICE_PAYMENT_INFO #478
  • Removed InvoiceItemType#REFUND_ADJ #30
  • Fix ConcurrentModificationException #641
  • Add safety bounds to disable invoicing a given subscription after N times during the same day
  • Fix invoice infinite loop #640

Junction

  • Fix bad exception handling potentially causing wrong invoicing
  • Improve performance on large number of subscriptions/bundles #659

Overdue

  • Overdue Ability to modify per-tenant overdue config using json descriptor
  • New api OverdueApi#getOverdueStateFor #51
  • Implemented new overdue conditions: OverdueCondition#getInclusionControlTagType, OverdueCondition#getExclusionControlTagType, OverdueCondition#getTimeSinceEarliestUnpaidInvoiceEqualsOrExceeds #256 #611

Payment

  • Payment method deletion
  • Payment attempts
  • Payment retries in timeline #69
  • Cancel scheduled payment retry
  • ChargebackReversal #477
  • Fix duplicated transactions issue when there is a previously unknown #639

Platform

  • Retries on push notifications #285
  • Endpoints to invalidate (per node) caches #304
  • Tenants: update tenant key values, search tenant key values
  • Per tenant Kiill Bill config #505
  • Change package name for osgi-bundles classes from org.killbill.killbill.osgi to org.killbill.billing.osgi #167
  • New events ExtBusEventType#BLOCKING_STATE,SUBSCRIPTION_BCD_CHANGE,ENTITLEMENT_CREATION,ENTITLEMENT_CANCEL,INVOICE_PAYMENT_SUCCESS,INVOICE_PAYMENT_FAILED
  • Improve security of killbill session id's #630
  • storage_engine is deprecated in mysql #652

Usage

  • New trackingId field

HTTP Error Code for Payment Operations

  • 201: Payment transaction created successfully
  • 400: Invalid paymentId supplied
  • 404: Account or payment not found
  • 402: Transaction declined by gateway
  • 422: Payment is aborted by a control plugin
  • 502: Failed to submit payment transaction
  • 503: Payment in unknown status, failed to receive gateway response
  • 504: Payment operation timeout

Other HTTP api changes

  • GET /1.0/kb/accounts/account_id/invoices : New query param withMigrationInvoices(false)
  • GET /1.0/kb/accounts/account_id/invoicePayments : New query param withAttempts(false)
  • GET /1.0/kb/bundles : New query param includedDeleted(false)
  • POST /1.0/kb/credits : New query param autoCommit(false)
  • GET /1.0/kb/invoicePayments/payment_id : New query param withAttempts(false)
  • POST /1.0/kb/invoicePayments/payment_id/refunds : New query param paymentMethodId
  • New api POST /1.0/kb/invoicePayments/payment_id/chargebackReversals
  • GET /1.0/kb/invoices/invoice_id : New query param withChildrenItems(false)
  • GET /1.0/kb/invoices/invoice_number : New query param withChildrenItems(false)
  • POST /1.0/kb/invoices/charges/account_id : New query param autoCommit(false), paymentExternalKey, transactionExternalKey
  • GET /1.0/kb/invoices/invoice_id/payments : New query param withAttempts(false)
  • New api PUT /1.0/kb/invoices/invoice_id/commitInvoice
  • New api GET /1.0/kb/overdue
  • New api POST /1.0/kb/overdue
  • DELETE /1.0/kb/paymentMethods/payment_method_id : New query param forceDefaultPmDeletion(false)
  • GET /1.0/kb/payments : New query param withAttempts(false)
  • New api POST /1.0/kb/payments/payment_id/chargebackReversals
  • New api DELETE /1.0/kb/payments/payment_transaction_id/cancelScheduledPaymentTransaction
  • POST /1.0/kb/subscriptions : New query param entitlementDate, billingDate; Deprecated requestedDate
  • POST /1.0/kb/tenants : New query param useGlobalDefault(true)
  • New apis GET,POST,PUT,DELETE /1.0/kb/tenants/uploadPerTenantConfig
  • New apis DELETE /1.0/kb/admin/cache, /1.0/kb/admin/cache/accounts/account_id, /1.0/kb/admin/cache/tenants
  • New Overdue model
  • Catalog new fields : all usage catalog description
  • Credit model new fields: description, currency #262
  • Invoice model new fields: paymentAttempts
  • InvoicePaymentTransaction model new fields: processedAmount, processedCurrency
  • Payment model new fields: paymentAttempts
  • PaymentTransaction model new fields: processedAmount, processedCurrency
  • Payment transaction tags
  • Subscription model new fields: planName, billCycleDayLocal
  • SubscriptionUsageRecord model new fields: trackingId

Database Changes

Note that this section only deals with killbill tables, and does not include any sql update for existing plugins (if any). One would need to check for each plugin if the schema changed (all our Kill Bill plugins include migration script, so the steps are similar to the one below).

In order to upgrade killbill database tables with latest schema, we created a KPM command that will export the sql that needs to be run. See database migration doc. To summarize, we provide here the command that needs to be run and the output (for those who don't want to run the command):

> kpm migrations killbill killbill-0.16.9 killbill-0.18.0 --token=$GITHUB_API_TOKEN
alter table accounts add column notes varchar(4096) DEFAULT NULL after phone;
alter table account_history add column notes varchar(4096) DEFAULT NULL after phone;drop index idx_invoice_payments on invoice_payments;alter table subscriptions drop column active_version;
alter table subscriptions add column migrated bool NOT NULL default FALSE after charged_through_date;
alter table subscription_events drop column requested_date;
alter table subscription_events drop column current_version;
alter table subscription_events change event_type event_type varchar(15) NOT NULL;
alter table subscription_events add column billing_cycle_day_local int DEFAULT NULL after price_list_name;
alter table rolled_up_usage add column tracking_id varchar(128) NOT NULL after amount;
CREATE INDEX rolled_up_usage_tracking_id_subscription_id_tenant_record_id ON rolled_up_usage(tracking_id, subscription_id, tenant_record_id);
alter table rolled_up_usage change subscription_id subscription_id varchar(36) not null;
alter table rolled_up_usage change unit_type unit_type varchar(255) not null;
alter table accounts modify external_key varchar(255);
alter table account_history modify external_key varchar(255);
alter table tenants modify external_key varchar(255);
alter table bundles modify external_key varchar(255) not null;
alter table payment_attempts modify payment_external_key varchar(255) not null;
alter table payment_attempts modify transaction_external_key varchar(255) not null;
alter table payment_attempt_history modify payment_external_key varchar(255) not null;
alter table payment_attempt_history modify transaction_external_key varchar(255) not null;
alter table invoice_items modify plan_name varchar(255) COLLATE utf8_bin DEFAULT NULL;
alter table invoice_items modify phase_name varchar(255) COLLATE utf8_bin DEFAULT NULL;
alter table invoice_items modify usage_name varchar(255) COLLATE utf8_bin DEFAULT NULL;alter table sessions add column id varchar(36) not null after record_id;
update sessions set id = record_id;
create unique index sessions_id on sessions(id);alter table subscription_events modify plan_name varchar(255) COLLATE utf8_bin DEFAULT NULL;
alter table subscription_events modify phase_name varchar(255) COLLATE utf8_bin DEFAULT NULL;
update invoice_items set type = 'CREDIT_ADJ' where type = 'REFUND_ADJ';
CREATE TABLE invoice_parent_children (
    record_id serial unique,
    id varchar(36) NOT NULL,
    parent_invoice_id varchar(36) NOT NULL,
    child_invoice_id varchar(36) NOT NULL,
    child_account_id varchar(36) NOT NULL,
    created_by varchar(50) NOT NULL,
    created_date datetime NOT NULL,
    account_record_id bigint /*! unsigned */ not null,
    tenant_record_id bigint /*! unsigned */ not null default 0,
    PRIMARY KEY(record_id)
) /*! CHARACTER SET utf8 COLLATE utf8_bin */;
CREATE UNIQUE INDEX invoice_parent_children_id ON invoice_parent_children(id);
CREATE INDEX invoice_parent_children_invoice_id ON invoice_parent_children(parent_invoice_id);
CREATE INDEX invoice_parent_children_tenant_account_record_id ON invoice_parent_children(tenant_record_id, account_record_id);


alter table invoice_items add column child_account_id varchar(36) after account_id;
alter table invoice_items modify start_date date;

alter table invoices add column  parent_invoice bool NOT NULL DEFAULT FALSE after migrated;
alter table invoices modify target_date date;

drop index invoices_account_target on invoices;
create index invoices_account on invoices(account_id asc);
alter table accounts add column parent_account_id varchar(36) DEFAULT NULL after billing_cycle_day_local;
alter table accounts add column is_payment_delegated_to_parent boolean DEFAULT FALSE after parent_account_id;

alter table account_history add column parent_account_id varchar(36) DEFAULT NULL after billing_cycle_day_local;
alter table account_history add column is_payment_delegated_to_parent boolean DEFAULT FALSE after parent_account_id;
alter table invoices add column status varchar(15) NOT NULL DEFAULT 'COMMITTED' after currency;
update invoices set status = 'COMMITTED';

Configuration Changes

EhCache

This section is provided for information for those who do not want to rely on the standard killbill war for installation. Such war should already contain the correct ehcache configuration and so nothing needs to be done. That being said, two new ehcache have been added and the file ehcache.xml should either contain the entries below or those should be added:


<cache name="tenant-config"
       maxElementsInMemory="1000"
       maxElementsOnDisk="0"
       overflowToDisk="false"
       diskPersistent="false"
       memoryStoreEvictionPolicy="LFU"
       statistics="true">
    <cacheEventListenerFactory
            class="org.killbill.billing.util.cache.ExpirationListenerFactory"
            properties=""/>
</cache>

<cache name="tenant-payment-state-machine-config"
       maxElementsInMemory="100"
       maxElementsOnDisk="0"
       overflowToDisk="false"
       diskPersistent="false"
       memoryStoreEvictionPolicy="LFU"
       statistics="true"
        >
    <cacheEventListenerFactory
            class="org.killbill.billing.util.cache.ExpirationListenerFactory"
            properties=""/>
</cache>

System Properties

  • New property org.killbill.invoice.maxDailyNumberOfItemsSafetyBound to disable invoicing after detecting too many items for a given subscription on a given day

Downloads

0.16.12

@sbrossie sbrossie released this Nov 11, 2016 · 747 commits to master since this release

Installation and Upgrade Notes

What's New

We have reverted the change we made in 0.16.11 with regard to how full item adjustments were handled. The comment in the issue #654 summarizes different cancellation use cases and in particular the case where we do full item adjustments.

DB Changes

N/A

Downloads

0.16.11

@sbrossie sbrossie released this Nov 7, 2016 · 755 commits to master since this release

Installation and Upgrade Notes

What's New

There is a change in behavior when doing invoice item adjustment as explained in issue #654

DB Changes

N/A

Downloads

0.16.10

@sbrossie sbrossie released this Nov 3, 2016 · 765 commits to master since this release

Installation and Upgrade Notes

Addresses some critical bugs. Users on 0.16.x should upgrade to 0.16.10.

What's New

N/A

DB Changes

N/A

Downloads

0.17.8

@sbrossie sbrossie released this Nov 2, 2016

Installation and Upgrade Notes

What's New

N/A

DB Changes

See migration files for Flyway.

Downloads