The BAMM CLI is a command line tool for the validation of Aspect models and the generation of artifacts, such as documentation or code, from Aspect models.
|
Tip
|
Download latest version: [download] bamm-cli-{sds-sdk-version}.jar |
For the executable jar, call java -jar bamm-cli-{sds-sdk-version}.jar followed by one of the following subcommands (e.g., java -jar bamm-cli-{sds-sdk-version}.jar help).
In the following sections, bamm will be used as the command name.
|
Tip
|
To make alias bamm='java -jar /location/to/bamm-cli-{sds-sdk-version}.jar' |
Successful execution of a command is signaled by returning 0. In case of logical or some other internal problem error code 1 is returned. Missing or wrong command parameters result in error code 2 being returned.
To get help for a certain subcommand, add 'help' before the subcommand name or add --help to the end, e.g., bamm help aspect
or bamm aspect --help.
Each subcommand can have its own set of options which allow the user to further fine-tune the execution of the command.
The available options and their meaning can also be seen in the help text of the individual subcommands.
| Command | Description/Options | Examples |
|---|---|---|
help |
Get overview of all commands |
|
help <subcommand> |
Get help for a specific subcommand |
|
aspect help <aspect subcommand> |
Get help for |
|
aspect <model> validate |
Validate Aspect Model |
|
--custom-resolver : use an external resolver for the resolution of the model elements |
|
|
aspect <model> prettyprint |
Pretty-print Aspect Model |
|
--output, -o : the output will be saved to the given file |
|
|
aspect <model> migrate |
Migrate Aspect Model to the latest BAMM version |
|
--output, -o : the output will be saved to the given file |
|
|
aspect <model> to html |
Generate HTML documentation for an Aspect Model |
|
--output, -o : the output will be saved to the given file |
|
|
--css, -c : CSS file with custom styles to be included in the generated HTML documentation |
|
|
--language, -l : The language from the model for which the HTML should be generated (default: en) |
|
|
--custom-resolver : use an external resolver for the resolution of the model elements |
|
|
aspect <model> to png |
Generate PNG diagram for Aspect Model |
|
--output, -o : output file path (default: stdout); as PNG is a binary format, it is strongly recommended to output the result to a file by using the -o option or the console redirection operator '>') |
||
--language, -l : the language from the model for which the diagram should be generated (default: en) |
||
--custom-resolver : use an external resolver for the resolution of the model elements |
|
|
aspect <model> to svg |
Generate SVG diagram for Aspect Model |
|
--output, -o : the output will be saved to the given file |
||
--language, -l : the language from the model for which the diagram should be generated (default: en) |
||
--custom-resolver : use an external resolver for the resolution of the model elements |
|
|
aspect <model> to dot |
Generate DOT diagram for Aspect Model |
|
--output, -o : output file path (default: stdout) |
||
--language, -l : the language from the model for which the diagram should be generated (default: en) |
||
--custom-resolver : use an external resolver for the resolution of the model elements |
||
aspect <model> to java |
Generate Java classes from an Aspect Model |
|
--output-directory, -d : output directory to write files to (default: current directory) |
||
--package-name, -pn : package to use for generated Java classes |
|
|
--no-jackson, -nj : disable Jackson annotation generation in generated Java classes |
||
--template-library-file, -tlf : the path and name of the Velocity template file containing the macro library |
||
--execute-library-macros, -elm : Execute the macros provided in the Velocity macro library |
||
--static, -s : generate Java domain classes for a Static Meta Model |
||
--custom-resolver : use an external resolver for the resolution of the model elements |
||
aspect <model> to openapi |
Generate OpenAPI specification for an Aspect Model |
|
--output, -o : output file path (default: stdout) |
||
--api-base-url, -b : the base url for the Aspect API used in the OpenAPI specification |
|
|
--json, -j : generate a JSON specification for an Aspect Model (default format is YAML) |
||
--parameter-file, -p : the path to a file including the parameter for the Aspect API endpoints |
For detailed description, see the section bellow |
|
--semantic-version, -sv : use the full semantic version from the Aspect Model as the version for the Aspect API |
||
--resource-path, -r : the resource path for the Aspect API endpoints |
For detailed description, see the section bellow |
|
--include-query-api, -q : include the path for the Query Aspect API Endpoint in the OpenAPI specification |
||
--paging-none, -pn : exclude paging information for the Aspect API Endpoint in the OpenAPI specification |
||
--paging-cursor-based, -pc : in case there is more than one paging possibility, it has to be cursor based paging |
||
--paging-offset-based, -po : in case there is more than one paging possibility, it has to be offset based paging |
||
--paging-time-based, -pt : in case there is more than one paging possibility, it has to be time based paging |
||
--custom-resolver : use an external resolver for the resolution of the model elements |
||
aspect <model> to json |
Generate OpenAPI JSON specification for an Aspect Model |
|
--output, -o : output file path (default: stdout) |
||
--custom-resolver : use an external resolver for the resolution of the model elements |
||
aspect <model> to schema |
Generate JSON schema for an Aspect Model |
|
--output, -o : output file path (default: stdout) |
||
--custom-resolver : use an external resolver for the resolution of the model elements |
||
aspect <model> to aas |
Generate Asset Administration Shell (AAS) submodel template for an Aspect Model |
|
--output, -o : output file path (default: stdout) |
||
--format, -f : output file format (xml or aasx, default: xml) |
||
--custom-resolver : use an external resolver for the resolution of the model elements |
To allow the users to provide their own custom implementations of a model resolver, --custom-resolver command-line switch can be used.
The value of the switch can be any command which is directly executable by the underlying operating system (such as a batch script on Windows or a shell script on Linux/Unix).
When a model element needs to be resolved, this command is executed with the URN of the element to resolve passed as the last parameter.
The command can provide other parameters as well, the element URN will be added automatically as the last one by bamm-cli.
The resolved model definition is expected to be output to the stdout in Turtle format.
From there, it is read by the bamm-cli and passed on to the internal processing pipeline.
In this way the extension can be flexibly done in any programming language/script language, including complex logic if necessary.
Every specification is based on one Aspect, which needs a separately defined server URL where the given aspect will be.
The URL will be defined as string with the -b option, i.e.: https://www.example.org.
The default URL, using the above defined --api-base-url, would result in https://www.example.org/api/v1/{tenantId}/<aspectName>;.
By default the Aspect’s local name is used as path.
The default path can be manipulated with the --resource-path switch.
If the path is defined further, for example --resource-path "/resources/{resourceId}", the resulting URL would be: https://www.example.org/api/v1/{tenantId}/resources/{resourceId}.
It will be required to specify the parameter, in case there is an additional parameter defined.
This has to be in JSON or in YAML, depending on the kind of specification chosen.
For example:
With the option --resource-path "/resources/{resourceId}" the generator constructs the URL https://www.example.org/api/v1/{tenantId}/resources/{resourceId}
and then the --parameter-file defines the parameter resourceId in yaml:
resourceId:
name: resourceId
in: path
description: An example resource Id.
required: true
schema:
type: string
The full command would result in:
java -jar bamm-cli-{sds-sdk-version}.jar aspect AspectModel.ttl to openapi -b "https://www.example.org" -r "/resources/{resourceId}" -p fileLocationAn Aspect model file can contain an Aspect definition as well as other model elements that are defined in the same versioned namespace, as described in the Namespaces section of the specification. Additionally, it is possible to split one versioned namespace across multiple files, for example to define a Characteristic that is usable in multiple Aspects into its own file. In order for BAMM CLI to be able to resolve references to such externally defined model elements, the model files must be organized in a directory structure as follows:
namespace/version/name.ttl
where namespace corresponds to the hierarchical namespace that is part of the model element’s URN, e.g.
com.mycompany.myproduct and version corresponds to the version of the namespace.
The resulting directory structure then looks like the following:
models root
└── com.mycompany.myproduct
├── 1.0.0
│ ├── MyAspect.ttl
│ ├── MyEntity.ttl
│ └── myProperty.ttl
└── 1.1.0
└── MyAspect.ttlThe name of the directory shown as models root above can be chosen freely.
The BAMM CLI will resolve the file path relative to the input file by following the folder structure described above.
Each of the files in the 1.0.0 directory should therefore have an empty prefix declaration such as @prefix : <urn:bamm:com.mycompany.myproduct:1.0.0#>.