Skip to end of metadata
Go to start of metadata

Class Diagrams for

KSA-RM Class Diagrams

Repeated Patterns

There are a number of repeating patterns which are assumed to be generally understood. Many classes have a creatorId, editorId and lastUpdate set of attributes. creatorId references the identifier for the creating entity, and editorId references the last entity that altered the object. This identifier is the authenticated name of the user who created or changed the type, and mimics the accountId field of an account. In the default configuration, this is derived from the principal id from KIM, which is most often a login name, or net id (for example, in an institution using first initial/ last name, it would be jdoe, fsmith, etc.) creationDate is the date when the entity came into existence, lastUpdate is the date/time stamp when the entity was last changed. There is a name field which is the standard name of the type, and also have a "description" field, which is primarily used in the UI to assist the user in making a decision. There is also a code field, which is unique, and is used for matching the types in a simplified manner, for example in the XML import process, referenced types are referenced by" code" .For example, the class BankType defines different bank account details that might be stored. A type might be "ACH", and if the user enquires as to what that is, the system might explain what an ACH transaction is, and what information needs to be captured in order to use an ACH transaction. Many of these "Types" are extensions of the "AuditableEntity" class.
Any change to an object that has these fields will trigger an event in the activity log (Class Activity)
There are a number of "Type" classes, which are considered to be self-explanatory.
Class diagrams in green are defined more fully elsewhere in the document. Class diagrams in red are as yet undefined.
Attribute definitions are included where they are KSA classes.

Class Transaction Overview

The Transaction class is one of the most important classes in the KSA system. Transactions are stored in a table called KSSA_TRANSACTION and contain the fundamental information that is used to support a number of complex operations. Once a transaction is saved to the KSA ledger, few parts of it can be altered. (Exceptions would be allocation amounts, rollup identifier, etc.) The meaning of the attributes is defined in the data model documentation. If attributes are defined in this document, either implicitly or explicitly, and they conflict with the data model definitions, the data model definition is the document of record.

Class Transaction

Transaction is a purely abstract class. Its concrete classes are Charge, Deferment and Payment. Once a transaction has been set up with the minimum information (accountId, externalId, amount, responsibleEntity, debitType || creditType) These attributes cannot be altered once set, except for amount, in the case of a deferment.

Attributes and Definitions

If the following fields are not provided, they will be set to default values as listed. Some fields are automatically set on certain events.

FieldDescription

transactionId

Populated by the system when the save() method is called. When the transaction is written to the database, a unique identifier is assigned to the transaction.

account

References the account object to which the transaction belongs. Passed by the constructor.

creationDate

Populated by the system when the save() method is called.

effectiveDate (star)

Date of instantiation.

originationDate (star)

Date that the transaction is effective with respect to ageing.

recognitionDate (star)

Period for which the transaction is recognized on the general ledger. By default, this is set to the effectiveDate, unless overridden.

amount (star)

Amount of the transaction set during instantiation. In the case of a deferment, this can also be set when the amount of the deferment is reduced or expired.

nativeAmount (star)

As amount.

isGlEntryGenerated

False. Set when GL transactions are created.

currency (star)

System currency object.

internalTransaction (**)

False

allocatedAmount (**)

0.00

lockedAllocationAmount (**)

0.00

statementText (**)

Derive from defaultStatementText, through creditType or debitType.

document (**)

null

rollup (**)

Derive from defaultRollupId through creditType or debitType.

glType

Zero by default. Refers to the general ledger type from which GL entries will be produced.

isGlOverriden

Are the standard general ledger codes to be used, or are they overridden?

glOverride []

Range of different general ledger overrides for the transaction.

status

ENUM of transaction status of ACTIVE, REFUNDED, EXPIRED, CANCELLED, WRITTEN_OFF, BOUNCED, See transaction status StateChart below.

tag []

Array of tags. By default, when a transaction is created, it is given the tags of its debit or credit type. Once instantiated, other tags can be attached to individual transactions.

isOffset

Does the transaction have one or more offsetting transactions? If so, these can be located using the allocation system.

Credits and Children

FieldDescription

creditType (star)

Set by constructor.

creditTypeSubCode (star)

Inferred from constructor and date.

Deferments Only

FieldDescription

originalAmount

The original value of the deferment.

expirationDate (**)

This field is a required piece of information in order to establish a deferment. It should be noted that deferments are only created through the defer() method of a Charge (or any future derived class of Debit)

Payments Only

FieldDescription

clearDate (**)

The clearDate is calculated from the ledgerDate plus the default clearing period as referenced through the creditType model.

isRefundable (**)

False

refundRule (**)

Null

Debits and Children

FieldDescription

debitType (star)

Set by the constructor. The date of the transaction allows the construction of a pointer to the correct type of debit, including the subcode.

debitTypeSubCode (star)

Set by inference from date and debitType. Stored here for information only.

Charges only

FieldDescription

cancellationRule

As with refund rules for payments, this attribute stores the rules relating to when and if a charge can be cancelled ("credited") to the account. The use cases and format for this field are in the data model document.


Items marked with a (star) can be set either during instantiation (through overloaded constructors) or through appropriate setters, until the save() method is called. After that point, these values are set and cannot be changed. Any attempt to alter these attributes after the save() method has been called should produce an exception.
Items marked with a (**) can be altered after a transaction has been saved to the ledger. Note that not all can be altered with setter methods. For example, while a Charge can have its isDeferred attribute altered, this would only happen through a call to its defer() method.

Transaction Status State Chart

Standard Transactions

For a standard transaction (that is, a non-offset transaction) the following statuses are applicable.

An active transaction that is a deferment may be expired.
An active transaction may be Offset. Once offset, the transaction's allocations will tell us the nature of the offset.
An active transaction may be refund requested, whereupon it might become offset (by the refund) or returned to active, if the refund is not processed.

State

Applies to

Cause

Meaning

ACTIVE

All

Most transactions are created with this status.

A "normal" transaction. The status of the majority of transactions in KSA. Most all status changes can be performed on this transaction.

EXPIRED

Deferments

Deferment has either expired or has been manually expired.

There is no offset transaction to a deferment.

REFUND_REQUESTED

Payments

A refund has been requested (but not produced) against this transaction.

Status change only. This transaction will not have an offset transaction until it is refunded. After this status, the transaction can be returned to Active status.

Offsetting Transactions

The offset transaction is the negated transaction It will point to an Offset transaction. In this way, the Offset transaction can have a number of statuses, via the transactions that offset it.



When a standard transaction is moved to status of Offset, one or more offsetting transactions will be produced. In many cases, an offset will be for an entire transaction, however, it might not be a full offset. So for example, we might have transferred part of the transaction, but then had to write off the remainder. To deal with this multiplicity, it is the Offset transaction that holds the status of the offset. A standard transaction in offset status might point to one or more offsetting transactions via its allocations.
If an offsetting transaction is reversed (that is to say, the offset from the original transaction is undone, so for example, a Refund check is returned, so the offsetting transaction that created the refund must be 'removed') then we create a second offsetting transaction, and the status of both offsets (that is, an offset to an offset) will be set to ReciprocalOffset. No further actions can be taken with a reciprocal offset.

State

Applies to

Cause

Meaning

TRANSFERRING

Charges (Common)
Payments (Uncommon)

PB or TP systems have transferred this to another account.

Transaction has been transferred to another transaction (possibly on this account, possibly on another account). The fuller record for this can be traced via the TransferTransaction system.

CANCELLING

Charges

Transaction was cancelled due to error, staff judgment, etc.

The original transaction was cancelled. This might be partial reversal or a full reversal of the transaction, according to the cancellation rules.

WRITING_OFF

Charges (Common)
Payments (Uncommon)

Transaction was written off.

Transaction was written off. Write off transactions may be of a different transaction type to their base transaction.

REVERSING

Charges and Payments

A generic transaction reversal. This is the catch-all status for a transaction that can be returned to active state.

Generic reversal. It will have a corresponding Offset transaction. This is created by the reverseTransaction() method, and will often be changed by the higher-level method to a more specific Offset.

REFUNDING

Payments

Refund has been processed.

This was paid out as a refund (possibly to another account). The record for this will be held by the refund system.

BOUNCING

Payments

Payment has been marked as bounced.

Uncommon to reverse this type of Offset, as a bounced payment often has to be re-presented, and will be entered as a new transaction.

DISCOUNTING

Charges

A charge has been reduced (usually via fee management)

Most commonly, a discount will be produced via fee management, where a certain class of student will be charged the full amount, but then the tuition will be discounted, often back to a different transaction type.

RECIPROCAL_OFFSET

Offset of an Offset

A reversal of a reversal.

This transaction acts purely to reverse another offset. That is to say that a reversal has been reversed. Both offset transactions will be marked as ReciprocalOffset. They will be identical other than the amount, (one will be a negation) and they will be locked together. No further actions can be taken with a ReciprocalOffset transaction.

Class AbstractGlOverride

Simple associative class to permit the storage of general leger accounts and its breakdown percentages to the associated general ledger accounts, when overridden in the transaction. This class is abstract to create the GlOverride class, which is also used with FeeManagementManifest as FeeManagementGlOverride.

Attributes and Definitions

FieldDescription

generalLedgerAccount

Set by constructor.

percentageBreakdown

Set by constructor.

Class GlOverride

Child class of AbstractGlOverride.

Class Currency

The currency class stores information relating to currencies. Before a transaction can be denominated in a currency (including the system-wide currency) the currency must exist in this class. Instantiating a currency automatically causes a persistent copy of the currency. Currencies may be edited, but not destroyed.

Attributes and Definitions

All currency attributes are established during instantiation. There are no default values.
Though currencyCode is expected to be the ISO standard currency code, the system does not make any attempt to enforce this.

Class Document

The document class provides a way of storing information about a transaction that can be displayed to the user.

Attributes and Definitions

If the following fields are not provided, they will be set to default values as listed. Some fields are automatically set on certain events.

FieldDescription

documentId

Field is populated on instantiation.

document

The document is passed during instantiation.

creationDate

Date on which the document was created, populated on instantiation.

creatorId

Populated on instantiation

editorId

Null

editReason

Null

lastUpdate

Set to creationDate

Class Transaction Type Overview

