(Click to open topic with navigation)
An allocation is a time-bound pool of credits associated with a fund. A fund may have multiple allocations, each for use during a different time period. Normally, only a single allocation will be active within a fund at any given time.
Allocations are normally created via a fund deposit. An allocation has an amount, an initial deposit, and an allocated value. The Amount attribute tracks the current amount of credits in the allocation. The InitialDeposit attribute stores the amount originally deposited into an allocation when it is initially created. The Allocated attribute stores the current adjusted allocated amount. It is begins set to the initial deposit amount and is incremented with each crediting deposit or incoming transfer and decremented with each withdrawal or outgoing transfer. When a deposit is made to a fund, if a matching allocation already exists with the appropriate time period, the existing allocation is modified. Otherwise, a new allocation is created. A resetting deposit will end the currently active allocation and create a new allocation.
An allocation has a start time and an end time that defines the time period during which the allocation may be used. If a start time or end time is specified when making a deposit, an existing allocation having the specified boundary times will be credited. If no start time or end time is specified, the active allocation will be credited. If no matching or active allocations can be found, a new allocation will be created with the specified or default start and end time (the start time defaults to the present and the end time defaults to infinity). An active flag is automatically updated to True if the allocation is within its valid time frame or False if it is not. An allocation that becomes active because the current time is greater than its start time undergoes an activation which normally registers as a credit to the fund. An allocation that becomes inactive because the current time is greater than its end time undergoes a deactivation which normally registers as a debit to the fund.
By using multiple allocations that expire in regular intervals it is possible to implement a use-it-or-lose-it policy and establish an allocation cycle. There are two primary methods to implement periodic allocations. In the first method, called Resetting Allocations, funds are reset (ending the current allocation and creating a new one) at the beginning of each allocation period. By setting and maintaining an appropriate default deposit amount for each fund, the process of resetting funds can be simplified. The periodic reset can be performed either by making a resetting deposit for each fund (e.g. gdeposit -f 1 --reset) which allows you to override default deposit amounts, by calling the reset action for each fund (e.g. gchfund -f 1 --reset) which allows you to select which funds to reset, or by invoking a reset across all funds (e.g. gchfund --reset --all). The effect of any of these commands is to end the currently active allocation in th ffund and then make a fresh deposit. The fund's default deposit amount is used any time the amount is not specified in a deposit (as in the case of a fund reset command). If the default deposit amount is positive, the currently active allocation is ended and a new allocation is created with the default amount. If the default deposit amount is set to a value of zero, the active allocation is ended and no new allocation is created. If the default deposit amount is not set, the fund's allocations are not affected. The reset can be performed via a scheduled event or via a cron script. If default deposit amounts are kept up-to-date (including being zeroed out for funds that are slated to end and being unset for funds that you do not want affected by the reset), automation of this method can be as simple as creating a single periodic event with a FireCommand of "Fund Reset (see Creating events). In the second method, called Expiring Allocations, funds with predesignated start and end times are created head of time. When the beginning of an allocation period is reached, the currently active allocation automatically expires and the next one automatically becomes active. A future allocation is created by making a deposit while specifying a start time and an end time in the future (e.g. gdeposit -f 1 -s 2014-10-01 -e 2015-01-01). This method can also take advantage of default deposit amounts. The overall effect of either of these methods is very similar.
By default, Moab Accounting Manager attempts to enforce Discrete allocations, or ensure that allocations within a fund are non-overlapping (in time) and non-reusable (each allocation period should use a distinct allocation). This behavior is designated by the allocation.enforediscrete server configuration parameter. If set to true, this policy prevents new allocations within a fund from overlapping existing ones. Enabling this policy helps to improve clarity when reporting on allocation usage during a particular period. If set to false, overlapping allocations within a fund can be created. This might be useful if you want to allow the remaining balance from a prior allocation period to carry over into the new allocation period. With overlapping allocations, it is harder to describe what percentage of a group's allocation has been used. This policy is applied when making deposits that create new allocations, when making transfers that create new allocations, or when modifying the start and end times of an existing allocation. It is possible to override the configured policy for an individual command by specifying the EnforcedDiscrete option (e.g. gdeposit --option name=EnforceDiscrete value=False).
An allocation may have a credit limit representing the amount by which it can go negative. Thus, by having a positive balance in the Amount field, the fund is like a debit account, implementing a pay-first use-later model. By establishing a credit limit instead of depositing an initial balance, the fund will be like a credit account, implementing a use-first pay-later model. These strategies can be combined by depositing some amount of funds coupled with a credit limit, implementing a form of overdraft protection where the funds will be used down to the negative of the credit limit.
It is possible for the allocation Amount or CredLimit to be set to Infinity (via a deposit). If the amount is infinite, debits will not decrease the balance. An infinite deposit will result in an infinite Allocated amount. If the credit limit is infinite, there will be no negative limit for debits. It is not possible to have infinite charges, liens, quotes, withdrawals, refunds, or transfers. However, it is possible to have infinite allocation activations, deactivations, and deletions. This capability is only available when using a database that supports IEEE Standard 754 for Floating-Point Arithmetic (e.g. PostgreSQL).
Operations include querying, modifying, and deleting allocations. Allocations can be created by a fund deposit, creating a fund with allocation auto-generation enabled, refunding a usage record, or a transfer between funds. Allocations may also be indirectly modified via charges, withdrawals, transfers, or refunds. By default, a standard user may only query allocations which pertain to them.
Allocation queries allow the specification of filter options which filter the allocations to those with funds meeting the specified fund constraints. There are two allocation filter types that can be employed: Exclusive and NonExclusive. If an exclusive filter type is used, the query will return only allocations relating to funds for which the specified filters meet all constraints. For example, Allocation Query FilterType:=Exclusive Filter:=User=scottmo would not return an allocation for a fund with the sole constraint Machine=blue. If a non-exclusive filter type is used, the query will return all allocations relating to funds for which the filters do not specifically exclude the constraints. The query assumes that if constraints are not specified within the filters, they can be assumed as a wildcard and will return all allocations involving funds that are not specifically excluded by the filter. For example, Allocation Query FilterType:=NonExclusive Filter:=User=scottmo would return an allocation with a fund whose only constraint was Machine=blue but would not return an allocation with a fund with the constraint User=bob.