NOTE: The below article details this feature for our customers utilizing our Kahua for Owner’s and Kahua for GC’s applications, which excludes custom workflow or configuration. Specific customer configuration, customers utilizing other versions of these applications, or custom application features may differ in functionality or processes to those outlined below. For more details on training guides specific to your company, please check with your company IT or Domain Administrator prior to submitting a request to Kahua Support.
TABLE OF CONTENTS
- Overview
- Feature Enabling and Security
- Domain Settings
- Role Permissions
- Cost Configuration Features
- General Tab
- Cost Guards Tab
- Cost Configuration Elements
- ConsolidatedWorkBreakdownItemTotal Component
- Dynamic App and Cost Unit Inclusion in Cost Configuration
Overview
This document provides a summary of the Cost Configuration features and how these various settings managed via cost configuration are utilized within appdef for dynamic control of cost validations and behaviors.
Cost Configuration provides the ability to control the following behaviors in cost apps that are built to comply with cost configuration settings:
- Control of selection of work breakdown item for leaf or summary nodes (this is independently configured for funding and expense apps).
- Control of selection of work breakdown item in expense apps based upon the presence of funding on the wbs item for specified funding cost units.
- Optional enforcement of budget guards comparing expense to funding amounts for specified funding and expense cost units during any of the following document operations:
- Modification of cost document (creation, editing).
- Deletion of cost document (i.e., deleting a funding document could remove budget below existing expenditures).
- Restoration of cost document from deletion (i.e., could restore a document that now consumes more expenditures than available budget).
- A future feature will potentially allow for selection of the guard algorithm. The current guard algorithm supported only allows for the comparison of funding to expense amounts directly on a given wbs item. A future feature may allow for the search of available funding up the wbs hierarachy.
Feature Enabling and Security
To access the Cost configuration in Kahua configuration, two feature and security related settings must be adjusted:
Domain Settings
Open the Domain Settings app, navigate to the Domain Defaults tab, and then enable the feature switch for “Enable Cost Configuration”. Save the settings.
Role Permissions
The Cost configuration tab in Kahua configuration has a dedicated role assigned for controlling its access called “Cost Administrator”. If you are a domain administrator, you will have access this to automatically. If you are not a domain administrator, you must belong to a group that has been granted Cost Administrator to the Configuration app.
The Cost configuration tab will only be visible to users when both the Domain setting “Enable Cost Configuration” is enabled, and the user is a member of a group that as the Cost Administrator role within the Configuration app.
Cost Configuration Features
Cost configuration is accessed via the Cost tab in configuration and applies to the partition in which the configuration is overridden and all partitions below it (unless otherwise overridden). This is consistent with every other configuration feature of Kahua.
Cost apps that integrate with cost configuration features will utilize some new appdef capabilities that are “aware” of the cost configuration and dynamically control the behavior of the appdef components. Note that cost apps must be engineered to use these new features. The remainder of this document will tie in and describe the various Cost configuration fields from the configuration user interface with the corresponding features in appdef that utilize these configuration elements to control the behavior of cost apps.
General Tab
The General tab of Cost Configuration provides features for controlling the behavior of cost apps with regard to the selection of work breakdown items for use on cost documents as well as the behavior of the optional CostWorkBreakdownItemAnalysis component that will display the current expense and funding amounts for a selected wbs item along with the remaining available funds (if any).
Cost Guards Tab
The Cost Guards tab of Cost Configuration provides the ability to enable the use of cost guard validation in cost apps. The tables of cost app cost units allow for customization cost unit amounts retrieved for work breakdown item totals for consideration in the guard algorithm.
The cost guard algorithm is a simple comparison is to ensure that the expense total is less than or equal to the funding total for the respective work breakdown item. If the expense total exceeds the funding total, then the guard is violated which will then prevent the completion of the requested operation (modification, delete, or restore of the cost document), reporting the work breakdown item, document item, and respective funding and expense totals that cause the guard violation.
Most Kahua cost apps provide a set of cost units which represent a cost item amount for a given state in an approval workflow or process that ultimately completes in an “Approved” state. This can be an automated or manual process; the cost guards make no assumptions about the workflow.
An administrator can configure what cost units are considered on the funding and expense side in the guard computation. In the example below, the Budget Guards column is including the Approved cost units from the various funding side cost apps. This means that only approved budgetary changes are summed into a total for the funding side of the comparison. In the Guarded Expenses column both Approved and Pending cost units from the various expense side cost apps are included in the expense side total. This means that from the expense side we consider both approved expenditures, plus provisional or pending expenditures that are not yet “approved” so this allows for the detection of potential budget violations prior to a final approval process on the expense side.
Cost Configuration Elements
The table below breaks down each element on the cost configuration user interface and highlights where it is used in cost apps appdef to control the behavior of the various cost components within a cost app. The Cost Configuration element column displays the control in the Cost Configuration user interface. The Hub Expression column shows the corresponding value of the cost configuration setting as an expression that is used in a component in a hubdef, such as view control or a variable. The Hub Condition column shows the corresponding setting name if used in a conditional statement in Hub to control program flow. Under each item in a table row is an appdef snippet illustrating the use of the expression and/or condition. In most cases the appdef snippet was used from the “kahua_Contract_extension” K4X extension, however similar usages are employed through the various K4X extensions. For funding specific examples, appdef snippets were used from the “kahua_FundingBudget_extension” K4X extension.
ConsolidatedWorkBreakdownItemTotal Component
In addition to the examples above, a Hub variable is available for use in guard implementations that provides the ability to compute the total funding and expense amounts for a given work breakdown item and set of funding and expense cost units. In addition to this, when future features are completed that allow for other wbs search capabilities, an input to this variable will allow for other guard algorithms to be utilized where something other than an on-wbs-item match is supported, so budget could be resolved somewhere up the wbs hierarchy to allow for more flexible scenarios when validating expenditures against budget. Presently this only supports the “Standard Guard” which requires a direct budget on the wbs item that supports the expense.
In the example above, a Hub function is defined that uses the ConsoldatedWorkBreakdownItemTotals variable to compute the funding and expense total for the given WorkBreakdownItemEntity input. This is called from a Hub Function as shown below:
Which in turn is invoked from a Hub Event called by the Hub EntityEvents feature in response to document modifications, as shown below:
Note that this only invoked conditionally if the CostGuardsEnabled cost setting is True.
Returning to the details of the ConsolidatedWorkBreakdownItemTotal usage, here is a detailed explanation of how this is used in cost guards:
Following execution of the ConsoliatedWorkBreakdownItemTotals variable, the “fundingTotal” and “expenseTotal” variables will be populated with the respective funding and expense amounts for the input work breakdown item. In the operations after this, other variables are computed as follows:
In the directives above, this computes the difference between the funding and expense totals placing that in the “guardedDifference” variable, and then the totals and the difference are rounded to the current project currency precision to eliminate the possibility of any mismatches due to fractional currency amounts.
Next the raw amounts are formatted to the project currency and placed in their own variables, as well as the wbs item code for use in an assertion message if the guard fails the test.
Lastly, an assertion is defined that will test to see if the rounded expense total exceeds the rounded funding total and if so, will display the error message indicating that the cost guard has failed.
Dynamic App and Cost Unit Inclusion in Cost Configuration
The participation of a cost app in the cost configuration and guard operations is an opt-in setting in an app definition. For a cost app to participate in cost configuration it must include a Cost.GuardConfiguration entry in App.Features, with the Enabled property set to “True”. Cost apps that do not include this setting will not have their cost units added to the list of expense or funding cost units that appear in the various cost unit lists for guard configuration and budgeted expenses in the Cost Configuration user interface.
It is also possible to provide detailed filtering on cost units for cost apps that do participate in cost configuration, but certain cost units should be excluded from guard operations:
For example – the Purchase Order cost app includes cost units that track the remittance state of a purchase order. These cost units should not be included as expenditures as those amounts are tracked in other cost units, so this filter designates will omit these cost units from the cost unit configuration.
The following elements are used to control cost configuration:
