Ledgers

A ledger is a table of numbers that you can save in a case, and access in forms.

Open

Definitions:

• A ledger can be viewed as a type of case property

• But unlike the case property the ledgers can be updated directly in the form-builder with the transactions.

• The row of the ledger is called an "entry" and corresponds to a product id.

• The column of a ledger is called a "section":

  • You can create your own section when creating a ledger (stock, balance, price, order amounts ...)

  • You can define as many sections as you want for a ledger.

  • Some section ids, such as consumption (which store the average monthly consumption) are reserved by the application.

• The number saved for each row and column is called a "quantity":

  • The quantities of a ledger are of integer type. Decimals are not supported.

Open

Do you want to use a ledger?

1.  

   • You are a community health worker who manages ORS, zinc, and vitamins

   • You are building an app to track shipments of products over time

   • You are building an app to track orders/requisitions of products over time

   • You want to track the number of Rapid Diagnostic Tests (RDTs) at a facility over time

   • You want to make a sandwich shop app that tracks how much money 50 different clients owe you
     
     
     

Transactions

A transaction allow you to save and update numbers in a ledger.

There are 4 types of transactions:

• Balance: set the ledger quantity to a specific value 

• Receive: increment the ledger quantity by a specific value 

• Dispense: decrement the ledger quantity by a specific value 

• Transfer: decrement the ledger quantity by a specific value on a case A & increment the ledger quantity by a specific value on a case B 

Good to know !!! 

• Transactions are atomic – so if your phone shuts down mid-transfer, things don’t get lost.

• Transactions are also resolved meaningfully. In CommCare, if 2 phones increments the same number, whichever phone writes last wins. In CommCare Supply, the increments are summed.

How to setup a transaction question?

• Question ID: anything you want

• Case: id of the case where your ledger will be saved. 

  • This can take different values depending on which case you want to use to save your ledger.

  • In order to save the ledger in the current selected case, use: instance('commcaresession')/session/data/case_id.

  • In order to save the ledger in the user supply-point, use: instance('commcaresession')/session/user/data/commtrack-supply-point.

  • ...

• Balance ID: id of the section (i.e. stock, balance, ...)

• Product: id of the product

  • When used in a repeat group over products, the syntax to use is current()/../../../@id. However this will depend if you put the transaction question in question groups or not (see here).

• Quantity: value to set to the ledger.