Transaction types are fundamental to the way payments and charges are tracked, recorded, and allocated within KSA. Any transaction on the system has a Transaction Type, which defines a number of characteristics about the transaction. As an example, a transaction may have a transaction code of "SF100" which would show on a statement (by default) as "Mandatory Student Fee", and might reconcile to a specific general ledger account or accounts.
Transactions types can change over time. That is to say that the way a certain transaction code acts is not always constant. Because of this, transaction types are subdivided into sub-transaction types, which are defined by date ranges. To continue the example, SF100 might reconcile to one general ledger account until 12/31/2012, but on 1/1/2013, it might reconcile to a different general ledger account(s).
Sub-transaction types then divide into two major groups, which are credit and debit types.

Class Transaction Type

Sub-transaction Types and children

FieldDescription

transactionTypeId

Field is populated on instantiation. The identifier is freeform and is defined by the institution. An institution may use a predefined set of codes, for example a 3+3 identifier (like TUT001, is tuition, subcode 001). The identifier format is mostly irrelevant to the system.

subTransactionCode

Field is populated on instantiation. This is an automatic number field.

startDate

Unless otherwise provided, this is set to the current date.

endDate

Null. Note that a null in the dateEnd field implies that this is the current period. In the event of a new period being added that is defined as the current, the pervious current sub-transaction code must be brought to an end, by setting its dateEnd to the day preceding the dateStart of the new current sub-transaction code.

defaultStatementText

Must be set in the constructor.

tagArray

Null. This array is populated through the addTag() method.

priority

Set in the constructor. Note that priority is used as part of payment application. The lower this number, the lower the priority. 1 is a low priority, 100 is a high priority.

defaultRollup

Null

chainTransactionType

If the transaction has a chained transaction (a "co-requisite fee") this is the transaction type of that fee.

chainPercentage

Percentage of the amount of the transaction that is created as a chain transaction.

chainAmount

Flat amount that is charged as part of a chain transaction. There is an expectation (though not a requirement) that only one of these will be used.

generalLedgerBreakdown []

Assigned during creation.

Debit Type Only

FieldDescription

cancellationRule

As with refundRule for the credit types, this defines the rules for when a charge can be cancelled. See the data model document for the use cases and format for this value.

Credit Type Only

FieldDescription

creditPermission

Null. Set via method.

defaultClearingPeriod

0 unless overridden.

isRefundable

True unless overridden.

refundRule

Null unless overridden.

authorizationText

UI component that indicates the type of data that is required for the authorization for an external payment transaction.

unallocatedGeneralLedgerAccount

If the credit cannot be allocated to a charge, then this is the general ledger account that will record the unallocated amount. This may be referred to as "unearned income" or "suspense".

unallocatedGeneralLedgerAccountOperation

(C)redit or (D)ebit.

Class Rollup

Rollup is a very simple class that manages rollup identifiers. Rollups are a way of grouping types of transactions into a single, expandable group.

Attributes and Definitions

FieldDescription

Id

Populated at instantiation

name

Populated at instantiation.

creatorId

Derived from creating entity.

editorId

Null

lastUpdate

System date at instantiation

description

UI assistive text.

code

Short name that is used in XML documents to identify this rollup. This must be unique. Uniqueness is checked on instantiation.

Class GeneralLedgerType

Simple type class that allows the storage of more than one type of general ledger breakdown. For example, when a charge is transferred to a third-party account, a different set of accounting strings may be used.

Attributes and Definitions

FieldDescription

generalLedgerAssetAccount

Set at instantiation.

generalLedgerOperationOnCharge

Set to C(redit) or D(ebit). Answers the question, when a standard charge is resolved to this account, do we issue a credit or debit to the general ledger. Note that for payments, this field is ignored.

Class GeneralLedgerBreakdown

Simple associative class to permit the storage of general leger accounts and its breakdown percentages to the associated general ledger accounts.

Attributes and Definitions

FieldDescription

generalLedgerType

Named type of the general ledger breakdown, allowing assignment of the transactions to different general ledger accounts (for example, third party, payment billing, etc.)

generalLedgerAccount

Set by constructor.

generalLedgerOperationOnCharge

Set to C(redit) or D(ebit). Answers the question, when a standard charge is resolved to this account, do we issue a credit or debit to the general ledger.

percentageBreakdown

Set by constructor.

Class CreditPermission

Simple associative class to store the permissible debit array for a CreditType.

Attributes and Definitions

FieldDescription

creditPermissionMask

Set by constructor.

priority

The lower this number, the lower the priority. 1 is a low priority, 100 is a high priority.

Class Tag

Tags are very similar to rollups, except a transaction may have more than one tag, whereas it may only have one rollup.

Attributes and Definitions

FieldDescription

Id

Populated at instantiation

Name

Populated at instantiation.

creatorId

Derived from creating entity.

editorId

Null

lastUpdate

System date at instantiation

isAdministrative

Boolean defining if a Tag is an administrative tag, and therefore needs a higher level of authorization to alter or add this Tag to a Transaction or Transaction Type.

description

Set during instantiation

code

Simplified name of the tag that can be passed to the system from other systems (example, via an XML upload).

Class Allocation

The allocation class keeps track of all allocations made for an account. Although each transaction carries the allocation amounts (both locked and "unlocked") this is insufficient for reversing allocations, and it is a summary of all the allocations made on a transaction. The allocation class is used to record which transaction was allocated to which transaction, for what amount, and whether or not the allocation was a locked allocation or a regular allocation (payment application cannot reallocate locked allocations, whereas regular allocations can be reallocated automatically by the system, and cleared before payment application.)

Attributes and Definitions

FieldDescription

Id

Identifier for the allocation. Automatically generated at instantiation.

firstTransaction

The first of the two transactions that are allocated together. Passed by constructor.

secondTransaction

The second of the transactions. Passed by construction.

isLocked

States the type of allocation. Passed by constructor.

isInternalLocked

If the allocation isLocked, then it may also be internally locked, which will require a higher level of authorization to unlock. In general, these locks are created via internal processes such as refunds that ought not to be unlocked without specific reasons.

amount

Value, in system currency, of the allocation. Passed by constructor.

Transaction Type Notes for UI – Altering a Transaction Type

Generic

It is generally a bad idea to alter a transaction type once it has been used by the system. However, this will happen. The following is a list of potential problems and ideas for how the UI might handle alterations.

Attributes that cannot be changed by the end user:

id [transactionTypeId], code, creatorId, editorId, creationDate, lastUpdate, subTransactionCode

Attributes that can be changed with minimal effect

priority, any items in the creditPermission [], authorizationText
The first two alter how payment application work, so a change here will affect the next run of payment application, but as a dynamic process, this is expected to change. The authorizationText is used as a UI tooltip, and as such, will only alter the UI. There is a possibility that a change here will render the externalid data inconsistent (if you were formerly asking for a check number and now you are asking for a routing number) but this information is not validated in any way, so the effect on the operation of the system is negligible.

Attributes that can be changed but have an impact

Attribute

Problematic Consequences

Use Cases for Change

Potential ways to reduce the problem

startDate

Changes to the startDate CANNOT make a transaction type overlap, so this will not be allowed.

However, a startDate could be moved earlier if (a) a prior period did not exist or (b) that period has been moved to allow the change.
Any transactions that have already occurred will have been rejected.

A window of time needs to be altered. This should be relatively infrequent.

Need a mandatory memo.
No real impact on the current data because transactions that did not match will have been rejected.

endDate

Changes to the endDate CANNOT make a transaction type overlap, so this will not be allowed.
Changes to the endDate will render any transactions falling between the new endDate and the old endDate no longer compliant with the new transaction type.

Erroneous entry of dates, unforeseen change.

Mandatory memo.
List of transactions that are now non-compliant (those that fall in the suspect date range)
Very high level of authorization required to do this.
Warn user that the old transactions remain on the system, if their GL entries are generated, this will not change, etc.
Realistically the only way to get around this and get the system back into compliance with its own data is to reverse these noncompliant transactions and reissue them.

defaultStatementText

All new transactions will have the new statementText. Older ones will not, unless we propagate.

Mistake made in name.

Mandatory memo.
Option to propagate. Note that this will overwrite any statementText entries that were overridden.

tagArray []

All new transactions will have the new tagArray []. Older ones will not, unless we propagate.

Sudden need to add a tag – Most likely for mandatory tagging of an item that is included in a special report.

Mandatory memo.
Option to propagate. Note that we should be aware of the CHANGE, and only add or subtract tags that were added or subtracted by the user – not just a blanked overwrite of the whole tagArray [] (unless requested?) Propagation should be very limited to certain users.

rollup

As with Tag.

Incorrect rollup entry.

Mandatory memo.
Option to propagate.
This would overwrite all current rollup entries for this type of transaction.
Propagation should be very limited to certain users.

cancellationRule/
refundRule

Already refunded or cancelled transactions are impossible to reverse.

Incorrect entry at creation time, or change to the policy of the school.

Mandatory memo. Option to propagate to current Active transactions. Notify the user that certain transactions will not be affected.

isRefundable

Setting this to false cannot pull back refunds that have already been made.

Incorrect entry at creation time, or change to the policy of the school.

Mandatory memo. Option to propagate to current Active transactions. Notify the user that certain transactions will not be affected.

defaultClearningPeriod

Setting this forward cannot be used to deny a refund once it has been created. Given the short period of time for a clearing period, it might not even be worth altering the former clearing periods.

Incorrect entry at creation time, or change to the policy of the school.

Mandatory memo.
Option to propagate might be overkill?

Attributes that can be changed but will leave the system inconsistent (which might be desirable)

Attribute

Problematic Consequences

Use Cases for Change

Potential ways to reduce the problem

unallocatedGeneralLedgerAccount
unallocatedGeneralLedgerAccountOperation
generalLedgerBreakdown []

Any transactions already created and/ or made effective would be inconsistent. There is no (easy) way to propagate these changes.

Note that for the glBreakdown [] this only affects transactions where isGlEntryGenerated is true. makeEffective() with force as an option could clear these transactions.

Error.
Moving to a new GL account once an old one is required (example – After the end of a term, USC points transactions to "prior-term charges")

Mandatory memo.

List transactions affected.

There is no option to propagate.

The only way to get the system back into pure compliance with itself would be to reverse the affected transactions, make the change, and then add the transactions back.

Class Activity Overview

The activity class is a structure for logging events within the system. All items are set during instantiation and the object is persisted. All attributes have standard getters, but post-instantiation, there is no setters for the values.

Activity

Attributes and Definitions

FieldDescription

date

Set to system date at instantiation

ipAddress

Set in constructor.

creatorId

Set in constructor.

alteredAccountId

Set in constructor.

alteredEntity

Set in constructor.

