How do you relate with external systems and communicate with other companies?
How do you define internal identifiers which grow with the application success?
How can you bridge the customer world with your software solution?
What are the good practices to create a maintainable, legible and efficient model of your domain model?
Entity Concept
We need an approach to model customer domain entities and map them to a legible and maintainable software construct.
An entity is a user domain model abstraction and is mapped to a software type. Any entity has
- Unique mandatory internal object identifier oid, we recommend the use of numeric values to improve performance
- External and public identifier id, we recommend the use of text to adequately support various external identification scheme. An example is the European enterprise identifier EUID identifying a company or a certified natural person in Europe
- Human readable name name.
- A set of tags to classify the instance through a crowd based ontology. Tags are often called labels.
- A list of comments to add human readable information to the instance. The comments can be extended to add audit information such as functional change information or activities related to the instance.
The entity features should be defined as a set of mixin interfaces.
Internal Object Identifiers oid
The object identifier oid uniquely identifies an instance in a given context. This identifier shall be a numerical value to increase performance of persistent solutions. It is used as an internal identifier in the application. It should never be visible outside the system or published through an API.
Ideally the identifier is universally valid and uniquely identifies an instance in all contexts. For example the concept of UUID tries to provide such an identifier. The drawback is that UUID is not a numerical value.
History has taught developers not to spare on the size of identifiers. Please use a long value meaning 64 bits.
Avoid using the internal identifier to communicate with external systems. If you respect this rule you are free to migrate your objects to another identification scheme in the future. New schemes are often helpful when the application grows or you have later to import and take over a lot of legacy data.
External Object Identifiers id
The external unique identifier id shall uniquely identify an entity instance. It is used as an external identifier to communicate with other systems. It should always be visible outside the system and used in any API.
Try to have exactly one external identifier per object to communicate with external systems. This restriction is a corollary of the rule stating an instance is owned by exactly one system. This system is the one defining and managing the external unique identifiers.
You should clearly define the owning system for the external identification scheme. This information shall also be documented and accessible to all involved parties. This process is part of the enterprise architecture activities of your ecosystem.
When working with legacy system ownership and external identifiers are often a murky situation. You often have multiple source of external identifiers, sometimes overlapping and sometimes no covering all instances. You have to formulate a long-term strategy to clean-up your landscape and handle the problem until clean-up activities are completed. By handling we mean administrative and import rules matching the various external identifiers to the same object.
One possible solution if other systems have define their own external identifiers due to system constraints or through history is to store this information as a tag specific to the external system involved. So you have a scalable approach and do not pollute your domain model with spurious information defined in external systems. Upon completion of the refactoring these tags document historical information and could safely be removed.
Multiple external object identifiers imply the existence of mapping functions to identify the object referenced. Because the ownership of external identifiers is outside your system, you are dependent to these systems and have to hope they are good citizens. The key rule of good systems is that they never change external identifiers. As soon as you modify identifiers they are per definition no more real identifiers.
Names name
The entity name is a human readable name to distinguish between entity instances. Ideally it should be almost unique. The fallback is always to use the external unique identifier id known to all external systems. The drawback is that we have no guarantees it is readable. Names are essential for well designed user interfaces. Never require from your users to memorize external identifiers, please provide names.
For example first and last names of a person is the name for a natural entity. Social security number is a possible external identifier. An internal identifier is used as primary key in the persistence storage.
Advices
- Internal object identifiers are identifiers. An identifier is immutable and should be numerical for performance reasons.
- External object identifiers have exactly one application in charge to create them.
- Names are human readable and improve the legibility and usability of user interface and reports.
External identifiers can be tricky. In Switzerland we had an old social security number which is still referenced in a lot of legal systems. For example it is still part of your tax salary yearly form.
We have a new social security number which is used in social insurance workflows. The same number is also used in medical insurance workflows.
We have also a federal identity card number, a federal passport number, a federal driver license number, additional medical card insurance numbers, a state tax personal identification number, and more external identifiers. All these external identifiers shall referenced the same natural person.
More interesting is that a tourist living in the European zone has none of these numbers.
Please implement the internal identifier feature as an interface marker. External identifier and name features can be grouped in one interface. Below an example written in Java.
public interface HasOid extends Serializable {
long oid();
}public interface HasId extends HasOid {String id();void id(String id);String name();void name(String name);}
We provide a Java library BUS implementing these constructs. More information is available under tangly open source components.
Extensions
See our blog how to extend the entity concept with the powerful and flexible concepts of tags and comment approaches.
Another blog shows a constrained form of tags using the concept of reference codes also called reference tables or lookup tables.
Related concepts are discussed in our blog series
No comments:
Post a Comment