Skip to end of metadata
Go to start of metadata

Conventions used in this document.

Method names.

Method names are written in title text, and are indexed in the content page. Parameters are in parentheses, including the objects that as passed.

Return Types

Return types are show in italics below the method name.

Permissions Documentation

Most methods have an associated permissions and security block.

Permissions Information

 

Permissions Required to Call Method

This is the name of the permission that the user must have in order to be able to access this method. These permissions may also be used in the UI to decide if an element renders.

Extended Permissions

This is a permission that might be used if certain conditions are met, for example, the difference between creating and changing an element.

Implied Permissions

Some permissions that are implied by the ability to execute this method. For example, if you can reverse a transaction, you need to also be able to create payment/ charge and create a locked allocation.

Activity requirement

Name of the type of system activity that is recorded.

Example description of the line that will be written to the activity log.

 

Access Control (Security Extension) Service [AccessControlService]

The Access Control Service is used to mediate security control between KSA and KIM. All permissions are stored within KIM, allowing easy and standardized access to the KIM permissions system.

Abstract Service Responsibility

The access control service makes a very small extension to the KIM control permissions. Access Control allows us to lock down the use of certain transaction types to a certain user. Transaction type masks are used in addition to other permissions as supplied by KIM.

getAllowedTransactionType (String userId)

Returns list of String.

isTransactionTypeAllowed (String userId, String transactionTypeIdentifier)

Returns Boolean.

hasPermissions (String userId, String permissionName)

hasPermissions (String userId, String permissionName…)

Returns Boolean.
(formerly isAllowed())

getPermissions(String userId)

Returns list of String.
Return permission associated with the passed user.

getRoles(String userId)

Returns list of String.
Return roles associated with the passed user.

getAllowedTransactionTypeMasks(String userId)

Returns list of String.
Returns a list of transactionTypeMasks associated with a user.

getAllowedTransactionTypes (String userId)

Returns list of String.
Returns a list of allowed transaction types for a user. See getAllowedTransactionTypeMasks().

getTransactionTypesByRoleNames (Set <String> roleNames)

Returns list of String.
Returns list of transaction types accessible by the role(s).

refresh()

Forces a reload of the cached TransactionTypePermission class. This should be called after changing a permission if it is required that the change be propagated instantly.

checkPermission(Permission permission, Map<String, Object> extendedAttributes)

Returns void.
The extendedAttributes Map is designed to allow extended information to be passed to the rules engine. The specific initial use case is to pass tranactionTypeId to the rules in order to filter by specific transaction types. Note the receiving accountId will also be in the map.

createAccountBlockOverride(String accountId, Date expirationDate, String reason, Long overriddenRuleId)

createAdministrativeAccountBlockOverride(String accountId, Date expirationDate, String reason, Permission administrativeOverridenPermission)

Returns Long

Permissions Information

 

 

Permissions Required to Call Method

CREATE_ACCOUNT_BLOCK_OVERRIDE, CREATE_ADMINISTRATIVE_ACCOUNT_BLOCK_OVERRIDE

 

Extended Permissions

 

 

Implied Permissions

 

 

Activity requirement

 

 


Create a new AccountBlockOverride object:
accountId-> accountId.
creatorId-> Current user.
creationDate -> Current Date/Time.
expirationDate -> from the parameters – must be non-null and in the future.
overridenRuleId => From parameter. Check rule exists. (Does not exist for Admin Block Override)
reason -> from parameter. Should not be empty.
isAdministrativeOverride -> True or false, depending on method.
administrativeOverridenPermission -> Optional from parameters of admin override only.
Persist in database and return.

removeAccountBlockOverride(Long accountBlockOverrideId)

Returns void

Permissions Information

 

 

Permissions Required to Call Method

CREATE_ACCOUNT_BLOCK_OVERRIDE, CREATE_ADMINISTRATIVE_ACCOUNT_BLOCK_OVERRIDE

 

Extended Permissions

 

 

Implied Permissions

 

 

Activity requirement

 

 


Check user has to the permission to create (and therefore remove) the override specified in the AccountBlockOverride.
Set expirationDate to current date/time.
Persist.

isAdminOveridden(String accountId, Permission permission)

Returns Boolean
Check to see if there is an in-force administrative override (expirationDate in the future isAdministrativeOverride= true, accountId matches the one passed in the parameters) on the account. If there is, return true, otherwise return false.

Account Blocking Sequence Generalized Patterns


This is the general pattern for the AccountBlock service. It is the job of the enforcing method to decide what to do if an AccountBlockInfo object is returned that is applicable to that method. Note that when a method is called through a batch, rather than online process, the ony block overrides that matter are the ones in force. That is to say, we don't envisage the abilty to override blocks on the fly with batch operations, as it doesn't make sense to.

Account Block with AdministrativeOverride


If there is an administrative override, the sequence is simpler.

Online Processing and Blocks (No Override)


Here we see the flow when a user initiates an action against an account that has a block that is illegal per the enforcing method.

Online Processing and Blocks with override


Here we see that the UI, in response to the exception, allows the user to issue a block override. If this block override is issued, then the original call is made again, this time either allowing a successful override, or a different block prevents the method from being effective.

checkBlock(String accountId, Map<String,Object> attriubes, Permission… permissions)

checkBlock(Map<String,Object> attriubes, Permission… permissions)


To document. Rule-based account blocking system.

Account Service [AccountService]

Abstract Service Responsibility

The account service is responsible for the maintenance of accounts, which are the abstract bundles of information that tend to refer to a person. This includes holding identity information which may or may not come from KIM, as well as holding critical accounting data for the student, such as aged balances, references to banking and other preference data, etc.
Where data in KSA Accounts is changed that is sourced from KIM details, these details are automatically populated back into KIM. Such details include names, addresses, date of birth, etc.

rebalance(String userId, Boolean ignoreDeferment)

Returns List<Pair<Debit, bigDecimal>>

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


This process creates a temporary subset of the account as if the account were being administered as a balance forward account. This permits aging the account in a way that is not affected by the payment application methodology. This temporary array is passed to the ageDebt() method.

ageDeb(String userId, Boolean ignoreDeferment)

ageDebt(String userId, Boolean ignoreDeferment, Date ageDate)

Returns ChargeableAccount.

Permissions Information

 

Permissions Required to Call Method

AGE_ACCOUNT

Extended Permissions

 

Implied Permissions

ACCESS_ACCOUNT

Activity requirement

FRIENDLY

Account + userId was aged.

Note that passing ageDate only affects the initial lateDate calculation, and updates the ageing date/time on the account with that date at the end, instead of the current date/time.

getDueBalance(String userId, Boolean ignoreDeferment)

getDueBalance (String userId, Boolean ignoreDeferment, Date balanceDate)

Returns BigDecimal.

Permissions Information

 

Permissions Required to Call Method

READ_BALANCE

Extended Permissions

 

Implied Permissions

READ_ACCOUNT

Activity requirement

 

This will get the balance of the account, taking into account only those transactions that are current (effectiveDate is today or before.)
Note getDueDalanceOnDate() only changes the logic of the initial select.

getOutstandingBalance(String userId, Boolean ignoreDeferment)

getOutstandingBalance (String userId, Boolean ignoreDeferment, Date balanceDate)

Returns BigDecimal.

Permissions Information

 

Permissions Required to Call Method

READ_BALANCE

Extended Permissions

 

Implied Permissions

READ_ACCOUNT

Activity requirement

 


This will get the balance of the account including future dated transactions.

getFutureBalance(String userId, Boolean ignoreDeferment)

getFutureBalance(String userId, Boolean ignoreDeferment, balanceDate)

Returns BigDecimal.

Permissions Information

 

Permissions Required to Call Method

READ_BALANCE

Extended Permissions

 

Implied Permissions

READ_ACCOUNT

Activity requirement

 


Get all charges with effectiveDate of tomorrow or
do getDueBalance() and getOutstandingBalance() or getDueBalanceOnDate() and getOutstandingBalanceOnDate() with the same parameters as this method, and then return outstanding – due.

getUnallocatedBalance(String userId)

Returns BigDecimal.

Permissions Information

 

Permissions Required to Call Method

READ_BALANCE

Extended Permissions

 

Implied Permissions

READ_ACCOUNT

Activity requirement

 


getDeferredBalance(String userId)

getDeferredBalance(String userId, Date date)

Returns BigDecimal.

Permissions Information

 

Permissions Required to Call Method

READ_BALANCE

Extended Permissions

 

Implied Permissions

READ_ACCOUNT

Activity requirement

 


Due to the fact that deferments can have expired, we have to make an inference of the deferment.


ksaAccountExists (String userId)

Returns Boolean.

Permissions Information

 

Permissions Required to Call Method

READ_ACCOUNT

Extended Permissions

 

Implied Permissions

Implication of CREATE_ACCOUNT which can be ignored as an internal call from this method because the data has already been validated via KIM.

Activity requirement

FRIENDLY

 

Account userId was created from KIM data.


This method is used to verify that an account exists before a transaction or other operations are performed on the account. There is an initial inquiry into the KSA store. If no account exists, then there is an inquiry into KIM. If KIM also returns no result, then false is returned. If a KIM account does exist, then a KSA account is created, using the KIM information as a template.

getOrCreateAccount (String userId)

Returns Account.

Permissions Information

 

Permissions Required to Call Method

READ_ACCOUNT

Extended Permissions

 

Implied Permissions

Implication of CREATE_ACCOUNT which can be ignored as an internal call from this method because the data has already been validated via KIM.

Activity requirement

FRIENDLY

Account userId was created from KIM data.

 

ACCESS

Account userId was accessed.


To start building an account, we first need an identifier. There are three types of account number. The first is an account number derived from KIM. In most implementations, this will be the standard student identifier used at the institution. The second is an external system identifier, where an account is made on behalf of another system. This exists to cover the use case of creating an account for an unknown identity, for example, a parking ticket where nothing is known about the account holder other than the identifier for the car. The third is a KSA account number. This is included to cover unknown use cases at this point, but is included for future use. KSA account numbers are prefixed with KSA to reduce possibility of conflicts. The format of KIM account numbers is defined by the institution, and the format of external account numbers is decided by the external system. All KSA will do is ensure there is no conflict between the numbers.
If an id is passed, check to see if the account already exists (ksaAccountExists()) If there is a KIM account with this id, the account will be generated in that method. If not, then an account framework will be generated, using the id passed. If no id is passed, an account framework is created with the next KSA account number (KSA0001910, etc.) The methods return the id of the account.
Create:
AccountProtectedInfo with only the new account id.
Account: accountId, status=defaultAccountStatusType, creationDate=current system datetime, creatorId, currently logged in user. creditLimit=defaultCreditLimit.
This gives the system a shell account, into which account details can now be placed.

getAch (String userId)

Returns Ach.

Permissions Information

 

Permissions Required to Call Method

READ_PROTECTED_INFORMATION

Extended Permissions

 

Implied Permissions

READ_ACCOUNT

Activity requirement

ACCESS

Protected information (ACH) was accessed for userId.


Get ACH looks into the AccountProtectedInformation class (which triggers a system event) to look for the ACH information for the user. By default, this is stored as a simple string, starting with C for checking or S for savings, followed by a colon, followed by the nine-digit routing number, followed by a colon, followed by the 4-20 digit account number. If this string is available and valid, the service will return an Ach object containing these details.

importAccounts (inputFile)

Simple import of accounts via XML.

Permissions Information

 

Permissions Required to Call Method

CREATE_ACCOUNT

Extended Permissions

 

Implied Permissions

READ_ACCOUNT

Activity requirement

FRIENDLY

User account userId was created via batch upload.


writeoffAccount (String accountId)

writeOffAccount (List<String accountId>)

writeoffAccount (String accountId, String memo)

writeOffAccount (List<String accountId>, String memo)

Returns void.

Permissions Information

 

Permissions Required to Call Method

WRITE_OFF_ACCOUNT

Extended Permissions

 

Implied Permissions

READ_ACCOUNT

Activity requirement

ACCESS

Account userId was accessed.

 

ACTIVITYMEMO

Memo

 

Friendly

Account userId was written off.


This will call a set of rules that will do a number of things, including establishing whatever accounts status the school wants for written off accounts, doing a final application of payments, and then calling the writeOffTransaction() on any remaining charges. The school can also use this set of rules to perform any other events they need to on accounts that are being written off.

advancedSearchAccounts(String accountSearch)

Returns List<String> (userId)

Permissions Information

 

Permissions Required to Call Method

ADVANCED_SEARCH, ADVANCED_SEARCH_PROTECTED

Extended Permissions

 

Implied Permissions

 

Activity requirement

 

ADVANCED_SEARCH_PROTECTED is needed to do any search that goes against the AccountProtectedInformation fields that contain the actual serials (not the types). These are marked in the documentation with a (star) otherwise only ADVANCED_SEARCH is required.
Parse the accountSearch string per the advancedSearch documentation, then query the accounts and return a list of accoutns that match.

Class Helpers for Account.

Note that all three account helper types (Name, ElectronicContact and PostalAddress) have a setDefault() method, which will look at all the helpers of the same type associated with an account, and ensure that they are false, before setting the specific helper to the default.

addPersonName (String userId, PersonName personName)

Returns PersonName.

Permissions Information

 

Permissions Required to Call Method

UPDATE_ACCOUNT

Extended Permissions

 

Implied Permissions

READ_ACCOUNT

Activity requirement

FRIENDLY

New name was added to account userId.


Check ksaAccountExists (userId)
Add the name to the account. If the Name.kimNameType already exists, overwrite that name, otherwise add it as a new name. If there is no default name, set the default flag on this name. If the isDefault flag is set, then make this the default name.
Update AuditableEntity fields (editorId, lastUpdate).
Note that if there is a name stored, then one of them has to be the default name, so even if a name is passed with isDefault=false, if there is no other default name, this entry must become the default name.

addPostalAddress (String userId, PostalAddress postalAddress)

Returns PostalAddress.

Permissions Information

 

Permissions Required to Call Method

UPDATE_ACCOUNT

Extended Permissions

 

Implied Permissions

READ_ACCOUNT

Activity requirement

FRIENDLY

New address was added to account userId.


Check ksaAccountExists(userId)
Add the address to the account. If the PostalAddress.kimAddressType already exists, overwrite that name, otherwise add it as a new address. If there is no default address, set the default flag on this address. If the isDefault flag is set, then make this the default address.
Update AuditableEntity fields (editorId, lastUpdate).
Note that if there is an address stored, then one of them has to be the default address, so even if an address is passed with isDefault=false, if there is no other default address, this entry must become the default address.

addElectronicContact (String userId, ElectronicContact electronicContact)

Returns ElectronicContact.

Permissions Information

 

Permissions Required to Call Method

UPDATE_ACCOUNT

Extended Permissions

 

Implied Permissions

READ_ACCOUNT

Activity requirement

FRIENDLY

 

Name was added to account userId.


Check doesKsaAccountExist(accountIdentifier)
Add the contact to the account. If the ElectronicContact.kimEmailAddressType/ kimPhoneNumberType already exists, overwrite that field, otherwise add it as a new ElectronicContact. If there is no default contact, set the default flag on this one. If the isDefault flag is set in the passed contact, then make this the default one.
Update AuditableEntity fields (editorId, lastUpdate).

findAccountsByNamePattern (String namePattern)

Returns List <Account>

Permissions Information

 

Permissions Required to Call Method

READ_ACCOUNT

Extended Permissions

 

Implied Permissions

 

Activity requirement

ACCESS

Account userId was accessed. (list)


Return a list of accounts matching the name pattern passed.

getFullAccounts ()

Returns List <Account>

Permissions Information

 

Permissions Required to Call Method

READ_ACCOUNT

Extended Permissions

 

Implied Permissions

 

Activity requirement

ACCESS

Account userId was accessed. (list)


Gets all KSA accounts and their associations.

getAccountProtectedInfo (String userId)

Returns AccountProtectedInfo

Permissions Information

 

Permissions Required to Call Method

GET _PROTECTED_INFORMATION

Extended Permissions

 

Implied Permissions

 

Activity requirement

ACCESS

Account Protected Information was accessed for userId.


For a given user id, get the AccountProtectedInformation block associated with it, and log the activity.

Guest Account Services (Special Cases)

permitGuestAccess (accountToAccess, accountToGrant)

Check that the logged in account is the accountToAccess, and that the accountToGrant exists. Add the accountToAccess, the entity ID of the user and the current date/time to the accountPermission array of the account referenced in accountToGrant.

Activity Service [ActivityService]

Abstract Service Responsibility

The Activity Service controls the recording of activity in the system. There are two major type of recorded activity within KSA. One is done at the hibernate layer, ensuring that all activity in the system can be logged. On top of this, the system may create more "human friendly" activity entries, that make it clearer what is happening at any specific point in the log. These entries are created through this service.

getActivity (Long id)

Returns Activity.

Permissions Information

 

Permissions Required to Call Method

READ_ACTIVITY

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Return the activity with the associated id.

getActivities ()

getActivities (String userId)

Returns List <Activity>

Permissions Information

 

Permissions Required to Call Method

READ_ACTIVITY

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Returns a list of all activities.

persistActivity (Activity activity)

Returns Long, the identifier for the activity.

Permissions Information

 

Permissions Required to Call Method

Internal

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Persists the activity in the database.

deleteActivity (Long id)

Returns boolean.
Removes the associated activity in the database, and return true.

createActivity (ActivityType activityType, String logDetail, int level)

Returns Activity

Permissions Information

 

Permissions Required to Call Method

Internal

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Create a new Activity entry, with the ipAddress and creatorId set to the current user/ ip. Set logDetail, level and activityType to items in the parameters.
Persist and return the object.

Currency Service

The currency service is responsible for currency establishment and tracking within the system.

getCurrency (Long id)

getCurrency (String code)

Returns Currency.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Get the currency identified and return it.

getCurrencies()

Returns List <Currency>
Returns list of all currencies in the system.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 

 

persistCurrency (Currency currency)

Returns Long id, identifier for the currency.

Permissions Information

 

Permissions Required to Call Method

Internal. ADMINISTER_CURRENCY

Extended Permissions

 

Implied Permissions

 

Activity requirement

FRIENDLY

UserID created Currency + CODE


Persists the passed currency in the database, and return its identifier.

deleteCurrency (Long id)

Returns Boolean.
Remove the currency identified, and return true.

Permissions Information

 

Permissions Required to Call Method

ADMINISTER_CURRENCY

Extended Permissions

 

Implied Permissions

 

Activity requirement

FRIENDLY

UserID removed currency + CODE.

 

General Ledger Service [GeneralLedgerService]

Abstract Service Responsibility

The general ledger service is responsible for all aspects of exporting transactions to the external general ledger service. By default, we support KFS, but this service is designed to be altered to permit communication with other general ledger solutions. This service takes over once the transaction service has marked a transaction as being "effective" and therefore ready to be sent to the general ledger.

createRecognitionPeriod (String code, String name, String description, Date startDate, Date endDate)

Returns RecognitionPeriod.

Permissions Information

 

Permissions Required to Call Method

ADMINISTER_GL_SETTINGS

Extended Permissions

 

Implied Permissions

 

Activity requirement

FRIENDLY

UserID created GL Recognition period + CODE


