Search Posts

Visits: 13

Nobuyuki SAMBUICHI
ISO/TC295 Audit data services/
Convener at SG1 Semantic model
Co-project leader at WG1 AWI 21926 Semantic data model for audit data services

1. Introduction

Technological Foresight & Innovation: Understanding software’s evolving nature, we recognized the pitfalls of solely relying on specific tools. JISC’s Python tools, designed with future adaptability in mind, convert complex outputs into universal CSV formats.

We’ve effectively standardized 71 tables, incorporating over a thousand data fields and their respective primary/reference keys. In light of this substantial achievement, the task of updating a single table with 1200 classes and properties appears relatively straightforward by comparison.

This guide outlines the process of transforming data from an ADCS format into an AWI Semantic model format. The focus is on using Unified Modeling Language (UML) for class modeling and enhancing semantic clarity in data representation.

2. Understanding UML and Semantic Modeling

Unified Modeling Language (UML) is essential for modeling and designing software systems. In the context of data transformation:

2.1. Class in UML

A class represents a blueprint for objects. It’s a template for creating instances with a specific set of attributes (properties) and behaviors (methods).

2.2. Property of a Class

Properties are characteristics of a class. They can be simple attributes (like a string, number, date) or associations (relationships with other classes).

2.3. Types of Properties

Attribute: Intrinsic properties of the class (e.g., a person’s name or age).

Association: A relationship between two classes. There are different types:

  • Referencing Association: Links one class to another, indicating a relationship without implying ownership (e.g., a student enrolled in a course).

  • Aggregation: A specific type of association that implies a ‘whole-part’ relationship but without strict ownership (e.g., a car and its wheels).

  • Composition: Stronger than aggregation, it implies ownership and a ‘part-of’ relationship. The lifecycle of the part is tied to the lifecycle of the whole (e.g., a person and their heart).
    Specialization (Inheritance): A mechanism where a new class (subclass) is derived from an existing class (superclass), inheriting its properties and possibly adding new ones.

  • Specialization (Inheritance): This mechanism allows for the creation of a new class (subclass) derived from an existing class (superclass). The subclass inherits the properties and methods of the superclass, while also having the ability to introduce its own unique properties and methods. This concept is pivotal in object-oriented modeling for representing hierarchical relationships and promoting reusability. For example, a ‘Vehicle’ class could be a superclass, with ‘Car’ and ‘Motorcycle’ as specialized subclasses inheriting common properties like ‘EngineType’ but also having unique attributes like ‘Number of Wheels’.

3. Preparation Tasks

To resume the original semantic model from the ADCS table and prepare it for transformation into an AWI Semantic model sheet, follow these steps:

3.1. Resuming Class and Property Names

Split and Join Names:

In ADCS, field names are concatenated and shortened with underscore (‘‘). Start by splitting these names at each underscore (‘‘) and then join them with a space. For example, ‘Reporting_Amount’ becomes ‘Reporting Amount’.

Resume Original Words from Abbreviations:

Convert abbreviations into their full forms based on context. For instance, ‘JE’ should be expanded to ‘Journal Entry’. This step requires domain knowledge to accurately interpret each abbreviation.

3.2. Define Data Types for Each Field

Reinterpret Data Types:

Where ADCS uses specific data types and representations (e.g., ‘Decimal’ with representation ‘%22.4f’), redefine these to more semantically meaningful types in AWI Semantic model. For example, ‘%22.4f’ as ‘Decimal’ becomes ‘Amount’ in AWI Semantic model, clarifying its semantic meaning as a monetary value.

3.3. Refine Description

To refine the descriptions according to ISO 11179-4 standards, they should be clear, unambiguous, singular, and stand-alone. The current descriptions have issues like embedding procedural information, relying on external references, and not being self-contained. Let’s refine a few examples:

  1. Original: “The unique identifier for the journal entry. Typically auto-generated by the system.”
    Refined: “A unique identifier assigned to each journal entry.”

  2. Original: “The GL account number. Shall match the GL_Account_Number used in the BAS_Chart_Of_Accounts table.”
    Refined: “The account number corresponding to an entry in the General Ledger.”

  3. Original: “Fiscal year in which the Effective_Date occurs…​”
    Refined: “The fiscal year, formatted as YYYY, during which the transaction is effective.”

These refined descriptions are singular, precise, and stand-alone, adhering to ISO 11179-4 guidelines. They avoid procedural details and external references while clearly stating the essence of each concept.

