The Ampla to B2MML Transformer converts an Ampla Project XML export into an ISA-95 B2MML Equipment model.
It uses Python to provide a command-line tool, a FastAPI service, and several export formats. Its multi-pass pipeline supports equipment hierarchies, class inheritance, and property overrides.
Ampla Project XML files can contain equipment hierarchies, equipment classes, class inheritance, and class and instance properties. The transformer converts that data into:
- B2MML Equipment XML
- A JSON model
- An Excel workbook with Equipment and Classes sheets
- CSV files
- An HTML report
The B2MML XML builder targets the ISA-95 B2MML v0400 schema and follows the structure of the original Ampla XSLT.
The project also includes validation warnings, inheritance auditing, duplicate detection, configuration diffs, and statistics such as equipment and class counts, property totals, and hierarchy depth.
The transformation pipeline:
- Builds a lookup table for class IDs.
- Extracts classes and computes their inheritance chains.
- Parses the equipment tree.
- Resolves class IDs and records warnings.
- Merges inherited class properties with equipment overrides.
- Sorts and normalizes the resulting model.
The transformer creates an internal model that output builders use for XML, JSON, Excel, CSV, and HTML.
classDiagram
class Equipment {
+String id
+String name
+String level
+List class_ids
+List children
+Dict overrides
+List properties
+String full_name
}
class EquipmentClass {
+String name
+String parent
+List properties
+List inheritance_chain
}
class ClassProperty {
+String name
+String value
+String datatype
}
class EquipmentProperty {
+String name
+String value
+String datatype
}
Equipment "1" *-- "many" Equipment : children
Equipment "1" *-- "many" EquipmentProperty : properties
EquipmentClass "1" *-- "many" ClassProperty : properties
Equipment ..> EquipmentClass : resolves attributes from
sequenceDiagram
participant XML as Raw XML
participant AT as AmplaTransformer
participant CTX as Context (Shared State)
participant Model as Internal Model
AT->>XML: Pass 1: Build ID lookup table
AT->>XML: Pass 2: Extract classes and compute inheritance
AT->>XML: Pass 3: Parse equipment tree
AT->>CTX: Resolve class IDs and record warnings
AT->>Model: Pass 4: Merge properties and apply overrides
Note right of Model: B2MML-ready model
The design aims for repeatable output from the same input, separates parsing from output generation, and collects warnings for structural issues such as unknown class IDs, malformed items, and missing configuration.
Level mappings are stored in config/mapping.toml:
[level_map]
"Citect.Ampla.Isa95.EnterpriseFolder" = "Enterprise"
"Citect.Ampla.Isa95.SiteFolder" = "Site"
"Citect.Ampla.Isa95.AreaFolder" = "Area"
"Citect.Ampla.General.Server.ApplicationsFolder" = "Other"If the file is missing or invalid, the transformer logs a warning and uses its default mappings.
from lxml import etree
from app.transformers.ampla_to_b2mml import AmplaTransformer
root = etree.parse("input.xml").getroot()
transformer = AmplaTransformer(config_path="config/mapping.toml")
model = transformer.transform(root)
print(model["equipment"])
print(model["classes"])
print(model["warnings"])The returned dictionary contains equipment, classes, and warnings.
Convert Ampla XML to B2MML XML:
b2mml convert input.xml output.xml
Export JSON to a file or stdout:
b2mml json input.xml output.json
b2mml json input.xml
Export an Excel workbook:
b2mml excel input.xml output.xlsx
Show statistics:
b2mml stats input.xml
b2mml stats --format json input.xml
Create an HTML report:
b2mml html input.xml report.html
Compare two Ampla XML files:
b2mml diff baseline.xml updated.xml
b2mml diff --format json baseline.xml updated.xml
Diff exit codes:
0: no differences1: differences found
Validate an Ampla XML model:
b2mml validate input.xml
b2mml validate --format json input.xml
Validation exit codes:
0: no warnings1: warnings found, such as unknown classes, missing parents, or circular inheritance
Audit class inheritance resolution:
b2mml audit-inheritance input.xml
The audit report shows:
- class inheritance chains
- declared properties
- inherited properties
- property origin classes
- summary counts for each class
Audit duplicate identifiers and properties:
b2mml audit-duplicates input.xml
The duplicate audit reports:
- duplicate equipment full names
- duplicate equipment IDs
- duplicate class names
- duplicate class property definitions
Issues are categorized as errors and warnings.
Start the FastAPI server:
uvicorn app.api:app --reload
| Method | Path | Description |
|---|---|---|
| GET | /health |
Health check |
| GET | /info |
API and pipeline version information |
| POST | /audit/duplicates |
Return duplicate audit information |
| POST | /audit/inheritance |
Return inheritance audit information |
| POST | /convert/json |
Return the JSON model |
| POST | /convert/xml |
Return B2MML XML |
| POST | /convert/excel |
Return an Excel workbook |
| POST | /convert/csv/equipment |
Return equipment CSV |
| POST | /convert/csv/classes |
Return classes CSV |
| POST | /convert/html |
Return an HTML report |
| POST | /stats |
Return model statistics |
| POST | /diff/json |
Return a JSON diff |
| POST | /diff/text |
Return a text diff |
| POST | /validate |
Return validation warnings |
Example requests:
curl -X POST -F "file=@input.xml" http://localhost:8000/convert/json
curl -X POST -F "file=@input.xml" http://localhost:8000/stats
curl -X POST -F "file_a=@baseline.xml" -F "file_b=@updated.xml" http://localhost:8000/diff/text
curl -X POST -F "file=@input.xml" http://localhost:8000/audit/inheritance
curl -X POST -F "file=@input.xml" http://localhost:8000/audit/duplicates
Interactive API documentation is available at http://localhost:8000/docs.
Start the API:
make up
The service runs at http://localhost:8000.
Stop the service:
make down
app/parsers— XML parsingapp/transformers— Ampla-to-model transformationapp/builders— B2MML XML generationapp/validators.py— model validation and warningsapp/diff.py— structural diffsapp/stats.py— statisticsapp/excel_export.py— Excel exportapp/csv_export.py— CSV exportapp/html_report.py— HTML report generationapp/cli.py— command-line interfaceapp/api.py— FastAPI serviceapp/schemas.py— Pydantic response modelstests/— tests and regression fixtures
This project reimplements the Ampla_to_Equipment_B2MML.xslt transformation in Python.
The original implementation is available in the Project-To-B2MML repository.
It preserves the stylesheet’s core behavior, including equipment hierarchy generation, class inheritance, property merging and overrides, full-name generation, and ISA-95 B2MML output structure.
It adds validation warnings, configurable level mappings, more export formats, command-line and REST interfaces, diff and statistics tools, and support for malformed input.
The automated test suite verifies the project’s expected behavior.
The project is licensed under the BSD 3-Clause License. It includes derivative work from Ampla_to_Equipment_B2MML.xslt by Oleg Tkachenko (2005), which is also licensed under the BSD 3-Clause License.
See LICENSE and THIRD_PARTY_NOTICES.md for license and attribution details.