alteredEntityId

Set in constructor.

alteredEntityProperty

Set in constructor.

logDetail

Set in constructor.

oldAttribute

Set in constructor

newAttribute

Set in constructor.

level

Set in constructor.

activityType

Set in constructor.

Methods

There are standard getter methods for all the attributes, but no setters.
The constructor must pass all values, except date (populated with system date at point of instantiation). The MAC address is optional. alteredAccountId is optional if a global entity is altered (example, Currency).

ActivityType

Attributes and Definitions

FieldDescription

identifier

Set during instantiation.

activityName

Set in constructor.

creatorId

Set during instantiation.

editorId

Null

lastUpdate

System date.

Methods

editActivityTypeName (newActivityName)

Validate the name, then place into object.

Class Information Overview

 

The information class is a class that is used to store different types of information about either accounts or transactions. There are three basic types of information. Memos, which are freeform text items, which can be entered by CSRs, to provide a history of when and why certain things have happened on the account. Certain automated events may also trigger memos to be created (for example a fee assessment, or an online payment might trigger a memo event). Alerts are similar to memos, but they are displayed to the user in a different way, and are considered more transient. Alerts are freeform, and could be used for any number of purposes, but fundamentally, an alert is used to bring important information to the attention of the user. Flags are equally used to bring important information to the attention of the user, however, unlike alerts, flags are always of a pre-defined type, and can therefore be used as part of a rule making process. For example, a student might have bounced a check, so the "Bounced Check" flag is set. This value may be used in the rules system to decide if they are allowed to pay by check in the future. A severity attribute also allows the engine to distinguish between levels of a flag. To continue the example, a client who bounces a check once might have a low severity assigned, however, if a second check is bounced, the severity is set to high.

Class Information

Attributes and Definitions

FieldDescription

Id

The unique identifier for the piece of information. Generated on instantiation.

responsibleEntity

Populated at instantiation.

creationDate

Established automatically at instantiation.

account

Established at instantiation

transaction

If applicable, established at instantiation. Otherwise set to null.

effectiveDate

Set on instantiation either through constructor or default to system date.

expirationDate

Initially set to null.

accessLevel

Set on instantiation. In the case of a flag, this value is derived from FlagType.accessLevel.

Class Memo

Attributes and Definitions

FieldDescription

Memo

The actual plain text of the memo, set during instantiation.

nextMemo

Null. This value is set when createFollowUp() is called

previousMemo

Null unless created through createFollowUp()

Class Flag

Attributes and Definitions

FieldDescription

flag

Created by the system on instantiation.

severity

Set by the constructor.

Class FlagType

Attributes and Definitions

FieldDescription

flagId

Created by the system on instantiation.

name

Set by the constructor.

creatorId

Set during instantiation.

accessLevel

Set during instantiation

description

Set during instantiation.

Class Alert

Attributes and Definitions

FieldDescription

alertText

Set during instantiation.

Class Account Overview

Helper Classes

The Account class is a central class that permits the system to tie together the transactions and other information into meaningful pieces of information that can then be used as the basis for billing, and for access to the system. In most instances, most of the information in the Account class is derived from KIM. Wherever possible, authorized changes to identity information made in KSA will be passed back to KIM.
The following helper classes are used to manage personal information relating to the different accounts. They are referenced in several of the account classes. The attribute initial values are either set by constructor, or are harvested from KIM.

Class PostalAddress

Attributes and Definitions

FieldDescription

kimAddressType

KIM is capable of storing several types of addresses. (Home, Office, Permanent, Billing). As KSA is not a system of record for the student address, it links its addresses to the KIM store. This field records the address type that was pulled from KIM. Is this field is null, then the address is a "local" address (i.e. local to KSA) and is therefore not copied from, or to be returned to KIM.

addressLine1

The first line of the address, in most cases, as returned from KIM.

addressLine2

The second line of the address, in most cases, as returned from KIM.

addressLine3

The third line of the address, in most cases, as returned from KIM.

city

The name of the city in which the address lies. No political distinction is made in the data model between different types of areas, as may be the case in certain locales.

stateCode

If the address contains some form of subdivision code (most commonly US states, Canadian provinces, etc.) it is stored here.

postalCode

If used, a postal code.

countryCode

ISO 3166 country code.

isDefault

False.

Methods

setAddressType (newKimAddressType)