4.1 Requirements
A data definition shall:
a) be stated in the singular
b) state what the concept is, not only what it is not
c) be stated as a descriptive phrase or sentence(s)
d) contain only commonly understood abbreviations
e) be expressed without embedding definitions of other data or underlying concepts

4.2 Recommendations
A data definition should:
a) state the essential meaning of the concept
b) be precise and unambiguous
c) be concise
d) be able to stand alone
e) be expressed without embedding rationale, functional usage, or procedural information
f) avoid circular reasoning
g) use the same terminology and consistent logical structure for related definitions
h) be appropriate for the type of metadata item being defined

— ISO 11179-4 Information technology — Metadata registries (MDR) — Part 4: Formulation of data definition

4. Semantic Analysis and Definition of Object Classes in GL Data Model

4.1. Check for Repetitive Field Sets

Identify Repeated Field Patterns:

Look for sets of fields that frequently appear together in ADCS. For example, a pair like ‘Reporting_Amount’ (Decimal, %22.4f) and ‘Reporting_Currency_Code’ (String, %3c) is a common pattern.

Create Reusable Structures:

In AWI Semantic model, define these repeated patterns as reusable structures or classes. For instance, an ‘Amount-Currency’ class could encapsulate fields for monetary amount and currency code, reflecting their repeated use across different contexts.

4.2. Integrating into AWI Semantic model

Class and Property Structuring:

Use the revised names and data types to structure classes and properties in AWI Semantic model. Ensure that each class and property reflects its real-world entity or concept accurately.

Handling Associations and Specializations:

For fields forming associations (like reference keys), clearly define their relationship types (association, aggregation, composition) in AWI Semantic model.

Where specialization is evident (e.g., subclasses for different types of activities), define these relationships, ensuring inheritance from appropriate superclasses.

Finalizing the AWI semantic model:

After restructuring the fields with semantic names and data types, and defining classes with their properties and relationships, review the AWI semantic model for completeness and accuracy.

Ensure that the AWI semantic model is a true representation of the original semantic intent of the ADCS table, with clear, meaningful class structures and relationships.

By following these steps, you will be able to transform the flat, abbreviated structure of the ADCS table into a more meaningful and semantically rich AWI semantic model, facilitating better understanding and utilization of the data.

Preliminary tasks for semantic model resumption involve understanding and modifying the structure and naming in the ADCS data.

5. Understanding Multicurrency Monetary Amounts in System Design

5.1. The Basics of Monetary Amounts and Currency Code Class

In financial systems, the “Monetary Amount” data type is crucial, consisting of:

  • Decimal Number: Represents the total amount, such as 100.25, without currency symbols.

  • Minor Unit: Refers to the fractional part after the decimal, limited in digits, like 25 in 100.25.

  • Currency Code: The standard abbreviation of the currency (e.g., USD).

The Currency Code Class is introduced to enhance this structure:

  1. Standardization: It adheres to ISO 4217 standards for consistency in currency representation.

  2. Precision in Financial Calculations: Defines minor unit digits for each currency, essential for accurate calculations.

  3. Enhanced Clarity and Interpretation: Provides clear identification of currencies, crucial for global transactions.

  4. Ease of Integration and Maintenance: Simplifies integration with other systems and maintenance related to currency information.

Understanding these components is vital for ensuring precision in financial transactions.

5.2. Designing a Multicurrency Monetary Amount Class

For handling multiple currencies, a “Multicurrency Monetary Amount” class becomes essential. Here’s how it can be structured:

  • Functional Amount: Amount in the entity’s primary accounting currency.

  • Reporting Amount: Amount for regulatory reporting in a specific currency.

  • Local Amount: Amount in local currency for foreign operations.

  • Transaction Amount: Amount in transaction currency for international business.

Each amount is paired with its corresponding currency code, offering a comprehensive view of financial transactions in various currencies.

5.3. UML Representation of Multicurrency Amounts

Representing this in UML using PlantUML script:

@startuml
class "Multicurrency Monetary Amount" {
  - Functional Amount: Decimal
  - Reporting Amount: Decimal
  - Local Amount: Decimal
  - Transaction Amount: Decimal
}

class "Currency Code" {
  - Code: ISO4217_Code
  - Minor Unit Digits: Integer
}

