anchor.diff:  
   As discussed previously, each existing account would be migrated independently from the others providing a small granularity (and avoiding a risky 'success or fail all' type of migration). It is also important to allow for a process that provides clarity on what failed and what succeeded and the ability to restart things from where they failed. In essence, migrating an account should be an idempotent process, so if it fails part way through, things can be resumed. In order to achieve that result, the Migration Framework should own a `migration` table with the following fields (obviously one could add/remove fields as needed):
   
  -* `account_key`: The unique identifier for the account to be migrated. Based on that key account data can be pulled from old billing system.
  +* `account_key`: The unique identifier for the account to be migrated. Based on that key account data can be pulled from the old billing system.
   * `migration_state`: We will see later that migrating an account is not an atomic operation so this will hold where we are in the migration process for that account
  -* `last_error_msg`: Some indication of what fails to ease debugging and and resuming operation
  +* `last_error_msg`: Some indication of what fails to ease debugging and resuming operation
   * `created_date`: Date when we first attempted to start the migration
   * `update_date`: Date when we last attempted to run the migration
   * `cut_over_date`: Date the migration completed (equals to `update_date` when migration has completed). Any subsequent requests after that date would be redirected to Kill Bill.
   
  -
   == Pre-Requisites
   
  -Before we can dig into more details on how the migration works, it is important to be ready to migrate these accounts. The readiness is something to be defined on a case by case, but there are a some things that are pretty much mandatory in all situations:
  +Before we can dig into more details on how the migration works, it is important to be ready to migrate these accounts. The readiness is something to be defined on a case by case basis, but there are a some things that are pretty much mandatory in all situations:
   
   === Setting up Kill Bill
   
  -Migrating accounts to Kill Bill first implies that Kill Bill has been deployed and configured correctly. The point of that doc is not describe those steps (we have other http://docs.killbill.io/[docs] to explain that), but let's go through a few items that require special care:
  -
  -* **Catalog Creation**: The catalog should include all the `Plans` that were configured in the old billing system, so that subscription migration works. Special care should be made for billing alignments to ensure that customer ends up being billed at the same dates as they used to. Most probably the abstractions between the two worlds are slightly different (e.g in Kill Bill world we have the concept of a `PlanPhase` while in the old billing system each `PlanPhase` may correspond to a different `Plan` or event implemented differently).
  +Migrating accounts to Kill Bill first implies that Kill Bill has been deployed and configured correctly. The point of that doc does not describe those steps (we have other http://docs.killbill.io/[docs] to explain that), but let's go through a few items that require special care:
  +
  +* **Catalog Creation**: The catalog should include all the `Plans` that were configured in the old billing system, so that subscription migration works. Special care should be made for billing alignments to ensure that customer ends up being billed at the same dates as they used to. Most probably the abstractions between the two worlds are slightly different (e.g in Kill Bill world we have the concept of a `PlanPhase` while in the old billing system each `PlanPhase` may correspond to a different `Plan` or even implemented differently).
   
   * **Templates and Translations**: Kill Bill allows to configure the system using templates (e.g. invoice html visible to customer) and for http://docs.killbill.io/0.16/internationalization.html[internationalization] (e.g translating plan names in different languages).
   
  -* **Payment plugins**: Kill Bill typically interracts with a payment gateway or processor through a http://docs.killbill.io/0.16/payment_plugin.html[playment plugin]. We already have quite a few tested integrations out there so the work is either to test one of our payment plugin or write a new one to integrate with the desired gateway/processor.
  -
  -* **Overdue Configuration**: Often called dunning in billing system, this http://docs.killbill.io/0.16/overdue.html[feature] lets you control what is happening when customers don't pay. Note that there is no obligation to try reproducing existing logic from old billing system if this one was not satisfactory as this will not directly impact migration. Instead it is advised to configure it to provide the desired results. This step could also be ommitted and postponed until the end of migration.
  -
  -* **Analytics**: This also a good time to think about how financial reports will be computed and what kind of reports will be available for the C-level team. At this stage, one can become familiar with the data model and investigate how existing reports will be generated. Kill Bill also has an https://github.com/killbill/killbill-analytics-plugin[analytics plugin], which provides the following benefits:
  +* **Payment plugins**: Kill Bill typically interacts with a payment gateway or processor through a http://docs.killbill.io/0.16/payment_plugin.html[playment plugin]. We already have quite a few tested integrations out there so the work is either to test one of our payment plugin or to write a new one to integrate with the desired gateway/processor.
  +
  +* **Overdue Configuration**: Often called dunning in billing systems, this http://docs.killbill.io/0.16/overdue.html[feature] lets you control what is happening when customers don't pay. Note that there is no obligation to try reproducing existing logic from the old billing system if this one was not satisfactory as this will not directly impact migration. Instead it is advised to configure it to provide the desired results. This step could also be ommitted and postponed until the end of the migration.
  +
  +* **Analytics**: This is also a good time to think about how financial reports will be computed and what kind of reports will be available for the C-level team. At this stage, one can become familiar with the data model and investigate how existing reports will be generated. Kill Bill also has an https://github.com/killbill/killbill-analytics-plugin[analytics plugin], which provides the following benefits:
   ** Denormalized tables (on which queries become easier to run)
   ** Ability to generate custom reports
   ** UI side for visulatization inside KAUI if needed
   
  -
  -After the system has been configured, it is imperative to try out creating subscriptions with all the plans defined in the catalog, moving through phases by moving the Kill Bill `Clock`, performing upgrade/downgrade and at each step verifying the behavior of the system (invoice generation, ...)
  +After the system has been configured, it is imperative to try out creating subscriptions with all the plans defined in the catalog, moving through phases by moving the Kill Bill `Clock`, performing upgrades/downgradse and at each step verifying the behavior of the system (invoice generation, payments, ...).
   
   === Behavioral Analysis
   
  
positive.code: 
  ==== Catalog Mapping
  
  We discussed in the Pre-Requisites section, the importance to build a Kill Bill catalog that will provide the same kind of products/plans than the one configured in the old billing system. In addition to the Kill Bill catalog we also need a **mapping layer** between the name of the plans defined in the old system and the name of the `Plan` in the Kill Bill catalog. At the time of the migration, the plan associated to the subscription in the old catalog becomes a key in that mapping table to chose the correct Kill Bill `Plan` to use for the creation of the subscription.
  
  
  ==== Billing Dates
  
  Migrating the active subscriptions correctly is definitely one of the challenge of the migration process. Whether the billing happens in arrear or in advance, for each subscription there is a date up to which it was billed for. This date is referred to as the `chargedThroughDate`:
  
  * When billing in advance, the `chargedThroughDate` is the date in the future where the next invoice will occur (charging for the next period). So `nextBillingDate` = `chargedThroughDate`
  * When billing in arrear, the `chargedThroughDate` is the date in the past (or present) when it was last billed. So `nextBillingDate` = `chargedThroughDate` + 1 period (e.g 1 month)
  
  A clean subscription migration implies that we stop the billing in the old system at the `currentBillingDate` (where `currentBillingDate` + 1 Period = `nextBillingDate`) and starts the billing in Kill Bill at the `nextBillingDate`. So how to achieve that result?
  
  The first mandatory piece is to be able to extract those dates from the old billing system for each individual subscription attached to the account. In some billing systems, there is only some support to have a `billCycleDate` (`BCD`) at the account level (day of the month at which account is billed) and so that simplifies the problem. In some other cases different subscriptions can have their own individual schedules. Kill Bill supports all models through the use of billing alignments (and for reference, even a `SUBSCRIPTION_BUNDLE` alignment) defined in the catalog. So, the starting point is to verify those alignments match the old system (this was part of the Pre-Requisites section).
  
  From a billing point of view, we want to cancel the old subscription at `currentBillingDate` and start (the billing of) the subscription at `nextBillingDate`.
  
  
negative.code: Note that subscription apis to create subscription don't allow to specify different dates for billing and entitlement, so additional apis calls to insert the `BlockingState` are required. While less practical, this is not really an issue because at that stage we have set `AUTO_INVOICING_OFF` at the account level so nothing will happen and atomicity is not required.
  
  
  Finally, we should explore a bit more the choice of the per-account `cutOverDate`: is that better to choose that date close to `currentBillingDate` or `nextBillingDate`? A choice of `cutOverDate` close to `currentBillingDate` (right after), means that customer just got invoiced and so the chances for adjustements right after are bigger than if we were to wait. Since we want to minimize actions on the old system after the customer got migrated, it seems a better choice would be to pick `cutOverDate` right before `nextBillingDate`. Of course, in situations where customers have multiple subscriptions on different schedules (`SUBSCRIPTION` billing alignment), there is a choice to be made (probably favor the annual versus monthly and subscriptions on higer `Plans`).
  
  
  
  