Why Delphi should have an application dictionary ( Part I )

By: Armando de la Torre Mothelet

Abstract: This article explains how Delphi would benefit from an application dictionary

    What is an Application Dictionary

         As programmers we are faced with the challenge of writing and maintaining applications. A number of elements , which here on will be called assets , are required to develop such business application. The list assets includes ( but is not restricted to ) :

  • Classes
  • Tables
  • Asociations
  • Messages ( e.g. warning, error , success)
  • Help documents ( internal and external help ).
  • Forms
  • Lookups
  • Views
  • Queries (SQL)
  • Security information
  • Proyects
  • Diagrams
  • Modules ( logical partition of application areas ).
  • Test cases
  • Recordings

         An application dictionary is a tool where all these assets are stored and managed. Even more , the dictionary provides a number of services which make developing and changing applications easier. The key services an application dictionary provide are:

  • Version management
  • Change control
  • Assets Listings (browsing)
  • Use lists (relation between assets)
  • Locking mechanisms
  • Translation facilities

         Additionally , a data dictionary can provide (given the proper framework) application metadata which can significantly reduce the amount of code needed to build an application and can be the base to create other tools :

  • Test data generators
  • Data loading facilities
  • Migration tools ( version upgrade )
  • Project tracking tools
  • Wizards / Code Generators

    Asset Management

         The dictionary will normally be a relational database which will store all the development assets mentioned in the previous section. To gain access to these assets the developer must log-in into the dictionary. Every time a developer wishes to make changes to an asset , the dictionary checks it is free or if it is currently being locked by another user. The locked asset can not be edited until it is released and a new version is generated. Once a lock is acquired , the asset is included into a project. A project can only be released ( e.g. into production ) when all of its assets have been individually released.

The key point from the above paragraph are :     

  • Assets are not stored locally ( e.g. in the developer’s workstation ) , but in a central repository.
  • Developers must log-in into de dictionary to gain access to the assets.
  • Assets can only be changed by one person at a time.
  • Changes are grouped together in projects.
  • Every change to any asset is recorded in the dictionary (who , when )

    Projects, Modules, Users

         A development project has an estimated duration, involves a number of developers and the modification or creation of certain modules during its lifetime. A project can be classified in the following types :

  • New development – If its goal is to create a new module or system.
  • New version – If its primary objective is creating a new version of an existing application.
  • Localization – If it is intended to create a version that is specific for a certain country or economy sector.
  • Bug fix – If its goal is to correct a malfunction .

         It is particularly important to note the dictionary’s behavior with a localization project. Due to its “local” nature , changes made with such a project do not become the “default” active version unless a new “local” project for the same sector or country is started.

         Modules are logical partitions of applications. An accounting system might be divided by modules into accounts receivable , accounts payable, general ledger and fixed assets. Including module information in all the dictionary assets provides the following advantages:

  • Assets can be found easily ( e.g you can search all the tables from the fixed assets module).
  • They help control a project , defining a project scope ( e.g. this project is intended ONLY for the fixed assets module).
  • They enhance the project security ( e.g. this programmer can only change code from the accounts receivable module).
  • The scope of changes may become appearent ( e.g. deleting this table will have an impact on 3 modules ).

         Users are the people who need to access the assets from the dictionary. There are 5 kind of users :

  • Managers – Are in charge of creating projects, maintaining modules and creating other users.
  • Designers – Are responsible of collecting requirements, and rendering them as diagrams and textual descriptions.
  • Developers – Are in charge of creating actual applications based on diagrams.
  • Testers – Are in charge of assuring the system quality by performing unit and integral tests.
  • Translators – Are responsible of translating the application texts into other languages.

         Of course , it is possible that these roles are combined ( e.g there might be a Developer / Tester or a Designer /Developer / Manager) . Having the capacity to restrict a users permit is important , as we probably will not want to have a professional translator messing with the code or diagrams.

         Figure 1 Shows the Class diagram for projects, modules and users

Hide image
Click to see full-sized image

Table 1 – Project table

Field Name

Key

Type

Description

ProjectKey

1

Char(20)

Pneumonic for the project

ProjectName

Char(100)

Project Name

CreatedOn

Datetime

Date and time in which the project was created

CreatedBy

Char(15)

User who created the project

ChangedOn

Datetime

Date and time of the project’s last change

ChangedBy

Char(15)

User who last changed the project

EstStartDate

Date

Estimated start date

EstEndDate

Date

Estimated end date

ReleaseDate

Date

Date of project Release

ReleasedBy

Char(15)

User who released the project

ProjectKind

Char(10)

New/Version/Localization/Bug Fix

Country

Char(2)

IsoCode of county ( localization )

Sector

Char(10)

