Skip to end of metadata
Go to start of metadata

XML

Introduction

As a matter of course, the standard format for data entering and leaving KSA in the XML format. A basic set of import, export and reports are defined in this document, including bills, checks, transactions, and certain standard forms.
Most data elements relate directly to the KSA attributes and to the data models. We have provided simple data dictionary entries for some of the fields for clarification purposes, especially those that are the most complicated; however the data definitions in the data model document always supersede these definitions.
Please note that for the basic dictionary types, such as currency, general ledger type, rollup, etc. the match field for these elements is the "code" field, unless otherwise stated. For example, the currency dictionary type expects the ISO code for the currency to be stored, so USD refers to U.S. Dollars, and EUR refers to Euros. Therefore a transaction denominated in Euros would expect <currency> to be listed as EUR.

KSA Transaction XML Schema


A simple XML schema to enable to transmission of transactions to the KSA system. In order to enforce basic document type for the transaction, the system must transmit the three parts of a document that are mandatory. Transactions will often come in under a batch identifier.

Data Definitions for Transaction

 

Element NameElement Format and ContraintsDescription

account-identifier

(Mandatory) String, maximum of 45 characters.

Student Account Identifier, the standard identifier for the student. By default, this is expected to be the network identifier, or user id.

incoming-identifier

(Optional) String. Maximum of 45 characters.

Can be used to indicate an external identification number for the transaction.  For example, if the transaction originates in another system, and has a transaction number there, the number could be passed to KSA to allow easier location of the transactions across the systems.

effective-date

(Mandatory) XML Date.

Date the transaction is to be effective; that is, the date on which it starts to age. This date could be a date in the past, a future date or the current date.  

origination-date

(Optional) XML Date.

Date the transaction was created, most likely the system date or the current date. In the case of a weekly batch upload, this date may be several days before the date when the transaction is uploaded.

recognition-date

(Optional) XML Date.

This date would be defined within the rules to determine the processing period for the General Ledger.  Allows posting transactions to a specific term or time period, for example; 2012-3.  If this value is not passed, this date is set to the Effective Date. 

amount

(Mandatory) decimal with two decimal places.

Amount of the transaction in the default system currency.

native-amount

(Optional) decimal with two decimal places.

Amount of the transaction in a foreign currency as defined by <currency>.  If the native currency and the system currency are the same, Native -amount and amount will be the same value.

currency

(Optional) String, up to 10 characters.

Type of currency that the native amount reflects. This is user defined in the Currency class, and is matched on the code field. If neither native amount or currency are passed, then native amount will be set to amount, and currency will be set to the code for the system currency.

document

(Optional) String.

Additional information relating to the transaction such as origin or details that may be useful to the user.  This would be located in a short XML file, consisting of the next three elements.

person-to-contact

(Mandatory if document is passed) String.

The contact person if populated in the XML file for <document>.

telephone-number

(Mandatory if document is passed) String.

The contact person's phone number if populated in the XML file for <document>.

email-address

(Mandatory if document is passed) String.

The contact person's email address if populated in the XML file for <document>.

open-document

(Mandatory if document is passed) String.

 HTML formatted information relating to the transaction. For example, for a bookstore charge, the bookstore could transmit a table showing the book title and charges for each individual book. This field can be used to allow a student to have a greater understanding of what a particular charge is for. It can be presented to the student in the UI.

override

(Optional) XML Complex type.

Container for override data. Most options here would normally be derived from the transction-type. These elements allow those defaults to be overridden.

override-rollup

(Optional) String, up to 10 characters.

Used to group similar transactions together.  When this value is set it would override the value defined in the ROLLUP class, matched on the code attribute.

override-statement-text

 (Optional) String, up to 100 characters.

The statement text (as shown on the billing statement for each line item) is generally derived from the transaction code. If provided here, the statement text presented will be set to this value, rather than the default value.

general-ledger-type

(Optional) String, up to 10 characters.

Typically the GL type would come from the GL Type table by default. However, when specified, for use with special transactions such as for third party charges a different GL type may be desired. These values are user defined, and are stored in the GeneralLedgerType class. They are matched on the code field.

general-ledger-override

(Optional) XML Complex type.

Container for general ledger override information.

general-ledger-account

(Mandatory if general-ledger-override is passed.)
(Unbounded) String, up to 45 characters.

If the general ledger breakdown for the transaction is to be overridden, the account number (or numbers) is passed here.

percentage-allocation

(Mandatory if general-ledger-override is passed) Decimal.

Percentage of the transaction to be assigned to this general ledger account. (0 = "remainder", or "entire amount" if no other general-ledger-account fields are passed.)