"Multicurrency Monetary Amount" "*" -- "1" "Currency Code" : Functional Currency
"Multicurrency Monetary Amount" "*" -- "1" "Currency Code" : Reporting Currency
"Multicurrency Monetary Amount" "*" -- "1" "Currency Code" : Local Currency
"Multicurrency Monetary Amount" "*" -- "1" "Currency Code" : Transaction Currency
@enduml
umlD

5.4. Integration with the Currency Code Class

The introduction of the Currency Code Class enhances the implementation of the ADCS table structure, particularly in defining the Monetary Amount Class. In the Multicurrency Monetary Amount class, each monetary amount type is linked to a specific instance of the Currency Code, denoting the associated currency.

The following UML class diagram clarifies this relationship. The Monetary Amount class is defined with an ‘amount’ attribute and associations to the Currency Code, illustrating a structured and meaningful connection between monetary values and their respective currencies.

@startuml
class "Monetary Amount" {
   - Amount: Decimal
}
class "Currency Code" {
  - Code: ISO4217_Code
  - Minor Unit Digits: Integer
}
"Monetary Amount" "*" -- "1" "Currency Code" : Currency

class "Multicurrency Monetary Amount" {
}
"Multicurrency Monetary Amount" "*" *-- "1" "Monetary Amount" : Functional Amount
"Multicurrency Monetary Amount" "*" o-- "1" "Monetary Amount" : Reporting Amount
"Multicurrency Monetary Amount" "*" o-- "1" "Monetary Amount" : Local Amount
"Multicurrency Monetary Amount" "*" o-- "1" "Monetary Amount" : Transaction Amount
@enduml
umlE

Each “Amount” is a Decimal, and each “Currency Code” is a String. This design encapsulates the complexity of handling multiple currencies in a single class.

5.5. Integration with the Currency Code Class

To further enhance the Multicurrency Monetary Amount class, an association with another class, Currency Code, is established. The Currency Code class has the following attributes:

  • Currency Code (ISO): The standard ISO code for each currency.

  • Minor Unit Digits: The number of digits after the decimal point for each currency.

Each currency code in the Multicurrency Monetary Amount class is defined as an association, referencing the Currency Code class. This association is crucial to retrieve information about the minor unit, ensuring precise financial calculations and compatibility with international standards.

5.6. Conclusion

Designing for multicurrency support requires careful consideration of both the monetary values and their associated currencies. By ensuring each amount is paired with a relevant currency code, financial systems can accurately manage and report monetary data across different currencies.

6. Example: Extracting Table Definition from ADCS and Defining in AWI

Example ADCS Table Extraction

Table 52 — GL_Details

No Name Data Type Representation Description

1

Journal_ID

String

%100s

The unique identifier for the journal entry. Typically auto-generated by the system.

8

JE_Type_Code

String

%60s

The code of journal entry type. Shall match the JE_Type_Code in the BAS_Journal_Entry_Type table.

Table 53 — Identifiers in GL_Details

No.

Name

Identifier

Referenced field

Referenced table

1

Journal_ID

PK

n/a

n/a

8

JE_Type_Code

REF

JE_Type_Code

BAS_Journal_Entry_Type

In AWI Semantic model

Type Class Name Property Name Data Type Associated Class Description

Attribute(PK)

GL Details Line

Joirnal ID

Identifier

Association

GL Details Line

Journal Entry Type Code (refers to)

Journal Entry Type

Note: Description texts are removed property type defines its semantic meaning and there is no further information.

6.1. Example: Defining ‘Entered Class’ Based on ‘Activity’ Superclass

In this scenario, we assume ‘Activity’ as a superclass that represents general actions or events within a system. This superclass might include attributes like ‘ActivityID’, ‘Timestamp’, and ‘UserID’.

Now, let’s define a specialized class:

Superclass: ‘Activity’

  • Properties:

ID

Type

L

Module

Class name

Property name

M

Data type

Associated class

Description

GEN02_01

Association

2

General

Activity

User ID

0..1

Base User

The unique identifier for the person who did the activity.

GEN02_02

Attribute

2

General

Activity

Date

0..1

Date

The date of activity. This should be a system generated date (rather than user-created date), when possible. This is sometimes referred to as the creation date.

GEN02_03

Attribute

2

General

Activity

Time

0..1

Time

The time of activity.

GEN03

Class

1

General

Address

Address information.

L: level, M: multiplicity