Key of economy sector ( localization )

    Classes , Tables and Asociations

         Although ECO applications are model based , storing the model in a dictionary would bring additional benefits :

  • Version control
  • Additional model information
  • Integrated help
  • Multilingual support
  • Easier query/report building

         One of the most important aspects of a class within an application is its persistence capability. In business applications a persistent class will usually be stored into a database table, hence additional information is required to perform storage and retrieval operations. Because persistence is achieved by the use of a database, it is very important to be able to determine the relation between the application tables. Often a developer is faced with the questions: which tables/classes are needed to retrieve this information? What is the relation between these tables/classes ?

         There are several kinds of persistent classes according to their use :

  • Configuration – Change the behavior of the application, allow customizing the application. We can further subdivide configuration classes into :
    • Organizational – Define the structure of the business.
    • Transactional – Define the behavior of the business.
    • Reference – Used by the master data as a reference , but with no other effect in the application
  • Master Data – Reference objects used to perform daily duties. In a sales application, this would include customers, products and discounts.
  • Transactional Data – Used to store daily operations. Taking the sales application as an example, sales and returns would represent the transactional data.
  • Summary Data – Used to store summarized transactional data.

         Figure 2 shows the class diagram for Classes, Tables and Asociations.

Hide image
Click to see full-sized image

    Messages, Documentation ,Hypertext

         Messages constitute the simplest form in which an application communicates with the end-user. Messages may be of the following types:

  • Error – A problem has occurred. The user is notified of the failure and has to take an action before continuing. Example : Customer number is missing.
  • Abortion – A fatal error has occurred and the current operation will be terminated / canceled . The user is notified, but has no choice but to accept the message.
  • Warning – The system warns the user about an unusual state of the current operation. He can choose either to continue or abort with the current operation. Example : All disk data will be deleted. Continue ?
  • Success – It informs the user that an operation has been successfully carried out.
  • Information – The user is informed of an event . Example : You have new mail in your inbox.

         Although simple messages may require no further explanation , in some cases the user may require further information in order to take an adequate decision or to know how to proceed. A message’s help can include :

  • Links to other help topics
  • Links to a screen ( form ) within the application
  • Links to a menu
  • Links to external applications

         It is therefore crucial that a message makes part of the dictionary . Among other things , the message should have :

  • A pnemonic code – Used by the programmer to invoke it . For example INVALID_ACCT_NUM – Invalid account number
  • Parámeters – Parameters passed to the message and displayed to the user
  • Description – A brief description of the error with less than 255 characters
  • Documentation – A longer description of the message, which can include possible courses of action and links. Example – The account number you typed is not valid. Either : use the lookup to locate a valid account OR create the account in the chart of accounts.

         I hope I have made clear just how important it is to have messages controlled and documented. I will also emphasize the fact that documentation can not be just a plain-text description . A comprehensive help system must support hypertext with links to other sections of the documentation as well as links to other parts of the application and even allow the execution of external applications.

         Documenting a system can be ( when thoroughly performed ) a daunting task because of the huge amount an variety of documents that can be generated. What follows is a list of the most common kinds of help within a business application.

  • Module overview – Provides an overview on the purpose of a module. For example : The accounts receivable module is used to register debtor operations as well as perform dunning.
  • Process description – Describes a process within a module . For example : how to perform fuzzy dunning , how to run the dunning procedure. A process description usually involves more than one object/document and requires the use of several functions which pertain to an object.
  • Object/Document help – Describes an object or document which is usually part of a process. Example : An invoice document , a debtor.
  • Function description – Describes a single operation within an object or document and is usually equivalent to a method or the execution of an operation within the screen menu.
  • Field description – Describes the use of a field, and possibly other fields and operations which are related to it.
  • Glossary – Describes terms which are specific to the application .
  • Examples / Tutorials – They demonstrate or give instructions on how to perform a certain task
  • Message description – Describe messages in detail and give information on subsequent courses of action.

    Forms

         Within a business application there are several kinds of forms :

  • Browsing Forms – They are usually made of a selection screen and a list. The selection screen is required to restrict the amount of records that will appear in the list. Forms for browsing classes with few instances ( less than 1000 ) may not require the selection screen. For simple classes ( those that do not use aggregation ) the browsing form can be used to maintain the instances. For complex objects the form can be linked to a business Object Form.
  • Business Object Forms – Are used to maintain a single object of a persistent class. They normally have three states :
    • Create – Allows creating an instance
    • Update – Allows performing changes to an instance
    • View –Allows viewing the instance , but allows no changes ( not even through operations ).
  • Dialog forms – Dialog forms are not linked to a persistent object, but allow the user to specify additional information when performing an operation.

         From the point of view of the dictionary it is important that the following attributes are stored with the form :

  • Name
  • Description
  • Type ( Browsing ,Business,Dialog )
  • Object ( for business object forms )
  • View/Table/Query (for browsing forms )
  • Module

         The above information allows to quickly find any form ( think of how difficult it can be a find a form in Delphi when the project has 200 or 400 forms and you are not-very-sure what the form’s name was).Also , with some parsing , it opens the possibility of getting table-form and object-form use lists. Use lists are particularly important when making changes to applications , as they give us some insight in the scope of the changes . A use list would answer a question like : which forms are affected if I remove table XXX ?

    Conclusion

         In the first part of this article we’ve seen what is an application dictionary and what programming assets are stored within it. Also an overview has been given about the advantages of using a Dictionary to manage some of these assets (projects, modules, Classes, tables, associations, messages, documentation, forms).

         In the second part I will continue exploring the advantages of an application dictionary for the rest of the assets. I’d truly appreciate any feedback from the community, particularly from the R&D team.

         Some topics I would like to hear about follow:

Does a dictionary seem like a useful tool?

Is it feasible?

Does it overlap with existing functionality?

Would it corrupt the traditional way of building applications with Delphi?

Server Response from: ETNASC01