override-refund-rule

(Optional) String, up to 2000 characters.

Defines the refund processing rules.  If this is blank, the refund rule defined by the CreditType is used.  However, if this value is set, then it overrides the default rules.  The rule follows the same format as CREDIT_TYPE except it also permits the option of refunding to another KSA account.  This override refund rule is "required" to permit overpayment refunds to other sources such as with Parent PLUS loans as well as sponsorship overpayments. The exact formatting of this element can be found in the data model document, under the title "Refund Rule Use Cases".

is-refundable

(Optional) Boolean.

Boolean that is only applicable to credits.  It answers the question; is this credit refundable? If false, the transaction cannot be refunded if it causes a credit balance.

override-clear-date

(Optional) XML Date

Only applicable to payment transactions. This date is the date that the transaction can be considered to be treated "like cash" for potential refunding purposes.  For example, when processing a check payment, an institution may choose not to refund against the check until 10 days have passed.

override-clear-period

(Optional) Integer.

Defines the number of days to be used for calculating the "clear date".

transaction-type

(Mandatory) String, up to 45 characters.

Represents the transaction type code necessary for posting the transaction.  These codes are defined in the TransactionType class, matched on the transactionTypeIdentifier attribute.

Example Transaction

This is a very simple transaction transmission. Notice that the external system is able to specify an incoming identifier. This identifier must be unique. It is recommended that external system's references are prefixed with a code to identify the system to ensure that there are no collisions.

KSA Batch Transaction Schema


Batch transaction schema is used to send a list of transactions to be processed by KSA. It works simply as a wrapper of the transaction schema, with a unique identifier field, which is the batch identifier from the external system. KSA does not care what this identifier is, but it does care that the identifier is unique. In coordination with external systems, it is expected that a numbering system with some level of namespace will be used to ensure that batch identifiers do not clash.

Example Transaction Batch

This is a very simple batch transmission of a single transaction (a batch of one). Notice that it is the external program's responsibility to generate a unique batch identifier. If a batch is received with the same identifier, it will be rejected. It is recommended that external system's references are prefixed with a code to identify the system to ensure that there are no collisions.

KSA Transaction Response Schema

Batch response is the file that is returned to an external system after a batch of transactions has been uploaded to the system. A response identifier is generated which will be a uuid. The batch status can either be "complete", or an error that relates to the preprocessing (Schema not valid, etc.) If the batch failed for some reason, there will be no other data in the response. If the batch status is complete, then it will list the accepted transactions, including a copy of the original uploaded transaction, with the newly generated transaction id and the accepted date (ledgerDate). Then it will list any failed transactions, again, repeating the transaction, with a failure reason (Account over credit limit, account blocked, etc.) Finally there is a batch summary for reconciliation, showing the total number of transactions, the total value, the total number of accepted transactions and their value, the total number of failed transactions and their value.

KSA Account XML Schema



Note that there is a high level of optional data here. The use case is to allow the creation of an account using no information- for example, UMD creates accounts for cars that get tickets, and all they pass is an identifier of state of tag, followed by the tag number. The system then generates an account based on that. At some point in the future, the details for the account are pulled from the vehicle record system, and the details populated. The state+tag remains as the identifier for the account.
The <command> tag informs KSA what the intention of the transmission is. It can be NEW or UPDATE. If a NEW account is pushed with a pre-existing <account-identifier> it will fail. If an UPDATE is pushed, then any fields in the schema will be used to update the system. NEW accounts are required to pass the <is-kim-account> tag. Updates are not required to push this, unless they are trying to change the value.
If command is not passed, the system will assume that accounts with an <account-identifier> that already exists are updates, and accounts with an <account-identifier> that does not exist are new accounts. It is recommended that systems always pass the <command> tag, to ensure that the intention of the sender is being carried out.
Notice that in most circumstances, accounts can be automatically generated if they exist in KIM. Indeed, if the account exists in KIM, KSA can be configured to automatically create accounts for those users without any intervention. Moreover, in most circumstances, KIM will connect to the school's single sign on [SSO] provider which will provide many of the account details. This functionality is provided for testing purposes, and for the creation of accounts that do not exist in the school-wide system.
Note that the <protected-information> are used to transmit extremely sensitive data, therefore transmission of this data using this schema is not recommended without end-to-end security of the connection between the external system and KSA.

Example Account

Notice a number of options are set by default. If the following fields are not supplied, they will be supplied by the default values in ksa.properties.

KSA Person Name Schema



The person name type is a compound type used to store a person's name. It mimics the name format as provided in KIM.

KSA Postal Address