Specialized Class: ‘Created’

ID Type L Module Class name Property name M Data type Associated class Description

GEN15_01

Specialization

2

General

Created

is a

0..1

Activity

GEN16

Class

1

General

Credit Amount

The accumulative credit total during particular accounting period.

L: level, M: multiplicity

  • Inherits from:
    ‘Activity’

  • Additional Properties:
    none

In the GL details context, ‘Created’ represents a specific type of activity related to GL entries. It inherits common attributes from ‘Activity’.

7. Utilization in GL Details

In the GL details table, you would then have entries for ‘Created’ and ‘Approved’ as follows:

In GL Detail Line (AWI Semantic model)

ID Type L Module Class name Property name M Data type Associated class Description

GEN02_01

Association

2

General

Activity

User ID

0..1

Base User

The unique identifier for the person who did the activity.

GEN02_02

Attribute

2

General

Activity

Date

0..1

Date

The date of activity. This should be a system generated date (rather than user-created date), when possible. This is sometimes referred to as the creation date.

GEN02_03

Attribute

2

General

Activity

Time

0..1

Time

The time of activity.

GEN03

Class

1

General

Address

Address information.

GEN15_01

Specialization

2

General

Created

is a

0..1

Activity

GEN16

Class

1

General

Credit Amount

The accumulative credit total during particular accounting period.

GEN06_01

Specialization

2

General

Approved

is a

0..1

Activity

GEN07

Class

1

General

Balance

Balance monetary amounts recorded in their currency. The balance here refers to the remaining balance unpaid or needing settlement, which can be calculated by analyzing net of the originating invoice and any payment made and adjustments against it.

GL02_01

Attribute(PK)

2

General Ledger

General Ledger Line

Journal ID

0..1

Identifier

Unique identifier for each journal entry.

GL02_02

Attribute

2

General Ledger

General Ledger Line

Journal Number

0..1

Identifier

Number of the journal entry

GL02_03

Association

2

General Ledger

General Ledger Line

GL Account Number

0..1

Base Ledger Account

Number of the GL account.

GL02_04

Association

2

General Ledger

General Ledger Line

Fiscal Year

0..1

Base Accounting Period

Fiscal year in which the Effective Date occurs.

GL02_05

Association

2

General Ledger

General Ledger Line

Accounting Period

0..1

Base Accounting Period

Accounting period in which the Effective Date occurs.

GL02_06

Attribute

2

General Ledger

General Ledger Line

Effective Date

0..1

Date

Date of the journal entry, no matter when the entry is received or created.
This sometimes refers to the accounting date or accounting effective date.

GL02_07

Attribute

2

General Ledger

General Ledger Line

Journal Line Number

0..1

Text

Number of the line within a journal entry.

GL02_08

Association

2

General Ledger

General Ledger Line

Journal Entry Type Code

0..1

Base Journal Entry Type

Code for the journal entry type.

GL02_09

Attribute

2

General Ledger

General Ledger Line

Journal Entry Header Description

0..1

Text

Description of the entire journal entry as described by the journal entry header.

GL02_10

Attribute

2

General Ledger

General Ledger Line

Journal Entry Line Description

0..1

Text

Description of the individual line within the journal entry.

GL02_11

Association

2

General Ledger

General Ledger Line

Source Code

0..1

General Ledger Source

Code for the source from which the journal entry originated.

GL02_12

Attribute

2

General Ledger

General Ledger Line

Bill Number

0..1

Text

Number of the bill.
A bill usually includes bank drafts, promissory notes and checks. A bill may be issued by the drawer who agreed upon themselves or entrusts the drawee at sight. A specified date to the payee or bearer unconditionally pays a certain amount of securities.

GL02_13

Association

2

General Ledger

General Ledger Line

Bill Type Code

0..1

Base Bill Type

Type of bill.

GL02_14

Attribute

2

General Ledger

General Ledger Line

Bill Date

0..1

Date

Date of the bill.

GL02_15

Attribute

2

General Ledger

General Ledger Line

Quantity

0..1

Amount

Quantity of items referenced in the journal entry line.
When the GL Account Number is for inventories or fixed assets, this field is effective. If not, this field is NULL.

GL02_16

Association

2

General Ledger

General Ledger Line

Unit of Measurement Code

0..1

Base Measurement Unit

Code for the physical measurement scale for the inventory and Property, Plant and Equipment referred to as a “unit of measurement (UOM)”.

