-
Notifications
You must be signed in to change notification settings - Fork 14
ledgerxml
V.1 - Initial Version
this needs to be rewritten
Ledger Models in CommCare applications provide a mechanism to store a structured list of numeric values. Unlike a case, where each property tracked has to have a structurally unique ID, in a ledger the list of what is tracked can be defined dynamically.
Currently ledger models have a "0 or 1" relationship with cases, and piggy-back onto the case lifecycle. If a ledger model exists for a case, it will be synced down for any user who receives that case. If a case is no longer relevant for a user, the ledger model associated with that case will be purged. Ledger models never need to be "declared" before a transaction references them. The first transaction processed will create a ledger model in the system.
Inside of their model, there can be multiple ledgers, each with a unique ID, so that different values can be tracked (IE: Real ledgers, losses, estimates of consumption). The term "ledger" refers to a set of products all "tagged" with the same ledger-id, and associated with a case. IE: an individual case has a set of "ledgers", within a "ledger" of that case, each product should represent the same type of value being tracked.
Modifications to the ledger database occur when a valid ledger xml transaction is found while processing a form. All transactions in CommCare are processed in document order, so a transaction which occurs above another will be processed before the latter. All ledger transactions are defined in the http://commcarehq.org/ledger/v1 namespace. Currently two transactions are available, <balance> and <transfer>.
There are two ways to identify which section a transaction should be applied to. If the section-id is declared in the top-level of a transaction, all of the actions should apply to that ledger-id for any models that are referenced. If there is no section-id at the top level transaction, each modification should supply a section-id.
The transactions should provide two possible formats. One is to declare a ledger by its id at the root of the transaction, which will apply all modifications to the appropriate ledger. The alternative (if no ledger-id is defined at the top level) will instead define the list of products first, then provide parings of ledgers and the value of that product to be defined inside of each of them.
The <balance> element declaratively sets the value of any products included in the transaction. The value for any products not included should not be modified as the result of a <balance> transaction. In order to specify an empty product ledger it should manually be set to 0.
The <balance> element schema is defined as either
<!-- Individual Ledger Balance -->
<balance xmlns="http://commcarehq.org/ledger/v1" entity-id="" date="" section-id="">
<!-- entity-id - Exactly One: the GUID of the the entity associated with this ledger (only case id's for now) -->
<!-- date - Exactly One: The date and time when this balance report occurred-->
<!-- section-id- Exactly One: The id of the section being modified for this entity. If not present, all entries must define their own section ID. If present, no entry can provide a section-id -->
<entry id="" quantity="" exponent=""/>
<!-- id - Exactly One: The unique ID of this entry.-->
<!-- quantity- Exactly One: The quantity (an integer value) of the entry being reported-->
<!-- [Not yet implemented, proposed] exponent- Zero or One: If present, describes the exponent E to be multiplied in the form (10^E) to the quantity. Defaults to 0 -->
</balance>or
<!-- Per-Entry Ledger Balance -->
<balance xmlns="http://commcarehq.org/ledger/v1" entity-id="" date="">
<!-- entity-id - Exactly One: the GUID of the the entity associated with this ledger (only case id's for now) -->
<!-- date - Exactly One: The date and time when this balance report occurred-->
<entry id="">
<!-- id - Exactly One: The unique ID of this entry.-->
<value section-id="" quantity="" exponent=""/>
<!-- section-id- Exactly One: The ID of the section that this entry value should be applied to. Must exist if <balance> does not supply a ledger ID. Must not exist otherwise. -->
<!-- quantity- Exactly One: The quantity (an integer value) of the entry being reported-->
<!-- [Not yet implemented, proposed] exponent- Zero or One: If present, describes the exponent E to be multiplied in the form (10^E) to the quantity. Defaults to 0 -->
</entry>
</balance>The <transfer> element describes a delta of entry quantities between one or more ledgers. Upon processing, the entry values included will be removed from the source (if defined) and appended to the destination (if defined).
Transfers do not have to define both a source and a destination. This provides a mechanism to add or remove entries in discrete quantities, which can be tagged with the type attribute to provide robust reporting.
The <transfer> element schema is defined as either
<!-- Individual Ledger Transfer -->
<transfer xmlns="http://commcarehq.org/ledger/v1" src="" dest="" type="" date="" section-id="">
<!-- src - At Most One (Exactly One if dest is not defined): the GUID of the the entity whose ledger model should have its entry values on the specified section subtracted by the described quantities -->
<!-- dest- At Most One (Exactly One if src is not defined): the GUID of the the entity whose ledger model should have its entry values on the specified section subtracted by the described quantities -->
<!-- date - Exactly One: The date and time when this transfer occurred-->
<!-- type- At Most One: An arbitrary string which describes what action is being represented by this transfer (like "loss", "receipt", etc). Can be used to provide the id of a structured action in a fixture. -->
<!-- section-id- Exactly One: The section id being modified for this entity. If not present, all entries must define their own section ID. If present, no entry can provide a section-id -->
<entry id="" quantity="" exponent=""/>
<!-- id - Exactly One: The unique ID of this entry.-->
<!-- quantity- Exactly One: The quantity (an integer value) of the entry being reported-->
<!-- [Not yet implemented, proposed] exponent- Zero or One: If present, describes the exponent E to be multiplied in the form (10^E) to the quantity. Defaults to 0 -->
</transfer>Or
<!-- Per-Product Ledger Transfer -->
<transfer xmlns="http://commcarehq.org/ledger/v1" src="" dest="" type="" date="">
<!-- src - At Most One (Exactly One if dest is not defined): the GUID of the the entity whose ledger model should have its its entry values on the specified section subtracted by the described quantities. Can be omitted if dest is defined, but must contain a value if the attribute is present -->
<!-- dest- At Most One (Exactly One if src is not defined): the GUID of the the entity whose ledger model should have its its entry values on the specified section subtracted by the described quantities. Can be omitted if src is defined, but must contain a value if the attribute is present-->
<!-- date - Exactly One: The date and time when this transfer occurred-->
<!-- type- At Most One: An arbitrary string which describes what action is being represented by this transfer (like "loss", "receipt", etc). Can be used to provide the id of a structured action in a fixture. -->
<entry id="">
<!-- id - Exactly One: The unique ID of this entry .-->
<value section-id="" quantity="" exponent=""/>
<!-- section-id- Exactly One: The ID of the section that this entry transfer should be applied to. Must exist if <transfer> does not supply a ledger ID. Must not exist otherwise. -->
<!-- quantity- Exactly One: The quantity (an integer value) of the entry being reported-->
<!-- [Not yet implemented, proposed] exponent- Zero or One: If present, describes the exponent E to be multiplied in the form (10^E) to the quantity. Defaults to 0 -->
</entry >
</transfer>