Check code is unique in all the recognitionPeriod objects.
Check dateStart is out of the range of other recognition periods, otherwise exception.
If there is a current recognition period with a null dateEnd, change the dateEnd to the day preceding the passed dateStart.
Create new recognitionPeriod object, updating the auditable entity information.
If there is a dateEnd, use it, if not, store as null.
Persist the recognition period.

editRecognitionPeriod (RegognitionPeriod recognitionPeriod, Date newDateStart, Date newDateEnd)

Returns RecognitionPeriod.

Permissions Information

 

Permissions Required to Call Method

ADMINISTER_GL_SETTINGS

Extended Permissions

 

Implied Permissions

 

Activity requirement

FRIENDLY

UserID created GL Recognition period + CODE


Check that altering the dates passed won't cause this recognition period to overlap with another. If dateEnd is null, ensure that no other period is also null. If not, throw exception.
If new period if valid, update auditable entity information, change the recognition period and persist.

getRecognitionPeriod (Date recognitionDate)

Returns RecognitionPeriod.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Using the passed date (which is assumed to be the recognitionDate of a transaction) find the recognition period in which the date falls. If a date falls between a startDate and the end date is null, this is the correct recognition period. Once the correct recognition period is found, lookup the code associated, and return the code. If no recognition period is found, throw an exception.

isGlOverrideValid (List<GlOverride> glOverride)

isGlOverrideValid (List<ManifestGlOverride> glOverride)

Returns Boolean

createGlTransaction(Long transactionIdentifier, String generalLedgerAccount, BigDecimal amount, GlOperationType glOperation, String statement)

createGlTransaction(Long transactionIdentifier, String generalLedgerAccount, BigDecimal amount, GlOperationType glOperation, String statement, Boolean isQueued)

Returns GlTransaction.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Simple add function. Get the next glTransactionIdentifier and take the constructor details and complete the object. Set the glTransactionDate to the current date/time stamp. Set status to Q unless isQueued is passed and is false, in which case, set status to W(aiting). Set transmission to null.
Using the recognitionDate of the KSA transaction, call getRecognitionPeriod() and store as recognitionPeriod.

getGeneralLedgerType (String glTypeCode)

Returns GeneralLedgerType

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 

getDefaultGeneralLedgerMode ()

Returns GeneralLedgerMode.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 

getDefaultGeneralLedgerType ()

Returns GeneralLedgeType.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 

isGlAccountValid (String glAccount)

Returns Boolean.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Check general.ledger.account.validation is "on". If not, return true.
Get the generalLedgerAllowableAccount object, and compare the account number glAccount to the generalLedgerAccountMask [], interpret each String as a regular expression. If a match is found, return true, otherwise return false.

searchForGeneralLedgerAccounts (String generalLedgerAccount)

Returns List <TransactionType>.
Returns a list of transactionType where the generalLedgerAccount exists in the generalLedgerBreakdown

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 

createGeneralLedgerType (String code, String name, String description, String generalLedgerAssetAccount, GlOperation glOperationOnCharge)

Returns GeneralLedgerType.

Permissions Information

 

Permissions Required to Call Method

ADMINISTER_GL_SETTINGS

Extended Permissions

 

Implied Permissions

 

Activity requirement

FRIENDLY

UserID created GL Type + code


Check that no generalLedgerType with the same code exists, otherwise thrown an exception.
Call isGeneralLedgerAccountValid () on the account. If this fails, throw an exception.
Create a new GeneralLedgerType object with the parameters passed.
Set creatorId to the current user, and creationDate to the current date/time.

persistGeneralLedgerType (GeneralLedgerType generalLedgerType)

Returns GeneralLedgerType

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Check no other generalLedgerType with the same code exists.
Do isGlAccountValid on the assetAccount.
Ensure operationOnCharge is CREDIT or DEBIT.
If any of these fail, throw exception.
If creatorId is null, set to current user, and set creationDate to current date/time
Otherwise, set editorId to current user and set lastUpdate to current date/time.
Persist the object.

summarizeGeneralLedgerTransactions (list<GlTransaction> glTransactions)

Returns void.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


generateGeneralLedgerReport (dateFrom, dateTo, isTransmitted)

generateGeneralLedgerReport (dateFrom, dateTo, isTransmitted, generalLedgerAccount)

Prepares a reconciliation report for KSA transactions to the general ledger. The schema for this report can be found in the consolidated schemata document.

Permissions Information

 

Permissions Required to Call Method

READ_GL_REPORT.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 



createGlTransmission(List<GlTransaction>)

Returns List<GlTransaction>

Permissions Information

 

Permissions Required to Call Method

Internally Called from exportTransactions()

Extended Permissions

 

Implied Permissions

 

Activity requirement

 



importGeneralLedgerAllowableAccount (String xmlImport)

Returns GeneralLedgerAllowableAccount

Permissions Information

 

Permissions Required to Call Method

ADMINISTER_GL_SETTINGS

Extended Permissions

 

Implied Permissions

 

Activity requirement

FRIENDLY

UserID imported new allowable GL accounts.


Validate the xmlImport against the <allowable-gl-account-batch> schema. If fails, throw exception.
If attribute of the batch <replace> is true, then remove all existing items in the GeneralLedgerAllowableAccount.allowableAccountMask [] array. Otherwise, if false, leave the list as it already is.
Iterate through the <allowable-gl-account-mask> nodes. Check that the account/ regex doesn't already exist in the array, and then add to the array.
Return the generalLedgerAllowableAccount object.

createGlBaselineAmounts(String batchId)

Return List <GlBaseline>

Permissions Information

 

Permissions Required to Call Method

PREPARE_GL_TRANSMISSION.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


getGlBaselineAmounts (String batchId)

Return List <GlBaseline>
For the given batchId, find the GeneralLedgerBaseline with the same glBatchIdentifer as the one passed in the parameters, and return the map stored in baselineAmount. If not found, return an empty map.

General Ledger Transmission Service – Part of General Ledger Service

[TransactionExportService]
These methods are implementation specific, and will need to be modified depending on the GL numbering system used by the school, as well as the general ledger in use. By default, KSA can produce KFS transactions. These reference processes show how the information from KSA is used to produce a list of XML transactions to be sent to KFS at the University of Maryland, College Park.

exportTransactions ()

exportTransactionsForDates(Date startDate, Date eendDate, Boolean isEffectiveDate)

exportTransactionsByRecognitionPeriod (String… glRecognitionPeriod)

Return String

Permissions Information

 

Permissions Required to Call Method

EXPORT_GL_TRANSMISSION.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Generic service designed to be overridden at the institution.
For the purpose of the proof of concept that will operate with Maryland's system -> KFS as a file upload:
Get the list of GlTransactions that match the parameters passed. If isEffectiveDate is true, filter by effectiveDate, otherwise filter by recognitionDate. If recognitionPeriod(s) is/are passed, filter the transactions by those.
Call createGlTransmission() with the list we just created.
Get the next General Ledger Batch number
Get all the GeneralLedgerTransmission objects with status of Q(ueued), and pass to
generateGlTransmission() passing the list and the batch number just gained.
If the export was for all transactions (nothing was passed in the parameters)
Call createGlBaselineAmounts() passing the current general ledger batch identifer to get the current status of KSA accounts.
Store this map in a new GeneralLedgerBatchBaseline object, storing the batch Id and the returned Map.
Return the completed XML file.

parseGeneralLedgerAccountNumber (generalLedgerAccount)

Return List<String>

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


generateGeneralLedgerTransmission (list <GeneralLedgerTransmission>, batch)

Return String.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


generateGeneralLedgerTransmissionHeader(batch)

Return String

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


generateGeneralLedgerTransmissionTransaction (generalLedgerTransmission, batch)

Return String

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 



generateGeneralLedgerTransmissionTrailer (List <GeneralLedgerTransaction>, batch)

Return String

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 



Information Service [InformationService]

Abstract Service Responsibility

Information service is responsible the storage of information that relates to an account. It is closely linked to the account service. At this time, the types of information that the service is responsible for is Flags, Memos and Alerts.

Memos

getMemo (Long id)

Returns Memo.

Permissions Information

 

Permissions Required to Call Method

READ_MEMO.

Extended Permissions

The memo's InformationAccessLevel.readPermission

Implied Permissions

 

Activity requirement

 


Returns the Memo referenced by ID.

getMemos ()

getMemos (Long transactionId)

getMemos (String userId)

Returns List <Memo>

Permissions Information

 

Permissions Required to Call Method

READ_MEMO.

Extended Permissions

The memo's InformationAccessLevel.readPermission

Implied Permissions

 

Activity requirement

 


Returns the Memos, filtered by parameter.

getDefaultMemoLevel()

Returns Integer.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 

 

createNewMemo (String userId, String memo, Long accessLevel, Date effectiveDate, Date expirationDate, Long previousMemoId)

createNewMemo (Long transactionId, String memo, Long accessLevel, Date effectiveDate, Date expirationDate)

Returns Memo.

Permissions Information

 

Permissions Required to Call Method

CREATE_MEMO.

Extended Permissions

AccessLevel's createPermission

Implied Permissions

 

Activity requirement

 


Instantiates a new memo on the system. Optionally a transactionId can be referenced in the memo. If there is no expirationDate of the memo, then this should be set to null. If effectiveDate is null, use current date.
If previousMemoId is passed, point created memo to previous memo, and point previous memo to new memo.

editMemo (Long memoId, Memo newMemo)

Certain users are empowered to edit a memo. Using this service, the original memo text can be replaced. The editorId and lastUpdate attributes will be set during the process.
Return Memo

Permissions Information

 

Permissions Required to Call Method

EDIT_MEMO.

Extended Permissions

EDIT_MEMO_TEXT, the Memo's accessLevel.editPermission

Implied Permissions

READ_MEMO

Activity requirement

Friendly

UserId altered memo on +accountId account.

 

Flags

getFlags()

getFlags (String userId)

Returns List <Flag>
Return a list of flags/ flags by user.

createNewFlag (Long transactionId, Long flagTypeId, Integer accessLevel, Integer severity, Date effectiveDate, Date expirationDate)

createNewFlag (Integer transactionId, Long flagTypeId, Integer accessLevel, Integer severity, Date effectiveDate, Date expirationDate)

Returns Flag.
Instantiates a new flag (not FlagType) on the system. Severity must be greater than 0.

changeFlagSeverity (Flag flag, Integer newSeverity)

Returns Flag.
Certain users can change other people's flag's severity. A user can change their own flag's severity. A change will cause an update to editorId and lastUpdate. Flag severity must be greater than 0.

isFlagActive (Flag flag)

Returns Boolean.
If the flag is currently active, return true, otherwise return false.

Flag Types

persistFlagType (FlagType flagType)

Returns Integer id.
Creates a new entity if it didn't already exist (id is null) otherwise updates the old flagtype.

getFlagType (String code, String name, String namePattern)

Returns List<FlagType>.
Finds all FlagType that match all the passed parameters. Parameters can be null.

Alerts

getAlerts()

getAlerts(String userId)

Returns List <Alert>.
Returns all alerts/ alerts for a user.

Permissions Information

 

Permissions Required to Call Method

READ_ALERT.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 

createAlert(Long transactionId, String alertText, Integer accessLevel, Date effectiveDate, Date expirationDate)

createAlert(String userId, String alertText, Integer accessLevel, Date effectiveDate, Date expirationDate)

Returns Alert.

Permissions Information

 

Permissions Required to Call Method

CREATE+ALERT.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Instantiates a new alert on the system. Optionally a transactionId can be referenced in the alert. If there is no expirationDate of the alert, then this should be set to null. If there is no level set in the constructor, then the level defaults to 1.

editAlert (Alert alert, String newAlertText)

Returns Alert.
Changes the text for the alert, if permitted. A change will cause an update to editorId and lastUpdate.

Permissions Information

 

Permissions Required to Call Method

EDIT_ALERT.

Extended Permissions

EDIT_ALERT_TEXT

Implied Permissions

 

Activity requirement

 

 

General

isEffective (Information information)

Returns Boolean.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Checks to see if the information is after the effectiveDate and before the expiredDate. If so, return TRUE.

changeLevel (Information information, Integer newLevel)

Returns Information.

Permissions Information

 

Permissions Required to Call Method

EDIT_(MEMO||ALERT)

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Certain users will be permitted to change the level of a piece of information. Any user can set the level to their own level or below. A change will cause an update to editorId and lastUpdate.

expire()

Returns void.

Permissions Information

 

Permissions Required to Call Method

EDIT_(MEMO||ALERT).

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Pieces of information can be expired, which means that they are no longer "effective". Generally a piece of information is only displayed to a user if it is not expired. When flags are used in rules, only those that are effective are interpreted to be valid. Generally, only certain users can expire a piece of information but a user can expire a piece of information they themselves have added. A change will cause an update to editorId and lastUpdate.

linkToTransaction (Information information, Transacation transaction)

Returns Information.

Permissions Information

 

Permissions Required to Call Method

CREATE_(MEMO||ALERT).

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Link the transaction to the piece of information by saving it in the transaction attribute. This will overwrite any previous link if it was there.

setNewEffectiveDate (Information information, Date newEffectiveDate)

setNewExpirationDate (Information information, Date newExpirationDate)

Returns Information.

Permissions Information

 

Permissions Required to Call Method

EDIT_(MEMO||ALERT).

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Check to see that the new date is valid (information cannot expire before it is effective) and then alter the appropriate attribute.

getInformation (Long id)

Returns Information.
Returns the information referenced by ID.

getInformations()

getInformations(String userId)

Returns List <Information>
Return a list of Information objects, filtered by userId if passed.

persistInformation (Information information)

Returns Long id of information.
Persists the information in the database.

deleteInformation (long id)

Returns Boolean.
Delete the information in the database referenced by ID. If not found, return false.

Language Service [LanguageService]

persistLanguage(Language language)

Returns Integer id.
Saves or updates the passed language.

deleteLanguage (Long id)

Returns Boolean.
If the language exists, remove from database.

getLanguage (Long id)

Returns Language.

getLanguage (String locale)

Returns Language.
Returns language for the locale string.

getLanguages ()

Returns List <Language>

Localization Service

The localization service is used to import XLIFF files into the InstalledLanguage and UserInterfaceString objects to permit localization of the language of the user interface for KSA.

importResources (String content, importType [Full, FullNoOverride, NewOnly])

Returns List<LocalizedString>

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


ImportType can be set to Full (all target strings are imported no matter what), FullNoOverride, where all target strings, except for those with the isOverriden flag are imported, or NewOnly, where only target strings that have not already been imported are brought into the system. This allows the importation of a new language pack, without destroying customizations made by the institution.

getLocalizedStrings (String locale)

Returns List <LocalizedString>

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Returns all localized strings for the given locale.

Transaction Import Service [TransactionImportService]

processTransactions (String xml)

This process is designed to process an XML file of transactions, per the standard schema. It should be recognized that this will be a standard process for many forms of transaction import from external systems. This process system prepares the file to be run through the produceTransactions() service, which will actually create the transactions. This double-stepped process is required to permit schools to have a policy of fail-one-fail-all, or fail individual transactions. It will also be possible in future iterations, for the transmitting system to decide on the failure tolerance of the transactions, subject to system-wide configuration parameters.
If the sending system includes the batch-check node, the system will calculate the total number of transactions and value of all transactions (taken as a literal. Negative transactions will negate, positive transactions will accrue, regardless of charge or payment status). If the batch totals do not match, the system will reject the batch en masse.

Permissions Information

 

Permissions Required to Call Method

IMPORT_TRANSACTIONS.

Extended Permissions

CREATE_CHARGE, CREATE_PAYMENT, CREATE_DEFERMENT

Implied Permissions

 

Activity requirement

FRIENDLY

Batch <batch id> of transacions was uploaded.



 

Allowable Fields Logic

For each of the types, the fields below are allowed. If they exist for another type, then the transaction is invalid. For example, if a charge carries a refund rule, the transaction is invalid.

Credit Types (payments)

Debit Types (charges)

Deferments only – Note that Deferments take a Payment TT.

<override-refund-rule>

<general-leger-override>

<expiration-date>

<override-clear-date>

 

 

<override-clear-period>

 

 

<is-refundable>

 

 

 

 

 

 

produceTransactions(validatedInputFile)

Logic is now internal to processTransactions()

Transaction Creation Flow (Boxed on previous page)


If <expiration-date> is set, we are creating a Deferment.
If <incoming-identifier> or <expiration-date> is set, call: (If either are null, pass null)
createTransaction(<transaction-type>, <incoming-identifier>, <account-idenifier>, <effective-date>, <expiration-date>, <amount>)
Else
createTransaction(<transaction-type>, <account-idenifier>, <effective-date>, <amount>)
This will return the transaction identifier, which should be stored in the reply XML document for this transaction. You can now also get the ledgerDate to be stored as <accepted-date>
If <origination-date> is set,
setOriginationDate (transactionId, <origination-date>)
If <recognition-date> is set
Set recognitionDate to this value
ELSE
Set recognitionPeriod to effectiveDate
If <native-amount>&&<currency> are set,
setForeignTransaction (transactionId, <currency>, <native-amount>)
Else
setForeignTransaction (transactionId, DEFAULT_SYSTEM_CURRENCY, <amount>)
If <document> exists (this will likely become non-optional)
setDocument (transactionId, <document>)
If <override> <is-refundable> is set to true,
setIsRefundable (transactionId, True)
If <override> <is-refundable> is set to false,
setIsRefundable (transactionId, False)
If <override> <refund-rule> is set,
setRefundRule (transactionId, <refund-rule>)
If <override><override-rollup> is set,
setRollup (transactionId, <rollup>) Not that the XML document field matches on the xmlName attribute.
If <override><override-statement-text> is set,
setStatementText (transactionId, <override><override-statement-text>)
If <override><override-clear-date> is set,
setClearDate ( transactionId, <clear-date>)
If <override><override-clear-period> is set,
setClearDate ( transactionId, current date+ <clear-period>)
If <override><general-ledger-type> is set,
Set the generalLedgerType of the transaction to <general-ledger-type>
ELSE
Default to general.ledger.type
If <override><general-ledger-override> is set,
Set the GL override to the account numbers and breakdowns as passed.
Set isGlOverride = True

Transaction Service [TransactionService]

Abstract Service Responsibility

The transaction service is a heavy service that is responsible for many aspects of the creation and the actions of transactions. The transaction is at the heart of KSA, which is why this is such a heavy service. The transaction service encompasses transactions and transaction types. Many transactional interactions are handled within the transaction service.

makeEffective (Long transactionId, Boolean forceEffective)

Returns void.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Moving a transaction from a pre-effective state to an effective state. Once a transaction is effective, its general ledger entries are created. In certain cases, a transaction might be moved to an effective state before its effective date, in which case, forceEffective is passed as true.

Icon

General Ledger Breakdown

Where schools divide single transactions over multiple general ledger accounts, these will be listed in this table, with BREAKDOWN amounts to spread the payment. In this case, percentages can be allocated, and there will be one "bucket" account, which receives the remainder of the funds. This prevents problems with fractional currency being unallocated or over allocated or under allocated. For example, a transaction that divides into two general ledger accounts as a 50/50 split would be defined as:
ACCOUNT 1 – 50%
ACCOUNT 2 – 0 (Bucket account)

Therefore a $100 transaction would divide as:
50% of $100 = $50. ACCOUNT 1 received $50.00
ACCOUNT 2 gets the remainder, therefore $100-$50 = $50 to account 2.