GL02_17

Attribute

2

General Ledger

General Ledger Line

Unit Price

0..1

Amount

Per unit price of the inventory or PPE.
This field is associated with Quantity and Amount.

GL02_18

Association

2

General Ledger

General Ledger Line

Settlement Method Code

0..1

Base Settlement Method

Code value or indicator of the settlement method used for cash receipt from customers (i.e. sales) and cash payment to suppliers (i.e. purchase).

GL02_19

Attribute

2

General Ledger

General Ledger Line

Credit Debit Indicator

0..1

Code

Indicates whether the amount is a credit or a debit.

GL02_20

Attribute

2

General Ledger

General Ledger Line

Reversal Indicator

0..1

Code

Indicates whether this entry is a reversal or to be reversed.

GL02_21

Attribute

2

General Ledger

General Ledger Line

Reversal Journal ID

0..1

Identifier

When the Reversal Indicator = 1, this field identifies the Journal ID of the entry being reversed.

GL02_22

Attribute

2

General Ledger

General Ledger Line

Cancellation Sign

0..1

Indicator

Sign of cancellation of a journal entry already formed but not yet posted.

GL02_23

Association

2

General Ledger

General Ledger Line

Account Segment Employee

0..1

Base Employee

Fixed account segment, recording information related to an employee

GL02_24

Association

2

General Ledger

General Ledger Line

Account Segment Project

0..1

Base Project

Fixed account segment, recording information related to a project.

GL02_25

Association

2

General Ledger

General Ledger Line

Account Segment Bank Account

0..1

Base Bank Account

Fixed account segment, recording information related to bank accounts.

GL02_26

Composition

2

General Ledger

General Ledger Line

has

0..*

Account Segment

GL02_27

Composition

2

General Ledger

General Ledger Line

has

0..1

Amount

GL02_28

Composition

2

General Ledger

General Ledger Line

has

0..1

Approved

GL02_38

Composition

2

General Ledger

General Ledger Line

has

0..*

Business Segment

GL02_39

Composition

2

General Ledger

General Ledger Line

has

0..1

Created

GL02_41

Composition

2

General Ledger

General Ledger Line

has

0..1

Posted

L: level, M: multiplicity

This example illustrates how a specialized class ‘Created’ is defined based on the ‘Activity’ superclass and how it’s used within the GL details structure, effectively demonstrating the concept of inheritance and specialization in UML modeling.

8. Further Consideration: Multicurrency Amount

Steps for defining a superclass and using composition association in the General Ledger Line with a specialized Monetary class, follow this approach:

  1. Identify Reusable Pattern:

    • Analyze lines 18 to 25 in GL_Details.csv and identify the common pattern that is repeated across several tables.

    • This pattern will form the basis of the superclass.

  2. Define the Superclass:

    • Based on the identified pattern, define a superclass. This superclass represents the common structure or attributes shared across different tables.

  3. Composition Association in General Ledger Line:

    • In the context of the General Ledger Line (GL02), use a composition association to include the superclass.

    • This means the General Ledger Line will contain or be linked to the superclass.

  4. Integrate Specialized ‘Monetary’ Class:

    • Define the ‘Monetary’ class as a specialized version of the superclass.

    • This specialized class tailors or extends the superclass to include specific details relevant to monetary aspects.

  5. Redefine Lines as Part of Composition:

    • Redefine the lines from 18 to 25 in the context of this composition association.

    • These lines will now be represented within the General Ledger Line as part of the specialized ‘Monetary’ class, which is a composition of the superclass.

This approach helps in structuring the data more effectively by identifying common patterns and using object-oriented principles like superclass definition and composition.

9. Conclusion

This guide provides a structured approach to transform ADCS data into an AWI Semantic model format, enhancing understanding and usage of the data through UML modeling and semantic clarity.

10. Refined Class and Association for HL7 R-MIM Generation

Upon reviewing the original UML class definitions, we have made significant refinements to both the class and its associations. These enhancements are pivotal in producing a robust R-MIM (Refined Message Information Model) for HL7, facilitating an effective graph walk to generate the HMD (Hierarchical Message Definition).

For a comprehensive overview and detailed insights, refer to our dedicated blog post:
Unified Table Design for Enhancing HL7 R-MIM, HMD Structures, and Graph Walk Processes.

Leave a Reply

Your email address will not be published. Required fields are marked *