System Integrations
One of the most important aspects of a good architecture documentation is to describe which systems integrate with each other, for what purpose and how the integration is set up.
This is the purpose of the IT System Integration element of the townplanner. The integrations are always described between IT Systems, which is the most useful granularity.
val bcms: ItSystem = {
ea describes ItSystem(title = "BatCave Management System") as { it =>
it has Description(
"A custom Lair Management System, designed and built by Lucius Fox"
)
}
}
val strapi: ItSystem = ea describes ItSystem(title = "Strapi") as { it =>
it has Description("Headless CMS powering all Batman marketing websites.")
}
val bcmsStrapiIntegration: ItSystemIntegration = ea describes ItSystemIntegration(title = "Strapi - BCMS - Marketing Content") between strapi and bcms as { it =>
it has Description("The Batcave Management System requires all the content of the marketing websites.")
}Properties
Description
An IT System Integration can have 0 or more descriptions.
val bcmsStrapiIntegration: ItSystemIntegration =
ea describes ItSystemIntegration(title =
"Strapi - BCMS - Marketing Content"
) between strapi and bcms as { it =>
it has Description(
"The Batcave Management System requires all the content of the marketing websites."
)
}Architecture Verdict
The architecture verdict uses the Gartner TIME model to categorize applications, determining whether to Terminate, Invest, Migrate or Tolerate them.
The architecture verdict property can appear only once on a concept. The value of the property can optionally contain a description, usually the reason why this concept was given this architecture verdict.
...
it should BeInvestedIn()
it should BeTolerated()
it should BeMigrated()
it should BeEliminated("option description: the reason why this should be eliminated")
...Criticality
The criticality of a system integration describes the impact on the business if that integration would fail or be unavailable. The possible values are:
- Catastrophic: a component failure would significantly affect the operability of the system/platform and could cause bankruptcy, law suits or even the loss of life.
- Hazardous: a failure in these systems would pose a major threat to the company and its employees
- Major: a failure in these systems will impact the working of the larger whole, resulting in outages and loss of money
- Minor: a failure in these systems will have a minor impact the working of the larger whole, not resulting in system outages, but a reduced customer experience
- NoEffect: a failure in these systems will have no impact the working of the larger whole, and will not have any impact on the customer experience
- UnknownCriticality
The criticality property can appear only once on a concept. The value of the property can optionally contain a description, usually the reason why this concept has this criticality level.
...
it ratesFailureAs Catastrophic("with an optional description of why it would be catastrophic")
it ratesFailureAs Hazardous()
it ratesFailureAs Major()
it ratesFailureAs Minor()
it ratesFailureAs NoEffect()
it ratesFailureAs UnknownCriticality
...Resilience Measures
A resilience measure property is simply a description of what has been provided in the system integration to deal with failures.
An integration can have 0 or more resilience measures.
...
it provides ResilienceMeasure("circuit breaker")
it provides ResilienceMeasure("fallback scenario")
...Throughput
A System Integration can have an (expected) throughput, expressed in volume and frequency. Both are just free text descriptions for now.
...
it has Volume("millions of transactions")
it has Frequency("hourly")
...Links
val bcmsStrapiIntegration: ItSystemIntegration =
ea describes ItSystemIntegration(title =
"Strapi - BCMS - Marketing Content"
) between strapi and bcms as { it =>
...
it has Website("https://wayne.com/bcms")
it has Wiki("https://dc.fandom.com/wiki/BCMS")
it has ApiDocumentation("https://api.wayne.com/bcms")
it has FunctionalDocumentations(url = "https://docs.wayne.com/bcms", title = "Functional Documentation")
it has TechnicalDocumentation("https://reference.wayne.com/bcms")
it has ArchitectureDocumentation(url = "https://wayne.com/architecture/bcms", title = "The BCMS in the Wayne Enterprises Town Plan")
it has ProductionUrl("https://bcms.wayne.com")
it has PreProductionUrl("https://staging.bcms.wayne.com")
it has DevelopmentUrl("https://dev.bcms.wayne.com")
it has SourceCodeRepository("https://github.com/wayne/bcms")
...
}External ID
An external ID is a reference to the description, documentation, implementation or anything else in some external system, for example in another EA tool, or in a cloud platform.
val bcmsStrapiIntegration: ItSystemIntegration =
ea describes ItSystemIntegration(title =
"Strapi - BCMS - Marketing Content"
) between strapi and bcms as { it =>
...
it isIdentifiedAs "{42a5e9d4-188d-4509-8145-eaac65ab86b8}" on "Sparx EA"
...
}SWOT
An integration can have strengths, weaknesses, opportunities and threats.
val bcmsStrapiIntegration: ItSystemIntegration =
ea describes ItSystemIntegration(title =
"Strapi - BCMS - Marketing Content"
) between strapi and bcms as { it =>
...
it has Strength("Lucius Fox built it")
it has Strength("Marketing content is available to Batman")
it has Weakness("it is not automated, Batman needs to export an XML file and import that into the BCMS.")
it has Threat(
"Something dangerous about marketing content"
)
he has Opportunity(
"Bringing it to the cloud and automating the integration"
)
...
}Father Time
Life events can be assigned to an IT System Integration, indicating the various stages in its lifetime:
- started development
- gone to preproduction
- gone to production
- active
- retired
- decommissioned
Depending on the lifecycle, an integration will be visible or not in a view. The Integration Map for example is time-sensitive and will not show integrations that were decommissioned or are not yet in production.
val batCaveDestructionDay: Day = Day(2027, 10, 31)
val bcmsStrapiIntegration: ItSystemIntegration =
ea describes ItSystemIntegration(title =
"Strapi - BCMS - Marketing Content"
) between strapi and bcms as { it =>
...
it has StartedDevelopment(description =
"Ra's al Ghul came to town"
) on Day(2003, 1, 1)
it has GoneToProduction(description =
"Just in time for the Joker"
) on Day(2005, 1, 1)
it is Decommissioned(description =
"The Batcave is destroyed"
) on batCaveDestructionDay
...
}