Case study
**********
In order to display the functionality of bframe, we've created a case study that blends real and fictional elements.

This demonstration will be used through out the documentation and the underlying configuration is available within the bframe code repository.

.. TODO2(link the bframe code repo)

Target business
===============
Given the well known and transparent operations of `Wikipedia <https://www.wikipedia.org/>`_; they can serve as the perfect hypothetical for a case study - and we can leverage realistic events from Wikipedia's publically available `data dump <https://meta.wikimedia.org/wiki/Data_dumps>`_.

Business need
-------------
In our fictional scenario, Wikipedia has decided to monetize their platform by charging users for creating or updating content. They have an idea of how to price their products and have created a mock pricing page to illustrate it. 

|pricing_page|

State of the world
==================
In order to implement Wikipedia's business model an understanding of the existing data is necessary. The most critical question is whether or not the available information is enough to handle the business need.

This can be answered by reviewing the user/customer model and the available event logging. The data source can be found `here <https://dumps.wikimedia.org/other/commons_impact_metrics/edits/>`_.

Users
-----
Users and customers are not always the same, but in this case it's assumed they are. While there is no user data within the source dataset, fortunately, each event has a username attached to it which can be used as a proxy. The username will be used as a `natural </metadata/natural_keys.html>`_ and a `durable </metadata/durable_keys.html>`_ key on the customer table.

.. csv-table:: Sample customers
   :file: /_static/ex_tables/ex_cs1_1_a.csv
   :class: bmodel-table
   :header-rows: 1

.. csv-table:: Customer count
   :file: /_static/ex_tables/ex_cs1_1_b.csv
   :class: bmodel-table
   :header-rows: 1


Events
------
The schema for the raw event data can be found within the `Wikimedia datasets <https://wikitech.wikimedia.org/wiki/Commons_Impact_Metrics/Data_Model#Event-based_datasets>`_. There are a large number of events, and these are the basis of customer usage on the platform. Each event is not uniquely identified, but this can be accomplished with a natural key that combines the filename and timestamp. This composite key is used as the ``transaction_id`` for each event. The ``username`` is the customer durable key, so this should be the ``customer_id`` field as well. The action taken, create or update, can be stored in properties under ``$.properties.event_type``. The timestamp of the event can represent the ``metered_at`` and ``received_at`` attributes.

.. csv-table:: Sample events
   :file: /_static/ex_tables/ex_cs1_2_a.csv
   :class: bmodel-table
   :header-rows: 1

.. csv-table:: Event count
   :file: /_static/ex_tables/ex_cs1_2_b.csv
   :class: bmodel-table
   :header-rows: 1

Business modeling
=================
Given the business need and underlying data, it is possible to use bframe to create an automated model. This section specifies each component of the system to apply the desired pricing.

Once complete, Wikipedia can generate normalized revenue documents like invoices, line items, and rated events - allowing them to power analytics, billing, and whatever other use cases may be needed to administer their business.

Configuration
-------------

Products
~~~~~~~~
Given the terms and pricing displayed above, two event based products and two flat rate products are formed. The two event based products would encompass "Create" and "Update". Each "Platform fee" would be represented as a different product since different features are associated with each.

.. csv-table:: Products
   :file: /_static/ex_tables/ex_cs1_3_a.csv
   :class: bmodel-table
   :header-rows: 1

Prices and Pricebooks
~~~~~~~~~~~~~~~~~~~~~
Each plan represents a different pricebook, which contain a price for each product. Both the standard and enterprise pricebooks have the same attributes but have differing prices. 

.. csv-table:: Products, Prices, Pricebooks
   :file: /_static/ex_tables/ex_cs1_3_b.csv
   :class: bmodel-table
   :header-rows: 1

Provisioning
------------
The top 30 customers have an enterprise contract while the rest use a standard plan. Wikipedia doesn't have any custom contracts, so there is no need for any ad hoc contract prices.

.. csv-table:: Sample contracts
   :file: /_static/ex_tables/ex_cs1_4.csv
   :class: bmodel-table
   :header-rows: 1

Metering
--------
Each event based product has a different usage calculation. The "Update" product employs a COUNT function and the "Create" product uses ``$.properties.file_size_kb`` as an ``agg_property`` to calculate the quantity.

.. csv-table:: Sample processed events
   :file: /_static/ex_tables/ex_cs1_5.csv
   :class: bmodel-table
   :header-rows: 1

Rating
------
The preceding inputs result in a monthly arrears based invoice created for each customer and an advanced annual invoice to represent the "Platform fee". Since there are multiple event based products, rated events are also generated. 

.. csv-table:: Sample rated events
   :file: /_static/ex_tables/ex_cs1_6_a.csv
   :class: bmodel-table
   :header-rows: 1

.. csv-table:: Sample products, line items, invoices
   :file: /_static/ex_tables/ex_cs1_6_b.csv
   :class: bmodel-table
   :header-rows: 1
 
.. |pricing_page| raw:: html
   :file: ../_static/html/pricing_page.html