anchor.diff:  == Overview
   
   This guide is intended to provide some guidelines for running migrations from an **existing billing system** to **Kill Bill**.
  -It is by no mean an exact recipe book to follow, but it provides some recommendations on how to do things (based on previous experiences) and highlights some specific areas of concern. The assumption is that there is already an internal or third party billing system in place, and so the goal of the migration is to preserve the current state of the system and yet reach a point where this old system can be fully unplugged. The old billing system currently:
  +It is by no means an exact recipe book to follow, but it provides some recommendations on how to do things (based on previous experiences) and highlights some specific areas of concern. The assumption is that there is already an internal or third party billing system in place, and so the goal of the migration is to preserve the current state of the system and yet reach a point where this old system can be fully unplugged. The old billing system currently:
   
   * receives some live traffic, and migration should not cause any downtime
   * contains existing state (subscriptions, invoices, ...) that needs to be migrated without impacting customers
  
positive.code: * Treat each phase as an upgrade/downgrade scenario (i.e move it to a different kind of plan)
  * ...
  
  There is obviously some amount of work to understand the old system's model, and how those will translate into the Kill Bill catalog (again part of the Pre-Requisites stage). So, assuming we are migrating a subscription into Kill Bill using a multi-phase `Plan`, we have to be cautious with the entitlement alignments and make sure we end up on the right phase.
  
  One strategy is to define more `Plans` in the Kill Bill catalog to include mono-phase versions of the multi-phase `Plans`. For example, assuming a subscription with a 2 phases `Plan` (`TRIAL`=15 days, followed by `EVERGREEN`), we could also create another `Plan` with only the last phase so as to migrate subscriptions that are already on the `EVERGREEN` phase.
  
  Alternatively, we could decide to only use the original `Plan`, and play with subscription alignments in the following way:
  
  
  1. At t=`cutOverDate`, the subscription is already in the `EVERGREEN` phase; in this case we need to make sure we start directly into that phase. Fortunately, this is possible because the Kill Bill api to create subscription allows to specify on which phase to start (skipping previous phases).
  2. At t=`cutOverDate`, the subscription is still in TRIAL, but by chosing the `originalSubscriptionStartDate` as the start date of that subscription in Kill Bill we should end up exactly with the correct state. Let's take an example to illustrate that point:
  * The subscription started on february 14th 2016 in the old system
  * We decide on a `cutOverDate` of february 24th 2016, which means we are 10 days into the trial, so there should still be 5 days of trial  when migrating to Kill Bill
  * The `nextBillingDate` is february 28th 2016 (date at which the trial ends, and billing would have started in old system)
  * We create the subscription in Kill Bill on `originalSubscriptionStartDate` (february 14th 2016), and because this is a 2 phases `Plan`, the system will generate a `PHASE` event on `nextBillingDate` (february 28th 2016), which is exactly what we need.
  
  
  ==== Pending Subscription Changes
  
  Some billing systems will also allow to schedule future changes associated to a subscription (such as upgrading a subscription in the future or cancelling a subscription in the future, ...). During the migration, it is important to keep track of those future changes. Fortunately this is fairly straight-forward using the Kill Bill apis to change Plan or cancel in the future.
  
  
  == Conclusion
  
  Migrations are always a difficult, lengthy process and risky endeavor. We have highlighed some of issues that need to be thought of and suggested a possible design (based on a set of simplification and work-arounds). Obviously each use case is different (migration happens from different systems with different characteristics, data set may be very different, and business requirements may also be different, ...).
  
  However, migrating to Kill Bill simplifies greatly the process for the following reasons:
  
  * **Testing**:
  ** One can run the migration many times on a test system (except for the cancellation of the active subscriptions on the old system, which can only happen once for obvious reasons)
  ** One can look closely at the data that was migrated and even run some tests by moving clock forward to ensure things will happen as expected in the future
  * **Altering System Behavior**:
  ** One can extend functionality through plugins (could intercept subscription calls, replace entirely catalog using catalog plugin api, modify invoice generation, ...)
  ** One can maintain a fork of Kill Bill (just during the time of the migration) where migration logic could be inserted as needed
  * **Owning The Data**:
  ** Migrated data is easily available to run reports that will highlight potential issues
  
negative.code: 
  The main idea it to provide a migration endpoint, implemented in the migration logic proxy, that knows how to migrate each account individually. Each account migration is composed of several steps:
  
  1. **`migration_state` = `INIT`**: Create an entry in the migration table.
  2. **`migration_state` = `ACCOUNT_MIGRATED`**: Migrate account data. This is relatively easy and low risk. The work consists of pulling account data from the old billing system and mapping that to the Kill Bill data model. As mentioned before, additional info could be added as custom fields on the Kill Bill created `Account` (e.g ID of the account in the old system).
  3. **`migration_state` = `AUTO_INVOICING_OFF`**: Setup `AUTO_INVOICING_OFF` for the `Account` to prevent the system to trigger invoices when we start migrating the subscriptions.
  4. **`migration_state` = `SUBSCRIPTIONS_MIGRATED`**: Migrate active subscriptions. We will provide more detail in the next section on how that works, but the overall idea is to fetch all active subscriptions from the old billing system and to recreate them in Kill Bill using the right date and using the right `Plan`. The goal is to get a clean cutover and avoid any misbilling (double billing, loss of revenue) or service disruption. Also note that in a system where there are dependencies among subscriptions (e.g. ADD_ON subscriptions), special care should be made to migrate them in the right order.
  5. **`migration_state` = `OLD_SUBSCRIPTIONS_CANCELLED`**: Cancel all subscriptions in the old billing system at the right time (more detail in the next section). This is a fairly risky step because this changes the state in the old billing system. This is *not* a point of 'no-return' but a point when rollback becomes difficult. Needless to say that cancellation code for the old billing system should have been tested carefully.
  6. **`migration_state` = `MIGRATED`**: Remove `AUTO_INVOICING_OFF` for the `Account`.
  
  