Build a Vocabulary by hand

An alternative to generating a vocabulary is to create one by hand. Creating a vocabulary by hand requires more effort then generating one, yet has the potential advantage of forcing you to carefully consider the elements to include in your vocabulary.

The first step in creating a Vocabulary is to collect information about the specifics of the business problem you are trying to solve. This step usually includes research into the more general business context in which the problem exists. Various resources may be available to you to help in this process, including:

• Interviews—The business users and subject matter experts are often the best source of information about how business is conducted. They may not know how the process is supposed to work, or how it could work, but in general, no one knows better how a business process or task is performed than those who actually perform it.
• Company policies and procedures—Any written policies and procedures are an excellent source of information about how a process is supposed to work and the rules that govern the process. Understanding the gaps between what is supposed to happen and what actually happens can provide valuable insight into problems.
• Existing systems and data sources— Systems address specific business needs, but needs often change faster than systems can keep up. Understanding what the systems were designed to do versus how they are actually used often provides clues about the core problems. Also, business logic contained in these legacy systems often captures business policies and procedures (the business rules!) that are not recorded anywhere else.
• Forms and reports—Even in heavily automated businesses, forms and reports are often used extensively. These documents can be very useful for understanding the details of a business process. Reports also illustrate the expected output from a system, and highlight the information users require.

Analyze the chosen scenario or existing business rules in order to identify the relevant terms and the relationships among these terms. Statements that express the relevant terms and relationships are called facts, and Progress recommends developing a Fact Model to more clearly illustrate how they fit together. A simple example shows you the creation of a Fact Model and its subsequent development into a Vocabulary for use in Corticon.js Studio.

Step 1: Design the Vocabulary

An air cargo company has a manual process for generating flight plans. These flight plans assign cargo shipments to a specific aircraft. Each flight plan is assigned a flight number. The cargo company owns a small fleet of three planes: two Boeing 747s and one McDonnell-Douglas DC-10 freighter. Each airplane type has a maximum cargo weight and volume that cannot be exceeded. Each airplane type also has a tail number that identifies it. A cargo shipment has characteristics like weight, volume and a manifest number.

Assume that the company wants to build a system that automatically checks flight plans to ensure that no scheduling rules or guidelines are violated. One of the many business rules that needs to be checked by this system is:

Step 2: Identify the terms

Identify the terms (entities and attributes) for our Vocabulary by circling or highlighting those nouns that are used in the business rules you want to automate. Step 1: Design the Vocabulary is marked up:

Step 3: Separate the generic terms from the specific

Why circle aircraft and not the names of the aircraft in the fleet?  It is because 747 and DC-10 are specific types of the generic term aircraft. The type of aircraft is an attribute of the generic aircraft entity. Several cargo shipments and flight plans can exist. Like the specific aircraft, these are instances of their respective generic terms. For the Vocabulary, you identify the generic (and therefore reusable) terms.  But, ultimately, you need a way to identify specific cargo shipments and flight plans from within the set of all cargo shipments and flight plans. Assigning values to attributes of a generic entity accomplishes this goal, discussed later.

Step 4: Assemble and relate the terms

None of the circled terms exists in isolation. They all relate to each other in one or more ways. Understanding these relationships is the next step in Vocabulary construction. The following facts are observed or inferred from the example:

Notice that some of these facts describe how one term relates to another term; for example, an aircraft carries a cargo shipment. This type of statement usually provides a clue that the terms in question, aircraft and cargo shipment, are entities and are two primary terms.

Also notice that a fact “has a” relationship. For example, an aircraft “has a” tail number, or a cargo “has a” weight. This type of relationship usually identifies the subject (aircraft) as an entity and the object (tail number) as an attribute of that entity. By continuing the analysis, the Vocabulary contains 3 main entities, each with its own set of attributes:

Entity: Aircraft

Attributes: aircraft type, max cargo weight, max cargo volume, tail number

Entity: Cargo

Attributes: weight, volume, manifest number, packaging

Entity: FlightPlan

Attributes: flight number

Step 5: Diagram the Vocabulary

Using this breakdown, sketch a simple Fact Model that illustrates the entities and their relationships, or associations. In the Fact Model, entities are rectangular boxes, associations between entities are straight lines connecting the entity boxes, and entity-to-attribute relationships are diagonal lines from the associated entity. The following illustration is the resulting Fact Model:

A unified modeling language (UML) class diagram contains the same type of information, and may be more familiar to you:

It is not a requirement to construct diagrams or models of the Vocabulary before building it in Corticon. But, it can be very helpful in organizing and conceptualizing the structures and relationships, especially for very large and complex Vocabularies. The BRMS Fact Model and UML Class Diagram are appropriate because they remain sufficiently abstracted from lower-level data models that contain information not typically required in a Vocabulary.

Step 6 Modeling the Vocabulary in Corticon.js Studio

The next step is to transform the diagram into your Corticon Vocabulary. This can be done in Corticon.js Studio using its built-in Vocabulary Editor.

In Corticon.js, choose New > Rule Project to create a Rule Project. Click that Rule Project, and then choose New > Vocabulary. Then create the entities, attributes, and associations that were defined in the diagram.

The Vocabulary must contain all of the entities and attributes needed to build rules, a process that is typically iterative, with Vocabulary changes made as the rules are built, refined, and tested.

-->