This is a complex type used for storing street addresses. It is designed to hold a wide range of addresses, regardless of the country of the address.

KSA Electronic Contact





 

Batch Account


Batch account is a simple wrapper that allows a number of accounts to be transmitted to the system in a single transmission. Unlike with transactions, there is no need for a batch identifier with accounts as they cannot be duplicated in the way a recurring transaction can be duplicated.

Batch Account Response



As with transaction responses, the system will send back an XML response to account uploads to allow the external system to know the status of any uploaded accounts.

 KSA Bill


Batch KSA Bill

 

Request Failure

Standard failure response when an incoming request fails outright. The most common reason for failure would be failed XML validation. Once the XML is validated, the system sends specific failure reports on the content. The message contains the failure message.

 

Check

Simple schema to transmit checks to a check printing system. These details can easily be transformed into the correct format for check production.

 

Batch Check


 

ACH

ACH is a simple class that will be transformed into an appropriate format to be transmitted to the bank. Post-processing of the XML file to create the correct headers will be institution and implementation specific.

 

Batch ACH


 

Transaction Receipt




 

External Statement

The external statement schema allows external systems that use the ksa-bill schema to produce other formats of the bill (for example, PDF, csv, etc.) and inform KSA that those statements are available. This permits institutions to produce whatever electronic bill forms they prefer, and make them available through the KSA front end. <external-statement> allows the external system to push this content to KSA. <external-statement-remove> provide mechanisms for removing the content.

 

External Statement Remove



 

External Statement Response

 

External Statement Remove Response


 

External Statement Batch

External Statement Batch Response


 

IRS Form 1098-T

<xs:element name="irs-1098-t">
 

Batch IRS 1098T


Simple batch wrapper to represent a number of 1098T forms.

Aged Balance (Aged Trial Balance) Report





 

Failed Transaction List Report


 

Account Report

 



 

Data Definitions for Account Report

 

Element Name

Element Format and Constraints.

Description.

account-identifier

(Mandatory) String, maximum of 45 characters.

Student Account Identifier, the standard identifier for the student. By default, this is expected to be the network identifier, or user id.

reporting-period

(mandatory) complex type.

Describes the period of time that the report covers.

start-date

(Mandatory) date type.

Date on which the report begins. Transactions on and after this date will be included.

end-date

(Mandatory) date type.

Date on which the report ends. Transactions on and before this date will be included.

name

(Mandatory) Complex type.

References the name of the account holder. This is a switched type, that can hold either a person-name or a company-name.

person-name

(Optional switched) Complex type.

Complex element describing a person's name. The entire element is defined earlier in the document.

company-name

(optional, switched) String

If the account in question belongs to a company, the company name, rather than the person name will be used.

balances

(Mandatory) Complex element.

The balance element stores the elements reporting the distinct balances for the account.

aged-balance

(Optional) complex element.

Defined earlier.

prior-balance

(Mandatory) decimal.

The balance of the account prior to the period being reported. This is a simple summary of the unallocated balances of any payments and charges in that time period. It does not rebalance the account, as is reflected in aged-balance.

period

(Mandatory) Complex element.

Wrapper for the balances that relate to the period information; the period as defined in <reporting-period>.

total-charges

(Mandatory) decimal.

Total of all charges posted to the account in the period.

total-payments

(Mandatory) decimal.

Total of all payments posted to the account in the period.

total-deferments

(Mandatory) decimal.

Total of all (active) deferments posted to the account in the period.

written-off

(Mandatory) decimal.

Total of all charges that were written off in the period.

unallocated-payments

(Mandatory) decimal.

Total of the unallocated portions of all payments within the period.

unallocated-charges

(Mandatory) decimal.

Total of the unallocated portions of all charges within the period.

future-balance

(Mandatory) decimal.

As prior-balance, except taking into account those transactions that occurred after toDate.

transaction-detail

(Optional) complex element.

If details are requested, then this element will contain a group of list-transaction elements. These are defined earlier in the document.

 

Batch Account Report

Simple wrapper permitting multiple account reports.

 

General Ledger Report



 

Student Profile (Fee Assessment Proof of Concept)


 

Key Pair (Part of Student Profile)

Simple key-pair schema to allow the transmission of key-pair values in the fee assessment module.


 

Learning Unit (Part of Student Profile)


 

KSA Action

This schema permits an external system to force updates in KSA. It is designed to allow batch operations to be performed on large numbers of accounts. The command portion of this is designed to be expanded.

 

KSA Batch Action


Wrapper to permit a number of actions to be performed on accounts.


 

IRS Form 8300

<xs:element name="irs-8300">
 

Allowable General Ledger Account Mask Import


 

  • No labels