Creating Use Case Blueprints
Blueprints are a type of templates tailored for pre-defined use cases: they contain a data product template with already-built relationships to certain components that should be created along with it. It is a very powerful and useful mechanism that will speed up the creation of well-known use cases. For more information check out this section.
To create your blueprint, you will need to define a catalog-info.yaml
at the root level of your repository.
Step one. catalog-info.yaml
Definition
Blueprints are Witboost custom entities, they contain a main template ID that should be referring to a template for a Data product and a list of other template IDs. Like templates, they can be stored inside the Catalog. This is why they must be compliant with a well-defined structure.
A blueprint definition describes the parameters that are rendered in the frontend part of the scaffolding wizard and the templates bound to the entity.
A catalog-info.yaml
definition generally contains these sections, as shown in the example below:
apiVersion: agilelab.it/v1alpha1
kind: Blueprint
metadata:
# data about the template, useful for the catalog
spec:
# the field name that will be automatically filled for all listed templates
parentRefField: parentRef
# the main template ID should be referring a template for a system
mainTemplateId:
# list of template IDs for components which CANNOT include any system template
templates:
# template's ID
- id: 'id'
# list of template's ID on which the current one depends on; if a dependency is defined, in the UI the current template will be selectable
# only if all the templates it depends on are already implemented
dependencies:
- 'id'
Publish step
Repository
An example of a valid Gitlab/Bitbucket/Azure DevOps/GitHub blueprint's definition is in the catalog-info.yaml
file looks like the following:
apiVersion: agilelab.it/v1alpha1
kind: Blueprint
metadata:
title: Blueprint
name: blueprint
description: A blueprint definition
tags:
- blueprint
spec:
lifecycle: experimental
owner: group:your-group
domain: domain:your-organization
mainTemplateId: template:default/your-template-name
templates:
- id: template:default/example-template
dependencies:
- template:default/another example template
When creating a new template, you will not need to start from scratch, but you can just start by cloning one of the provided example templates and editing it. This is the easiest and most recommended way to create a new template. Check out the Templates Examples section and our Witboost Starter Kit for real life examples.
- The
metadata.name
field supports only[a-z0-9+#]
separated by[-]
, no spaces or other special characters are allowed here - The values of the
tags
field follow the same rule
Step two. Registering a Use Case Blueprint
You can add the blueprint using the catalog-import
plugin, which you can find on the templates page by clicking on Register existing component
. Inside the page, you will need to link the committed catalog-info.yaml
file; make sure to not commit the blueprint to a branch with slashes (e.g. feature/branch-name) since the plugin will not be able to figure out the right path in this case.
The URL you register to import the blueprint must refer to the catalog-info.yaml
file and should be related to a specific branch (like in the example above).
Blueprints can be disabled by setting the configuration mesh.builder.scaffolder.blueprints.enabled
to false.
This will not delete any of the blueprints you already imported into witboost, and you can always enable it back later.
Default behavior
When selecting a blueprint and checking it against the existing system, remember that the user will see in the list only system that can be created from such a blueprint. In more detail, the list of systems will be filled with all the systems in the builder which have the same useCaseTemplateId
field as the one defined in the blueprint's mainTemplateId
. This will prevent to use wrong blueprints on existing systems.
After creating/selecting the entity from a template, other templates, that depend on it, will use that entity kind and name to prefill the form.
If the current template depends on a template of kind "system" and contains a picker field named according to the value of the spec.parentRefField
property defined in the Blueprint's catalog info, which defaults to dataproduct
, then that picker field will be automatically populated with the corresponding entity. This is the default behavior for the main template, which will always be used to fill possible fields of the other templates.
This is a heuristic validated for system case, it may not work for other scenarios.