For a $99.99 transaction
50% of $99.99 = $49.995. With a rounding down, ACCOUNT 1 would be credited $49.99
ACCOUNT 2 would be credited with $99.99-$49.99 = $50.00

 


makeAllTransactionsEffective(Boolean forceEffective)

Return void

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Select all transactions where isGlEntryGenerated = False, [ and if forceEffective = false, where effectiveDate is today or earlier.]
If needed, batch these transactions into smaller groups (<50) and loop.
Pass the IDs to makeEffective() passing forceEffective as in the parameters.
For each transaction that throws an exception, record the transactionId, the current dateTime and the exception text into a new glFailed object and persist.

getFailedGlTransactions()

getFailedGlTransactions(String accountId)

getFailedGlTransactions(Date startDate, Date endDate)

Returns List<GlFailed>

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Get all GlFailed objects where the most recent version of the transactionId shows isFixed = false.

makeFailedGlTransactionEffective(GlFailed glFailed)

Return void

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 

Get the transaction id from the glFailed object, and do makeEffective(). forceEffective should be true. If it works, mark the GlFailed object as isFixed = true.
If it fails, add a new failed object, per makeAllTranasctionsEffective()

makeFailedTransactionsEffective()

Returns void

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Get each GlFailed object where the referenced transaction is isGlEntryGenerated = false, and attempt to do makeEffective() on the transactionId. forceEffective should be true.
If it works, mark GlFailed object as isFixed = true.
If it fails, add a new failed object, per makeAllTranasctionsEffective()

createAllocation (Long transaction1, Long transaction2, BigDecimal amount)

createAllocation (Long transaction1, Long transaction2, BigDecimal amount, Boolean isQueued)

Returns CompositeAllocation.

Permissions Information

 

Permissions Required to Call Method

CREATE_ALLOCATION.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 



createLockedAllocation (Long transaction1, Long transaction2, BigDecimal amount)

createLockedAllocation (Long transaction1, Long transaction2, BigDecimal amount, Boolean isQueued)

createLockedAllocation (Long transaction1, Long transaction2, BigDecimal amount, Boolean isQueued, Boolean isInternallyLocked)

Returns CompositeAllocation.

Permissions Information

 

Permissions Required to Call Method

CREATE_LOCKED_ALLOCATION.

Extended Permissions

CREATE_INTERNALLY_LOCKED_ALLOCATION

Implied Permissions

 

Activity requirement

 


removeAllocation (Long transactionId1, Long transactionId2)

removeAllocation (Long transactionId1, Long transactionId2, Boolean isQueued)

Returns List <GlTransaction>

Permissions Information

 

Permissions Required to Call Method

REMOVE_ALLOCATION.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 



removeLockedAllocation (Long transactionId1, Long transactionId2)

removeLockedAllocation (Long transactionId1, Long transactionId2, Boolean isQueued)

removeLockedAllocation (Long transactionId1, Long transactionId2, Boolean isQueued, Boolean isInternallyLocked)

Returns List <GlTransaction>

Permissions Information

 

Permissions Required to Call Method

REMOVE_LOCKED_ALLOCATION.

Extended Permissions

REMOVE_INTERNALLY_LOCKED_ALLOCATION

Implied Permissions

 

Activity requirement

 


removeAllocations (Long transactionId)

removeAllAllocations (Long transactionId, isQueued)

Returns List <GlTransaction>

Permissions Information

 

Permissions Required to Call Method

 

Extended Permissions

 

Implied Permissions

REMOVE_ALLOCATION, REMOVE_LOCKED_ALLOCATION, REMOVE_INTERNALLY_LOCKED_ALLOCATION

Activity requirement

 


This method would most often be used when a payment has "bounced" and needs to be reversed off the account. A search is made of all allocations made against the transaction, and then those allocations are reversed. It is expected that the transaction referenced would then be reversed before a new payment application is applied to the account which would reallocate it. Pass isQueued to each change in allocation, if passed.
removeAllocations() will remove all unlocked allocations.
removeAllAllocations() will remove all allocations, locked and unlocked, including those that are if the user has the appropriate permissions.
Return a list of all general ledger transactions created.

reverseAllocations(Long transactionId, BigDecimal requiredBalance)

