Skip to content

Getting Started

Jump to bottom
Kristof Vandenbroucke edited this page Jan 18, 2024 · 2 revisions

Getting Started with the OSLO UML Transformer

Welcome to the "Getting Started" guide for the OSLO UML Transformer! This guide is designed to help you quickly get up and running with the OSLO UML Transformer tools.

Prerequisites

Before diving into the OSLO UML Transformer, it's important to ensure that you have the following prerequisites in installed:

  1. NodeJS, version 18 or higher
  2. Local copy of the OSLO UML Transformer repo. This can be accomplished by downloading the repository as a ZIP file or by cloning it, using the following command git@github.com:Informatievlaanderen/OSLO-UML-Transformer.git

Note: each tool of this repository is also published on NPM. Head to the README.md of a tool for installation and usage instructions.

Getting Started Steps

To get started with the OSLO UML Transformer, follow these steps:

  1. Install the necessary dependencies by running the npm install command in the root folder.
  2. Link the local packages together and install remaining package dependencies by running npm run bootstrap
  3. Compile to Typescript code to Javascript with the following command: npm run build

With these initial steps, you are now able to run the converter or generators. The subsequent sections will help you transform an Enterprise Architect UML diagram (that used the OSLO modelling rules) into various artefacts.

Let's get started!

1. Converting a UML diagram to an OSLO JSON-LD compliant output file

In this example, we are going to convert the UML diagram of OSLO Verkeersmetingen to an OSLO JSON-LD compliant RDF file. If you want to open this UML diagram, you can download the free (read-only) version of Enterprise Architect.

Navigate to the folder packages/oslo-converter-uml-ea and run the following command:

node bin/runner.js --umlFile https://github.com/Informatievlaanderen/OSLOthema-verkeersmetingen/raw/main/Verkeersmetingen.eap --diagramName OSLO-Verkeersmetingen --specificationType ApplicationProfile --versionId test/1 --publicationEnvironment https://data.vlaanderen.be

This will generate an RDF file (in JSON-LD serialization) that complies with the OSLO JSON-LD model, report.jsonld. But first, let's explain the options that we used to execute the command above:

  • umlFile is that local path or URL of the EAP file
  • diagramName is the name of the diagram within the EAP file that must be converted
  • specificationType is used to determine which labels to use for classes and attributes. It is possible to have a different label for an application profile and vocabulary
  • versionId is the relative URL that will be used as the identifier of the document
  • publicationEnvironment is the base URI of the domain on which the specification is going to be published. Is used to determine the scope of each URI and together with the version ID, forms the identifier of the document.

Note: If you have the package globally installed, you can replace node bin/runner.js with oslo-converter-ea to use the tool.

2. Creating an artefact using one of the generators

Once you have an OSLO JSON-LD compliant RDF file obtained by using our converter (which transform Enterprise Architect UML diagrams) or another converter, you are able to use the generators.

2.1 Generating a JSON-LD context

In this example, we are going to use the output from the previous step to generate a JSON-LD context file for this UML diagram. Navigate to the folder packages/oslo-generator-jsonld-context and execute the following command:

node bin/runner.js --input report.jsonld --language nl

This will generate an RDF file (JSON-LD serialization), context.jsonld. Again, let's go through the options:

  • input is the OSLO JSON-LD RDF file.
  • language is used to extract the labels of classes and attributes in the configured language.
  • (Optional) addDomainPrefix can be used to prefix every attribute with the label of its domain.

Note: If you have this package installed globally, you can replace node bin/runner.js with oslo-jsonld-context-generator.

2.2 Generating an HTML file

In this example we are going to generate an HTML page (with the ReSpec template) to have a human-readable version of our domain model. Navigate to the folder packages/oslo-generator-respec-html and execute the following command:

node bin/runner.js --input report.jsonld --language nl --specificationType ApplicationProfile --specificationName "OSLO-Verkeersmetingen"

This will generate an HTML file, respec.html. Let's go through the options:

  • input is the OSLO JSON-LD RDF file.
  • language is used to extract the labels of classes and attributes in the configured language.
  • specificationType is used to determine the HTML template. Possible options are ApplicationProfile or Vocabulary
  • SpecificationName is used as the title in the HTML document

Note: If you have this package installed globally, you can replace node bin/runner.js with oslo-generator-respec.

Clone this wiki locally