Building Confidence

Maintaining an organisation-wide data model requires among many things, communication with stakeholders, building assurance as to its quality, relavance, and maintenance.

ALFA helps in such efforts through a number of methods as shown below.

Documentation

ALFA models can include documentation which get processed and associated with model elements.

By convention Model Documentation can be defined using # character on the line before the model element. Or /# … #/ for multi-line documentation. Furthermore, same line documentation can be defined using ##.

# Documentation for the Order
record Order {
    # Id Description
    Id : uuid
    When : date ## Same line documentation
}

All these comments gets used when generating model HTML documentation. Keeping the documentation alongside the model instead of external tools - such a Excel, Confluence, Wiki etc, means its unlikely to get stale and forgotten. Those changing the model and easily keep the documentation uptodate.

Model tests and testsuites

In adding to creating models and rules in ALFA, it is possible to create tests that ensure correct behaviour of those models and business rules over time, as further changes get made.

Each model type can have an associated test which is named by suffixing the model name with the word ‘Test’. Or a Test Suite can be defined, which is not associcated with any one particular model definition.

record Order {
    ...
    OrderDate : date
    ShipDate : date
    ...

    assert ShipDateAfterOrderDate {
        if ( OrderDate > ShipDate )
            raise error( "Order date cannot be after ShipDate")
    }
}

record OrderTest {
    testShipDateAfterOrderDate( s : alfa.test.Scenario ) : void {
        // Assert this fails
        s::fails("Order after shipped", ( ) => new Order(.. , OrderDate=date("2022-11-12"), ShipDate=date("2022-11-10"), .. ) )
        s::succeeds("Order before shipped", ( ) => new Order(.. , OrderDate=date("2022-11-08"), ShipDate=date("2022-11-10"), .. ) )
    }
}

Test coverage

ALFA Studio - the browser tool that opens from the ALFA Editor, allows tests to be run and coverage to be viewed.

The test coverage reports can also be run from the command line to be executed on Continuous Build servers to track changes, breaking changes, code coverage.

Managing Model Changes

ALFA Studio - the browser tool that opens from the ALFA Editor, allows comparing different versions of the project - local and versions from a repository to view the differences between the 2 versions and identify any breaking changes.

The model changes report can be executed on Continuous Build servers and emailed to keep stakeholders aware of upcoming changes or be used for preparing Data Model change release notes.

A sample model changes report can be seen here.