Integrating a Source Document with Budget Control
When adding a document extending the source document framework, the document can also be enabled for ledger budget checking. This provides the ability for the financial activity of the document to be checked to ensure funds are available to pay for those activities. Budget control is already integrated with the source document framework. This integration ensures the budget funds available check occurs at the expected times in the document's life cycle and that all of the data prerequisites for budget checking are completed.
After you have a document extending the source document framework follow these steps to enable that document to be checked for budget:
- Add a new value for the integrating document to the BudgetControlSourceIntegrator enumeration
- Each value in this enumeration corresponds to a document that can be enabled for budget control from the budget control configuration form. Adding this value to the enumeration ensures that budget control data corresponding to the integrator is handled properly during budget control configuration maintenance.
- Implement the SourceDocumentTypeIBudgetControl interface
- The SourceDocumentType subclass for the integrator must implement the SourceDocumentTypeIBudgetControl interface. This interface provides the following data:
-
-
-
- Budget control source integrator value: This maps the document's implementation to its setup in budget control configuration.
-
-
-
-
-
- Budget control category value: This determines how the amounts of the document are included in the calculation of budget funds available.
-
-
- Extend the BudgetControlSourceDocumentLinePolicy class
- The BudgetControlSourceDocumentLinePolicy class provides default budget control policy for a source document line. The default policy can be extended. The extension must be decorated with the SourceDocumentExtensionAttribute based on the BusinessEvent enum and value. See the PurchOrderLineBudgetControlPolicy and VendorInvoiceLineBudgetControlPolicy classes for some examples of extending the behavior to add additional conditions for determining when budget funds available can be checked.
- Extend the BudgetControlSourceDocumentLineRule class
- The BudgetControlSourceDocumentLineRule class provides default budget control processing rules for a source document line. The default rule can be extended. Similar to the policy extension, the rule extension must be decorated with the SourceDocumentExtensionAttribute based on the BusinessEvent enum and value. See the PurchOrderLineBudgetControlRule and VendorInvoiceLineBudgetControlRule classes for some examples of extending the behavior of the base rule in determining how the budget funds available check is performed against the document.
- Add new data source edit methods on BudgetControlConfiguration data source on the BudgetControlConfiguration form to allow for budget checking to be enabled and disabled at the document level
- Add a method calling the setSourceIntegratorEnabled() method. This method will provide the option to enable and disable budget checking for the source document. Then to refresh the form display when the value changes, call the setEnabledSourceDocuments() method.
Example: editVendorInvoiceEnabled()
public edit NoYes editVendorInvoiceEnabled(boolean _set, NoYes _isEnabled)
{
BudgetControlSourceIntegrator sourceIntegrator = BudgetControlSourceIntegrator::VendorInvoice;
boolean isSet;
if (_set)
{
// Set whether vendor invoice budget control is enabled.
isSet = this.setSourceIntegratorEnabled(sourceIntegrator, _isEnabled);
if (isSet)
{
element.setEnabledSourceDocuments();
}
}
return enabledSourceIntegrators.in(sourceIntegrator);
}
- Add a method calling the setSourceIntegratorDoBudgetCheckOnEntry() method. This method will provide the option to specify whether the source document will perform a budget check at line item entry.
Example: editVendorInvoiceDoCheckOnEntry()
public edit NoYes editVendorInvoiceDoCheckOnEntry(boolean _set, NoYes _doBudgetCheckOnEntry)
{
BudgetControlSourceIntegrator sourceIntegrator = BudgetControlSourceIntegrator::VendorInvoice;
if (_set)
{
// Set whether vendor invoice do budget check on entry.
this.setSourceIntegratorDoBudgetCheckOnEntry(sourceIntegrator, _doBudgetCheckOnEntry);
}
return doBudgetCheckOnEntrySourceIntegrators.in(sourceIntegrator);
}
- Add controls to the form on the SourceDocuments tab page to expose the edit methods that were added.
- Add code to maintain the form controls in the setEnabledSourceDocuments() and setVisibleSourceDocuments() methods.
These additional extension areas can be considered depending on the requirements of the new source document:
- Add extension attributes to enable budget checks when the accounting distribution form is interacted with from the source document. This allows the budget funds available check to also occur after interacting with the accounting distributions form.
- Add the SourceDocumentExtensionAttribute based on the SourceDocument enum and value to the BudgetControlAccDistFormViewExtension and BudgetControlAccDistViewModelExtension classes.
- Add calls for on-demand checks
- Budget checking is performed for a source document enabled for budget control through budget control configuration when the document is transitioned to a Completed state. In addition to this state transition, budget checking is performed based on the option in the budget control configuration to do the budget check on line entry. Additional calls can be added to perform a budget check at other times by calling one of the submitOnDemand() methods on the SourceDocumentProcessorFacade class. Using this method will ignore the setting of the configuration option to perform the check on line entry. Examples of when this can be used are workflow actions that should perform a budget check or a user-initiated action such as the "Perform budget check" action on the action pane.