Skip to main content

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 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
tip

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.

warning
  • 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.

Register existing component

warning

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).

info

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 in the UI​

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.

warning

This is a heuristic validated for system case, it may not work for other scenarios.