Amendments
**********
What are amendments?
====================
An amendment within bframe refers to a scheduled change to a contract or a pricebook. This is most commonly used to evolve terms and conditions over time. Amendments are different than edits because they do not overwrite the underlying model. Instead they are created with an effective period which determines which models are active at a specific point in time. This design necessitates additional overhead to set an effective date range, but it allows for coexistence between each iteration of the pricebook or contract. Thus bframe respects prior terms and conditions when generating invoices, line items and rated events across time.

Amendments are recognized when the ``durable_id`` is the same between multiple rows with non-overlapping ``effective_at`` and ``ineffective_at`` timestamps. In the diagram below it's shown what this could look like for a pricebook with an amendment.

.. figure:: /_static/images/features/amendment_effective_range.png
    :width: 500px

Why are amendments important?
=============================
Amendments are the safest way to make changes within a business model. The two main benefits that amendments offer are as follows:

1. Their capacity to be scheduled on a specified date.
2. They do not overwrite prior models allowing for the transformation layer to respect historical configurations. 

How do amendments work in bframe?
=================================
Amending a contract or pricebook is more overhead than making an edit. For an amendment to work, the entity being changed must have an effective time range. This range is represented by the ``effective_at`` and ``ineffective_at`` fields. On model creation the ``ineffective_at`` date is often unknown and is left as ``NULL``. If this is the case, the model must first be edited to set the ``ineffective_at`` before the amended model can be inserted. Once an effective time range has been set, a new row is then created with a consecutive non-overlapping effective range along with other modifications.

To demonstrate an amendment let's make a modification to an enterprise contract for one of the customers in the `Wikipedia case study </case_study/index.html>`_.

Making an amedment
------------------
To make an amendment to a contract we first need a target. For this example let's use the contract in place for the customer ``Scann``.

.. tab-set::

    .. tab-item:: Result

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

    .. tab-item:: Query

        .. literalinclude:: /_static/ex_sql/amend_feat_1_1.sql
            :language: sql

The contract that is currently in place doesn't have an ineffective_at, so this will need to change in order for us to make an amendment. We will change the ineffective_at timestamp to be 2/1/2024.

.. tab-set::

    .. tab-item:: Query
        
        .. literalinclude:: /_static/ex_sql/amend_feat_1_2.sql
            :language: sql

    .. tab-item:: Result

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

Now that the target contract is ready, let's amend the pricing to be discounted by 50%. 

.. tab-set::

    .. tab-item:: Query
        
        .. literalinclude:: /_static/ex_sql/amend_feat_1_3.sql
            :language: sql

    .. tab-item:: Result

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

Exploring the change
--------------------
Now that the amendment has been put in place let's observe the generated invoices and line items associated with this contract.

.. tab-set::

    .. tab-item:: Result

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

    .. tab-item:: Query

        .. literalinclude:: /_static/ex_sql/amend_feat_1_4.sql
            :language: sql

Since this is an amendment the changes are only applied during the effective range. Thus the discount is only applied to months past 2/1/2024.