Returns Set<AllocationReversalType>
This method is used to progressively undo allocations on a transaction to try to find an unallocated balance.
The system will return a list of values. (these are stored as the Enum AllocationReversalType.

Return Value

Meaning

UNALLOCATED

The system only had to reverse unlocked allocations. (Payment Application allocations).

LOCKED_ALLOCATED

The system had to reverse manual locked allocations.

MANUAL_REVERSAL

The system had to reverse a manual reversal transactions.

INTERNALLY_LOCKED_ALLOCATION

The system had reverse administratively locked allocations.

INTERNALLY_LOCKED_MANUAL_REVERSAL

The system had to reverse a manual reversal transaction that had been administratively locked.


getUnallocatedAmount (Transaction transaction)

Returns BigDecimal.

Permissions Information

 

Permissions Required to Call Method

READ_BALANCE.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Get the amount of the transaction, and subtract allocatedAmount and lockedAllocationAmount. Return this value.

expireDeferment(Long transactionId)

Returns void.

Permissions Information

 

Permissions Required to Call Method

EXPIRE_DEFERMENT

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


canPay (Long transaction1, Long transaction2)

canPay (Long transaction1, Long transaction2, int priority)

canPay(Long transaction1, Long transaction2, int priorityFrom, int priorityTo)

Returns Boolean.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Check both transactions are on the same account. If not, return false.
Check the transactions are compatible:

One of the transactions is…

And the other transaction is…

Credit with positive amount

Debit with positive amount

Credit with positive amount

Credit with negative amount (payment reversal)

Debit with positive amount

Debit with negative amount (charge reversal)


If not, return false.
If the two transactions are charges, then return true.
If the two transactions are payments / deferments then return true.
If one transaction is a payment or a deferment, and the other is a charge, look into its creditType.creditPermission[]
Use standard regex matching between the members of the creditPermission[] to see if any of them match against the debitType of the Charge. If a priority is passed, only those types that match the priority or range or priorities will be checked.
If there is a match, return true, otherwise return false.

createTransaction (String transactionTypeId, String account, Date effectiveDate, BigDecimal amount)

createTransaction (String transactionTypeId, String externalId, String account, Date effectiveDate, Date expirationDate, BigDecimal amount)

createTransaction (String transactionTypeId, String externalId, String account, Date effectiveDate, Date expirationDate, BigDecimal amount, Boolean overrideBlocks)


Returns Transaction.

Permissions Information

 

Permissions Required to Call Method

CREATE_PAYMENT, CREATE_CHARGE, CREATE_DEFERMENT

Extended Permissions

 

Implied Permissions

 

Activity requirement

FRIENDLY

Transaction of type <transactionTypeId> was created in the amount of <amount>


Note that the transaction type will indicate if this is a payment or a charge. If a payment is passed with an expirationDate, then it will be treated as a deferment. If a charge is passed with an expiration date, then an exception will be thrown.
Note that deferments, unlike payments and charges, cannot be negative.

getTransactionType (Long transactionTypeId)

getTransactionType (Long transactionTypeId, Date effectiveDate)

Returns TransactionType.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Gets transaction type using the identifier.

getTransactionTypeClass (transactionTypeId)

Returns TransactionType

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


For a given transactionType, return CreditType.class, DebitType.class or null (no match found).

persistTransaction (Transaction transaction)

Returns Transaction.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Persist the transaction. If the transaction is a payment, with a tag of cash.tracking.tag, call the checkCashLimit() method.

getDaysBeforeDueDate()

Returns int.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Returns the number of days between now and the due date (effectiveDate) of the transaction.
This method is not available as a service, it must be called via the processTransactions() method to ensure that the transactions have all been checked before starting to add them to the KSA ledger.

isTransactionAllowed(String accountId, String transactionTypeId, BigDecimal amount)

isTransactionAllowed (String accountId, String transactionType, BigDecimal amount, BigDecimal overrideCurrentBalance)

[Notes, other factors are:
effectiveDate
current user (permission to override)]
Returns Boolean.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Returns a list of reasons the transaction would fail, or no list if the transaction would work. This validation is performed in RULES.
This performs any number of checks, but is expected to cover blocks and credit limit checks.
Using the rules-based block evaluation, (see getAccountBlockedStatus) evaluate if a transaction is allowed to be posted to an account. An initial check for the existence of the account and the transaction type (if passed) is first performed.
This allows the following types of scenarios. This list serves as examples. Schools may have simpler or more complex blocking rules as defined in their own policies. Blocks are defined as AccountBlock objects.

  • Account may be blocked to all transactions.
  • Account may be blocked to new charges, but not payments.
  • Account may be blocked to all new charges, except for tuition.
  • Account may allow all charges, but this transaction may fail as it takes the account over a credit limit.
  • Account may allow all payments except for checks, due to the student passing a number of bad checks in the past.

If null is passed in transactionType and amount, only the account block(s) is/are returned, if there is one. (i.e. only those blocks that apply to all transactions in all cases.)
If an overrideCurrentBalance is passed, then this value is used during the credit limit check, rather than the actual current balance of the account. This permits pre-flighting of transactions even before transactions are created.
This method returns any AccountBlock objects that block the transaction, or in the case of no problems, a null response.

clearExpiredDeferments (String accountId)

Returns void.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Check the expiration dates of all deferments on the account. If the date has passed, then call the expireDeferment method on each deferment.

writeOffTransaction (Long transactionId, Long transactionTypeId, String memoText, String statementPrefix)

Return Transaction

Permissions Information

 

Permissions Required to Call Method

WRITE_OFF_TRANSACTION

Extended Permissions

 

Implied Permissions

CREATE_PAYMENT, CREATE_CHARGE, {CREATE_LOCKED_ALLOCATION, CREATE_INTERNALLY_LOCKED_ALLOCATION}

Activity requirement

FRIENDLY

Transaction <transactionId> was written off.

 

LOGMEMO

<memoText>


The logic of this is very similar to reverseTransaction(), except a partial write off is allowed, and only credits can be written off. Also, the institution can choose to write off charges to a different general ledger account, instead of the original, permitting the writing off to a general "bad debt" account, if they so choose. If parameter is not passed, then the write off will negate the original general ledger accounts that the transaction credited. These general ledger entries will be created during the standard makeEffective() run.

cancelCharge (Long transactionId, String memoText)

Returns void.

Permissions Information

 

Permissions Required to Call Method

CANCEL_TRANSACTION

Extended Permissions

 

Implied Permissions

CREATE_PAYMENT, CREATE_CHARGE, {CREATE_LOCKED_ALLOCATION, CREATE_INTERNALLY_LOCKED_ALLOCATION}

Activity requirement

FRIENDLY

Transaction <transactionId> was cancelled.

 

LOGMEMO

<memoText>


Check the transactionId refers to a charge, otherwise throw exception.
Check the status of the transaction is ACTIVE, otherwise throw exception.
Check the allocations of the transaction. If any of the allocated tranasctions has a status of CancelledOffset, then throw exception (you can't double-cancel a transaction).
Clear any unlocked allocations against the base transaction.
Call getCancellationAmount() on the transaction.
Check the unallocated balance on the base transaction is => the cancellationAmount, otherwise throw exception.
Call reverseTransaction() passing the transaction and the result from getCancellationAmount().
Set the status of the offset transaction from reverseTransaction() to status of CANCELLING.

bouncePayment (Long transactionId, String memoText)

Returns void.

Permissions Information

 

Permissions Required to Call Method

BOUNCE_TRANSACTION

Extended Permissions

 

Implied Permissions

CREATE_PAYMENT, CREATE_CHARGE, {CREATE_LOCKED_ALLOCATION, CREATE_INTERNALLY_LOCKED_ALLOCATION}

Activity requirement

FRIENDLY

Transaction <transactionId> was cancelled.

 

LOGMEMO

<memoText>


Check status of transaction is Active. {Realistically, a bounced transaction is an entire reversal}
Check transaction is a payment, otherwise throw exception.
Clear all unlocked allocations against this transaction. All allocations should be able to be cleared. If not, throw exception.
Reverse the transaction using reverseTransaction()
Set the offset transaction to BOUNCING.
System then calls a business rule to decide if a charge is to be made for the bounced transaction. Business rule is responsible for assessing the charge, should one be necessary. This logic can also set any flags as needed, such as a "Bad Check" flag, etc.

discountCharge(Long transactionId, String transactionTypeId, String memoText, BigDecimal amount, String statementPrefix)

Returns Long

Permissions Information

 

Permissions Required to Call Method

DISCOUNT_TRANSACTION

Extended Permissions

 

Implied Permissions

CREATE_PAYMENT, CREATE_CHARGE, {CREATE_LOCKED_ALLOCATION, CREATE_INTERNALLY_LOCKED_ALLOCATION}

Activity requirement

FRIENDLY

Transaction <transactionId> was discounted.

 

LOGMEMO

<memoText>


Check that the passed transaction is a charge.
Attempt to do a reverseTransaction() against the charge, passing the amount, memo, statement prefix, and the transaction type from the parameters.
If the reversal is successful, change the status of the returned transaction to DISCOUNTING.
Return the offset transaction to the caller.

transactionExists (String userId, String transactionTypeId)

transactionExists (String userId, String transactionTypeId, Date dateFrom, Date dateTo)

transactionExists (String userId, String transactionTypeId, BigDecimal amountFrom, BigDecimal amountTo)

transactionExists (String userId, String transactionTypeId, Date dateFrom, Date dateTo, BigDecimal amountFrom, BigDecimal amountTo)

Returns Boolean.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 

 

 


These methods are provided to assist the fee management service decided if it needs to reassess a certain fee.
Allows the fee management rules locate a transaction that already exists. This returns true if the transaction that meets the criteria of the method is found. Otherwise it returns false. This would be used for example, to check that a prepayment has been made before fees are assessed on a student.
Return true if the transaction indicated exists, otherwise return false.

contestCharge (Charge charge, Date expirationDate, String memoText)

Returns Deferment.

Permissions Information

 

Permissions Required to Call Method

CONTEST_CHARGE

Extended Permissions

 

Implied Permissions

CREATE_DEFERMENT, {CREATE_LOCKED_ALLOCATION, CREATE_INTERNALLY_LOCKED_ALLOCATION}

Activity requirement

FRIENDLY

Transaction <transactionId> was contested.

 

LOGMEMO

<memoText>



findTransactionsByStatementPattern (String pattern)

Returns List<Transaction>

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 

 

 


Returns a list of transactions that match the pattern against the statementText.

getCharge(Long id)

Returns Charge.

Permissions Information

 

Permissions Required to Call Method

READ_TRANSACTION

Extended Permissions

 

Implied Permissions

 

Activity requirement

 

 

 


Returns the charge with the passed identifier.

getCharges()

getCharges(String userId)

Returns List<Charge>

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

READ_TRANSACTION

Activity requirement

 

 

 


Returns a list of all charges/ charges on an account.

getPayment(Long id)

Returns Payment.

Permissions Information

 

Permissions Required to Call Method

READ_TRANSACTION

Extended Permissions

 

Implied Permissions

 

Activity requirement

 

 

 


Returns the payment with the passed identifier.

getPayments()

getPayments(String userId)

Returns List<Payment>

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

READ_TRANSACTION

Activity requirement

 

 

 


Returns a list of all payments/payments on an account.

getDeferment(Long id)

Returns Deferment.

Permissions Information

 

Permissions Required to Call Method

READ_TRANSACTION

Extended Permissions

 

Implied Permissions

 

Activity requirement

 

 

 


Returns the deferment with the passed identifier.

getDeferments()

getDeferments(String userId)

Returns List<Deferment>

Permissions Information

 

Permissions Required to Call Method

Internal

Extended Permissions

 

Implied Permissions

READ_TRANSACTION

Activity requirement

 

 

 


Returns a list of all deferments/ deferments on an account.

getTransaction(Long id)

Returns Transaction.

Permissions Information

 

Permissions Required to Call Method

READ_TRANSACTION

Extended Permissions

 

Implied Permissions

 

Activity requirement

 

 

 


Returns the Transaction with the passed identifier.

getTransactions()

getTransactions(String userId)

Returns List<Transaction>

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

READ_TRANSACTION

Activity requirement

 

 

 


Returns a list of all Transactions/ Transactions on an account.

calculateCancellationRule (String cancellationRule, Date baseDate)

Returns String.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 

 

 


Takes the cancellationRule from the debit transaction type, and, using the baseDate, calculates the appropriate dates to be stored in the actual transaction version of the cancellationRule.

isCancellationRuleValid (String cancellationRule)

Returns Boolean.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 

 

 


Checks to see if the rule being entered is legal.

parseCancellationRule (String cancellationRule)

Returns Map <Date date, Pair<String command, BigDecimal value>>

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 

 

 


Note that we would only parse a cancellation rule once it is part of a transaction and has therefore gone through calculateCancellationRule() which replaces DAYS() with DATE() so we don't need to parse against DAYS().

getCancellationAmount (Charge charge, Date cancellationDate)

Returns BigDecimal.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 

 

 


Using the cancellationRule, calculates the appropriate amount that can be cancelled from a charge.

setGlType (Transaction transaction, GeneralLedgerType generalLedgerType)

Returns Transaction.
Checks that the transaction has not been made effective, otherwise throw exception.
Change glType of transacation to generalLedgerType and persist.

addTagToTranasaction (Long transactionId, Tag tag)

addTagsToTransaction(Long transactionId, List<Tag tag>)

Returns Transaction

Permissions Information

 

Permissions Required to Call Method

ALTER_TAG_TO_TRANSACTION

Extended Permissions

ALTER_ADMIN_TAG_TO_TRANSACTION

Implied Permissions

READ_TRANSACTION,

Activity requirement

 

 

 


Check the Tag can be added by the user (user can add, if isAdministrative, user has permission to add an administrative tag)
Add to the array of Tag on the transaction.
If a list is passed, do for each allowable Tag.

removeTagFromTransaction (Long transactionId, Tag tag)

removeTagsFromTransaction (Long transactionId, List<Tag tag>)

Returns Transaction

Permissions Information

 

Permissions Required to Call Method

ALTER_TAG_TO_TRANSACTION

Extended Permissions

ALTER_ADMIN_TAG_TO_TRANSACTION

Implied Permissions

READ_TRANSACTION,

Activity requirement

 

 

 


Check the Tag can be removed by the user (user can add, if isAdministrative, user has permission to add an administrative tag)
Remove from the array of Tag on the transaction.
If a list is passed, do for each allowable Tag.

setGlBreakdownOverrides(Long transactionId, List<GlBreakdownOverride> glBreakdownOverrides)

Returns void.

Permissions Information

 

Permissions Required to Call Method

SET_GL_BREAKDOWN

Extended Permissions

 

Implied Permissions

 

Activity requirement

 

 

 

reverseTransaction(Long transactionId, String memoText, BigDecimal reversalAmount, String statementPrefix, TransactionStatus reversalStatus)

reverseTransaction(Long transactionId, String memoText, BigDecimal reversalAmount, String statementPrefix, String reversalTransactionType, TransactionStatus reversalStatus)

Return Transaction

Permissions Information

 

Permissions Required to Call Method

REVERSE_TRANSACTION.

Extended Permissions

CREATE_CHARGE, CREATE_PAYMENT, {Creation of internally locked allocation}

Implied Permissions

 

Activity requirement

Friendly

Transaction TransactionID was reversed for reason +memoText.


This is used to "reverse" a transaction, which it does by issuing an identical transaction with a negated amount. A memo is passed to the reverse operation, which is entered into the memo field.
This method underpins all other methods to remove a transaction from an account.
Note that by default, the transaction type of the reversal transaction is the same as the original transaction. Where this is not the desired case (for example, write offs might go to a different transaction type) this can be passed as an optional parameter.
If a reversalStatus is passed, the returned transaction will be of that status. If nothing is passed, then the system will default to returning a "REVERSING" transaction. This option will be ignored if you are reversing anything other than an ACTIVE transaction, which will automatically produce a RECIPROCAL_OFFSET transaction.

Cash Limit Service [CashLimitService]

Generic

The cash limit service is responsible for tracking cash payments coming into the system in order to allow the system to file 8300 forms with the IRS.

checkCashLimit (String accountId)

Returns Boolean.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

CREATE_PAYMENT

Activity requirement

 


This process is triggered when a "cash" payment (tag is equal to cash.tracking.tag) is posted to an account. The system reviews the account for other cash payments, and if applicable, creates an event which can then be verified, and an 8300 produced.
The system is designed to permit collection of information related to the filing of IRS form 8300, however, it can be highly customized to permit the tracking of transactions as required for anti-laundering legislation in other jurisdictions. The amount, time period and types of transactions tracked are all configured by the end user.
This will return true if there has been a cash limit event. A CashLimitExceededEvent object will be created and persisted and an email will be sent to the appropriate administrator to allow them to check up on the event. A further step will be required to actually register the event (by producing an 8300 form to be filed with the IRS).
The method exportCashLimitExceededEvent() will create the XML file that can be used to create an 8300.

createCashLimitParameter(String code, String name, String description, Tag tag, BigDecimal lowerLimit, BigDecimal upperLimit, Boolean isActive, String authorityName, String xmlName)

Return CashLimitParameter

Permissions Information

 

Permissions Required to Call Method

CREATE_CASH_LIMIT_PARAMETER

Extended Permissions

 

Implied Permissions

 

 

FRIENDLY

Created <code> cashLimitParameter.


Check that no cashLimitParameter exists with the same code as the one that is passed.
Check that the Tag passed is an administrative tag.
Check lowerLimit, if passed, is lower than upperLimit, if passed.
Check xmlName is different to any other xmlName in this class.
If all these tests pass, then:
Create object, mapping attributes with same names.
Set auditable entity fields.
Persist, and return object.

persistCashLimitParameter (CashLimitParameter cashLimitParameter)

Return Long

Permissions Information

 

Permissions Required to Call Method

EDIT_CASH_LIMIT_PARAMETER

Extended Permissions

 

Implied Permissions

 

 

FRIENDLY

Edited <code> cashLimitParameter.


Check that the passed object has an ID that already exists for another cashLimitParameter.
Check that the Tag passed is an administrative tag.
Check lowerLimit, if passed, is lower than upperLimit, if passed.
Check xmlName is different to any other xmlName in this class.
If all the tests pass:
Set AuditableEntity information, persist, and return the object.

Transaction Type Service (TransactionService)

Methods relating to the creation of transaction types.

createDebitType (String transactionTypeId, Date startDate, String defaultStatementText, int priority, String name)

Returns DebitType

createCreditType (String transactionTypeId, Date startDate, String defaultStatementText, int priority, String name)

Returns CreditType

Permissions Information

 

Permissions Required to Call Method

CREATE_TRANSACTION_TYPE

Extended Permissions

 

Implied Permissions

 

Activity requirement

FRIENDLY

User has created transaction type <transactionTypeId> for dates <startDate> to <endDate>

 

 



These methods rely on much of the same implementing code (as detailed in the single process flow) but they have different interfaces in order to allow greater flexibility. These methods create a credit or debit type that does not already exist. An attempt to create a credit or debit type with these methods, when the transactionTypeId already exists will cause an exception.

createSubCreditType (String transactionTypeId, startDate)

Returns CreditType

createSubDebitType (String transactionTypeId, startDate)

Returns DebitType

Permissions Information

 

Permissions Required to Call Method

CREATE_TRANSACTION_TYPE

Extended Permissions

 

Implied Permissions

 

Activity requirement

FRIENDLY

User has created transaction type <transactionTypeId> for dates <startDate> to <endDate>

 

 


These methods allow the creation of a new subtype of a credit or debit type. They, like createCreditType() / createDebitType() use a great deal of overlapping code to create the actual type, but they are divided into different interfaces for flexibility and a cleaner API. Only an amalgamated process flow for both is included.
In order to create a sub-type of the credit or debit type, there must already be a credit or debit type with the passed transactionTypeId already created.

createGlBreakdowns (TransactionTypeId transactionTypeId, Long generalLedgerType, List<GeneralLedgerBreakdown>)

Returns DebitType.

Permissions Information

 

Permissions Required to Call Method

CREATE_TRANSACTION_TYPE

Extended Permissions

EDIT_TRANSACTION_TYPE

Implied Permissions

 

Activity requirement

 

 

 



persistTransactionType (transactionType)

Returns TransactionType

Permissions Information

 

Permissions Required to Call Method

CREATE_TRANSACTION_TYPE

Extended Permissions

EDIT_TRANSACTION_TYPE,

Implied Permissions

 

Activity requirement

 

 

 


Check to see if there is an exisiting transaction type with this id. If so, user needs EDIT_TRANSACTION_TYPE permission, otherwise, needs CREATE_TRANSACTION_TYPE permission. In each of the following permissions, if this is an EDIT situation, we must check the edit permission. If this is a create, only check the CREATE permissions. If there is no CREATE permission, then the CREATE_TRANSCTION_TYPE will suffice.

Check for basic validity.

Check that there is a valid start date.
If endDate is set, check that it is after startDate.
Check defaultStatementText is not null.
Check that the date range passed does not overlap another transaction type with the same code.
If this is a credit type, check the clearing period is 0 or greater.

Tags

Ensure the user has the appropriate permissions for the types of tag they are adding to a transaction type (ADD_TAG_TO_TRANSACTION_TYPE, ADD_ADMIN_TAG_TO_TRANSACTION_TYPE)

Priority (Edits only)

If priority has changed, check user has permission EDIT_TRANSACTION_TYPE_PRIORITY

Rollup (Edits only)

If Rollup has changed, check user has permission EDIT_TRANSACTION_TYPE_ROLLUP

General Ledger Breakdown

Call checkGeneralLedgerBreakdown() with the generalLedgerBreakdown.
If this is an edit and the GL Breakdown has changed, check permission EDIT_TRANSACTION_TYPE_GENERAL_LEDGER_BREAKDOWN

Debit Type Checks

If this is a debitType, call isCancellationRuleValid()
If this is an edit, and cancellationRule has changed, check user has permission EDIT_TRANSACTION_TYPE_CANCELLATION_RULE

Credit Type Checks

If this is a creditType, call isRefundRuleValid()
If this is an edit, and refundRule has changed, check user has the permission EDIT_TRANSACTION_TYPE_REFUND_RULE.

Unallocation Checks

If this is a creditType, check that both unallocatedGeneralLedgerAccount and unallocatedGeneralLedgerAccountOperation are not null.
If this is a creditType, call isGlAccountValid() on the unallocatedGeneralLedgerAccount.
If this is an edit, check the user has the permission EDIT_TRANSACTION_TYPE_UNALLOCATED_ACCOUNT.

Credit Permission

If the creditPermission block has changed, and this is an edit, check that the user has the permission EDIT_TRANSACTION_TYPE_CREDIT_PERMISSION.
If any of these checks fail, thrown an exception.
Persist the transaction type, including the updating of the auditable entity information, in the database.

User Preference Service [UserPreferenceService]

The user preference service allows the system to store attributes for each user, allowing fine-grained preference control for each user. In many instances, the UI will allow a student to alter preferences stored here. The details of these preferences are located in the document "System-wide Configuration Settings".
These are simple, but powerful key/pair values. They are called by name. For example, a student may have a preference of how they want to receive their refunds. In this example, this is called refund.method. In certain circumstances, the bursar's office may wish to override the student's preference. To do this, they can set the preference override.refund.method, and this will take precedence over refund.method.
If neither of these values are set, then the system will look to the system-wide options for default.refund.method.
If a school does not want a student to be able to set refund method, then locked.refund.method will be set to true. In this case, default.refund.method will apply no matter what values might be stored in user preferences.

getUserPreferences (String userId)

Returns List<UserPreference>

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 

 

 

getPreference (preferenceName)

getPreference (preferenceName, accountId)

Return String

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 

 

 


setPreference (preferenceName)

setPreference (preferenceName, accountId)
Return String

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 

 

 


Transfer Transaction Sub Service (In progress) [TransactionService]

The transfer transaction service is a set of methods that take care of transferring transactions from one account to another, or, in the case of payment billing, within the account, breaking a group of transactions into payments with different due dates.
Transfer transaction is a method that transfers responsibility for a transaction from one account to another. It does this by issuing a negative transaction on the original account to wipe out its value (and its general ledger effect, if appropriate) which is done via the reverseTransaction() method. Then it creates a new transaction on the new account.
Amount is passed, allowing only part of a transaction to be moved to a new account. For example, a sponsor may agree to pay 80% of a student's tuition charges, therefore only 80% of the tuition charge would be transferred.

transferTransaction (Long transactionId, String transactionTypeId, String accountId, Long transferTypeId, Date effectiveDate, Date recognitionDate, String memoText, String statementPrefix, String transactionTypeMask)

Returns TransactionTransfer.

Permissions Information

 

Permissions Required to Call Method

TRANSFER_TRANSACTION

Extended Permissions

 

Implied Permissions

CREATE_PAYMENT, CREATE_CHARGE

Activity requirement

Friendly

Transaction was transferred from <accountId> to <accountId>

 

 


Note that the general ledger type of the resulting transaction may be changed via to a setting in TransferType.

persistTransactionTransfer (TransactionTransfer transactionTransfer)

Returns TransactionTransfer.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


If the transactionTransfer object has a non-null transaction group, check if any other transactionTransfer objects exist with the same transferGroup, check that the account referenced in sourceTransaction and the account referenced in destinationTransaction match the accounts referenced in this transasctionTransfer's sourceTransaction.account and destinationTransaction.account. If not, throw an exception.
Otherwise, persist the transactionTransfer object.

setTransferGroup (String transferGroupId, List <Long> transferTransacitonIds)

Returns void.
Go through each item in the list of transferTransaction objects, and set the transactionGroup to the string in transferGroup. This should be a UUID, but this is not enforced.

setRollupForTransferGroup (String transferGroupId, Long rollupId)

Returns void.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Iterate through every destinationTransaction of all TransferTransction objects that have groupIdentifier as their transferGroup that are of reversalStatus "N"(ot reversed) Set the rollup of each of the destination transactions to the passed rollup.

reverseTransferTransaction (Long transferTransactionId, String memoText)

reverseTransferTransaction (Long transferTransactionId, String memoText, BigDecimal partialAmount)

Returns TransactionTransfer

Permissions Information

 

Permissions Required to Call Method

REVERSE_TRANSFER_TRANSACTION

Extended Permissions

 

Implied Permissions

 

Activity requirement

FRIENDLY

Transaction transfer was reversed.

 

MEMOLOG

<memoText>

This method can be used to reverse a previously made transaction transfer. This allows the system to dynamically restore the charges and credits to an originating account without the user having to look up those values.

reverseTransferGroup (String transferGroupId, String description, Boolean allowLockedAllocations)

Returns List<TransactionTransfer>

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

REVERSE_TRANSFER_TRANSACTION

Activity requirement

 


createTransferType(String code, String name, String description, String generalLedgerTypeCode)

Returns TransferType

Permissions Information

 

Permissions Required to Call Method

CREATE_TRANSACTION_TRANSFER_TYPE

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Test the generalLedgerTypeCode references an appropriate GeneralLedgerType.
Create a transferType object, and call persist.

persistTransferType(TransferType transferType)

Returns TransferType

Permissions Information

 

Permissions Required to Call Method

CREATE_TRANSACTION_TRANSFER_TYPE/ EDIT_TRANSACTION_TRANSFER_TYPE

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Lookup the id for the transactionTransferType. If there is already one with this ID then we are doing an edit, check the user has the correct permission.
If this ID does not exist, check the code does not exist. If it does, cause an exception.
Check the generalLedgerType is valid.
Update the A/E information and persist.

deleteTransferType(Long transferTypeId)

Returns void.

Permissions Information

 

Permissions Required to Call Method

DELETE_TRANSFER_TRANSACTION_TYPE

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Check the transferType is not used elsewhere. If not, then delete the transferType.

Rate Service [RateService]

Generic

The RateService is an important shared service between KS and KSA. KS attaches rates to offerings, KSA uses those attachements to charge the student the appropriate amounts to the appropriate codes.
Rates may be established either in KSA or KS.
In overview, a Rate (found by its code, plus ATP) has a number of attributes, all of which are limited by the settings of the RateCatalog to which it is attached. Each RateCatalog object (and by extension, each Rate) has a RateType which allows the rules engine to interpret what to do with that specific rate.

createRateType (String code, String name, String description, Boolean isGrouping, RateAmountType rateAmountType)

Returns RateType

Permissions Information

 

Permissions Required to Call Method

CREATE_RATE_TYPE

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Ensure that no other rate type exists with the same code, otherwise throw an exception.
Get the next id, create, and persist, updating auditable entity information.

persistRateType (RateType rateType)

Returns Long

Permissions Information

 

Permissions Required to Call Method

UPDATE_RATE_TYPE

Extended Permissions

 

Implied Permissions

CREATE_RATE_TYPE

Activity requirement

 


Get the existing rateType object referenced by code if it exists, and check the A/E information in the passed object hasn't been altered.
Update A/E information and persist.
Return rateTypeId.

deleteRateType (Long rateTypeId)

Returns void.

Permissions Information

 

Permissions Required to Call Method

DELETE_RATE_TYPE

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Get the rateType object referenced by id. If it does not exist, throw exception.
Check that no rateCatalog objects exist that use this rateType. If they do, throw exception.
Remove rateType from the system.

getRateTypeByCode (String code)

Return RateType

rateTypeExists(String code)

Returns Boolean
If RateType with a given code exists, return true.

getRateTypesByNamePattern (String namePattern)

getAllRateTypes()

Permissions Information

 

Permissions Required to Call Method

READ_RATE_TYPE

Extended Permissions

 

Implied Permissions

 

Activity requirement

 

Return List<Long>
Return a filtered list (by partial name), or a full list of rateTypeId.

createRateCatalog (String rateTypeCode, String rateCatalogCode, List<String> applicableAtp, BigDecimal minAmount, BigDecimal maxAmount, Boolean isTransactionTypeFinal, String defaultTransactionType, Boolean isTransactionDateTypeFinal, DefaultTransactionDateType defaultTransactionDateType, Boolean isKeypairFinal, List<Keypair> keypair, Boolean isRecognitionDateDefinable, Boolean isLimitAmountFinal, Boolean isLimitAmount Int minLimitUnits, Int maxLimitUnits, BigDecimal minLimitAmount, BigDecimal maxLimitAmount)

Returns Long

Permissions Information

 

Permissions Required to Call Method

CREATE_RATE_CATALOG

Extended Permissions

 

Implied Permissions

 

Activity requirement

 

isRateCatalogValid(RateCatalog rateCatalog)

Returns Boolean

validateRateCatalog (RateCatalog rateCatalog)

Returns Void

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


validateRateCatalog() will throw an execption on an error. isRateCatalogValid() calls validateRateCatalog() and will return false if it catches an exception.

persistRateCatalog (RateCatalog newRateCatalog)

Return Long

Permissions Information

 

Permissions Required to Call Method

UPDATE_RATE_CATALOG

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


isRateValid(Rate rate)

isRateValidWithCatalog (RateCatalog rateCatalog, Rate rate)

Returns Boolean

validateRate (Rate rate)

validateRateWithCatalog(RateCatalog rateCatalog, Rate rate)

Returns Void

Permissions Information

 

Permissions Required to Call Method

Internal

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


These methods perform the same checks, however, isRateValid() calls validateRate(). If validateRate() throws an exception, isRateValid() returns a false. validateRate() allows you to to receive an exception with the actual error in the rate.

assignAtpsToRateCatalog(Long rateCatalogId, String … atpIds)

Return RateCatalog

Permissions Information

 

Permissions Required to Call Method

UPDATE_RATE_CATALOG

Extended Permissions

 

Implied Permissions

 

Activity requirement

 

removeAtpFromRateCatalog(Long rateCatalogId, String atpId)

Return Long

Permissions Information

 

Permissions Required to Call Method

UPDATE_RATE_CATALOG

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Check that no Rate objects are depending on this RateCatalog/Atp combination. If they are, throw exception.
Otherwise, remove the ATP from the rateCatalog object and return the Id.

transferAtpsToRateCatalog (Long rateCatalogId, String … atpIds)

Return Long

Permissions Information

 

Permissions Required to Call Method

UPDATE_RATE_CATALOG, UPDATE_RATE

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Get the rateCatalog associated with the Id.
Check that the rateCatalog doesn't already have the ATPs referenced. If so, ignore.
Check that another rateCatalog with the same code has the ATP listed. If not, add the ATP to this rateCatalog and continue.
Add the ATP to the new rateCatalog without persisting, and test any rates that depend on it against the settings in the new rateCatalog. Note that the new ATP(s) will be ADDED to the new RateCatalog. They do not REPLACE the exisiting ones.
If they fail (if the rateCatalog is not consistent with the rate) then throw an exception. (ATP cannot be moved).
If rates are compatible with the new rateCatalog, then move the ATP from the old rate catalog to the new rate catalog.
Return Id of the new rate catalog.

addKeypairToRateCatalog (String key, String value, Long rateCatalogId)

Return RateCatalog

Permissions Information

 

Permissions Required to Call Method

UPDATE_RATE_CATALOG

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Add the keypair object to the RateCatalog.
Add the keypair to each Rate object that depends on this RateCatalog.
Persist RateCatalog and Rate objects.

removeKeypairFromRateCatalog (String key, Long rateCatalogId)

Return RateCatalog

Permissions Information

 

Permissions Required to Call Method

UPDATE_RATE_CATALOG

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Remove the keypairs from the RateCatalog and depenent Rate objects.
Persist, and return the RateCatalog.

deleteRateCatalog (Long rateCatalogId)

Return void.

Permissions Information

 

Permissions Required to Call Method

DELETE_RATE_CATALOG

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Check that no Rate objects have this RateCatalog referenced in them. (Ensure that the validation is done against both the RateCatalog.code plus the appropriate ATP.
If any Rates use this RateCatalog, throw exception.
Otherwise delete the RateCatalog.

getRateCatalogByCodeAndAtpId (String code, String atpId)

Return RateCatalog

getRateCatalogsByCode (String code)

getRateCatalogsByNamePattern (String namePattern)

getRateCatalogsByAtpId(String atpId)

getAllRateCatalogs()

Return List<RateCatalog>

Permissions Information

 

Permissions Required to Call Method

READ_RATE_CATALOG

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Return a filtered list (by partial name), or a full list of RateCatalog objects.

createRate (String rateCode, String subCode, String RateCatalogCode, String applicableAtpId, Date transactionDate, TransactionDateType overrideTransactionDateType, Date recognitionDate, Boolean isLimitAmount, Int minLimitUnits, Int maxLimitUnits, BigDecimal limitAmount, BigDecimal defaultAmount, String transactionTypeId)

Returns Long

Permissions Information

 

Permissions Required to Call Method

CREATE_RATE

Extended Permissions

 

Implied Permissions

 

Activity requirement

 

addRateAmount(Long rateId, List<RateAmount> rateAmount)

Returns Long
Get the Rate and check that the new rateAmounts comply with Rate and RateCatalog.
Ensure the number of units referenced only exists once.
Add the RateAmount linked to flexibleAmount list.
Persist the Rate.

deleteRateAmount (Long rateAmountId)

Returns Void
Ensure that the RateAmount being removed isn't the default amount otherwise throw exception.
Remove and persist the rate.

persistRate (Rate newRate)

Returns Long

Permissions Information

 

Permissions Required to Call Method

UPDATE_RATE

Extended Permissions

 

Implied Permissions

 

Activity requirement

 

deleteRate (Long rateId)

Returns void.

Permissions Information

 

Permissions Required to Call Method

DELETE_RATE

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Warning – KS entities might rely on this rate.
Delete rate.

getRateByCode (String code, String atpId, String subCode)

Return Rate

getRateIdByCode (String code, String atpId, String subCode)

Return Long

getRatesByCode (String code)

getRatesByCodeAndSubcode (String code, String subCode)

getRatesByNamePattern (String partialName)

getRatesByAtpId(String atpId)

getAllRates()

Return List<Rate>

Permissions Information

 

Permissions Required to Call Method

READ_RATE

Extended Permissions

 

Implied Permissions

 

Activity requirement

 

getRateSubCodes(String rateCode, String atpId)

Returns List<String>
Return each distinct subCode on a Rate.

addKeypairToRate (String key, String value, Long rateId)

Return Rate

Permissions Information

 

Permissions Required to Call Method

UPDATE_RATE

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Check that Rate.RateCatalog.isKeypairFinal = false. If not, throw exception.
Add the keypair object to the Rate, adding the creationDate, then persist.

removeKeypairFromRate (String name, Long rateId)

Return Rate

Permissions Information

 

Permissions Required to Call Method

UPDATE_RATE

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Check that Rate.RateCatalog.isKeypairFinal = false. If not, throw exception.
If no value is passed, then remove ALL keypairs with the name in the parameters. If a value is passed, remove only the keypair with that name/value combination.
Persist, and return the Rate.

Fee Management Service [FeeManagementService]

Generic

Fee Management is a highly rule-based process. The basic system works like this:
Enrollment data is received from the registration system.
A new fee management session is created, and the enrollment data is sorted into the Signup section. Each signup will come with Rate objects attached, that provide KSA with the basis of the fees it will charge.
An initial set of rules fire, that processes the signup, taking into account the top level information – i.e. this is an add, a drop, etc. and copying the appropriate rate information into the charge manifest.
From here, a second set of rules fire that process each type of fee. This is institution specific, but in our default case, we'll look at course fees, semester fees, mandatory fees, etc.
Then we'll move to the tutitions.
Then once all the special cases are worked out, the ChargeManifest will be returned to KSA.
KSA will process the charge manifest, placing appropriate charges (via delta) onto the account, and will update the charge manifest.
This can then be passed back to the registration system to provide information to the student.
The high-level process is shown here.

There are three basic paths through the Fee Management Process. These are shown on the next page. A session can be created and queued, or it can be run as a "what if" session, or it can be run against he student's account and the charges can be created. In all cases, a session will be created with the data that arrives from the registration system.

addFeeManagementSessionToQueue(Long feeManagementSessionId)

Return void

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Check status of FeeManagementSession is current, otherwise throw exception. (It is pointless to queue a what if session!)
Create a new QueuedFeeManagementSession object using autogenerated ID, current date/time as creationDate, feeManagementSessionId as passed, and isCompelte as false. Persist.

removeFeeManagementSessionFromQueue (Long feeManagementSessionId)

Return void

Permissions Information

 

Permissions Required to Call Method

DELETE_FM_QUEUE

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Search the QueuedFeeManagementSession objects for one that as the same feeManagementSessionId as passed. If found, remove the object.

assessRealTimeFeeManagement(FeeManagementTermRecord feeManagementTermRecord)

Returns Long (FeeManagementManifest id)

simulateRealTimeFeeManagement(FeeManagementTermRecord feeManagementTermRecord)

Returns FeeManagementReport (As the receiving system will need the report, we will pass back the whole object.)

Permissions Information

 

Permissions Required to Call Method

RUN_FM

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


This method kicks off the workflow for assessing fees by creating a fee management session, passing that session over to the rules, and in the case of a non-simulated session, reconciles and charges the fees to the student account.
Call createFeeManagementSession() passing the feeManagementTermRecord in the parameters.
Call the rules engine (processFeeManagementSession() )to execute the rules against this session.
Take the response from the rules engine, and call reconcileSession()
For assess:
Take the response from reconcileSession() and call chargeSession()
For simulate:
Take the reposone from reconcileSession() and call createFeeManagementReport()

queueFeeManagement(FeeManagementTermRecord feeManagementTermRecord)

Return void

Permissions Information

 

Permissions Required to Call Method

RUN_FM

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


This method kicks off the workflow for assessing fees by creating a fee management session and then queuing it up for later execution.
Call createFeeManagementSession() passing the feeManagementTermRecord in the parameters.
Call addFeeManagementSessionToQueue()

processFeeManagementSession(Long feeManagementSessionId)

Returns Long (Manifest)

Permissions Information

 

Permissions Required to Call Method

Internal

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Take the FM Session, use the rules engine to produce the manifest, and return.

createFeeManagementSession (FeeManagementTermRecord feeManagementTermRecord)

Returns Long (FeeManagementSessionId)

Permissions Information

 

Permissions Required to Call Method

Internal

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


createFeeManagementReport(Long feeManagementSessionId)

Returns FeeManagementReportInfo

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


In order to report back a simulated session, we can use this method to create a simplified version of the manifest. This can be sent back to an external system.

Logic for moving Rates to the Manifest

Rate Types

These rate type are copied from the document "Fee Management" and that list if update takes precedence. It is included here for reference only.

Tuition – AO connected Tuition Rates

KSA Name

Name at SI if know.

Rate Type

Description

Fixed Credit Tuition

 

tuition.credits.fixed

Tuition that is billed per credit hour. This may be subject to a limit rate (cap, or cap between unit ranges) which is discussed later.

Flexible Credit Tuition

 

tutition.credits.flexible

Tuition that is billed per credit hour. This may be subject to a maximum cap. The rate is not done as a multiplier, rather as a discrete but different amount per credit.

Fixed Course Tuition

 

tuition.course

Tuition that is billed once per course (activity offering).

Flat Tuition

 

tuition.flat

Tuition that is billed once per semester for a certain group of courses – for example, no matter how many courses from an MBA program are taken, a certain amount will be billed. This might also vary by cohort. This tends to be limited to a certain group of courses.

Flag Tuition

 

tuition.flag

A flag rate is one that has no inherent value, other than to instruct the rules engine that the rate must be chosen by the engine. For example, standard tuition flags might all be converted to resident, graduate rates for students in that situation.

Flag Rates – General Note

Note that if KS-ENR needs to have actual rates attached to each AO/PO in order to surface these to the student in the course catalog, it will be necessary for them to attach all possible course rates, not just the flag rate. The selection of the correct flag rate would be done then by the rules, using some agreed way to identify the groups of rates.

AO Fees

KSA Name

Name at SI if know.

Rate Type

Description

Period Fee

 

fee.ao.term

A fee that is charged once per time period, regardless of the number of AOs it is attached to. This can be used to charge a fee if a student registers for one, or several of a group of courses. It is implicitly a "fixed" fee – i.e. one charge, regardless of the number of credit hours.

Hourly Fee (Fixed rates)

 

fee.ao.credits.fixed

A fee that is charged by the number of credit hours for each AO it is attached to. It is implicitly either a flat or flexible fee, due to the relation to credit hours.
Note, per SB-2, the TransactionType can change per rate.

Hourly Fee (Flexible rates)

 

fee.ao.credits.flexible

 

Course Fee

 

fee.ao.course

A fee that is charged once for each AO it is attached to. This is implicitly a "fixed" fee.

Annual Fee

 

fee.ao.annual

A fee that is only ever charged once to a student, per year. This is implicitly a fixed fee.

One-time Fee

 

fee.ao.once

A fee that is only ever charged once to a student, during their academic lifetime. This is implicitly a fixed fee.

Flag Fee

 

fee.ao.flag

A fee that doesn't implicitly have a value, but can be replaced with a non-flag fee by the rules engine.

Hourly Fee (Fixed rates)
(Grouped)

 

fee.ao.credits.grouped.fixed

Identical to the same type without the grouping, however, the fee is charged as a single unit, with the number of credits being derived from the collective of courses with this fee. This is essentially a fee that works in the same way as tuition.

Hourly Fee (Flexible rates)
(Grouped)

 

fee.ao.credits.grouped.flexible

This is very unlikely as a use case, but is included for completeness.

 

PO Fees – Attached to the program offering / major/ etc.?

KSA Name

Name at SI if know.

Rate Type

Description

Program Fee

 

fee.po.term

A fee that is charged once per time period, regardless of the number of AOs it is attached to. This can be used to charge a fee if a student registers for one, or several of a group of courses. It is implicitly a "fixed" fee – i.e. one charge, regardless of the number of credit hours.

Program Enrollment Fee

 

fee.po.once

A fee that is only ever charged once to a student, during their academic lifetime. This is implicitly a fixed fee.

Flag Fee

 

fee.po.flag

A fee that doesn't implicitly have a value, but can be replaced with a non-flag fee by the rules engine.

Non-AO Fees – Generated within the rules system.

KSA Name

Name at SI if know.

Rate Type

Description

Late Fee

 

fee.late

A fee that is charged for late registration, etc.

General Fee

 

fee.general

A fee that is charged to a student if a certain number of circumstances are met – not specifically attached to an AO.

These are fees that might be incurred by a student that are not specifically attached to the AO. These fees would be referenced via the rules that are established in KSA-FM. There is an expectation that these are not attached to the AOs.
Technically the fees break down into these groups.

Grouping Charges

Grouping charges are those that create a single charge based on a number of existences of a rate. This breaks into two sub areas:

Fixed/Flexibles. This is done by calculating the number of credits being taken, and then using either the flat or flexible algorithm, the amount is calculated.

Examples are:

Tuition.credits.fixed
Tuition.credits.flexible
Fee.ao.credits.grouped.fixed
Fee.ao.credits.grouped.flexible

Flats. A flat grouping rate is one that is charged once no matter the number of occurrences.

Examples are:

Tuition.flat
Fee.ao.term
Fee.ao.annual (note the annual enforcement has to be done via rules and account keypairs)
Fee.ao.once (note the once enforcement has to be done via rules and account keypairs).
Fee.po.term
Fee.po.annual (note the annual enforcement has to be done via rules and account keypairs)
Fee.po.once (note the once enforcement has to be done via rules and account keypairs).
Fee.general and fee.late are both actually examples of fee.term and should be treated as such.

Non Grouping Charges

Non-grouping charges are those which are charged on each occurrence of the rate. That is, each occurrence of the rate will trigger a manifest line. These equally break into two groups. The fixed/flexible and the flat.

Fixed/flexibles. These will use the number of hours on EACH signup to charge the rate.

Examples are:

Fee.ao.credits.fixed
Fee.ao.credits.flexible

Flats. These will simply charge the default rate on each signup.

Examples are:

Fee.ao.course
Tuition.course

Grouping

Grouping

Non Grouping

Non Grouping

Credit Based

Non-credit Based

Credit Based

Non-Credit Based

Tuition.credits.fixed
Tuition.credits.flexible
Fee.ao.credits.grouped.fixed
Fee.ao.credits.grouped.flexible

Tuition.flat
Fee.ao.term
Fee.ao.annual Fee.ao.once
Fee.po.term
Fee.po.annual Fee.po.once Fee.general
fee.late

Fee.ao.credits.fixed
Fee.ao.credits.flexible

Fee.ao.course
Tuition.course



In order to create the line(s) in the manifest, we need to pass a pointer to the session and the rate code or rate code pattern.

Creating the Manifest Object (Charges)

This logic will be part of the DSL.
Rates are charged either by being present on the signup or by being passed as an incidental rate. They are treated in the same way in the initial part, when the amount, transaction types, and dates are calculated, unless the amount is passed (for an incidental rate), in which case amount calculation can be skipped.

Grouping Types

If the type is a grouping type, then a single manifest object will be created for all the signup lines that have the rate attached. The number of units for the all the signup lines with the rate should be calculated.
Then, the amount needs to be calculated.
For flat rates, it is simply the default amount (and transaction type) in the rate.
The logic for this is in getAmountFromRate(), getTransactionTypeFromRate()

Non-Grouping Types

If the type is non-grouping, then a manifest object will be created for each signup line with the rate. The number of units to pass will be the number of units on the given signup line.
The amount and transaction types have to be discerned, using the logic in getAmountFromRate() and getTransactionTypeFromRate()

Incidental Rates

If the amount is passed in the incidental rate construction, then this amount should be used. Otherwise it will be calculated from the rate as above. The transaction type will be discerned from the rate as above.

All Rates

The effectiveDate and recognitionDate should be calculated from the Rate using the logic in getEffectiveDateFromRate() and getRecognitionDateFromRate()
Then create the manifest item.
For all, these will be the same:
FeeManagementManifestType = CHARGE
FeeManagementManifestStatus = PENDING
rateId = the passed rateId
effectiveDate, recognitionDate, amount – per calculations in this routine.
currentSessionCharge = true
For grouping charges, set the registrationId to null, the offeringId to null and the internalChargeId to the rate code.
For Non-grouping charges, set the registrationId and the offeringId to the registration and offering ids of the signup line, and set the internalId to null.
For Incidental charges, set the internalId to the passed internal id.


Once rates have been placed on the manifest from signup, they should be marked as isComplete = true

Creating the Manifest Object (Discounts)


Discounts can only be created against rates that have already been charged to the manifest.
The most common use case it to discount a fee against the same rate, however sometimes it is necessary to discount against a different rate (i.e. charge to this t-code but discount against this t-code). This rate is used purely to discern the correct t-code.
Get the fee manifest line or lines referenced by the rate.
If multiple fee manifest lines are discounted, create a new manifest line for each of them.
If amount is passed, divide the amount by the number of manifest lines being created and round down. This will be the amount of each manifest line.
For each manifest line create a new manifest line, using:
Type – DISCOUNT
internalChargeId per the original line
registrationId per the original line
offeringId per the original line
status = QUEUED
rateId per the passed rate, or per the original line.
effectiveDate and recognitionDate per the original manifest line.
amount is either the divided amount from above, or the percentage value of the original amount.
currentSessionCharge = True
point the linkedManifestId to the original manifest item, and point the original manifest's linkedManifestId to the id for this item.

Creating the Manifest Object (Cancellation)

There is no use case for this any more. A 100% discount can be diven if needed, but cancellation due to the course no longer being chargeable is handled during the reconciliation section of the code.

createFeeManagementManifest(FeeManagementManifestType type, FeeManagementManifestStatus status, String transactionTypeId, Long rateId, String internalChargeId, String registrationId, String offeringId, Date effectiveDate, Date recognitionDate,  BigDecimal amount, Boolean isSessionCurrent)

Returns FeeManagementManifest
Check either internalChargeId or registrationId has ben set.
Check rateId, effectiveDate, recognitionDate, transactionTypeId are not null.
Check amount is >0.
Create an object with the parameters mapped and return.

reconcileSession(Long feeManagementSessionId)

Return void

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Session reconcialliation takes former sessions and ensures that charges that need to be removed are accurately recorded in the new session.

Process (There is a process diagram listed afterwards)

The session's status must be current.
Find a prior session with charged. If not, skip to the charge section. (with no prior session, all we have to do is charge the account. There is nothing prior to this so we don't need to do anything.)
Statuses can be CHARGE, CANCEL, DISCOUNT, ORIGINAL, CORRECTION (ORIGINAL is the transaction that was wrong, CORRECTION is the transaction that corrects the transaction).
A CHARGE is a standard charge, at a rate, against an account. Nothing prevents a charge from actually being a payment.
A CANCEL reduces or removes a CHARGE. It is interpreted as a negative, and must relate to a CHARGE on the account (this link should be able to be performed automatically, due to transaction similairities.
A DISCOUNT is like a CANCEL, except it can be a differnet transaction types, etc. So we might charge the full amount and credit a GL , but then the discount is taken from a different GL. If this is not the case, the discount can be applied in the rules. This would not be in the manifest, as it would simply reduce the charge.
AN ORIGINAL is not generated by rule. It is generated when the reconciliation process finds a charge that no longer applies. An ORIGINAL item will be already charged (and it is going to be offset by a CORRECTION) and will be copied to the manifest during reconciliation.
A CORRECTION is not generated by rule. It is generated to offset an ORIGINAL item.
Compare the list using signup+ [offering is implied by signupId] +rate or internalId+rate (the keys) looking only at statuses of CHARGE or CANCEL or DISCOUNT (Not CORRECTION or ORIGINAL)

Compare Line by Line

If all the pieces match (rate, effectiveDate, recognitionDate, transactionTypeId, amount) then copy the transactionId over to the new charge manifest (this has already been charged, and nothing needs to be done). Mark as status CHARGE. (It will not recharge as transactionId is set.)
If the keys match, but the pieces do not (rate, effectiveDate, recognitionDate, transactionTypeId, amount) then something has changed in rate, or somewhere else. The old charge needs to go and the new charge needs to be implemented. Mark the new charge as CHARGE. This charge will be charged as it has no transactionId.
Bring the old line of the charge manifest into the new manifest to make a complete record. Then add a new line to the charge manifest (current session) which is a cancellation of the manifest on the old session. Point them to each other. Mark as statuses ORIGINAL, CORRECTION. (The corrected will be igored as it has a transaction id, the correction will not as it is new.) The corrections will be ignored in the next run.
Compare Transactions Looking for Links
Search the list for matches on offering+rate or internalId+rate with status of CHARGE and CANCEL
Point these lines of the manifest to each other.
CHARGE and DISCOUNT ought to be inherently linked.

Compare Whole Lists

If there are items on the old list that are not on the new list then they need to be cancelled off completely.
First, check that the original item wasn't cancelled also on the list (otherwise we'll issue two cancellations – net effect will be the same but it is cleaner this way). If there is a full reversal, we can ignore them.

If there is not a full reversal:

Bring the old charge over (or indeed, old cancellation over) and then produce a reversal transaciton in the manifest. Mark as statuses ORIGINAL, CORRECTION. (The cancellation of the old will be created during charging). The corrections will be ignored in the next run.

chargeSession(Long feeManagementSessionId)

Return void.

Permissions Information

 

Permissions Required to Call Method

Internal

Extended Permissions

 

Implied Permissions

CREATE_TRANSACTION + associated.

Activity requirement

 

Process (There is a process diagram following.)

Take each line of the manifest.

If there is no transactionId:

Is there a linkedManifestId.

If the status is CHARGE or CORRECTION

Create the charge using the parameters in the line. Update the line with the transaction ID and set currentSessionCharge to true.

If the status is DISCOUNT

Create the transaction, allocate to the linked transaction. (clear only unlocked allocations if needed). Set currentSessionCharge to true.

If the status is ORIGINAL or CANCEL

Clear all allocations against the linkedManifestId.transactionId's transaction (this should be forced if necessary).
Call reverseTransaction() on the transaction passing partialAmount if appropriate.
Send the memo as transaction ID was reversed during fee management session number xxx.
Update the transactionId with the id of the reversal.
Set currentSessionCharge to true.

If there is no linkedManifestId

Call create transaction passing the parameters from this line of the manifestId.
CANCEL should interpret the amount in the negative and issue a transaction that way.
Store the newly created transaction Id in the manifest.
Set currentSessionCharge to true.

Do this for each line of the Manifest.

Set status of session to CHARGED.
Return a list of transactionIds that have been created. (all those with currentSessionCharge = true)


Create Transaction Pullout

Transfer Found

Transfer Reinstatement

Test Cases for Charge Session

Example 1:

Manifest line : CHARGE. No linkedId
This is the simple case, nothing is to be done other than raise the charge and move on.

Example 2:

Manifest line: CANCEL/CORRECTION/DISCOUNT.
There ought to be a linkedId. If not, we process, but raise a warning. Then we process as a CHARGE with a negated amount.

Example 3:

Manifest line: CANCEL/CORRECTION/DISCOUNT.
There is a linkedId (which is entirely appropriate).
If the linked ID is incomplete, you go back and do the linkedId first (it will be a charge)

Left-hand branch (where things get fun).

Just an FYI (I wrote this diagram thinking Michael would implement, and he and I had spent a lot of time looking at the whole offsetting system so it will take a little explanation…) I'm sure you know most of what is here, but I'm summarize, in part to remind myself how it works.
We cannot ever "remove" a transaction once it has been created, so what we do when we need to "reduce" or "remove" a transaction is issue an offset against it. An offset transaction is a transaction that is identical in most ways to the transaction that it offsets (transaction type, etc.) except the amount is negative, so if we have a $100 charge, we remove that charge by issuing a ($100) charge.
Because a transaction might have several offsets (for example, maybe a transaction was partially discounted, and then it was partially written off) we set the status of the offsetting transaction to tell us what happened to the transaction. So for example, if we have a $1000 transaction, with $300 discounted from it, and then $700 written off, we actually end up with the following.
Base transaction - $1000 – Status ACTIVE
Discount Transaction – ($300) – Status DISCOUNTING (so we "could" say the base transaction was discounted)
Write off Transaction – ($700) – Status WRITING_OFF (So we could say the base transaction is written off)
The relationships between these transactions is done via the ALLOCATION system. So Base transaction will be allocated to discount transaction, and base transaction will be allocated to write off transaction.
One final wrinkle in all of this! 
Let's say we decide to "unwrite off" a transaction…
First we break the allocation between Base Transaction and Writing off transaction. Kapow, base transaction now has an unallocated balance of $700 to be paid.
Then we issue a reversal against the writing off transaction. (This is handled by the service…) The upshot is that we reverse the writing off transaction, which means we negate a negative charge (so yes, we issue a charge), allocate them together, and then set their statuses to RECIPROCAL_OFFSET. RECIPROCAL_OFFSET is the end of the line. Those transactions cannot be reversed or anything, now. If you want to reverse the writing off of the writing off, you can't… !  You just have to do the write off again.
So the final situation would be:
Base transaction - $1000 – Status ACTIVE (allocated to Discount transaction)
Discount Transaction – ($300) – Status DISCOUNTING (so we "could" say the base transaction was discounted) (Allocated to base transaction)
Write off Transaction – ($700) – Status RECIPROCAL_OFFSET (Allocated to reverse write off transaction)
Reverse Write off Transaction – $700 – Status RECIPROCAL_OFFSET (Offsets an offset, resulting in a net 0.) (Allocated to write off transaction)

Example 4:

Manifest line: CANCEL/CORRECTION/DISCOUNT. (which should be issued against a CHARGE)
There is a linkedId (which is entirely appropriate). (It will point at a charge)
The linked Id is complete (it has a transaction id).

**Before we set about trying to issue reversals against the linked Id in order to complete this manifest line we need to clear access to the linked id transaction, which is the charge against which this cancel, correction or discount is issued.
Before we start, we clear all unlocked allocations, which are created by payment application.


Check for allocations.


There are none. We are fine.


We can call reverseTransaction() on the linked transaction (that is the original charge on the manifest) which will create a reversing transaction (which is a negative charge). And we set its status to the appropriate type per the diagram.

Example 5:

Manifest line: CANCEL/CORRECTION/DISCOUNT. (which should be issued against a CHARGE)
There is a linkedId (which is entirely appropriate). (It will point at a charge)
The linked Id is complete (it has a transaction id).

 

**Before we set about trying to issue reversals against the linked Id in order to complete this manifest line we need to clear access to the linked id transaction, which is the charge against which this cancel, correction or discount is issued.
Before we start, we clear all unlocked allocations, which are created by payment application.


Check for allocations.


Allocations remain.


Look to the statuses of those allocated transactions. If any of them are WRITING_OFF (If an account is written off, we should not be messing with it). RECIPROCAL_OFFSET (for the reasons outlined above, we don't touch those), REFUNDING (really ought to only apply to payments, so it has no place here, we have a problem) or BOUNCING (again, this is for payments… something is wrong) we skip this manifest item with a SEVERE warning, and we mark the session for manual review.
Note that I've slightly rearranged the check here. Do this check first for WO, RO, R or B status. If you have it, all bets are off. If not, you can move on to the second check for transfers, etc.
This branch is very unlikely except for WRITTEN_OFF.

Example 6:

Manifest line: CANCEL/CORRECTION/DISCOUNT. (which should be issued against a CHARGE)
There is a linkedId (which is entirely appropriate). (It will point at a charge)
The linked Id is complete (it has a transaction id).

 

**Before we set about trying to issue reversals against the linked Id in order to complete this manifest line we need to clear access to the linked id transaction, which is the charge against which this cancel, correction or discount is issued.


Before we start, we clear all unlocked allocations, which are created by payment application.


Check for allocations.


Allocations remain. They are of status REVERSING, DISCOUNTING, CANCELLING or ACTIVE


Note that if it's ACTIVE, it's probably a payment that has been locked, or internally locked.
If it's reversing, discounting or cancelling, it's likely a manual transaction that was put on the account to achieve what we're currently trying to achieve. This is why we ask that it be reviewed manually.

**See if we can proceed regardless:


Remember that the actual thing we're trying to process here is a manifest line of CANCEL/CORRECTION/DISCOUNT, so get the amount of that line (the current manifest line, not the linked line) and see if the linked transaction has enough unallocated balance to proceed. That is to say if we have a $1000 transaction and $50 of it is cancelled, (leaving $950) nothing is going to prevent us from issuing a $100 discount against it.
So – get the amount from the current manifest line, and test against the unallocated amount of the linked transaction. If the unallocated amount is equal to or exceeds it, we're in the clear.
It does, so write a warning to the log, mark for review, and continue to the reversing stage.

Example 7:

Manifest line: CANCEL/CORRECTION/DISCOUNT. (which should be issued against a CHARGE)
There is a linkedId (which is entirely appropriate). (It will point at a charge)
The linked Id is complete (it has a transaction id).

 

**Before we set about trying to issue reversals against the linked Id in order to complete this manifest line we need to clear access to the linked id transaction, which is the charge against which this cancel, correction or discount is issued.


Before we start, we clear all unlocked allocations, which are created by payment application.


Check for allocations.


Allocations remain. They are of status REVERSING, DISCOUNTING, CANCELLING or ACTIVE


Note that if it's ACTIVE, it's probably a payment that has been locked, or internally locked.
If it's reversing, discounting or cancelling, it's likely a manual transaction that was put on the account to achieve what we're currently trying to achieve. This is why we ask that it be reviewed manually.

**See if we can proceed regardless:
Remember that the actual thing we're trying to process here is a manifest line of CANCEL/CORRECTION/DISCOUNT, so get the amount of that line (the current manifest line, not the linked line) and see if the linked transaction has enough unallocated balance to proceed. That is to say if we have a $1000 transaction and $50 of it is cancelled, (leaving $950) nothing is going to prevent us from issuing a $100 discount against it.
So – get the amount from the current manifest line, and test against the unallocated amount of the linked transaction. If the unallocated amount is equal to or exceeds it, we're in the clear.
It doesn't… the amount that we're trying to CANCEL/CHARGE/DISCOUNT exceeds the available balance. We have to go further.
Call reverseAllocations() passing the linkedId and the amount of the manifest line CANCEL/CHARGE/DISCOUNT
This method will unlock allocations step by step, trying to get the unallocated amount into check. It will do this by reversing off the least important transactions, in order, to try and free up enough balance. (So for example, it might reverse a partial reversal, in order to allow us to do a full reversal, etc.)
Once this method has completed, check the amount again as you did before.
There is enough balance now to proceed, so we can complete as we did in example 6.

Example 8:

 

Manifest line: CANCEL/CORRECTION/DISCOUNT. (which should be issued against a CHARGE)
There is a linkedId (which is entirely appropriate). (It will point at a charge)
The linked Id is complete (it has a transaction id).

**Before we set about trying to issue reversals against the linked Id in order to complete this manifest line we need to clear access to the linked id transaction, which is the charge against which this cancel, correction or discount is issued.


Before we start, we clear all unlocked allocations, which are created by payment application.


Check for allocations.


Allocations remain. They are of status REVERSING, DISCOUNTING, CANCELLING or ACTIVE


Note that if it's ACTIVE, it's probably a payment that has been locked, or internally locked.
If it's reversing, discounting or cancelling, it's likely a manual transaction that was put on the account to achieve what we're currently trying to achieve. This is why we ask that it be reviewed manually

**See if we can proceed regardless:
Remember that the actual thing we're trying to process here is a manifest line of CANCEL/CORRECTION/DISCOUNT, so get the amount of that line (the current manifest line, not the linked line) and see if the linked transaction has enough unallocated balance to proceed. That is to say if we have a $1000 transaction and $50 of it is cancelled, (leaving $950) nothing is going to prevent us from issuing a $100 discount against it.
So – get the amount from the current manifest line, and test against the unallocated amount of the linked transaction. If the unallocated amount is equal to or exceeds it, we're in the clear.
It doesn't… the amount that we're trying to CANCEL/CHARGE/DISCOUNT exceeds the available balance. We have to go further.
Call reverseAllocations() passing the linkedId and the amount of the manifest line CANCEL/CHARGE/DISCOUNT
Once this method has completed, check the amount again as you did before.
There is still not enough unallocated balance – something could not be reversed. This is VERY unlikely, hence we write a severe log, again, mark for manual review, and we skip the item.

 

Rate Interpretation

These methods might be implemented as part of the rules flow. They are presented here as methods to capture the logic underpinning the date inside Rate.
Though there are many more rate types, fundamentally, rates fall into one of six categories.

getEffectiveDateFromRate(Long rateId, Date baseDate)

Returns Date

getRecognitionDateFromRate (Long rateId, Date baseDate)

Returns Date.

getAmountFromRate (Long rateId, int unit)

Returns BigDecimal
The overloaded version allows us to calculate the correct rate when override values are provided from the enrollment system.

getTransactionTypeFromRate (Long rateId, int units)

Returns String

Auditable Entities Services

KSA relies on a number of classes that are derived from the AuditableEntity class. These methods permit the creation and editing of these types.

persistRollup (Rollup rollup)

Returns Rollup.

Permissions Information

 

Permissions Required to Call Method

CREATE_ROLLUP

Extended Permissions

EDIT_ROLLUP

Implied Permissions

 

Activity requirement

 


Check that no other rollup exists with the same Code (and id is different). If it does, throw exception.
If this is a new rollup, populate the id field, set creatorId to the current user, and creationDate to the current system date/time. and then persist.
If this is an update, set the editorId to the current user, and the lastUpdated to the current date/time, then persist.

persistTag (Tag tag)

Returns Tag.

Permissions Information

 

Permissions Required to Call Method

CREATE_TAG, EDIT_TAG

Extended Permissions

CREATE_ADMIN_TAG, EDIT_ADMIN_TAG

Implied Permissions

 

Activity requirement

 


Check that no other tag exists with the same Code (and id is different). If it does, throw exception.
Check if isAdministrative is true. If so, then check the user is allowed to create administrative tags.
If the Tag already exists, and the isAdministrative of the old tag is true (and is being changed to false) check the user is allowed to change an administrative tag.
If this is a new tag, populate the id field, set creatorId to the current user, and creationDate to the current system date/time. And then persist.
If this is an update, set the editorId to the current user, and the lastUpdated to the current date/time, then persist.

persistBankType (BankType bankType)

Returns BankType.

Permissions Information

 

Permissions Required to Call Method

CREATE_BANK_TYPE

Extended Permissions

EDIT_BANK_TYPE

Implied Permissions

 

Activity requirement

 


Check that no other bankType exists with the same Code (and id is different). If it does, throw exception.
If this is a new bankType, populate the id field, set creatorId to the current user, and creationDate to the current system date/time. and then persist.
If this is an update, set the editorId to the current user, and the lastUpdated to the current date/time, then persist.

persistIdentityType (IdentityType identityType)

Returns IdentityType.

Permissions Information

 

Permissions Required to Call Method

CREATE_IDENTITY_TYPE

Extended Permissions

EDIT_IDENTITY_TYPE

Implied Permissions

 

Activity requirement

 


Check that no other identityType exists with the same Code (and id is different). If it does, throw exception.
If this is a new identityType, populate the id field, set creatorId to the current user, and creationDate to the current system date/time. And then persist.
If this is an update, set the editorId to the current user, and the lastUpdated to the current date/time, then persist.

persistTaxType (TaxType taxType)

Returns TaxType.

Permissions Information

 

Permissions Required to Call Method

CREATE_TAX_TYPE

Extended Permissions

EDIT_TAX_TYPE

Implied Permissions

 

Activity requirement

 


Check that no other taxType exists with the same Code (and id is different). If it does, throw exception.
If this is a new taxType, populate the id field, set creatorId to the current user, and creationDate to the current system date/time. and then persist.
If this is an update, set the editorId to the current user, and the lastUpdated to the current date/time, then persist.

persistAccountStatusType (AccountStatusType accountStatusType)

Returns AccountStatusType.

Permissions Information

 

Permissions Required to Call Method

CREATE_ACCOUNT_STATUS_TYPE

Extended Permissions

EDIT_ACCOUNT_STATUS_TYPE

Implied Permissions

 

Activity requirement

 


Check that no other accountStatusType exists with the same Code (and id is different). If it does, throw exception.
If this is a new accountStatusType, populate the id field, set creatorId to the current user, and creationDate to the current system date/time. and then persist.
If this is an update, set the editorId to the current user, and the lastUpdated to the current date/time, then persist.

persistAccountType (AccountType accountType)

Returns AccountType.

Permissions Information

 

Permissions Required to Call Method

CREATE_ACCOUNT _TYPE

Extended Permissions

EDIT_ACCOUNT _TYPE

Implied Permissions

 

Activity requirement

 


Check that no other accountType exists with the same Code (and id is different). If it does, throw exception.
If this is a new accountType, populate the id field, set creatorId to the current user, and creationDate to the current system date/time. and then persist.
If this is an update, set the editorId to the current user, and the lastUpdated to the current date/time, then persist.

persistGeneralLedgerType (GeneralLedgerType generalLedgerType)

Returns GeneralLedgerType.

Permissions Information

 

Permissions Required to Call Method

CREATE_GL _TYPE

Extended Permissions

EDIT_GL _TYPE

Implied Permissions

 

Activity requirement

 


Check that no other generalLedgerType exists with the same Code (and id is different). If it does, throw exception.
If this is a new accountStatusType, populate the id field, set creatorId to the current user, and creationDate to the current system date/time. and then persist.
If this is an update, set the editorId to the current user, and the lastUpdated to the current date/time, then persist.

persistActivityType (ActivityType activityType)

Returns ActivityType.

Permissions Information

 

Permissions Required to Call Method

CREATE_ACTIVITY _TYPE

Extended Permissions

EDIT_ACTIVITY _TYPE

Implied Permissions

 

Activity requirement

 


Check that no other activityType exists with the same Code (and id is different). If it does, throw exception.
If this is a new activityType, populate the id field, set creatorId to the current user, and creationDate to the current system date/time. and then persist.
If this is an update, set the editorId to the current user, and the lastUpdated to the current date/time, then persist.

persistRefundType (RefundType refundType)

Returns RefundType.

Permissions Information

 

Permissions Required to Call Method

CREATE_REFUND _TYPE

Extended Permissions

EDIT_REFUND _TYPE

Implied Permissions

 

Activity requirement

 


Check that no other refundType exists with the same Code (and id is different). If it does, throw exception.
If this is a new refundType, populate the id field, set creatorId to the current user, and creationDate to the current system date/time. and then persist.
If this is an update, set the editorId to the current user, and the lastUpdated to the current date/time, then persist.

persistTransactionTypeMaskRole (TransactionTypeMaskRole transactionTypeMaskRole)

Returns TransactionTypeMaskRole.

Permissions Information

 

Permissions Required to Call Method

ASSIGN_TT_TO_ROLE

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Check that no other transactionType exists with the same Code (and id is different). If it does, throw exception.
Check the transaction mask is a valid regular expression. If not, throw exception.
Check the role exists with KIM, otherwise throw exception.
Add to the security service.

persistTransferType (TransferType transferType)

Returns RefundType.

Permissions Information

 

Permissions Required to Call Method

CREATE_TRANSFER_TYPE

Extended Permissions

EDIT_TRANSFER_TYPE

Implied Permissions

 

Activity requirement

 


Check that no other refundType exists with the same Code (and id is different). If it does, throw exception.
Check that generalLedgerType is valid, if not, throw exception.
If this is a new transferType, populate the id field, set creatorId to the current user, and creationDate to the current system date/time. and then persist.
If this is an update, set the editorId to the current user, and the lastUpdated to the current date/time, then persist.

Refund Service

Abstract Service Responsibility

The refund service is the core of KSA-RM-RM. It handles the production of refunds from the system. At its heart is the Refund object, which acts as a queue for refunds to be processed.
The refund service will try to determine if a transaction can be paid as "cash" (that is, without restrictions, not going to a third party, or being repaid in a specific way.) If a refund (or part of a refund) can be paid as "cash" then it will be paid with the refund type as defined in refund.method, which is a student-specific attribute, unless override.refund.method is set to a different refund type, in which case, this takes precedence. If neither are set, then default.refund.method is used.
This allows a default method for all students (likely paper check) with students able to sign up for other refund types (bank transfer, etc.) and it allows a counselor to override that choice in certain cases (for example, they may require certain students to pick up their refund check at the office.)

getPotentialRefunds(String accountId)

getPotentialRefunds(String accountId, Date startDate, Date endDate)

Returns List<Int> (transactionId)
Go through the payments on the account, looking for an unallocated amount >0, isRefundable = true, and clearDate < today's date. Return this list of transactions. Filter by the startDate and endDate if supplied.

checkForRefund (String accountId, Date fromDate, Date toDate)

Returns List<Refund>

checkForRefundOnTransaction (Long transactionId)

Returns Refund

checkForRefundOnTransaction (Long transactionId, BigDecimal amount)

Returns Refund

Permissions Information

 

Permissions Required to Call Method

REQUEST_REFUND

Extended Permissions

 

Implied Permissions

 

Activity requirement

FRIENDLY

Refund requested on transaction <transactionId> in amount of <amount>

This creates a list of unverified refunds.

Notes:

The syntax of "refundRule" is discussed in the data model documentation under the heading "Refund Rule Use Cases".
paymentApplication() should be run before calling the refund routine.
It is expected that once the system has produced this refund list, an institution-specific set of rules would then check for use cases specific to the school in question and ensure that the list is ready for human validation. As an example, for an account refund (a refund from one KSA account to another KSA account) the refundAttribute can be used to override the statement text of the refund. The rules engine could be used to insert this text, based on institution-specific preferences.

checkForRefund (List<String accountId>, Date fromDate, Date toDate)

Returns List<Refund>
For each accountId, perform a checkForRefund()

checkForRefunds()

checkForRefunds(Date dateFrom, Date dateTo)

Returns List<Refund>

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

REQUEST_REFUND

Activity requirement

 


Iterates through all accounts looking for refundable amounts. For each account, checkForRefund() is called. If the dates are passed, these are passed to the checkForRefund method. If not, then maximum dates are passed.
In many cases, "produceRefundList()" will be used infrequently, as many schools will elect to run refunds against specific populations of students.

performRefund(Long refundId)

performRefund(Long refundId, String batch)

Returns Refund.

Permissions Information

 

Permissions Required to Call Method

CREATE_REFUND

Extended Permissions

 

Implied Permissions

CREATE_PAYMENT, CREATE_CHARGE

Activity requirement

 


This actually creates the refund transaction, in addition to allocating the refund to the original charge. It marks the refund object as refunded.

validateRefund (Long refundId)

Returns Refund.

validateRefundWithAmount (Long refundId, BigDecimal amount)

Returns Refund.

Permissions Information

 

Permissions Required to Call Method

VALIDATE_REFUND

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Sets the refundStatus to "V" and the authorizedBy to the current user. If amount is passed, alter the amount in the refund object.

cancelRefund (Long refundId, String memoText)

Returns Refund.

Permissions Information

 

Permissions Required to Call Method

CANCEL_REFUND

Extended Permissions

 

Implied Permissions

CREATE_PAYMENT, CREATE_CHARGE, REVERSE_TRANSACTION

Activity requirement

MEMOLOG

memoText


createAccountRefund (Long refundId)

createAccountRefund (Long refundId, String batch)

Returns Refund.

Permissions Information

 

Permissions Required to Call Method

CREATE_REFUND

Extended Permissions

 

Implied Permissions

CREATE_PAYMENT, CREATE_CHARGE

Activity requirement

 


createAccountRefunds (String batch)

Returns List<Refund>

Permissions Information

 

Permissions Required to Call Method

CREATE_REFUND

Extended Permissions

 

Implied Permissions

CREATE_PAYMENT, CREATE_CHARGE

Activity requirement

 


Go through the Refund objects. For each validated refund with type set to account refund (refund.account.type). For each one that is found, call doAccountRefund (refundId, batch).

createCheckRefund(Long refundId, Date checkDate, String checkMemo)

createCheckRefund(Long refundId, Date checkDate, String checkMemo, String batch)

Returns String (XmlCheck).

Permissions Information

 

Permissions Required to Call Method

CREATE_REFUND

Extended Permissions

 

Implied Permissions

CREATE_PAYMENT, CREATE_CHARGE

Activity requirement

 


produceXmlCheck (String identifier, String payee, PostalAddress postalAddress, BigDecimal amount, String memo, Date checkDate)

Returns String (XmlCheck).

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


createCheckRefunds(String batch, String checkMemo, Date checkDate)

Returns String (batch-check).

Permissions Information

 

Permissions Required to Call Method

CREATE_REFUND

Extended Permissions

 

Implied Permissions

CREATE_PAYMENT, CREATE_CHARGE

Activity requirement

 

createAchRefund(Long refundId)

createAchRefund(Long refundId, String batch)

Return String (XmlAch).

Permissions Information

 

Permissions Required to Call Method

CREATE_REFUND

Extended Permissions

 

Implied Permissions

CREATE_PAYMENT, CREATE_CHARGE

Activity requirement

 



produceAchTransmission (BigDecimal amount, String reference, Ach ach)

Returns String (ach).

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


createAchRefunds (String batch)

Return String (batch-ach)

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Go through the Refund objects. For each validated refund with type set to ach refund (refund.ach.type). For each one that is found, call doAchRefund (refundId, batch).

isRefundRuleValid(String refundRule)

Returns Boolean.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Miscellaneous Process Flows

These flows do not try to describe methods, rather larger processes to achieve a result.

Unauthenticated Web Portal Flow

Billing Service

The billing service is responsible for the production of XML bills according the ksa-bill schema. These bills can be exported to other applications to produce bills in whatever format the institution prefers.

generateBill (String accountId, Date billDate, Date startDate, Date endDate, Boolean showOnlyUnbilledTransactions, Boolean showDeferments, Boolean showInternalTransactions, Boolean showDependents, Boolean runPaymentApplication, Boolean, List<Int> rollupsOnSameDate, List<Int> rollupsOnSameStatement, String message>)

Returns String (XmlBill)

Permissions Information

 

Permissions Required to Call Method

CREATE_BILL

Extended Permissions

 

Implied Permissions

GET_ACCOUNT, GET_TRANSACTION

Activity requirement

 


The billing system can produce an XML exported bill on the following attributes:
The billDate is the date on which the bill is produced, so we calculate our balances as of that date. This includes removing transactions with a CREATION date after that date. (Note that creationDate is used because if the bill is produced at a point in time, even if we put in new transacitons with effectiveDates that would have fallen on the bill, if they didn't EXIST at bill production time, they shouldn't be on the bill. Note that this is the rationale behind using the CREATION DATE in the balance methods that are called by this method, too.
Start and end date windows the transactions to a time period. This might be derived from ATP. If they are not supplied, KSA will calculate them based on the logic at the start of the method. Supplied or not, the bill will inherently have a start and an end date, which will be stored in the bill object.
showOnlyUnbilledTransactions removes from the bill any transaction that has been show on a prior billing statement.
showDeferments stops defements from being suppressed in the billing statement.
showInternalTransactions stops internal transactions from being surpressed in the billing statement.
runPaymentApplication causes payment application to be run before the billing statement is produced. (note that account ageing is called automatically on the date in question.)
rollupsOnSameDate is a list of rollups that will show as a single line if transacitons with the same rollup have an effective date which is the same. (i.e. all Financial Aid transactions on a given day).
rollupsOnSameStatement will rollup all transactions on this statement of the given type.
If billing dates are not provided, the system will set them based on the following logic:

For the startDate:

If showOnlyUnbilledTransactions is true, then the startDate will be set to the earliest date on the account, ensuring that all unbilled transactions are caught.
If showOnlyUnbilledTransactions is false then the startDate will be set to the latest endDate of a bill that was produced. If a bill has not formerly been produced, then it will be set to the earliest date on the account.

For the endDate:

This will be set to the billDate or the latest date on the account, whicheaver is earliest.
We then need to check that the dates are appropriate (i.e. start is before end) before we continue.



generateBills (List<String accountId>, Date billDate, Date startDate, Date endDate, Boolean showOnlyUnbilledTransactions, Boolean showDeferments, Boolean showInternalTransactions, Boolean showDependents, Boolean runPaymentApplication, Boolean, List<Int> rollupsOnSameDate, List<Int> rollupsOnSameStatement, String message>)

Returns String (ksa-bill)

Permissions Information

 

Permissions Required to Call Method

CREATE_BILL

Extended Permissions

 

Implied Permissions

GET_ACCOUNT, GET_TRANSACTION

Activity requirement

 


For each accountId in the list, produce an XML bill and return an XML document containing all the <ksa-bill> nodes.

registerExternalStatement(Long billRecordId, String uri, String fileType, Boolean isRedirect)

Returns ExternalStatement

Permissions Information

 

Permissions Required to Call Method

REGISTER_STATEMENT, EDIT_STATEMENT

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Check that billRecordId points to a valid BillRecord
Check uri and fileType are non-null.
Look for other records with same fileType and billRecordId, if found, user must have permission EDIT_STATEMENT, otherwise, just REGISTER_STATEMENT
Map all elements to same names in ExternalStatement, update modified auditable entity information and persist.

removeExternalStatement (Long externalStatementId)

Returns void.

Permissions Information

 

Permissions Required to Call Method

REMOVE_STATEMENT

Extended Permissions

 

Implied Permissions

 

Activity requirement

 

Check appropriate permissions, then remove the external statement record.

 

Payment Application Service [PaymentApplicationService]Payment application services fall under the transaction service, and many payment applications services are already listed under the Transaction and Account services. They are placed here for clarity.
Notice that many of these methods are very explicit and simplified, as they are designed to be called via rules from the rules engine. For this reason, they are rarely overloaded, and the nomenclature of Payments/Charges/Deferments is always used.

paymentApplication (String accountId)

Returns void.

Permissions Information

 

Permissions Required to Call Method

RUN_PAYMENT_APPLICATION

Extended Permissions

 

Implied Permissions

CREATE_ALLOCATION, REMOVE_ALLOCATION

Activity requirement

 


Calls the rules set for payment application. Many other services can be used and will be useful to payment application, including a direct creation of an allocation if needed. However, the majority of use cases should be possible by filtering the lists as needed and passing them to the automatic applyPayments() method. This method will create a TransactionList object containing all the unallocated transactions (of any value) for this accountId, ignoring all expired deferments (isExpired = true) and pass this object to the rules engine.

paymentApplication (List<String accountId>)

Returns void.
For each accountId, call paymentApplication()

allocateReversals (String accountId)

allocateReversals (String accountId, Boolean isQueued)

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


This method is used to apply "obvious" payments to their reversal. Under normal circumstances, this will not be needed, as reversals created inside of KSA will automatically be locked together. However, after an import from an external system, this allocation may not exist. This method is provided to ensure that transactions that are obviously designed to be together, are allocated together. "Obvious" means they are entirely unallocated, have the same amounts, but one is negated, and they have the same transaction type.

applyPayments (TransactionList transactionList, Boolean isQueued)

applyPayments (TransactionList transactionList, Boolean isQueued, BigDecimal maximumAmount)

Return void.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


applyPayments takes the list that has been manipulated by the other payment application filters. The system will then iterate through the list and apply payments, following simple payment logic. Note that when a payment is encountered, the priority in the creditPermission will be used. Where a charge is encountered, the next available payment will be applied (that is allowed to pay the charge). Under normal circumstances, payments will be first in the list, unless the user wants to override this behavior.
If maximumAmount is passed, then the payment application will not allocate more than that amount.
If isQueued is set as false, the general ledger transactions that are created will be put into status of Waiting, so they will not be transmitted to the general ledger until this status is set to Queued. This will usually be done by passing the list of general ledger transactions to the summarizeGeneralLedgerTransactions() method.

TransactionList

Note that many of these methods supply values that can be achieved in other ways, however these methods are designed to be implemented by an end user that has a narrower knowledge of the Java language. Therefore some of the calls are designed to give that user easier access to information that otherwise they would have no way of achieving.
Notice that deferments are always fully allocated by the system, and are therefore not found in the TransactionList supplied to the payment application rules engine.

getNumberOfTransactions (TransactionList transactionList)

Returns integer.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Returns the size of the transaction[] array.

refreshList(TransactionList transactionList)

Returns TransactionList.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Remove all transactions from the list that are now fully allocated (amount = allocatedAmount + lockedAllocationAmount), or expired deferments.

getUnallocatedPaymentAmount(TransactionList transactionList)

getUnallocatedChargeAmount(TransactionList transactionList)

getUnallocatedDefermentAmount(TransactionList transactionList)

Returns BigDecimal.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Returns the value of the unallocated amount of all payments/ charges / deferments in the list.

getRestrictedPaymentAmount(TransactionList transactionList)

getUnrestrictedPaymentAmount(TransactionList transactionList)

getRestrictedDefermentAmount(TransactionList transactionList)

getUnrestrictedDefermentAmount(TransactionList transactionList)

Returns BigDecimal.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Return the unallocated amount of all restricted or unrestricted payments/ deferments. Unrestricted payments/ deferments have a creditPermission Type of "*".

calculateMatrixScore (TransactionList transactionList)

Returns Void.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


This is a very expensive method, and should be used sparingly.
The matrixTransactionScore is an element that is only calculated during payment application, and changes depending on the list that is passed to this method.
For each credit (payment and deferments), this score is the number of debits (charges) IN THE PASSED LIST, which can be paid by this credit. For example, if a payment is unrestricted, then this will equal the number of debits in the list, as it can pay them all. If a payment is restricted to a single debit code, and only one debit with that debit code exists, then its score will be 1.
Conversely, for each debit (charge), the score is the number of credits (payments) that can pay off this debit.
The lower the score, the more limited a credit/debit is. A transaction with a matrixTransactionScore of 0 is not able to be allocated to any transaction in the current working list.

orderByPriority (TransactionList transactionList, Boolean ascending)

orderByEffectiveDate (TransactionList transactionList, Boolean ascending)

orderByRecognitionDate (TransactionList transactionList, Boolean ascending)

orderByAmount (TransactionList transactionList, Boolean ascending)

orderByUnallocatedAmount (TransactionList transactionList, Boolean ascending)

orderByMatrixScore (TransactionList transactionList, Boolean ascending)

Returns TransactionList.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Order the list on the field mentioned in the method. If ascending is true, sort from lowest to highest, else sort from highest to lowest.

reverseList (TransactionList transactionList)

Returns TransactionList.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Invert the list from bottom to top.

getNewList (TransactionList transactionList)

Return a new copy of the list that can be manipulated.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Returns TransactionList.

removeCharges(TransactionList transactionList)

removePayments(TransactionList transactionList)

removeDeferments(TransactionList transactionList)

Returns TransactionList.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Remove the appropriate transactions types from the list.

performUnion (TransactionList transactionList1, TransactionList transactionList2)

Returns TransactionList.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Using the lists referenced, perform a union between the lists and return a new list. Any entries that are in transactionList that are not in the current list are added to the current list. (OR)

performIntersection (TransactionList transactionList1, TransactionList transactionList2)

Returns TransactionList.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Using the lists referenced, perform an intersection between the lists and return a new list. Any entries that are not in both lists are removed from the new list. (AND)

performCombination (TransactionList transactionList1, TransactionList transactionList2)

Returns TransactionList.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Using the lists referenced, perform a combination between the lists and return a new list. The two lists will be merged, removing transactions on both lists. (XOR).

performSubract (TransactionList transactionList1, TransactionList transactionList2)

Returns TransactionList.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Using the lists referenced, perform a subtraction between the lists and return a new list. Any items in the second list will be removed from the first list.

filterByPriority (TransactionList transactionList, int priorityFrom, int priorityTo)

Returns TransactionList.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Remove all transactions from the object that fall outside of the priorities specified. If either parameter is null, it can be ignored (no lower/upper value).

filterByEffectiveDate (TransactionList transactionList, Date startDate, Date endDate)

filterByRecognitionDate (TransactionList transactionList, Date startDate, Date endDate)

Returns TransactionList.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Remove all transactions from the object that fall outside of the dates specified. If either parameter is null, it can be ignored (no lower/upper value).

filterByAmount (TransactionList transactionList, BigDecimal amountFrom, BigDecimal amountTo)

Returns TransactionList.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Remove all transactions from the object that fall outside of the amounts specified. If either parameter is null, it can be ignored (no lower/upper value).

filterByUnallocatedAmount (TransactionList transactionList, BigDecimal amountFrom, amountTo)

Returns TransactionList.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Remove all transactions from the object that fall outside of the unallocated amounts specified. If either parameter is null, it can be ignored (no lower/upper value).

filterByMatrixScore (TransactionList transactionList, int matrixScoreFrom, int matrixScoreTo)

Returns TransactionList.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Remove all transactions from the object that fall outside of the unallocated amounts specified. If either parameter is null, it can be ignored (no lower/upper value).

filterByTransactionType (TransactionList transactionList, List<String transactionTypeMask>)

Returns TransactionList.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Filter out only those transactions that match the transactionTypeMask, or list of them, that is passed.

filterByTag (TransactionList transactionList, List<String tagCode>)

Returns TransactionList.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Remove all transactions from the list that do not have the Tag.code = tagCode.

removeByTag (TransactionList transactionList, List<String tagCode>)

Returns TransactionList.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Remove all transactions from the list that have the Tag.code = tagCode.

filterByRollup (TransactionList transactionList, List<rollupCode>)

Returns TransactionList.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Remove all transactions from the list that do not have the Rollup.code = rollupCode

removeByRollup (TransactionList transactionList, List<rollupCode>)

Returns TransactionList.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Remove all transactions from the list that have the Rollup.code = rollupCode.

Payment Application Rules (Example)

This is an example of how the payment application rules could be applied. This example takes into account the priority of payments (which is built into the applyPayments() logic), the difficulty of applying payments, and basic financial aid methodology.
In order for the system to correctly identify financial aid payment that are subject to the $200 previous period rule, the payment would have to be appropriately tagged. For this example, we will assume that all financial aid transactions are tagged with a Tag where Tag.code = "finaid". In a production system, the filtering likely be more complex.

Methods that will be invoked (as example) and the lists that will be created.

Description of what is being achieved.

removeAllocations()

Clear out the current allocation table of the list of transactions we're dealing with, keeping a list of the GL entries created (the return value) Each time we apply payments, we keep a copy of these GL transactions. This should only clear unlocked allocations from the account to allow the system to reallocate as it needs to.

allocateReversals()

Do any "obvious" allocations, where there exists transactions designed to clear other transactions. In most cases, these transactions will carry a lockedAllocationAmount, and therefore will already be allocated. Keep a list of the GL entries created.

Filter transactionList by status "Active"

Only perform PA on active transactions.

Using getNewList() and the filterBy… methods:
filterByEffectiveDate () using year 2009, 2010, 2011, 2012…
to create transactionsForYear2009..2012

Create a copy of the transaction list for each year that we are applying payments for (schools may elect to lock allocations at year end for prior years, to prevent allocation and reallocation of earlier years).

Using the filterBy methods, and removeCharges()/ removePayments(), filterByTag() to create the following lists:
allPayments
allCharges
paymentsForYear2009… paymentsForYear2012
chargesForYear2009… chargesForYear2012
financialAidForYear2009.. financialAidForYear2012 (using filterByTag, where tag = "finaid")

Create a list of payments, charges, and financial aid payments.

applyPayments() using the union of chargesForYear**** and financialAidForYear**** in descending order.

Allocate financial aid to charges within the year. The transaction code masking will ensure that the financial aid can only pay off the appropriate charges. Keep a list of the GL entries created.

For each financialAidForYear***, check value of payments. If it's not 0, call applyPayments() on the financialAidYear*** with all remaining charges, using maximumAmount of $200. Do this also in descending order.

Allocate any remaining financial aid payment to prior years up to a maximum of $200, per financial aid regulations.

Refresh all the lists, and use performSubtract() to remove the remaining financialAidPayments from the allPayments list.

After this, no more financial aid payments can be allocated, so they can be removed from the payment lists.

Using performUnion, create a new list of all remaining payments and charges (with FA removed)

Now all the remaining payments and charges that can be allocated are passed.

calculateMatrixScore() on the list.

Calculate the matrix score, which dictates which charges and payment will be the hardest to allocate.

orderByMatrixScore (True)

Order this list with the lowest scores at the top. This puts the highest priority on those payments and charges that are hardest to allocate.

Call applyPayments()

Perform the payment application. Keep a list of the GL entries created.

Call summarizeGeneralLedgerTransactions() with the list of GL transactions that were recorded.

Clean up after the session, removing any duplicate entries caused by deallocation/reallocation.

Collections Service (In Progress – This Service is Phase 2: This is designed only to meet phase 1 objective)

 

assignToCollectionAgency (String accountId, CollectionAgency collectionAgency, String memoText)

Returns Account.
Calls the rules engine to perform the prerequisite tasks for assigning to collection agency, including establishing flags, blocks, audit trail, and setting the account status to the appropriate value. Finally, this method adds the accountId to the collectionAgency object. Then the memo for this event is placed on the account.

removeFromCollectionAgency (String accountId, String memoText)

Returns Account.
Remove the accountId from the collection agency list. This does not knock the account out of "collections" status.

removeFromCollections (String accountId, String memoText)

Rule-based process to remove the account from collections status, including lifting of any blocks related to that status, and de-assigning the collection agency if one exists. (see removeFromCollectionAgency()).

Payment Billing Service

Generic

This service takes an input of a Payment Billing Plan, which acts as the template for payment billing, and produces transactions on future dates to allow the student to pay over time. The discrete steps of the process are:

 

  • Produce a payment billing transfer detail class which starts the process.
  • Generate payment billing transactions which looks for transctions that can be financed.
  • Generate payment billing schedule, which allocates amounts to dates.
  • Finally, create payment billing transactions, which produces the transaction transfer.

This is wrapped in the generic method generatePaymentBilling()

createPaymentBillingPlan()

Returns PaymentBillingPlan

getPaymentBillingPlan()

Returns PaymentBillingPlan

persistPaymentBillingPlan()

Returns paymentBillingPlan

executePaymentBilling (String accountId, Long paymentBillingId, BigDecimal maximumAmount)

Return PaymentBillingTransferDetail.
Call generatePaymentBillingTransfer(accountId, paymentBillingPlanId, initiationDate)
With the returned PaymentBillingTransferDetail.
Call generatePaymentBillingTransactions()
With the same id
Call generatePaymentBillingSchedule()
If the return value is null, exit this whole method will null.
With the same id
Call transferPaymentBIllingTransactions()
Return PaymentBillingTransferDetail.

createPaymentBillingQueue(String accountId, Long paymentBillingPlanId, BigDecimal maxAmount, Boolean forceReversal)

Return PaymentBillingQueue
Check pieces of the parameters are valid (they exist, etc.)
Create a new PaymentBillingQueue object. Persist.
Return the object.

processPaymentBillingQueue()

processPaymentBillingQueueByCreatorId(String creatorId)

processPaymentBillingQueueByAccountId(String accountId)

Return void.
Get the list of PaymentBIllingQueue objects with no paymentBillingTransferDetail (filtered by accountId or creatorId if passed)
For each, check for the existence of a paymentBillingTransferDetail object on the same account the same paymentBillingPlan that is not REVERSED.
If the status is anything other than ACTIVE then skip and move to the next item in the queue. (This must mean that something is already in progress and we need to leave it alone.)
If one exists with ACTIVE status, and if forceReversal is false, set the paymentBillingTransferDetail to the one that was found and move to the next object in the list.
If one exists with ACTIVE status and if forceReversal is true, reverse the transfer using reversePaymentBilling() and move to the next step.
Call executePaymentBilling() passing the parameters from the object. Store the returned paymentBillingTransferDetail in the paymentBillingQueue object, and move to the next one, until none remain.

generatePaymentBillingTransfer (String accountId, Long paymentBillingPlanId,BigDecimal maximumAmount, Date initiationDate)

Return PaymentBillingTransferDetail

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Check to see there is no other paymentBillingDetail object with the same paymentBillingPlan on this account with a status of anything but REVERSED. If so, throw exception.
Check for any blocks on the account that would prevent the plan from posting (This is still a To do).
Check that maximumToFinance is less than or equal to paymentBillingPlan.maximumAmount. If false, set maximumToFinance to maximumAmount.
Check effectiveDate (or, if null, current date) falls between paymentBIllingPlan.startOpenPeriod and paymentBillingPlan.endOpenPeriod
Create a new PaymentBillingTransferDetail object.
Map intiatationDate to initiationDate
accountId to accountId
Current user to creatorId
paymentBillingPlanId to passed paymentBillingPlanId.
maximumAmount to paymentBillingDetail.maximumAmount
Set status to Initialized

generatePaymentBillingTransactions (Long paymentBillingTransferDetailId)

Return PaymentBIllingTransferDetail.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


This method creates the list of type PaymentBillingTransaction, detailing which transactions can be financed, and how much of each of them can be financed. The parameters for this calculation derive from PaymentBillingPlan. Note that the requestedMaximum in paymentBIllingDetail allows the system to underride the amount to finance, allowing a student to finance LESS (but not more) than the maximum amount specified in the plan.

generatePaymentBillingSchedule(Long paymentBillingTransferDetailId)

Returns List<PaymentBillingSchedule>
Note at this stage we might discover nothing is financed, or there are no payment billing dates, in which case, we will return a null and destroy the paymentBillingTransferDetail object.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


calculatePaymentAmount (BigDecimal totalAmount, float percentage, Integer roundingFactor)

Returns BigDecimal.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


This is used to produce a monthly payment amount, based on the original amount, the percentage and the rounding factor.
Ensure roundingFactor is 0 or higher (it cannot be negative).
Multiply the totalAmount by the percentage. (This is paymentAmount)
If roundingFactor is zero, round the paymentAmount up to the second decimal place. Return the paymentAmount.
If the rounding factor is set, round the number up to zero for the number of digits covered.
E.X.
If rounding is 1, the last (non-decimal) digit will be zero, so 1029 becomes 1030.
If rounding is 100, the last three digits will be 0, so 1029 becomes 2000.
(Rounding factor is not likely to be anything other than 0,1, or 10)
Take the paymentAmount, and divide by the roundingFactor. Convert this to an integer and add one to it. Now multiply that integer by the rounding factor. The resulting amount is paymentAmount.
(So 309 with a rounding factor of 100 is 309/100 = 3 (as integer) add 1 gives 4, multiply back by rounding factor = 400)
Return the paymentAmount

transferPaymentBillingTransactions (Long paymentBillingTransferDetailId)

Returns List<PaymentBIllingTransaction>

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

CREATE_PAYMENT, CREATE_CHARGE

Activity requirement

 


Once the preparation of generatePaymentBillingAllowableList() and generatePaymentBillingSchedule() have been called, this method does the actual work of creating the transactions that make up the payment billing charges, and nets off the transactions that are financed.

persistPaymentBillingDetail (PaymentBillingDetail paymentBillingDetail)

Returns PaymentBillingDetail.
Persist paymentBillingDetail to the database.

reversePaymentBilling (PaymentBillingDetail paymentBillingDetail, Boolean removeFees, String memoText)

Permissions Information

 

Permissions Required to Call Method

REVERSE_PAYMENT_BILLING

Extended Permissions

 

Implied Permissions

REVERSE_TRANSACTION, CREATE_CHARGE, CREATE_PAYMENT

Activity requirement

LOGMEMO

<memoText>

 

FRIENDLY

Payment billing was reversed.


If a payment plan must be removed, this method will reverse the reversal transactions, and will reverse the charges that are the payment billing charges. If removeFees is TRUE, then the fee charges will also be reversed. A memo as passed in memoText will be created to explain why this has happened. The original transactions will therefore be eligible for payment.
This method clears the allocations on the account. PaymentApplication should be run before looking back to the account.

getPaymentBillingPlansByAccountId (String accountId)

Returns List<PaymentBillingPlan>

Permissions Information

 

Permissions Required to Call Method

GET_PB_PLAN

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Return all PaymentBillingPlan with accountId as passed.

getAccountsByPlanId (Int paymentBillingPlanId)

Returns List<String> (AccountId)

Permissions Information

 

Permissions Required to Call Method

GET_PB_PLAN

Extended Permissions

115

Implied Permissions

 

Activity requirement

 


Return all accountsIds that exist in PaymentBillingTransferDetail objects with paymetnBillingPlanId as passed.

getAllPaymentBillingPlans()

getPaymentBillingPlansByOpenPeriod(Date earliestStartOpenPeriod, Date latestStartOpenPeriod, Date earliestEndOpenPeriod, Date latestEndOpenPeriod)

getPaymentBillingPlansByChargePeriod(Date earliestStartChargePeriod, Date latestStartChargePeriod, Date earliestEndChargePeriod, Date latestEndChargePeriod)

Return List<Int> (paymentBillingPlanId)

Permissions Information

 

Permissions Required to Call Method

GET_PB_PLAN

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Return a list of the IDs of all PaymentBillingPlan with parameters as passed.

Reporting Service (Part of KSA-RR)

generate1098T ByYear(String accountId, int year, int numberOfDisplayedDigits, Boolean isTransient)

generate1098TReport (String accountId, Date startDate, Date endDate, int numberOfDisplayedDigits, Boolean isTransient)

Returns String (XML 1098T)

Permissions Information

 

Permissions Required to Call Method

GENERATE_1098_T

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Returns a representation of the federal 1098T form including the XML. Note that many of the parameters for producing a correct 1098T must be established in the system preferences, and transactions must carry the appropriate tags in order to be counted correctly.
Note that if year is passed, the startDate and endDate fields are assumed to be 1/1/year through 12/31/year. It is unlikely these dates would need to be changed.
If isTransient is passed as true, then the system will not keep a record of the produces 1098T. This option is ONLY to be used if the 1098T is being used to verify previous year's data, as the system does in order to complete the current year's return. This form will automatically be returned as void, and a paper 1098T should not be produced from this data.

get1098TReport (String accountId, Date startDate, Date endDate)

getIrs1098TReportByYear (String accountId, int year)

Returns String (XML 1098T)

Permissions Information

 

Permissions Required to Call Method

READ_1098_T

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


The method will get the most recent report for the account ID by the year.

generateAgedBalanceReport (List<String accountId>, Boolean ignoreDeferments, Boolean ageAccounts)

Return String.

Permissions Information

 

Permissions Required to Call Method

GENERATE_AGED_BALANCE_REPORT

Extended Permissions

 

Implied Permissions

READ_ACCOUNT, READ_TRANSACTION, AGE_ACCOUNT

Activity requirement

 


Produce an XML aged balance report for the accounts in the list. If ageAccounts is true, then each account will be aged before the report is run. If ignoreDeferments is true, then deferments will be ignored in the calculation of the balances, ONLY if ageAccounts is set to true.

generateRejectedTransactionReport (Date dateFrom, Date dateTo, Boolean onlyFailed)

generateRejectedTransactionReport (Date dateFrom, Date dateTo, Boolean onlyFailed, String entityId)

Return String.

Permissions Information

 

Permissions Required to Call Method

READ_BATCH_FAILED_REPORT

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Checks the batch records for transactions that have been sent and rejected. The method can filter by date range, and by entity. If no entity is passed, all batches in the date range will be included. If onlyFailed is set to true, only the transactions that failed on their own will be reported (i.e. if a whole batch was rejected due to a failure, the transactions that would have posted ok will not be reported.) If onlyFailed is false, all transactions that were not accepted, even those which were inherently "valid" will be reported.

generateAccountReport (List<String accountId>, Date fromDate, Date toDate, Boolean details, Boolean paymentApplication, Boolean ageAccount, Boolean ignoreDeferment)

Return String (XML document <batch-account-report>)

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

READ_ACCOUNT_REPORT

Activity requirement

 


Following the inherent logic of generateAccountReport, complete an account report for each of the accounts listed in List<String accountId>.

generateAccountReport (String accountId, Date fromDate, Date toDate, Boolean details, Boolean paymentApplication, Boolean ageAccount, Boolean ignoreDeferment)

Return String (XML document <account-report>)

Permissions Information

 

Permissions Required to Call Method

READ_ACCOUNT_REPORT

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Return an XML account report for the account id, between the dates listed. If details is true, then all transactions within the range will also be reported. If paymentApplication is true then paymentApplication() will be run before the account is reported. If ageAccount is true, the account will be aged before the report is generated. If ignoreDeferment is true, then deferments will be ignored in the aged balance section of the report.



generateTransactionReceipt (Long transasctionId)
Return String.

Permissions Information

 

Permissions Required to Call Method

READ_RECEIPT

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


generateIrs8300Report (CashLimitExceeded cashLimitExceeded)

Returns String

Permissions Information

 

Permissions Required to Call Method

GENERATE_IRS_8300

Extended Permissions

 

Implied Permissions

 

Activity requirement

FRIENDLY

User exported cash limit event.


System Preference Service

getPreference(String preferenceName)

Returns String.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


If the preference exists, return the value, otherwise throw an exception.

setPreference (String preferenceName, String value)

Return void.

Permissions Information

 

Permissions Required to Call Method

Internal.

Extended Permissions

 

Implied Permissions

 

Activity requirement

 


Check the user is permitted to change the system preferences, otherwise throw an exception.
If the preference does not exist, create, and incorporate the creator and creation time.
If the preference exists, update the value, and alter the editor and last update.

Services Service 

numberMask (String number, Integer numberOfDisplayedDigits)

Return String.
Mask the number passed to only show the last digits as passed in the parameter. The masking character can be found in security.masking.character.
take the value of numberOfDisplayedDigits and keep that number of the right-most digits. Replace the other digits with the masking character.
(ex. number = "123456789", digits=4, security.masking.character=X, return "XXXXX6789")

Third-Party Transfer Service [ThirdPartyTransferService]

The third-party billing service is responsible for the transfer of responsibility for transactions from a "student's" account to a third-party (sponsorship) account. Once the plans are established, the system can automatically calculate the appropriate transactions to transfer, in what amount, and move them to the third-party account.

generateThirdPartyTransfer (String accountId, Long thirdPartyBillingPlanId, Date initiatedDate)

Returns ThirdPartyTransferDetail.

Permissions Information

 

Permissions Required to Call Method

GENERATE_THIRD_PARTY_BILLING

Extended Permissions

 

Implied Permissions

CREATE_PAYMENT, CREATE_CHARGE, READ_ACCOUNT, READ_TRANSACTION

Activity requirement

 


This method takes an account and follows the established third-party plan and applies it to the account. The return value is a ThirdPartyTransferDetail object, explaining what occurred during the execution of the plan. This object is required to be able to re-run the plan in the future (for example, if future charges posts, that might also be placed into the plan) as well as to be able to reverse the plan, in the case of a third party who refuses to pay.

Non-divided funding flow.


*NOTE that the only transactions that we look at in this loop are those which have matched the pattern stored in transferMask*

Divided funding flow.

*NOTE that the only transactions that we look at in this loop are those which have matched the pattern stored in transferMask*

reverseThirdPartyTransfer (Long thirdPartyBillingDetailId, String memoText)

Returns ThirdPartyBillingDetail.

Permissions Information

 

Permissions Required to Call Method

REVERSE_THIRD_PARTY_BILLING

Extended Permissions

 

Implied Permissions

CREATE_PAYMENT, CREATE_CHARGE, READ_ACCOUNT, READ_TRANSACTION, REVERSE_TRANSACTION

Activity requirement

MEMOLOG

<memoText>


Check that the status of the thirdPartyTransferDetail is Active, then issue a reverseTransactionTransferGroup on the transferGroup, passing memoText as description, and true as partialAllocations. (There ought to be no partial allocations, due to the manner in which these transfer work.)
Set status to Reversed.
Set the student record in ThirdPartyPlanMember to isExecuted = false
Return the thirdPartyBillingDetail.

generateThirdPartyTransferForStudent (String accountId)

generateThirdPartyTransferForStudent (String accountId, Date overrideOpenPeriodDate, Boolean forceReexecution)

Returns List<ThirdPartyTransferDetail>

Permissions Information

 

Permissions Required to Call Method

GENERATE_THIRD_PARTY_BILLING

Extended Permissions

 

Implied Permissions

CREATE_PAYMENT, CREATE_CHARGE, READ_ACCOUNT, READ_TRANSACTION

Activity requirement

 


Get every ThirdPartyBillingPlan where the current date (or overrideOpenPeriodDate, if passed) is between openPeriodFrom and openPeriodTo, where the passed account appears in eligibleStudent.account and isExecuted is false, unless forceReexecution is true, in which case, ignore this requirement.
The, in descending order of eligibleStudent.priority, call generateThirdPartyBilling() on the account + plans.

generateThirdPartyBillingForPlan (Long thirdPartyBillingPlanId, Boolean forceReexectution)

Returns List<ThirdPartyTransferDetail>

Permissions Information

 

Permissions Required to Call Method

GENERATE_THIRD_PARTY_BILLING

Extended Permissions

 

Implied Permissions

CREATE_PAYMENT, CREATE_CHARGE, READ_ACCOUNT, READ_TRANSACTION

Activity requirement

 


For each eligibleStudent [] where isExecuted is false (unless forceReexecution is true, in which case, ignore this requirement) call generateThirdPartyBilling().
Note that executing by plan necessitates ignoring the priority value of eligibleStudent.

Key Pair Service [KeyPairService]

The key pair service is in charge of maintaining the CRUD operations on keypairs.

addKeyPair(Set<KeyPair> keyPairs, String name, String value)

Returns Set<KeyPair>
Check no keypair with the same name exists in the set, otherwise, remove it.
Add the name/value pair to the set of keypairs, setting creationDate to current date.
Persist the new keypair.
Return the set.

removeKeyPair(Set<KeyPair> keyPairs, String name)

Returns Set<KeyPair>
Remove from the set of keypairs the pair with the name passed in the parameters. If this does not exist, do nothing.
Remove the key pair from the database, too.
Return the new set of keypairs.

Kuali Student Services

The following services are Kuali services that are used by KSA. This is a non-exhaustive list.

Academic Time Period Service (ATP)

Referenced Version 1.0-rc2
(https://wiki.kuali.org/display/KULSTR/Academic+Time+Period+Service+v1.0-rc2)
ATP is used to set up time periods and is used primarily by fee management (for semester codes) and by the UI to present display options.

getAtpTypes getAtpType

getAtpSeasonalTypes getAtpSeasonalType getAtpDurationTypes getAtpDurationType

getMilestoneTypes getMilestoneType getMilestoneTypesForAtpType

getDateRangeTypes getDateRangeType getDateRangeTypesForAtpType

validateAtp validateMilestone validateDateRange

getAtp getAtpsByDate getAtpsByDates getAtpsByAtpType

getMilestone getMilestonesByAtp getMilestonesByDates getMilestonesByDatesAndType

getDateRange getDateRangesByAtp getDateRangesByDate

createAtp updateAtp deleteAtp

addMilestone updateMilestone removeMilestone

addDateRange updateDateRange removeDateRange

 

  • No labels