Firm.Insurance, II
Example project; Business analysis, Entity Model
Story list: part I, part II, part III, part IV, part V, part VI, part VII, part VIII
index
- Solution created
- Business Entities - analysis view
- Application Entities - design view
- Database Tables - Entities mapping
Solution created
In the previous story we've created new Solution for our project:
http://catarsa.com/Articles/Code/Example-Insurance-Company-01-New-Solution
The next step needed for our Example is the Business Analysis. Result of this analysis will be converted into the Entity Model. Entities discovered this way: need to be persisted. The final step will introduce the Database table schema. A lot to do...
Business Entities, analysis view
Insurance company is an Example, which should help us understand how to develop applications with the strong support of the Catharsis framework. The main aim of these stories is to show you how to think in Catharsis Architecture. The Business case for our application is of course simplified and concerning on the web-application part mostly (no import or export routines). But anyhow, we will face almost any possible issue of the Entity management and give you answers 'how to' do it in common. If you'll find any area which should be described in more detail or which is completely missing, do not hesitate, append comment.
Business Analysis
Analysis results: Insurance company needs application which will help with the day-to-day business operations. There are three main Entities from the business point of view:
- Agent (the person or company hunting the customer...)
- Customer (the insured and paying person)
- Contract (the Insurance policy, settings of the contract)
The amount of Agent won't access 1000 in next years. Every Agent need its own Commission rate, which is applied for his revenue calculation. Agents are distinguished by Code, coming from external public source (unique; typed into our system manually once, when new Agent is inserted). Agents are internal or external (employed or contracted).
Customer is always the person (in reality it could be a company of course, but we accept only humans). We need their Name, Address, Birth date. Customers can have (none,) one or more Contracts. There is a dream to have millions of Customers.
Contract is a bit 'Life insurance' oriented. There is a payment (per month, quarter, year) and the final TargetAmount - sum insured. Each contracts can have different Currency selected. There is a start and finish date (it must be the first day of any month). Signing date will be reliable for the Commission calculation. The Contract represents one Product, which affects the sum insured calculation. Our solution probably won't go such far, we'll select the Product for Contract, and maybe later we will extend it...
Contract can also have one or more Beneficiary (the Person who will get the money when customer cannot...). There could be even none! The planned amount of contracts is in tens of millions...
That's the requirement summary, spoken. There are even more wishes, and some even hidden expectations. These could be called as standards: e.g. Table view, which could be paged, sorted, filtered. The detail view and edit view. Users are ready to cooperate on the UI adjusting (naming, titles ...). For some marketing campaigns the Excel sheet of Customers, Contracts would be helpful. Currency inserted must be valid, the same for Country, Payment period. Commission Rate should (can) be from 0.000001 to 100. And so on ...
Application Entities, design view
Now we have to translate these requirements into the Application Entities. The recommended way is to find out the CodeLists Entities first.
CodeLists
The list of values which have unique, well known 'Codes' and their count is very small. The best examples are Country and Currency, used in almost any financial application.
CodeList are used for other Entity's definition, for instance: Contract (each instance) has its own Currency selected. The Agent can be Internal or External, and 'who knows?' in the near future it could be even 'Corporate' or 'Foreign'...
What is the benefit, the added value of the CodeLists? There are three:
- Separation of concern - CodeList has its own management, available in run-time
- Validation check - Values can be selected, no need to check the 'typed texts'
- DB storage optimization - Each CodeList owner references only the CodeList ID, instead of the char array
The Catharsis framework extends these CodeLists with the bool setting IsVisible. That comes from the experience! There is almost 200 Countries all around the world. Even in scenarios, when all of these countries are used, some of them can be used more often. And for users it is very helpful, if the list (combobox list) contains only the part of them.
Every application created with the Guidance provides for this purposes the IsVisible switch. Only the values which are marked as IsVisible = true are rendered in the ComboBox lists. Users can in the application run-time easily adjust this setting for any CodeList. And that will in fact keep their application user-friendly!
What are the CodeLists in Insurance company example?
The Agent has currently one: AgentType (External, Internal)
Customer could have at least the Country. We can also provide the City or Street CodeLists, but their count would be so large that it would (almost surely) lose any of the above mentioned advantages. We will store them as text values.
The Contract has few candidates. PaymentPeriod is obvious. Also the Currency. The last would be the Product.
In the real world, the Product would be more than a code list, it could have some calculation matrix dependent on the client age, insured period ... For us and our example it would be the CodeList! We can still in the future move it, because the C# .NET application will reference the Product without any dependency on the persistence table or type. Only the IProductDao interface implementer would have to be changedThe Entities
We've identified CodeLists, so we can move on and uncover the 'full' Entities. At the first look we will surely have Agent, Contract and Customer.
There are some very similar settings for different business entities. These are the Person based definitions: Name, Address, etc. for the Customer and the Beneficiary included in the Contract. Why to store the same information in the two Application Entities? There could even rise the situation when a person is the Customer in one contract and the Beneficiary one in another.
The separate Person Entity will do this job for use. Every (physical) person will be inserted in the system as a Person instance. Then it could be used for 1-1 mapping Customer-Person or the N:M mapping for the Contract-Beneficiary. Great.
The Application Entities review
The list of the currently known Entities which will be persisted and used in our application contains 9 elements:
- Currency
- Country
- Product
- AgentType
- PeriodTime
- Agent
- Contract
- Customer
- Person
Database Tables - Entities mapping
There was 9 entities identified and 1 pair relation Contract-Beneficiary. This could easily be transformed into 10 Tables in the Database.
The Catharsis framework will help us reduce this table count! This is possible due to the ultimate power of the ORM tool: NHibernate. The currently used version in Catharsis ver. 2.5 is NHibernate 2.1 with LinFu proxies. NHibernate One-Table-per-Hiearchy strategy is used with cooperation of the Catharsis built-in base class CodeList.
CodeList is the base class implementing almost everything for the simple derived types (implementing only the ICodeList interface properties). All these classes are persisted in 1 Table, which has the ID, Code, Name and IsVisible columns for the ICodeLists purposes and Discriminator column for NHibernate handling.
The CodeLists Entities are intended as the small lists of values. Expected size is tens or hundreds at maximum. And that is why we can from the beginning optimize their table design. Their ID column won't be horrible Guid (16 Bytes), nor the long (8 Bytes) and even not the int (4 Bytes). The columen type will be the smallint (SQL Server world - 2 Bytes). What it means? There are these aspects of this approach
- + Every ID will take 2 bytes in the persistence.
- - There cannot be more then 32 thousands CodeList values (2 bytes are just 2 bytes, and when signed)
- + Any 'full' Entity table referencing such a CodeList needs only 2 bytes for a reference!!!
- + C# .NET code will (thanks to NHibernate) map them into int (compliant) values.
Very good, we have one table with smart mapping for many Entities (CodeLists) saving lot of space:
1 milion of contracts referencing the SmallInt for Currency, Product and PaymentPeriod will save 6 bytes per row == 6MB space for the whole table. If these will be used for three Indexes, saved space is 6MB + 36MB = 24 MB. And that means that searching can target much less data!
But to have it even better, we can do more for space saving. If there are some CodeLists, which won't ever exceed the tens we can use the second Catharsis built-in approach: Tiny CodeLists.
These only differ in base classes for Entity and Dao. Nothing else in the code is tuched! For the Database needs, the Tiny CodeLists have a special table: CodeListTiny, where the Column ID is of the type tinyint (1 Byte)
Tiny CodeLists in practice? Female/Male; Month/Qurter/Year; External/Internal...In our solution we will move two CodeLists to the Tiny world: PyamentPeriod and AgentType. Now we really did covered whole the Business analysis and the Application Entities with the Database tables! This is the resulting DB schema diagram:
If you'd like to download the Create table SQL script:
The above diagram (and also the above SQL scripts) contain foreign-keys, to force and assure the DB health. Without any other explanation, we won't need and use these foreign-keys == constraints. All the checks will be done on the Business tier - in Facades' Validators: see http://catarsa.com/Articles/Code/Validator-how-to-use-it
Next? Guidance Recipe, CodeLists
In the next story we will firstly use the Catharsis Guidance 'Recipe'. The most funny and really simple is the ICodeList Entity creation. So we can expect lot of fun with the Currency, Country, Product, AgentType and PaymentPeriod
http://catarsa.com/Articles/Code/Example-Insurance-Company-03-Code-Lists
good
very good