Validate that the new KIM address type is valid for the student. If the address is appropriate (as defined by business rules, then get the new address from KIM and import it into the class.

setAddress ( newAddress)

If the new address has a KIM type, import and attempt to update KIM. Where KIM cannot be updated (due to validation or policy) set the address type to null.

Class ElectronicContact

Attributes and Definitions

FieldDescription

kimEmailAddressType

KIM is capable of storing several types of email address. (Home, work) As KSA is not a system of record for this information, it links its addresses to the KIM store. This field records the address type that was pulled from KIM. Is this field is null, then the address is a "local" address (i.e. local to KSA) and is therefore not copied from, or to be returned to KIM.

emailAddress

Set from KIM or by passed value.

kimPhoneNumberType

As with other KIM types, the type flag, to locate the phone number within the KIM system.

phoneCountryCode

Country code, stored in ISO format (gb, us, fr, sv, etc.)

phoneNumber

The full telephone number of the contact.

phoneExtension

An Extension to the phone system, if needed.

isDefault

False.

Class BillReceiver

Attributes and Definitions

FieldDescription

personName

Set at instantiation

postalAddress

Set at instantiation.

electronicContact

Set at instantiation.

preferredContactMethod

Set at instantiation.

creationDate

Set by the constructor.

entityId

Set by the constructor.

editorId

Set by the setter methods.

lastUpdate

Set by the setter methods.

releaseAgreedBy

Set at instantiation.

releaseAgreedDate

Set at instantiation.

Class AccountAuthorization

Attributes and Definitions

FieldDescription

authorizedAccount

Account which has had access granted to it.

dependentAccount

Account which has had access (to authorizedAccount) granted to it.

agreementDate

Date/time stamp when the account was given access.

Class CollectionAccount

Attributes and Definitions

FieldDescription

agencyAccount

Idenitifer of the collections account.

accountInCollection

Identifier of the account that has been assigned to collections.

startDate

Timestamp when the account was assigned to this agency.

endDate

Timestamp when the account was cleared from this collection agency. If null, it is currently assigned to this collections agency.

Class AccountProtectedInformation

AccountProtectedInformation stores potentially sensitive data. All access to this class is audited. These data are stored in a different table to other account information fields, and few accounts that have direct access to the database tables would have any type of access to this table. The class stores three major types of protected information, tax information (commonly the social security number in the US) banking information (usually ACH routing information in the US) and identity validation information (for example a passport or driver's license). These types of information can be configured in TaxType, BankType and IdentityType which are standard dictionary types in the KSA system.

Attributes and Definitions

FieldDescription

taxType

Defined tax type, as stored in TaxType.

taxDetail

The actual tax identifier as described by TaxType.

bankType

The bank type being defined, as stored in BankType

bankDetail

The actual bank details, as described by bankType

identityType

The type of identity that has been seen.

identitySerial

The serial number of the document proving identity.

identityIssuer

The issuing authority responsible for the document.

Class Account

Accounts in KSA are one of the primary classes that tie together huge amounts of data within the system. All accounts have an accountId, which is used throughout the system to label transactions and memos as part of the same group. Accounts can either be ChargeableAccount (ones that can have charges levied against them) or NonChargeableAccount, for example, a parental account which exists solely to provide access to their son or daughter's account.

Class Account

Attributes and Definitions

FieldDescription

accountId

Generated automatically by KSA, or imported from KIM.

status

Null, set via method.

accountType

Null, set via method.

entityId

If the account is populated from KIM (an Authenticated account) then this value will be set during instantiation. If this is an unauthenticated account, this value will be null. If this is a non-KIM based account, coming from an external system, this will be the identifier from that system.

lastKimUpdate

When the account is a KIM account, this is set to creationDate on instantiation.

isKimAccount

Boolean. If true, the account is derived from KIM. If false, the account is KSA specific.

canAuthenticate

Boolean. If true, the account is permitted to authenticate into the KSA system. If false, this is not permitted.

personName

List of personName objects associated with this account.

entityName

Pointer to a single entity name for this account. If this is empty, then this is a personal account.

address

Address of the account owner. See Class Address. Set during instantiation either by value, or derived from KIM.

electronicContact

Email and telephone number of account holder. See Class ElectonicContact. Set during instantiation either by value, or derived from KIM.

information

List of Information objects.

userPreference

Array of objects of type UserPreference.

protectedInformation

Link to the protected information fields for the account.

creatorId

Identifier of the user who created the account.

creationDate

Set to system date at instantiation. This is the date the account was created in the KSA system.

editorId

Identifier of the user who last edited the account.

lastUpdate

Date and time of the last update to the account.

keyPair

Map of keypair object, used primarily by KSA-FM

Class NonChargeableAccount

Abstract Class

Class DelegateAccount

Special account type that can only be used to access third-party account information through the web portal. This type of account cannot accept charges

Attributes and Definitions

FieldDescription

permittedAccount

List of PermittedAccount objects.

Class Delegate Account

No extended attributes.

Class CollectionAgencyAccount

Attributes and Definitions

Class ChargeableAccount

Abstract Class.

Attributes and Definitions

FieldDescription

transaction

Links to all transactions on the account.

balanceOutstanding

0.00

balanceDue

0.00

unallocatedAmount

0.00

latePeriodDefinition

Set to the default LatePeriodDefinition

period1Late..period3Late

0.00

lastLateUpdate

Null at instantiation. Set to current date and time when ageing process runs.

creditLimit

Set to default for system at instantiation.

billReceiver

List of BillReceiver objects- allows the bill for this account to be sent to multiple places.

accountPermission

Set of accountPermission objects.

Class DirectChargeAccount

The direct-charge account is the most common type of account. It could be generalized as a "student account" however, many institutions extend the use of these accounts to non-student actors (for example, a childcare facility extended to students might also allow faculty to use the service, and have their "student" account be billed for the charges. As such, the account is a direct-charge account, which is defined as an account which may be billed directly for charges. This would differ from a sponsor account, which is traditionally billed indirectly for activities accrued on another account.

Attributes and Definitions

FieldDescription

dateOfBirth

Set during account setup from KIM or external source.

Class ThirdPartyAccount

Attributes and Definitions

FieldDescription
  
  

Class LatePeriod

In general, accounts are aged on a 30/60/90 day period. In KSA, they are measured relative to the effectiveDate of the transaction. To provide flexibility, the LatePeriodDefinitions permits the creation of other late period types, to be applied to certain types of accounts. The envisioned use case is to permit sponsor accounts longer periods of time to pay.

Attributes and Definitions

FieldDescription

latePeriodId

Autonumbered field.

name

Set by constructor.

period1LateDays.. period3LateDays

Set by constructor.

description

Set by constructor, information to tell admin when a late period is appropriate.

isDefault

False

Class AccountStatusType

Account statuses will provide a very basic ability to enforce certain holds on the account. These are not yet defined.

Attributes and Definitions

FieldDescription

Id

Autonumber set during instantiation.

name

Set in constructor.

description

Set in constructor.

Class AccountType

The account type is used to provide configurable account types to the system, so that an institution can stream account holders into different "buckets", for example by year of study, or by program, etc.

Attributes and Definitions

FieldDescription

Id

Autonumber set during instantiation.

name

Set in constructor.

description

Set in constructor.

Class AccountName

AccountName is the abstract class to used to wrap the personal or company name record.

FieldDescription

creatorId

Creator of the name record.

creationDate

Date the record was created.

editorId

Editor of the name record.

lastUpdate

Last time the name record was updated.

kimNameType

The name type as it is stored in KIM, or, if null, this is a local name, which will not be pulled back from KIM.

Class PersonalName

Attributes and Definitions

FieldDescription

firstName

First name of the entity.

middleName

Middle name of the entity.

lastName

Last name of the entity.

suffix

Suffixed part of name, including generation codes.

title

Preferred title, ex. Mr. Miss, etc.

isDefault

Is this the default name record.

Class OrgName

Attributes and Definitions

FieldDescription

orgName

Name of the organization.

contactName

Name of the contact person for this organization.

Class UserPreference

UserPreference are used to store simple key/value pairs for the user. These can be accessed easily to allow the system to be configured to the individual user.

Attributes and Definitions

FieldDescription

name

Set during instantiation.

value

Set during instantiation.

Class GeneralLedgerTransaction and GeneralLedgerTransmission Overview

As different types of transactions are recorded within the KSA module, frequently, those transactions have to also be recorded on the general ledger. A number of configurable factors go into the derivation of the correct amount and general ledger accounts to which a transaction is sent, and a fuller description of these factors can be found in the explanation of the Transaction class. Once it is discerned that a transaction will be transmitted to the general ledger, and the appropriate accounts and amounts have been discovered, a GeneralLedgerTransaction is instantiated. This records the value being transmitted to the general ledger, as well as a reference to the KSA transaction that causes the general ledger transaction(s).
The GeneralLedgerTransmission class is responsible for the actual transmission of transactions to the general ledger. Depending on configuration, transactions may be transmitted in real time, in batch by transaction, or in rolled up batches.

Class GeneralLedgerTransaction

Attributes and Definitions

FieldDescription

glTransactionIdentifier

A unique transaction identifier for this transaction. This is assigned at instantiation.

glTransactionDate

Datetime stamp when the general ledger transaction was generated by KSA.

transaction []

Pointer to the transaction that generated this entry. Passed by the constructor. If the GL transaction is collapsed from a group of transactions by the session cleanup after payment application, this can be an array of transactions.

glAccount

Passed by the constructor.

glRecognitionPeriod

Recognition period based on the transaction.

glOperation

Either CREDIT or DEBIT.

amount

Passed by the constructor.

status

Defaults to Q (queue) or W (Waiting). Other values as the transaction processes are P (set to process) and C (completed processing). F (failed) means the transaction did not get sent to the general ledger.

transmission

Null. Pointer to the GeneralLedgerTransmission. This value will be null until status is C.

statement

Passed by the constructor. This string is used to assist a power user to understand where the transaction was generated. In most cases, GL transactions will be generated through the makeEffective() method, which will create general ledger transactions, or by the paymentApplication() method.

Class GeneralLedgerTransmission

Attributes and Definitions

FieldDescription

glTransmissionIdentifier

Autonumbered field set during instantiation.

generalLedgerAccount

Set by constructor

glRecognitionPeriod

Recognition period for the transmission.

glOperation

Either {CREDIT or DEBIT}

amount

Set by constructor.

transmissionTime

Null at instantiation. Set when the actual transmission is made to the GL.

batchIdentifier

Null at instantiation. Set when the transmission is made to the GL in batch mode.

status

Enumeration of {QUEUED, TRANSMITTED, COMPLETED, FAILED}

generalLedgerTransactionArrray

Set by the constructor.

generalLedgerExport

Null at instantiation. Once the actual transmission has been created, this will point to the actual transmission.

Class GeneralLedgerExport

Attributes and Definitions

FieldDescription

creationDate

Created at instantiation.

entityId

Created at instantiation.

transmissionData

Passed by constructor.

baseLineAmount

List of Mapped Strings and amounts. The Strings will be the name of the GL Types (accrual accounts) or unallocated cash, and the amount will be the amount in KSA that relates to that account/ cash. This will be used to reconcile KSA against the general ledger.

Class GeneralLedgerRecognitionPeriod

Attributes and Definitions

FieldDescription

startDate

Initial date of the general ledger recognition period. Any transaction with a recognition period on or after this date is part of this recognition period.

endDate

End date of the recognition period. Any transaction with a recognition period up to this date is in this recognition period. If this date is null, only the dateStart needs to be checked (as it is current).

recognitionPeridCode

Period code for the recognition, institution specific.

fiscalYear

Code for the fiscal year (often a four digit year number).

code

Specific recognition period code. For example, FALL, SPRING, T1, T2, etc.

Class GeneralLedgerBatchBaseline

The baseline account is the totals from the GeneralLedgerType objects plus unallocated cash, plus deferments as stored at the point of a full export of general ledger transactions from KSA.

Attributes and Definitions

FieldDescription

glBatchIdenifier

The batch identifier (from GeneralLedgerTransmission) that this baseline is associated with.

baselineAmount

List of GlBaseline objects.

Class GlBaseline

Attributes and Definitions

FieldDescription

baselineType

Enum value for the baseline type. Can be GL_TYPE meaning it is one of the general ledger types. The reference to type will be in glType. Or DEFERMENT or UNALLOCATED_CASH

glType

If baselineType is GL_TYPE this will point to the appropriate general ledger type.

Amount

Amount of the line.

Class GeneralLedgerAllowableAccount

A simple class that stores a list of allowable accounts (as account numbers or as regular expressions) that can be used to validate the general ledger account numbers when they are entered into KSA. This is a simple validation process that can be replaced with a more integrated solution with general ledgers that are able to perform real-time account number validation.

Attributes and Definitions

FieldDescription

allowableAccountMask []

Array of String objects that store valid account numbers or regular expressions that represent allowable account numbers.

Class FailedGlTransaction

Simple class to store failed general ledger transactions.

Attributes and Definitions

FieldDescription

transactionId

The transaction against which a gl transaction could not be made.

creationDate

Last recorded attempt at making the transaction effective.

reason

Error reported by makeEffective()

isFixed

Is the transaction now cleared.

Class UserInterfaceString and InstalledLanguage Overview

These classes support UI localization by permitting simple lookups against a locale parameter and a UI identifier. So long as the appropriate language pack has been loaded, the system should be able to communicate with the user in that language. There is also a simple dictionary service called Language that can take the language code and give a name for use in the UI.

Class UserInterfaceString

FieldDescription

locale

Passed by the constructor.

maxLength

Passed by the constructor.

userInterfaceId

Passed by the constructor.

userInterfaceText

Passed by the constructor. If the value is set by a setter, then isOveridden should be set to TRUE.

isOverriden

Set to false if the string comes from an XLIFF file. If the string is overridden internally, then this is set to true. The value of this alters how the system deals with imports after strings have been changed.

Class Language

FieldDescription

locale

Specific code used to refer to a language, passed by the constructor.

Class CashLimitExceeded Overview

This class exists to store information on accounts that have exceeded the amount of cash that can be passed through them without flagging the transaction to the IRS. The system is designed specifically to monitor the "combined cash limit tracking" as required by U.S. law, and to ease the filing of IRS form 8300. However, the system has been designed to be flexible enough to be used under other tracking systems that may exist in other countries. The cash limit, time period over which it is tracked, and which types of transaction are traced over the period of time.
Many of these attributes could be extracted by reference, however, this class is used to take a snapshot of the account at the time when the event happened, so that it can easily be transformed into a form and sent to the IRS or other body.


CashLimitParameter

The cash limit parameter objects are used to store the details of transactions that trigger a cash limit event. Other transactions relating to the cash tracking system are established in the ksa.properties file. These include cash.tracking.* and 8300.*

Attributes and Definitions

FieldDescription

tag

Tag of the transaction that is invoked. For example, the IRS requires all "cash" transactions to be counted (using a very inclusive definition of cash) so all transaction will have that specific tag. (see ksa.properties) however, the IRS also requires that the "cash" be broken down further. This is the more specific tag, for example, "foreign currency", "money order" etc.

lowerLimit

If the "cash" is to be ignored under a certain amount, then this is that value. Currently, there is no lower limit supplied for the 8300.

upperLimit

If "cash" is to be ignored over a certain amount, the this is the value. Certain cash instruments are currently ignored by the IRS if they exceed $10,000.

isActive

Boolean, describing if this cashLimitParameter is currently in force.

friendlyName

The name of the subgroup, as understood by the user. (for example, "Money orders, postal order, etc."

authorityName

The name of the subgroup as defined by the taxing authority (in the default case, the IRS). For example, the name that would be used on the formal paperwork. (For example, "Section 32(d) – Money Order")

xmlElement

The name of the category as it will be designated in the XML version of the form. For example "money-order". This will be recorded for an irs-8300 under <transaction-description><detail><type>

Class CashLimitExceededEvent

Attributes and Definitions

FieldDescription

accountId

Account to which the overage relates.

creatorId

The user who placed the transaction on the account that triggered the cash-limit flag. For example, if the transaction were passed via a cashier, it would be the id of that user.

dateOfEvent

The date on which the event (transaction that caused the event) occurred.

payments

Set of payments that make up the event.

totalPaymentAmount

Sum of all the payments that have caused the event.

totalChargeAmount

Total amount being paid by the cash transaction.

isMultiplePayments

Boolean indicating whether or not this transaction is a single transaction or is composed of multiple transactions.

serialsOfInstruments

Serial numbers of any known monetary instruments used in the transaction. This is a generated string.

notificationSentTo

Email address of the person to whom the email notification was sent (derived from cash.tracking.notify)

notificationSentDate

Date when the notification email was sent to notificationSentTo.

status

Status of the transaction. Q for queued, C for complete, I for ignored. At this time there is no use case for Ignored.

reportingCompleteDate

Date when the legal reporting requirement was met. For the initial use of this feature, this will mean the date on which the 8300 was filed. This date will be generated when the 8300 is generated by KSA.

summaryElements []

Array of type CashLimitExceededExtendedElements used to store extended values for the cash-limit tracking. These values are manipulated during the processing logic.

externalDocument

The generated XML document for this event.

Class CashLimitExceededExtendedElements

Simple key-pair value class linking to the CashLimitExceededEvent. This is used by the rules engine to establish other values that are used to complete the cash-limit tracking form (8300 in the US.)

Attributes and Definitions

FieldDescription

friendlyName

Name of element as understood by a user of the system, derived from cashLimitParameter.friendlyName

xmlElement

XML identifier for the element, derived from cashLimitParameter.xmlName

amount

Amount of the summarized transactions.

nativeAmount

The amount of the transactions in the native currency. For "foreign currency" transactions, this field will be used to fill out the "amount of foreign currency" line on the 8300.


The XML names for the types can be anything, however, for the purpose of consistency for the reference implementation, they are as follows.

NameDescription

us-currency

Amount of the transaction composed in native currency.

foreign-currency

Amount of the transaction composed in a foreign currency.

cashiers-check

Amount of the transaction composed of cashier's checks.

money-order

Amount of the transaction composed of money orders.

bank-draft

Amount of the transaction composed of bank drafts.

travelers-check

Amount of the transaction composed of traveler's checks.


The types of transaction are defined in the enumeration of the XML document. For completeness, they are listed here.

TypeDescription

personalproperty

Personal property, defined 33(a) of 8300.

realproperty

Real property, defined 33(b) of 8300.

personalservice

Personal service, defined 33(c) of 8300.

businessservice

Business service, defined 33(d) of 8300.

intangibleproperty

Intangible property, defined 33(e) of 8300.

debtobligation

Debt obligation, defined 33(f) of 8300.

exchangeofcash

Exchange of cash, defined 33(g) of 8300.

escrow

Escrow of trust funds, defined 33(h) of 8300.

bail

Bail received by court clerks, defined 33(info) of 8300.


Anything passed here other than these, will result in the creation of an "other" category, and the detail passed will be used to define "other" in section 34 of the form.

Class Refund Overview

The refund class is used to record the issuance of refunds. Refunds may be provoked by a number of actions, automated batch processed, user request, CSR request, but essentially, the system will go through a rule-based procedure to calculate which unused payments are eligible for refunds, how they are eligible (not all refunds happen in the same way, for example, check and cash payments may be refunded as a check, credit card payments may be refunded to the credit card, etc.)
Once the refund has been entered into this class, it will be picked up by the appropriate subsystem that will generate the actual refund, which will generate the actual refund transaction, and create a locked allocation between the refund and the payments that were refunded.

Class Refund

Attributes and Definitions

FieldDescription

refundId

Autonumber identifier provided by at instantiation.

requestDate

Date of the request of the refund.

transactionToRefund

Identifier of the transaction that is being refunded. Furnished at by constructor.

amountToRefund

Value of the refund in system currency.

refundType

Pointer to the type of refund being issued. Passed by constructor.

refundAttribute

Depending on the type of refund, the attributes associated with creating that refund. For example, for an ACH refund, the ACH bank information needs to be passed. Null at instantiation unless passed by a constructor.

overrideStatementText

Override text for account refunds only – when account refund is made, by default, the text will be defined by the transaction type for the refund. If this attribute is set, then this field will be used instead.

requestedBy

Entity identifier of the user who requested the refund. Likely values will be the user who ran a refund job, or the student requesting their own refund. Passed by the constructor.

authorizedBy

The user who authorized the refund. Null at instantiation.

refundDate

The date the refund was applied to the KSA account. Null at instantiation.

refundTransaction

The transaction that is the produced refund. This will be null at instantiation until the actual refund is produced. Note that a number of transactions may have a single refundTransactionId, as one large refund may be issued to cover several smaller credits.

refundStatus

A refund may be Unverified, Verified, Failed, Cancelled or Active. Once a transaction is refunded, the refundTransactionId must be completed. Set to U at instantiation.

refundSystem

Null at instantiation. Stores the refund system that creates the refund in plain text to assist tracing a refund.

refundBatch

Null at instantiation. Stores batch identifier, if the refund is run as part of a batch process.

refundManifest

Null at instantiation. References a RefundManifest object, which records how the refund was actually manifested. For example, if the refund is given as a check, we will record the check number, if an account refund, the transaction Id and the KSA account number.

refundGroup

If several refunds are issued under a single refund header (i.e. four transactions are refunded, but only one check is issued) then the refund group of all the refunds will be the same. This will be a UUID.

Class RefundType

Attributes and Definitions

FieldDescription

refundDebitType

The transaction type for refunds that are made by this type. This is a debit type ("charge"), as it deducts the overpayment from the account.

refundCreditType

For refund types that send the refund back to a KSA account ("Account Refunds", "Payoff Refunds") this is the credit type ("payment") that will be applied to the other account. For most refund types where the money is sent

Class RefundManifest

Note that KSA is only responsible for the manifestation of account refunds (that is, the credit that is made to an external party is most often handled by another system (check writer, ACH processor, etc.) therefore these fields will only be recorded if the external system can report back the identification of the document/ transaction to KSA. In the case of an account refund, KSA will store the appropriate values automatically.
It is advised in implementation that values stored in the otherIdentifier box are prefixed with the type (for example PAYPAL:, etc.) in order to allow for future expansion.

Attributes and Definitions

FieldDescription

checkIdentifier

Open field, usually storing the check number issued to the user.

ksaAccountIdentifier

If the refund is an account refund, then this will store the account identifier where the funds were sent.

ksaTransactionIdentifier

If an account refund is made, this field will hold the transaction identifier for the credit to the other account.

bankTransferIdentifier

If the refund is made via electronic bank transfer (SWIFT, BACS, ACH, etc.) the identifier for the refund will be stored here.

creditCardIdentifier

If the refund is made back to a credit card or similar, the return identifier (authorization number) will be stored here.

otherIdentifier

If some other refund is made that has an identifier, it will be stored here.

Class Ach (Helper Class)

Simple helper class to allow us to store ABA routing numbers. This is a non-persisted class, used to unwrap banking details from the AccountProtectedInformation class.

FieldDescription

accountType

C for checking, S for savings.

accountNumber

Account number (up to 20 digits). (17 is max for ACH)

routingNumber

9-digit ABA routing number.

Class BatchReceipt Overview

BatchReceipt is a simple class that records the status of batches of transactions that have been sent to the KSA system. Once a batch has been sent to the system, and it has been checked to see if it has already been transmitted, an object is instantiated to reflect this batch. The Xml class is a simple helper class used to store XML transmissions to/ from the system.


Class BatchReceipt

Attributes and Definitions

FieldDescription

ksaBatchIdentifier

Set to the next KSA batch number at instantiation.

externalBatchIdentifier

Passed by constructor.

entityId

Passed by the system, reflecting the authenticated user or system that uploaded the batch.

incomingDate

DateTime, set at time of instantiation.

totalTransacitonsInBatch

Null

totalValueOfBatch

Null

totalAcceptedTransactionsInBatch

Null

totalAcceptedValueCredits

Null

totalAcceptedValueDebits

Null

totalRejectedTransactions

Null

totalValueRejectedTransactions

Null

batchResponseSentDate

Null

incomingXmlMessage

Null

outgoingXmlMessage

Null

statusOfBatch

Set to "Q" at instantiation.

Class XmlDocument

Attributes and Definitions

FieldDescription

creationDate

Date that the XML message was created in the KSA system. For incoming XML, this will be the date/time that the message was stored.

creatorId

Entity identifier for the creator of the message (sender)

xmlMessage

The raw XML message.

Class AccessControl Overview

AccessControl is a KSA access point to KIM permission information. Most KIM permissions translate to simple Boolean permissions, which are documented in the Security Permissions document. These security permissions are mapped to methods that can answer questions about the logged in user, such as "canEditAccount" etc.
In addition, certain permissions can be used to designate access to certain ranges within KSA. This system is used to enforce policies relating to which transaction types a user has access to. Other access restrictions can be added through the AccessControl class.


Class AccessControl

This is a stateless class which is not persisted. The only class that is persisted is the TransactionTypePermission class, which stores the relationship between roles in KIM and allowable transaction types in KSA.

Attributes and Definitions

FieldDescription

entityId

Entity to which these permissions apply. This is derived from the user identity in the session.

permission []

Array of Permissions in the KIM classes.

transactionMask []

Array of transaction masks, derived from Role/TransactionTypePermission mapping.

role []

Role of the user

Class TransactionTypeMaskRole

Note that this is a standard Auditable Entry. The name and description fields are set to allow a power user to easily select this type of permission.

Attributes and Definitions

FieldDescription

role

Role that maps to this transaction mask.

transactionTypeMask

Transaction mask defined as a Java regular expression. Where a user the given role, they are allowed to use any TransactionType where TransactionType.transactionTypeIdentifer matches the regular expression in this attribute.

Class InformationAccessLevel

InformationAccessLevel is an access control group associated with pieces of Information. It is an auditable entity.

Attributes and Definitions

FieldDescription

createPermission

Permission required to be able to create this type of information.

readPermission

Permission required to be able to view the information.

updatePermission

Permission required to be able to edit the piece of information.

deletePermission

Permission required to be able to remove the information from the system.

expirePermission

A subset permission of updatePermission. With this permission, you can expire the information but not change any other field. (i.e. you can expire a memo, but not change the information within the memo).

Class AccountBlockOverride

AccountBlockOverride is used to override rule-based blocks in the account system.

Attributes and Definitions

FieldDescription

id

Internal ID for the block override.

accountId

Account against which the block is overridden.

creatorId

User ("staff member") issuing the override.

creationDate

Time and date stamp when the override was issued.

expirationDate

Time and date stamp for the expiration of the override.

reason

String, containing the reason for the override.

overriddenRuleId

Rule to be overridden in the blocking rules.

isActive

If true, all account blocks are suspended against this account.

Class TransactionList

The TransactionList is a wrapper for the Transaction class that provides easy access to groups of transactions so that they may be accessed more easily from the rules-driven payment application process. The class is not persisted, and most of its attributes are linked directly from the Transaction class. Most getter methods pull their values from the actual transaction. The class also allows the storage of the matrixRestrictionScore which is only calculated on-the-fly during payment application.


Attributes and Definitions

FieldDescription

transaction []

Array of transactions in this list.

matrixScore []

Array of matrix scores for the transactions.


For method definitions, see the process document under the Payment Application Service.

Class BillRecord and ExternalStatementConnector

The external statement connector allows KSA to display statements that are generated in an external system. KSA is built on the principle that all communications in and out of the system are in XML, allowing schools to customize the look and feel of customer-facing items such as bills, etc. This class and the associated service allows an external piece of software to produce the bills in a format that can be consumed by users (for example, PDF statements). The software can then produce the statements and store them, and inform KSA where those statements are located so that they can be accessed by the user.
BillRecord is a record of billing statements produced by the system.


Class BillRecord

FieldDescription

id

Internally produced bill ID number.

creatorId

Person requesting the bill.

creationDate

Date on which the bill was produced in the system.

accountId

Identifier of the account for the bill.

startDate

Start date of transactions on the bill.

endDate

End date for transactions being put on the bill.

showOnlyUnbilledTransactions

Suppresses transactions that have already been shown on another billing statement.

showDeferments

If true, deferments will be shown on the bill.

showInternalTransactions

If true, internal transactions will be shown on the bill.

runPaymentApplication

If true, payment application will be run before the bill is produced.

rollupsOnSameDate

A list of rollups that the bill will display on the same billing line, if the dates of the transactions are the same (i.e. all financial aid transactions that post on the same day will be rolled up into a single detail line).

rollupsOnSameStatement

A list of rollups on the bill that will display on the same billing line regardless of date. I.e. show me all financial aid transactions this month as a single payment.

produceDependents

If the student allows statements to go to multiple sources, this must be true in order to produce those copies.

message

A message to be placed on the bill (i.e. THIS ACCOUNT IS PAST DUE)

xmlBill

The output from the system (the actual XML bill file).

billedTransactions

List of transactions included in this bill.

Class ExternalStatementConnector

Attributes and Definitions

FieldDescription

billRecord

Pointer to the billRecord object for this statement.

uri

Set by constructor.

fileType

Type of the file at this location. An external may wish to provide the statement in different formats. This field permits the system to track the different versions.

isRedirect

Boolean that tells the UI how to deal with the URI. If this is true, then the system will redirect the user to the URI listed. If false, the URI will be fetched, and sent to the user.

Class RateCatalog [Underlies RateService]

The Rate system is used as an interface point between KS and KSA (and other systems) to be able to share the details of rates used as part of fee management.

(info) Note:  In the model, we store all units as their value *100, so a 3 unit course is stored as 300, allowing for easy and fast comparison of units up to two decimal places (covering halves and quarters of units). A specific instance of a Rate is identified through the following keys: The atpId, the Rate.code and the Rate.subcode – Upon location of the specific rate instance, you can access the RateCatalog, the RateType and the rateAmount objects associated with that specific rate.


Class RateType

RateType is a standard AuditableEntity class which defines the high-level type of rate that is being defined. The interpretation of a RateType is done within the rules engine, and will be specific to the implementing institution. See the document KSA-Fee Management for more details on RateType.

FieldDescription

rateAmountType

Enum of FIXED, FLAT or FLEXIBLE

isGrouping

Does the rate apply to individual signup items, or does it apply to all signup items as a group. See charge creation.

Class RateCatalog [Template for a Rate]

The RateCatalog class defines the outline for any rates that are in this catalog. It imposes restrictions on items that are formed from the RateCatalog.

Attributes and Definitions

FieldDescription

rateType

The RateType associated with this catalog item.

minAmount

If a rate's base amount has a lower bound, it is set here.

maxAmount

If a rate's base amount has an upper bound, it is set here.

isTransactionTypeFinal

Can the Rate override the transactionType or is it fixed in the RateCatalog. Note that the Rate stores TransactionType as part of RateAmount per USC requirement.

transactionTypeId

TransactionType of the fee when it hits the student account.

isTransactionDateTypeFinal

Can the transaction date type (see below) be overridden by the Rate, or is it fixed at the catalog level.

transactionDateType

The transcationDateType at the Catalog level. This can be ALWAYS, UNTIL, AFTER or NONE. These are defined below.

isKeypairFinal

The RateCatalog can have associated keypair objects. If this is false, then the Rate itself can have associated keypairs.

keypair

List of keypair values associated with the RateCatalog (and therefore with the Rate)

isRecognitionDateDefinable

Can the recognition date be changed in the Rate. If not, then the recognition date will default to the effective date.

isLimitRateAmount

Limit rates, units, etc. cannot be overridden in Rate. If catalog is set to be a non-limit Rate, then Rate cannot override.

isLimitAmount

Does the rate have a plateau in it? See the FM documentation.

limitAmount

Amount of currency applied during the plateau.

minLimitUnits

Minimum number of units to qualify for the plateau (limit) rate. Note that units are stored as 100ths (3 units =300)

maxLimitUnits

Maximum number of units that qualify for the plateau (limit) rate.

minLimitAmount

Constraints on limitAmount of Rate

maxLimitAmount

Constraint on limitAmount of Rate

The different values for transactionDateType

ValueDescription

TYPE

General Meaning

ALWAYS

The date of the transaction will always be the date in this field, no matter when it is posted to the account.

UNTIL

The date of the transaction will be the transactionDate, until that date has passed, after that date, the transaction will be the date the transaction is created. This can be used to allow a student to sign up in advance for classes and be billed in the future, but after that date has passed, transactions will fall on the date they are generated.

AFTER

The transaction will be dated on the day the transaction is generated until the transactionDate has passed, after which the transactionDate will become the effective date. This allows late registering students to be back billed.

{null}

The date of the transaction will be derived elsewhere. The working assumption is that it would reflect the effective date received from course signup, but the determination would have to be made in the FM rules.

Class RateCatalogAtp

In order to enforce the RateCatalog/Rate/Atp relationship, these classes (RateCatalogAtp/RateCatalogAtpId) are used.

Attributes and Definitions

FieldDescription

rateCatalogAtpId

Single rateCatalogAtpId object.

rateCatalog

The rateCatalog implicated by this relationship.

Class RateCatalogAtpId

Attributes and Definitions

FieldDescription

code

The code of the Rate implicated in this relationship.

atpId

The atpId for this Rate/RateCatalog relationship.

Class Rate

The Rate class is a period-based object that defines the rate in force for that particular item. It is a Rate object (defined by code + ATP) that KS would record as being attached to an offering.

Attributes and Definitions

FieldDescription

subCode

The subcode is the secondary part of the key for a Rate object. This allows a rate to have the same code (but not subcode) in the same ATP.

rateType

Pointer to the RateType object for this Rate.

rateCatalog

Pointer to the rateCatalog that this Rate belongs to.

aptId

ATP that this Rate is in force for. Note that the code of the Rate, plus subCode plus the ATP are the identifying keys.

defaultRateAmount

For flat and fixed fees, this is the amount that will be used. For flexible amounts, the amount in the flexibleAmount list will be used if it can be found. If not, this amount will be used.

rateAmounts

List of RateAmount objects. These are used to calculate the actual amount of the rate.

transactionDate

Date that will be used as the effectiveDate in tandem with transactionDateType.

transactionDateType

If the transactionDateType can be overridden at the Rate level, the override will be here.

recognitionDate

If the recognition date can be defined, it is defined here.

keypair

If the Rate is allowed to have keypairs, they are listed here.

isLimitRate

Does the rate have a plateau in it? See the FM documentation.

minLimitUnits

Minimum number of units to qualify for the plateau rate. Note that units are stored as 100ths (3 units =300)

maxLimitUnits

Maximum number of units that qualify for the plateau rate.

limitAmount

Amount of currency applied during the plateau. (note that this is inherently a fixed rate, so the transaction type will be derived from the defaultAmount transaction type, which will also be needed to get the rate per unit.

Class RateAmount

RateAmount is a lookup table that defines the actual amounts that are used. For FLAT and FIXED types, there will be no entries, as they will be defined as defaultRateAmount.

Attributes and Definitions

FieldDescription

unit

The number of units that this amount refers to. Note that we store units/100 to avoid rounding and comparison problems.

amount

Amount of the rate in system currency.

transactionTypeId

The actual transactionType is stored here.

Class TransferTransaction


The transferred transaction classes keep track of transaction responsibility that has been moved between accounts, or within an account (for example, when switching to payment billing). Tracking the transfer of payments is helpful not only to allow a CSR to understand how certain charges were applied to the account, but to also permit the reversal of such a transfer, for example, if a third party refuses to sponsor a student, the charges could be returned to the student's account.


Class TransactionTransfer

Attributes and Definitions

FieldDescription

transferGroup

Null at instantiation or set by constructor. A UUID that is used to bind together groups of transfers under a single identifier.

transferDate

Date on which the transaction takes place, set during construction.

sourceTransaction

Original transaction that was transferred.

transferAmount

Amount of the transaction that is transferred in the first instance.

offsetTransaction

Transaction that negates the source transaction.

destinationTransaction

Transaction that was created by the transfer.

transactionType

Defined type of transfer. Default transfers of ThirdParty and PaymentBilling will be defined in the system. Defined in the contructor.

reversalStatus

(R)eversed, (P)artially Reversed, (N)ot reversed.

reversalAmount

Is transaction reversalStatus is Reversed, or PatiallyReversed, this will store the amount of the reversal.

sourceReciprocalTransaction

If the transfer is reversed, both the original reversal (reversalTransaction) and the created transaction (destinationTransaction) need to be reversed. This stores the reversing transaction for the original reversal.

destinationOffsetTransaction

If the transfer is reversed, this points to the reversal transaction that negates destinationTransaction.

transactionTypeMask

If a transaction is transferred through the third party system, it will be transferred on the strength of a transactionMask. Because there might be limits placed on the transfers based on a mask, the mask must be stored here to allow us to "look up" how much has been transferred on that mask in any prior transfer under the same transferGroup. This field is optional, but will always be filled by the third party system.

Class TransferType

Attributes and Definitions

FieldDescription

generalLedgerType

Indicates the general ledger type of the new transactions that will be created by the transfer.

Class PaymentBillingPlan

The PaymentBillingPlan holds the definition of the payment plans that a school offers to its account holders. The plan, and its associated classes of PaymentBillingDate and PaymentBillingAllowableCharges define when, what, and how much of an account can be financed. This plan forms the template for producing a payment billing run on an account. The plan and its associated classes of PaymentBillingDate and PaymentBIllingAllowableCharges form the blueprint to be applied to an account.
An associated class, the PaymentBillingTransferDetail, is created when an account is financed by the student. PaymentBillingTransferDetail records how the plan was applied to an individual account, allowing a CSR to view how the plan was applied, and also allowing the system to roll back the plan, in the event of non-conformance with the terms, or if transactions change, the plan can be reversed, and payment billing reapplied to the account to take into account new charges.


Class PaymentBillingPlan

Attributes and Definitions

FieldDescription

startOpenPeriod

Date from which the plan is available – the start of the window of time that the plan can be accessed.

endOpenPeriod

Date until which the plan can be offered.

startChargePeriod

Date from which charges can be taken into account for this plan.

endChargePeriod

Date to which charges can be taken into account for this plan.

allowableCharges

List of PaymentBillingAllowableCharges.

maximumAmount

BigDecimal amount, the maximum amount that can be financed under this payment plan. A zero value means there is no theoretical limit.

paybackSchedule

List of PaymentBillingDate objects.

flatFeeAmount

BigDecimal amount of the fee to be charged for this payment billing plan. This will be charged as a flat fee to the student, if present.

variableFeeAmount

Percentage of the amount that is placed in a plan that is charged to a student. Nothing prevents any combination of flatFeeAmount and percentageFeeAmount from being charged.

feeMinimum

If the percentageFeeAmount is being used, this is the lower bound of the fee that can be charged.

feeMaximum

If the percentageFeeAmount is being used, this is the upper bound of the fee that can be charged.

flatFeeTransactionType

If a fee is charged (based on flatFeeAmount )this is the transaction type used to charge the fee to the student's account.

percentageFeeTransactionType

If a fee is charged (based on percentageFee)this is the transaction type used to charge the fee to the student's account.

transferType

This is the transferType that will be used to move the transaction from one date to another.

roundingFactor

This number dictates the number of places to which most payments will be rounded. For example, a $487.82 payment might be rounded to $488, $490 or $500 depending on this field. See paymentCalculation() roundingFactor.

nonRoundedPayment

In order for the rounding to be calculated, one of the payments must be declared "unrounded". Potential values are FIRST and LAST.

isGlImmediate

Boolean that decides if the general ledger should be affected upon the creation of the plan (TRUE) or as the transactions hit their effective date (FALSE).

schedulePlan

This attribute helps the system decide what to do if a plan is started late (after the first payment should have been due.) Possible values are NOTALLOWED, BACKBILL, SKIPEARLIER, BALANCETODAY. These are explained in the process documents.

statementPrefix

If the transferred transactions are to have a prefix on the statement line, then it is store here. (For example: Financed Transaction(smile)

Class PaymentBillingDate

Attributes and Definitions

FieldDescription

paymentDate

Effective date of the payment.

percentageOfTotal

Percentage of the total financed amount (potentially subject to rounding) that this charge will cover. This allows a plan to weight an earlier payment or a later payment if they wish.

rollup

Rollup that will be applied to this group of charges. For example, all payments due in June might be in a rollup called "Payment Billing June Payment". If blank, the rollup for the transaction type will be used.

Class PaymentBillingAllowableCharges

Attributes and Definitions

FieldDescription

transactionTypeMask

Regular expression, defining the transaction types that can be covered by this payment plan.

priority

The priority with which these charges are accepted. This allows a plan with limited available funds to prioritize certain types of charges first.

percentageAllowed

If this transaction type is limited to a percentage, the percentage will be stored here (for example, only 50% of bookstore charges may be financed, etc.)

maximumAmount

Maximum amount that can be financed under this type. This may be used with or without the percentageAllowed attribute.

Class PaymentBillingTransferDetail

PaymentBillingTransferDetail is used to store the results of a payment billing plan, in part to allow the system to automatically reverse the plan if required.

Attributes and Definitions

FieldDescription

initiationDate

Date the payment billing plan was put into effect. This is the date that is checked against the allowable plan dates. By default, this will be the current time and date, but there might be times (for example, when the account has to refresh) that this date will be altered at setup.

accountId

Account against which the payment plan is lodged.

creatorId

Identifier of the user who initiated this payment plan. This might be the student themselves (via SSS) or a staff user id.

paymentBillingPlanId

Reference to the type of payment billing plan that this plan covers.

requestedAmount

Amount requested to be financed. If this is set as higher than the plan's maximum amount, this amount will be reduced to match the maximum amount.

amountOfPlan

Amount that is being financed by the plan.

feeTransactions

A list of any fee transactions that were added to create the payment plan. See PaymentBillingPlan references.

status

Enum of Initialized, Allowable, Scheduled, Active or Reversed.

transferGroupId

Id of the transfer group that handled the transfer.

flatCharge

Pointer to the flat charge if there is one.

variableCharge

Pointer to the variable charge, if there is one.

Class PaymentBillingTransaction

Attributes and Definitions

FieldDescription

charge

Existing KSA transaction to which this payment billing transaction refers.

originalTransactionAmount

Derived from transaction.

originalUnallocatedAmount

Derived from transaction.

financedAmount

Amount of the transaction that will be moved to payment billing.

transactionType

Derived from transaction.

remainingAmount

Temporary counter used when producing the actual payment billing transactions.

assignedRatio

Calculated ratio of this transactions to the other transactions within a payment billing cycle.

temporaryAmount

During a payment billing cycle, this is the calculated amount for this transaction.

Class PaymentBillingSchedule

Attributes and Definitions

FieldDescription

date

Date of the payment billing transaction.

percentage

Percentage of the total that this charge will cover.

amount

Amount (often rationalized) of the entire charge for this period.

Class PaymentBillingQueue

Attributes and Definitions

FieldDescription

account

The account id of the account signed up to this billing plan.

creatorId

User that created the item in the queue.

creationDate

Timestamp of creation.

initiationDate

Date on which the billing plan was added to the account. This will be validated against the open period in order to test validity.

paymentBIllingPlan

The specific payment billing plan being signed up to.

forceReversal

If a plan has already been executed, it will be ignored, unless this is set to true.

paymentBillingTranferDetail

If the plan has been executed, this is the detail object.

Class ThirdPartyBilling

The third party billing classes are responsible not only for the establishment of third-party billing plans, but also the tracking of their application to an account, and thus the ability to reverse a plan if needs be.


Class ThirdPartyBillingPlan

Attributes and Definitions

FieldDescription

responsibleAccount

The account to which the third-party charges will be applied. The "recipient" account.

allowableCharges []

Array of ThirdPartyAllowableCharges objects that define what charges can be transferred to the responsibleAccount under this plan.

startOpenPeriod

Date from which the plan can be executed.

endOpenPeriod

Date to which the plan can be executed.

startAllowableCharges

Start date of charges that can be transferred under this plan.

endAllowableCharges

End date of charges that can be transferred under this plan.

effectiveDate

Effective date of the transferred transactions. If this is null, the transactions will be transferred with the same effective date as the source transactions.

recognitionDate

Recognition date of the transferred transactions. If this is null, the transactions will be transferred with the same recognition date as the source transactions.

maximumAmount

Maximum amount that can be transferred under this plan.

transferType

Transfer type to be used by the plan.

thirdPartyMembership

List of students who are able to use this plan.

Class ThirdPartyAllowableCharges

Attributes and Definitions

FieldDescription

transactionTypeMask

Regular expression that defines the transaction types that this plan can transfer.

priority

As funding may be limited within a plan, this defines the priority of these types of transactions. The higher this number, the more likely it is that these types of transactions will be transferred.

maximumPercentage

If a plan will only pay a percentage, then this will be stored here. For example, a plan may offer to pay 100% of tuition and 80% of bookstore charges.

maximumAmount

Maximum value of the transfer for this type of charge. For example, a third party might specify that they will pay for a parking pass up to a certain value. This maximum value is also subject to the maximumAmount of the whole plan.

chargeDistributionPlan

If the maximum allowed for either the plan, or these charges are hit, then this is the rules that is used to transfer any transactions to the responsible account. The two values are FIRST or DIVIDED. FIRST means that the oldest charges will be transferred up to the cap, leaving the later charges for the student to pay. DIVIDED means that a percentage of each of the charges will be transferred, leaving the balance of each of the charges for the student to pay.

Class ThirdPartyPlanMember

FieldDescription

account

Account from which the transactions will be transferred. The source account.

isExecuted

If this is true, then third party billing has been run against this student on this plan. This does not mean it cannot be run again (as more transactions on the account may have posted) but it will not run again by default.

priority

If a student has more than one third party plan then this attribute is used to decide which plan is run against the account first. There is no theoretical limit on the number of plans that may be registered against a student's account.

Class ThirdPartyTransferDetail

Third-party billing details is used to record the third party billing plan as it is applied to an account. This object records the actual flow of transactions from the "student" account to the third-party ("sponsor") account. This recording is used not only for audit purposes, but also to allow the system to reverse a third party plan, if a third party were to refuse to pay for a student for whatever reason.

FieldDescription

fundedAccount

Account identifier for the account that is funded (the "student" account, the account which is "paid").

transferAmount

Under this arrangement, the total amount that was transferred to the third-party account.

initiatedDate

The date on which the plan was initiated. This is set by the system. If the system has to regenerate, it will regenerate using the same initiatedDate as the original set.

thirdPartyBillingPlan

Reference to the specific third party billing plan that was the basis for these transfers.

transferGroupId

Transactions are transferred to the third-party account via transactionTransfer. This is the unique identifier that ties together all the transfers to the other account.

status

ACTIVE, REVERSED

Class Irs1098T

The Irs1098T class is used to store information relating to the 1098T form which is used to track tuition payments within US institutions. The object can store the data for the form, and the XML representation for the form if required.


Class Irs1098T

Attributes and Definitions

FieldDescription

id

Identifier for the Irs1098T object.

accountId

KSA account identifier for the account to which the 1098T refers.

startDate

Date of the start of the 1098T reporting. Under most circumstances, this will be 1/1 of the year for which the form was produced.

endDate

Date of the end of the 1098T reporting. Under most circumstances, this will be 12/31 of the year for which the form was produced.

creatorId

User ID of the person who requested that the form be created.

creationDate

Date on which the form was assembled.

formYear

Numerical representation of the year on the form.

isVoid

Boolean representing if the form has been voided.

isCorrected

Boolean representing that this form corrects an earlier form.

isReportingMethodChanged

Boolean indicating that the institution has changed its reporting method.

filerName

Name of the filer of the form (the University).

filerAddressLine1

Address line 1 of the filer.

filerAddressLine2

Address line 2 of the filer.

filerAddressLine3

Address line 3 of the filer.

filerAddressCity

City of the filer.

filerAddressState

State of the filer.

filerAddressPostalCode

Zip of the filer.

filerAddressCountry

Country of the filer.

filerTelephoneNumber

Telephone number for the institution.

filerFein

FEIN for the filer.

studentName

Concatenated name for the student referenced in accountId.

studentPostalAddress

Postal address of the student, stored as a PostalAddress object.

studentSsn

Student's (masked) social security number.

studentAccountNumber

Stored if used by the institution. If a school uses another number other than the UID for the account identifier, then it will be stored here. In the reference implementation, this duplicates accountId.

isStudentHalfTime

Boolean indicating that the student is half time for IRS purposes. This information will come from an external system of record.

isStudentGraduateStudent

Boolean indicating that the student is a graduate student. This information will come from an external system of record.

paymentsReceived

If the school's reporting method is payments received, then the amount will be in this box. The reference implementation uses the amount billed method, used by both of the sponsoring institutions.

amountBilled

If the school's reporting method is by amount billed, then this will be the total amount billed to report on the 1098T. This is the default method used in the reference implementation.
Only one field (paymentsReceived/ amountBilled) will be completed for any 1098T.

isInclusiveOfNextQuarter

Boolean indicating that amounts on this form reference charges relating to the next year.

priorYearAdjustment

Records an adjustment to a prior year's amounts.

scholarshipsOrGrants

Amounts applied to the student's accounts in the form of scholarships or grants.

priorYearScholarshipAdjustment

Adjustment to prior year's scholarshipsOrGrants

insuranceContract

Amount paid towards an insurance contract.

Class FeeManagementTermRecord

The FeeManagementTermRecord will be the starting point for Fee Management. It will be from this record that KSA can create a FeeManagementSession, from which KSA-FM can then start the processing. This is the DTO required to start the fee management process.

(info) Note: We do not persist these objects. This construction is used purely to allow the transfer of data from an external registration system.


Class FeeManagementTermRecord

Attributes and Definitions

FieldDescription

accountId

The identifier for the account to be charged.

status

This is the status of the session. It can be SIMULATED or CURRENT

atpId

The ATP identifier for the whole session.

keypairs

List of session keypairs. This is where registration information (or what if information) can be passed to KSA.

majorCode

List of major codes from the registration system.

cohortCode

List of cohort codes form the registration system.

signup

List of signup objects (the registration activity).

Class IncomingSignup [As distinct from Signup]

The incoming signup object is used to store the details of signup activity from the registration system.

Attributes and Definitions

FieldDescription

registrationId

The identifier of the signup activity. This is a unique identifier for the registration activity, supplied by the registration system, which is the system of record for this information. Each time a student signs up, the registration system sends the whole activity instead of just the delta, so we use this identifier to tie together the records.

creationDate

This date is for audit purposes only. This is the date in the registration that the activity was created. KSA doesn't use this date directly in fee management.

effectiveDate

This is the date on which KSA registers the activity. This is supplied by the registration system.

operation

This is the operation performed by the line. See Operations in the next section.

offeringType

KS provides at present two forms of offering, the program offering and the activity offering. KSA recognized PO (program offering) and AO (activity offering)

offeringId

ID of the offering (probably a UUID)

atpId

ATP of this offering. This ATP has to be the same as, or a subsection of the ATP In FeeManagementTermRecord, but KSA does not enforce this.

units

Number of units associated with the course, if applicable. KSA recognizes units as hundredths.

rates

List of FeeManagementSignupRate objects.

Class FeeManagementSignupRate

The FMSR object is used to store the details of Rate from the registration system. When this is translated into a session, the Rate will be converted to the appropriate ID.

Attributes and Definitions

FieldDescription

rateCode

Code for the rate that is attached.

rateSubcode

Subcode for the rate that is attached.

Class FeeManagementSession


Class Signup

Attributes and Definitions

FieldDescription

id

Internal identifier for the signup line.

registrationId

Identifier for the signup line from KS (Likely a UUID.) This would not change over time no matter how many times this line is sent to us. (That is to say that this identifier will remain stable over sessions, which is important for KSA's ability to reconcile charges from one session to the next.)

creationDate

Date on which the action was taken by the student/ admin etc. for audit purposes.

effectiveDate

Date on which the action was placed. This would be the data against which a late fee would be applied, if applicable. From a student's end, this would be the same as creationDate. An administrative person might have the ability to alter this date (for example, if they were processing paper applications, etc.)

operation

See below for the operations.

offeringType

At present the offering type can be either AO or PO.

offeringId

The KS ID for the offering (likely a UUID)

atpId

Specific ATP of the offering (will be the same as, or a subsection of the atp in the session.)

units

Number of units that the student signed up for. In our modeling, we allow a decimal up to two decimal places. Note that we store this as an integer and interpret as 100ths of a unit (so one unit = 100, 2.5 units = 250, etc.)

rates

List of FeeManagementSignupRate objects.

keypairs

List of keypairs attached to the signup.

isComplete

Internal field marking that the offering has been completely processed by the rules.

isTaken

Internal field marking that this signup is being "taken" by the student – that is to say it is an adder that has no legal dropper.

Operations (Agreed with KS)

Able to be performed by Student

Able to be performed by administrative user

ADD (Adder)
DROP (Dropper)
WITHDRAW

ADD_WITHOUT_PENALTY (Adder)
DROP_WITHOUT_PENALTY (Dropper)
TRANSFER_IN (Adder)
TRANSFER_OUT (Dropper)
WITHDRAW

Class FeeManagementSignupRate

Simple Rate information class. Note that the point of acceptance of the signup from the registration system, the rateCode + rateSubcode structure is converted to a rateId and stored here.

Attributes and Definitions

FieldDescription

id

Internally generated identifier

rateId

Pointer to the rate for this line.

isComplete

Used in the rules to mark a rate as charged (or ignored).

Class FeeManagementSession

Attributes and Definitions

FieldDescription

id

Internally generated unique session identifier.

creationDate

Date/Time stamp when this object was created (when the fee management system started to process the signup.

accountId

Account against which the fee management session was run. This is the account that will be billed for the fee management transactions.

atpId

This is the high-level ATP identifier for the term that is being billed for. KS sends a high-level identifier for the term, even if the basket contains sub-terms. (Minimesters, and the like).

status

Status of the session. This can be SIMULATED, CURRENT, RECONCILED, SIMULATED_RECONCILED Or CHARGED.

priorSessionId

Identifier of the session that preceded this one, for this account, in this ATP. If this is null, you're at the start of the chain.

nextSessionId

Identifier of the session that comes after this one, for this account, in this ATP. If this is null, you are at the end of the chain.

keyPairs

Set of keypair values that are used within this session alone. They are not available in a future session.

signup

Pointer to the list of signup objects that underlie this session.

feeManagementManifest

List of FeeManagementManifest objects that are associated with this session.

sessionLog

Pointer to log items for the session.

isReviewRequired

Something in the session needs manual review.

isReviewComplete

Has the required review been performed?

reviewerId

Account ID Of the person performing the review.

reviewDate

Timestamp of the review.

isQueued

Is this session queued to be executed?

FeeManagementSession Statechart (For status)

Class Keypair

Often used Keypair class.

Attributes and Definitions

FieldDescription

key

Name of the element.

value

Value of the keypair.

creationDate

Date/time stamp of the creation of this key pair.

Class FeeManagementManifest

Attributes and Definitions

FieldDescription

Id

Internal id of the chargeManifest line.

type

Type of added line. This can be CHARGE, CANCEL, DISCOUNT, ORIGINAL or CORRECTION.

internalChargeId

If the line is not based on a signupId + rateId then this is an internally generated identifier to allow us to do session comparisons.

registrationId

Identifier of the line of the signup (by registration Id) that triggered this charge manifest item.

offeringId

Identifier of the offering that triggered this charge manifest item.

status

Is this CHARGED or PENDING

rateId

Rate pointer if applicable.

effectiveDate

Calculated effectiveDate of the transaction.

recognitionDate

Calculated recognitionDate of the transaction.

transactionTypeId

ID (code) for the transaction type to use to charge this fee.

amount

Amount to be billed or cancelled.

transactionId

Once the KSA transaction has been created, this will be the identifier for the created transaction.

keypairs

Keypair items relating to this line of the manifest.

linkedManifestId

If this is a charge cancellation or a discount, this will point to the other half of the equation.

currentSessionCharge

If this is true, then a transaction was raised for this manifest line during the charging process.

rollup

Pointer to a rollup if set. If present, the created transaction will have this rollup.

tag

List of tags to be set on the transaction.

Class ManifestGlOverride

If the GL has to be overridden this will hold the override.

Attributes and Definitions

FieldDescription

glAccount

GL account number.

breakdown

Percentage breakdown per regular transaction rules.

Class FeeManagementSessionLog

The session log contains information about what happened during the session. It is used from both the rules (when rules execute, they can write a line to the log) and during the reconciliation and charging process.

Attributes and Definitions

FieldDescription

level

Level of the log. INFO, WARN, SEVERE.

log

Actual text of the log.

Class FeeManagementReportInfo

This class is used to return information to a calling system when a what-if call is made. This data is not persisted. It is used only as the data structure to send the message back to the caller.


Class FeeManagementReportInfo

Basic wrapper class.

Attributes and Definitions

FieldDescription

accountId

User id of the student account.

creationDate

Time and date stamp of the assessment.

feeManagementReport

List of feeManagementReportItem objects.

netImpactOnAccount

Financial impact on the account. How much more or less this assessment would cost the student.

Class FeeManagementReportItem

Basic wrapper class.

Attributes and Definitions

FieldDescription

type

Type from the manifest (CHARGE, DISCOUNT, etc.)

effectiveDate

Effective date of the transaction

TransactionTypeId

Transaction type identifier.

statementText

Readable statement text.

amount

Amount of the transaction.

isAlreadyCharged

If true, this charge was already on the student's account (and is therefore not included in the netImpactOnAccount figure).

 

Class NamedSearch


  • No labels