Skip to main content

Creating Use Case Templates

An Use Case Template on Witboost is define at its base by two files:

  • A YAML file that configures the fields that a user needs to fill when creating a new component that the scaffolder wizard will render (i.e. template.yaml)
  • A parameterized file defining the skeleton used by Witboost to generate entities based on the user inputs, normally called catalog-info.yaml.

Alongside these two files, Witboost also allows to define a folder of files and subfolders that the entity created by this template will be made of; we will refer to them as skeleton files. The catalog-info.yaml file is part of these skeleton files.

Those files together with all files and folders related to a template must be stored in the Git provider configured in Witboost (e.g. GitLab). This allows the platform to register your template by using the repository URL, pointing to the catalog-info.yaml file.

A common folder structure for templates is as follows:

template.yaml
mkdocs.yml
docs/
├──── index.md
skeleton/
├──────── README.md
├──────── catalog-info.yaml
├──────── mkdocs.yml
├──────── .gitlab-ci.yaml   <--- CI/CD pipeline which will be executed by Use case templates
├──────── docs/
│         └──── index.md
├──────── environments/
│         ├──────────── dev/
│         │             └─── configurations.yaml
│         ├──────────── prod/
│         │             └──── configurations.yaml
│         └──────────── # any other env config goes here
└──────── # any other skeleton files here

Step 1. template.yaml Definition​

Templates are entities, and as such, they can be stored inside the Catalog. This is why they must be compliant with a well-defined structure.

A template definition describes both the parameters that are rendered in the frontend part of the scaffolding wizard and the steps that are executed when scaffolding that component.

Structure of a template file​

A template.yaml definition generally contains these sections, as shown in the example below:

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
# data about the template, needed for Witboost

spec:
  parameters:
  # defines the form fields for the user to insert the data required by the system or component

  steps:
  # steps performed by the scaffolder engine to effectively create your system or component in the Git provider and registered on Witboost

  output:
  # some extra metadata for the scaffolder actions

Let's break down more those sections, leveraging an example template that we created.

The metadata section defines information about the template that is meaningful for Witboost, for identification and display purposes:

apiVersion: backstage.io/v1beta3 # internal, can be leaved as it is
kind: Template # kind will be always `Template` when defining a template.yaml
metadata:
  name: example-template # unique id for this template inside Witboost
  title: Example Template # display name
  description: Template definition of an Example Template
  mesh:
    icon: https://<icon_url>.png # icon appearing inside the catalog when displaying this template
  annotations:
    backstage.io/techdocs-ref: dir:. # this is used by TechDocs to know where to look for docs, can be leaved as that
  tags: # tags meaningful for users, they can be used for filtering templates inside the catalog
    - example

The spec section defines:

  • template owner (spec.owner) and the type of the scaffolded entity (spec.type). The spec.type field of the template is used in the UI to group templates on the "Template" page (templates with the same type field will be grouped). You can put types in camel case and they will be displayed using spaces in the UI groupings.
  • the parameters (spec.parameters) that define which fields are presented to the user in the form; detailing the format of the fields, which ones are mandatory, etc.
spec:
  owner: agilelab
  type: component # or any other available type
  parameters:
    - title: Example Page # A form is divided into sections, each one with its title and its fields
      required:
        - fieldone
        - fieldtwo
      properties:
        fieldone:
          title: Name
          type: string
          description: Name of the example component
        fieldtwo:
          title: Owner
          type: string
          description: Owner of the example component
          ui:field: EntityPicker # a custom picker
          ui:options: # with custom options values
            allowArbitraryValues: false
            allowedKinds:
              - User
        fieldthree:
          title: Description
          type: string
          description: Description of the example component

Moreover, spec also defines:

  • spec.generates: This field is required if the template instantiates a system or component entity and includes a fetch:template action. See the Practice Shaper section below
  • Steps performed by the scaffolder

Template Steps​

The steps section defines the list of actions that Witboost performs after the user has filled all the form data and has clicked on the submit button. Overall, it renders, publishes (commits) the entity in the target git provider, and registers it on Witboost. It contains, among other things:

  • Values spec.steps[template].values passed to all files in the skeleton (including the catalog-info.yaml) when a new component is cloned. So that inside the skeleton you can refer to those values with the assigned key ( e.g. values.fieldone)
  • spec.steps[template].useCaseTemplateId: the unique identifier that will be used to register the Use Case Template to the Provisioner module.
  • spec.steps[template].infrastructureTemplateId: the unique identifier that will be used to register a Tech Adapter to the Provisioner module.
info

Remember: all URNs are treated as case-insensitive values, except for infrastructureTemplateId. This is deprecated, in the future it will be all case-insensitive.

spec:
  # we are still in the same section as in the above example
  steps:
    - id: template # fetches values from UI
      name: Fetch Skeleton + Template #
      action: fetch:template
      input:
        url: ./skeleton # this is used to locate catalog-info.yaml
        copyWithoutRender: # you can also specify files that will not be affected by variables replacement
          - .gitlab-ci.yml
        values:
          fieldone: '{{ parameters.fieldone }}'
          fieldtwo: '{{ parameters.fieldtwo }}'
          fieldthree: '{{ parameters.fieldthree }}'
          useCaseTemplateId: urn:dmb:utm:aws-cdp-outputport-impala-template:0.0.0 # Specify any well-formatted URN you desire
          infrastructureTemplateId: urn:dmb:itm:aws-cdp-outputport-impala-provisioner:1 # Specify any well-formatted URN you desire
          useCaseTemplateVersion: 0.0.0
          repoUrl: ...

    - id: publish # custom action that publishes the example component to GitLab
      name: Publish
      action: witboostMeshComponent:publish:gitlab
      input:
        allowedHosts: ['gitlab.com']
        description: 'This is {{ parameters.fieldone}}'
        repoUrl: '{{ steps.template.output.values.repoUrl }}'
        rootDirectory: '.'

    - id: register # register the example component into witboost entities
      name: Register
      action: catalog:register
      input:
        repoContentsUrl: '{{ steps.publish.output.repoContentsUrl }}'
        catalogInfoPath: '/catalog-info.yaml'

  output:
    remoteUrl: '{{ steps.publish.output.remoteUrl }}'
    entityRef: '{{ steps.register.output.entityRef }}'
info

If you are not using Gitlab, as in the example, please refer to the Git Providers section below

All the input values defined in template.yaml (spec.steps[template].values) will be available to be referenced from the catalog-info.yaml and all files inside the skeleton folder using the values variable ( e.g. values.fieldone).

template.yaml has some requirements to which it must be compliant:

  • Field metadata.title and metadata.description are mandatory fields
  • Field spec.steps.values.useCaseTemplateId: Must match the following URN format: urn:dmb:utm:{name}:{version} (note that is utm).
  • Field spec.steps.values.infrastructureTemplateId must match the URN identifier urn:dmb:itm:{name}:{version} (note that is itm).
  • Field spec.steps.values.useCaseTemplateVersion must be not empty and should equal to the {version} in the useCaseTemplateId field.

Moreover:

  • allowed characters in {name} section are alphanumeric ([a-zA-Z0-9]), dashes (-), and/or underscores (_).
  • allowed format for {version} section must be a single positive number (e.g. 13) or a dot-separated sequence of three numbers (e.g. 1.11.16)
  • Use case template URN starts with urn:dmb:utm while an Infrastructure template URN starts with urn:dmb:itm
warning

Notice that the registration step will reject your request of creating a new component if such mandatory requirements are not fulfilled.

Publish and register steps​

The publish step is in charge of pushing the files and artifacts of the generated entity (its skeleton/ folder) to the remote SCM provider. Depending on the step configuration, it either creates the repository if it does not exist, or commits the generated files from the scaffolding phase onto a existing repository (e.g. under a subfolder).

When integrating with an SCM provider (like Gitlab), the templates for all the entities handled by Witboost must use the specific publish action for each different git provider. This is because each provider needs different input parameters, and the data used to perform the operations can differ (e.g. for Bitbucket all the URLs must end with ?at={branchName}). In general, the inputs that must be passed are the target host, the description, the repository URL, the root directory where files will be pushed, and the System name.

The register step on the other hand, takes the output of the publish action and registers the committed files as an entity inside Witboost.

Select below your Git provider to see the reference and an example on how to configure the step for each of the supported providers.

info

Please note that the examples given in this page are valid for a System template, while when used for a Component template the parentRef line should be changed to refer to the System chosen in the steps above (e.g. with an EntityPicker or an EntitySearchPicker with name parentRef):

parentRef: '${{ parameters.parentRef }}'

Furthermore, it assumes the fetch:template step (with id: template) computed a repoUrl value and exposed it through its output, so it can be referenced from later steps as ${{ steps.template.output.values.repoUrl }}. Please check this page for a dive-in on how to generate this URL for different repository structures.

Git provider configuration​

An example of valid Gitlab template's actions in the template.yaml file looks like the following (for a System template):

- id: publish
  name: Publish
  action: witboostMeshComponent:publish:gitlab
  input:
    allowedHosts: ['gitlab.com']
    description: 'This is ${{ parameters.name }}'
    repoUrl: '${{ steps.template.output.values.repoUrl }}'
    rootDirectory: '.'
    parentRef: '${{ parameters.name }}'

- id: register
  name: Register
  action: catalog:register
  input:
    repoContentsUrl: '${{ steps.publish.output.repoContentsUrl }}'
    catalogInfoPath: '/catalog-info.yaml'
Publishing in multiple repositories​

It is possible to publish to more than one repository starting from one template. In that case, you would probably want to create two separate fetch, publish and register phases. Here we are introducing the input.sourcePath value in the publish phase which is used to read from the folder specified in the input.targetPath of the fetch phase so these two variables must be an exact match. An example of this is:

spec:
  steps:
    - id: templateOne
      name: Fetch Skeleton + Template
      action: fetch:template
      input:
        url: ./skeleton
        targetPath: '${{ parameters.rootDirectory }}'
        values:
          ...
          identifier: '${{ parameters.identifier }}One'
          destination: '${{ parameters.repoUrl | parseRepoUrl }}One'
          ...
    - id: publishOne
      name: Publish
      action: witboostMeshComponent:publish:gitlab
      input:
        allowedHosts: [ 'gitlab.com' ]
        description: 'This is ${{ parameters.name }}'
        repoUrl: '${{ parameters.repoUrl }}'
        rootDirectory: '${{ parameters.rootDirectory }}'
        parentRef: '${{ parameters.parentRef }}'

    - id: registerOne
      name: Register
      action: catalog:register
      input:
        repoContentsUrl: '${{ steps.publishOne.output.repoContentsUrl }}'
        catalogInfoPath: '/${{ parameters.rootDirectory }}/catalog-info.yaml'

    - id: templateTwo
      name: Fetch Skeleton + Template
      action: fetch:template
      input:
        url: ./skeleton
        targetPath: '${{ parameters.rootDirectory }}/two'
        values:
          ...
          identifier: '${{ parameters.identifier }}Two'
          destination: '${{ parameters.repoUrl | parseRepoUrl }}Two'
          ...
    - id: publishTwo
      name: Publish
      action: witboostMeshComponent:publish:gitlab
      input:
        allowedHosts: [ 'gitlab.com' ]
        description: 'This is ${{ parameters.name }}'
        repoUrl: '${{ parameters.repoUrl }}Two'
        rootDirectory: '${{ parameters.rootDirectory }}'
        parentRef: '${{ parameters.parentRef }}'
        sourcePath: 'two'
    - id: registerTwo
      name: Register
      action: catalog:register
      input:
        repoContentsUrl: '${{ steps.publishTwo.output.repoContentsUrl }}'
        catalogInfoPath: '/${{ parameters.rootDirectory }}/catalog-info.yaml'

  output:
    links:
      - title: Repository
        url: '${{ steps.publish.output.remoteUrl }}'
      - title: Open in catalog
        icon: catalog
        entityRef: '${{ steps.register.output.entityRef }}'
      - title: Repository
        url: '${{ steps.publishTwo.output.remoteUrl }}'
      - title: Open in catalog
        icon: catalog
        entityRef: '${{ steps.registerTwo.output.entityRef }}'
caution

Be careful to not to use any special characters(for example -) in the id field of the publish and register steps.

Publishing shared files in a Data Product monorepo​

When a component is created in the monorepo of its parent Data Product, a template can publish a second set of shared files to the same repository, for example at its root. Configure this additional phase without a catalog-info.yaml: set catalogInfoOptional: true on both actions and allowNonEmptyDirectory: true on the publish action. The latter is required because the component phase has already created files in the repository; existing unrelated files are preserved, while files with matching paths can be overwritten.

The additional phase must not include a catalog:register step, because it does not create another catalog entity:

- id: sharedFiles
  name: Fetch Shared Files
  action: fetch:template
  input:
    url: ./shared-files
    targetPath: shared-files
    catalogInfoOptional: true
    values: {}

- id: publishSharedFiles
  name: Publish Shared Files
  action: witboostMeshComponent:publish:gitlab
  input:
    allowedHosts: ['gitlab.com']
    repoUrl: '${{ steps.template.output.values.repoUrl }}'
    rootDirectory: '.'
    sourcePath: shared-files
    catalogInfoOptional: true
    allowNonEmptyDirectory: true

Both options default to false, so existing templates keep requiring a descriptor and an empty destination. The same options are available on all witboostMeshComponent:publish:* actions.

So, now that we have a template.yaml ready, we should now map all user inputs to catalog-info.yaml which will define the structure of your component.

Step 2. catalog-info.yaml Definition​

The catalog-info.yaml file, that must be defined inside the skeleton folder, will be used as the YAML definition of the entity that will be created by the template. Refer to the Witboost Entities Overview for more details.

As other files in the skeleton folder, it can be a Nunjucks template referencing variables defined in templates.yaml.

Example:

apiVersion: backstage.io/v1alpha1
kind: Component # Either "Component", "System" or "Domain" based on the registered entity
metadata:
  name: ${{ values.fieldone }}
  description: ${{ values.fieldthree }}

spec:
  # fixed fields
  type: component
  lifecycle: experimental
  owner: ${{ values.fieldtwo }}
  mesh:
    # custom fields, all of these are optional and depend on the information you want to save on your entity
    componentOwner: ${{ values.fieldtwo }}
    useCaseTemplateId: ${{ values.useCaseTemplateId }}
    infrastructureTemplateId: ${{ values.infrastructureTemplateId }}
    version: 0.0.0 # Specify whatever component version you desire

    specific: # all extra fields goes here

The metadata.name is the main identifier inside Witboost catalog. For this reason, this field supports only [a-z0-9+#] separated by [-], no spaces or other special characters are allowed here. We strongly recommend to use the output of an IdentifierPicker/ComponentIdentifierPicker as value of this field.

Instantiation​

The instantiation phase is the process that takes place when a user creates a new entity using a Creation Template. It reads:

  • The contents of the skeleton folder inside the template repository.
  • The parameter values provided by the user through the visual wizard.
  • The values defined under spec.steps[template].values in templates.yaml.

Then it generates and writes files into the new entity's repository.

There are two distinct behaviors during instantiation, depending on whether the entity being created is a Skeleton Entity or a Legacy Entity.

Skeleton entities​

Skeleton Entities are the recommended and standard approach for defining systems and components in Witboost since version 2.3.

To instruct the template to instantiate an entity as a Skeleton Entity, simply place the %SKELETON directive at the top of the catalog-info.yaml file in the template's skeleton folder. This directive activates special handling during the instantiation phase.

Example:

%SKELETON
kind: System
metadata:
  name: finance.cashflow.2
  description: ${{ parameters.description }}
spec:
  type: dataproduct
  lifecycle: ${{ parameters.lifecycle }}
  owner: group:witboost
  domain: domain:finance
  mesh:
    name: ${{ parameters.displayName }}$
    version: ${{ parameters.version.major }}.${{ parameters.version.minor }}.${{ parameters.version.patch }}$
    fullyQualifiedName: Liquidity ${{ parameters.displayName }}s
    maturity: ${{ values.maturity }}$

During instantiation of a Skeleton Entity:

  • The catalog-info.yaml file is copied as-is into the new entity's repository. It retains all Nunjucks templating expressions and is not rendered at this stage.
  • A parameters.yaml file is created in the entity's repository, with the following structure:
    • parameters: — this section is populated with user-provided inputs, as defined in the spec.parameters section of template.yaml. Each parameter appears using a 1:1 name match with its definition in template.yaml; their values are collected through the visual wizard at instantiation time.
    • values: — this section is populated as-is from the spec.steps[template].values section of template.yaml. This includes any default or computed values meant to be available inside the skeleton for compatibility with older templates that rely on values.
    • readonly: — see note below.
    • refs: — if present in skeleton/parameters.yaml, these definitions are kept in the generated entity repository and resolved later when the skeleton is rendered. For the complete refs reference, see Skeleton Parameters.
    • environmentParameters: - see section below.
  • If the template's skeleton folder already includes a parameters.yaml file, it will be merged during instantiation:
    • Any new values provided during instantiation override those in the existing file.
    • This allows for default values to be pre-configured while still honoring user input.

This approach results in a new entity's repository where the YAML structure is dynamic, and values are maintained separately, improving maintainability and tooling integration.

note

Reserved Parameters are special fields automatically handled by Witboost during the entity lifecycle (e.g., versioning, registration). These can appear in either the readonly: section of parameters.yaml or — in some cases — under parameters:.

Key behaviors:

  • Witboost automatically infers and generates reserved parameters like __name__, __version__, and __instanceOf__ if they are not explicitly set in the template.
  • They can be predefined in the template's skeleton/parameters.yaml to override or set default values.
  • They are injected into the final parameters.yaml file under the appropriate section (readonly or parameters).
  • These values are accessible inside catalog-info.yaml using standard Nunjucks syntax:
    ${{ readonly.__version__ }}, ${{ parameters.dependsOn }}, etc.

See the full list in Reserved Parameters.

Environment Parameters​

Environment parameters customize the skeleton's behavior based on the specific environment (production, development, etc.) in which it is rendered. They are defined in the environmentParameters section of parameters.yaml, and accessible from the catalog-info.yaml when rendering the skeleton for a specific environment.

Refer to the Environment Parameters documentation for more information.

If you want users to provide environment-specific values during template instantiation, mark one of the spec.parameters sections in your template.yaml with

environmentParameters: true

Once enabled, Witboost automatically:

  • Duplicates the section in the Creation Wizard UI — one panel for each available environment (dev, qa, prod, etc.)
  • Collects user inputs into the environmentParameters section of the generated parameters.yaml

Example:

kind: Template
# ...
spec:
  parameters:
    - title: Environment Parameters
      environmentParameters: true # enable environment parameters
      properties:
        clusterSize:
          title: Cluster Size
          type: string

Using this example, the form will look like the one in the image. Production Env step

note

Limitations

  • At most one environment parameters section can be enabled per template.
  • Pickers in an environment parameters section cannot be referenced by other pickers in the template, even if they are in the same environment parameters section.

Legacy entities​

note

This approach was standard prior to Witboost 2.3 for systems and components, however it is now considered a legacy pattern for these entity types. New systems and components should be defined as Skeleton Entities, which offer better tooling support, easier maintainability, and improved integration with Witboost's visual tools.

Legacy Entities follow an older pattern where catalog-info.yaml is treated as a static file, as well as all other files inside the skeleton directory.

During instantiation of a Legacy Entity:

  • The catalog-info.yaml file is rendered immediately, using the Nunjucks engine and values from spec.steps[template].values, as well as all other files inside the skeleton directory.
  • The rendered output is saved into the entity's repository as a static YAML file.
  • No parameters.yaml file is created.
  • You cannot reference parameters, readonly or environments parameters in the skeleton/catalog-info.yaml, only values defined in template.yaml (spec.steps[template].values). Environment values can only be defined under static files on the environments/ folder of the skeleton directory.
tip

Files under environments/<env>/configurations.yaml define environment-specific overrides that will merged in final entity descriptor when rendering it in the scope of a given environment <env>.

On Skeleton Entities these environment-overrides have been replaced by more flexible Environment Parameters. However, they are still supported and can be used if needed.

The configurator can choose between two different strategies:

  • override (default): When merging array values, the array defined in the configurations.yaml file will completely replace the array defined in the descriptor. No elements from the original array are preserved.

    Example

    Base descriptor:

    endpoints:
      - url: /a
        method: GET
      - url: /b
        method: POST

    configurations.yaml:

    endpoints:
      - url: /override
        method: PUT

    Result (override):

    endpoints:
      - url: /override
        method: PUT

  • merge: This strategy merges arrays by index position. Each item in an array in the configurations.yaml file is merged into the corresponding item at the same index in the base descriptor array.

    Example

    Base descriptor:

    endpoints:
      - url: /a
        method: GET
      - url: /b
        method: POST

    configurations.yaml:

    endpoints:
      - url: /override
        method: PUT

    Result (merge):

    endpoints:
      - url: /override
        method: PUT
      - url: /b
        method: POST

Merge strategy can be defined in values.yaml file under the key ui.appConfig.mesh.builder.editAndTest.mergeStrategy.

Skeleton vs Legacy Entities Summary​

FeatureSkeleton EntitiesLegacy Entities
Declared via %SKELETON✅ Yes❌ No
Dynamic rendering (delayed)✅ Rendered at runtime❌ Rendered at instantiation
parameters.yaml file created✅ Yes❌ No
Parameters usable in template✅ parameters, readonly, values, environments parameters❌ Only values
Recommended for systems/components✅ Yes❌ Deprecated

Step 3. Other artifacts in skeleton folder​

The skeleton folder contains all the files and directories that will be copied into the newly created repository during the instantiation of a Use Case Template.

At a minimum, it must include the required files for entity definition — namely catalog-info.yaml and, optionally, parameters.yaml — which have been described in detail above.

In addition to those, the folder can include any other resources necessary to scaffold a fully functional repository, such as:

  • Documentation files (e.g., README.md, docs/)
  • Configuration files
  • Source code, scripts, or boilerplate directories

These files can include Nunjucks templating expressions and will be rendered at instantiation using the values provided in template.yaml (spec.steps[template].values). Use the values variable to inject dynamic content (e.g., ${{ values.fieldone }}) into any of these files.

This allows you to fully customize the structure and content of the generated repository beyond the entity metadata itself.

note

All files in the skeleton folder except catalog-info.yaml are always processed at instantiation time. Their templated expressions (e.g., ${{ values.xxx }}) are replaced immediately using the values defined in template.yaml. This applies to both Skeleton and Legacy Entities.

As a result, documentation, configuration files, and code files included in the template will always be fully resolved before being committed to the generated repository.

Enabling docs generation in your components​

In the template definition, there are two customizable points that you can leverage to increase the user experience for witboost users:

  1. in the template repository, you can define a mkdocs.yaml file and a docs directory to let users better understand what the template will create once selected for creation.
  • Create a mkdocs.yml file in the root of your repository that will have the following content:
site_name: 'example-docs'
nav:
  - Home: index.md
plugins:
  - techdocs-core
  • Update your template definition by adding the following lines to its template.yaml file in the root of the repository:
metadata:
  annotations:
    backstage.io/techdocs-ref: dir:.
  • Create a /docs folder in the root of your repository with at least an index.md file in it. (If you add more markdown files, make sure to update the nav in the mkdocs.yml file to get proper navigation for your documentation.) Note - Although docs is a popular directory name for storing documentation, it can be renamed to something else and can be configured by mkdocs.yml. See https://www.mkdocs.org/user-guide/configuration/#docs_dir
  1. you can add an icon to your template that will be displayed in the templates page by adding a public png URL in the template.yaml file, like:
metadata:
  mesh:
    icon: https://path.to.a.public/image.png

Step 4. Testing a Use Case Template​

After defining the basics of your template, you can test it directly on Witboost without registering and rendering it available to all users. Witboost provides the Template Studio, a playground where you can load templates from your local computer filesystem and test them directly on the platform, seeing how the form is rendered, editing at real time, and executing dry-runs to see the whole pipeline. You can find the Template Studio in Administration > Templates and click on the context menu ( ⋮ ) to the right of the title. There, you have three tools at your disposal:

Template Studio

  • Local Directory Template Studio: The main tool for creating, editing and testing templates present in your local directory filesystem.
  • Edit Registered Template: A tool to test small changes on templates already registered on the platform.
  • Catalog Info Rendering Preview: A tool to test existing catalog-info.yaml/parameters.yaml files and quickly test changes on the rendering of these files. Find more information here.

Opening the Local Directory Template Studio will allow you to load a directory from your computer and see in real time the form that would get rendered on the platform. It also have tools to debug the underlying generated form parameters, and to perform dry-runs of the entity generation and publish. This dry-run won't create any files or repositories on the target Git provider, but will simply output the files that would be pushed onto the registry, including the logs, links and catalog entity output a user would see as part of the entity creation process.

Dry Run

Step 5. Registering a Use Case Template​

After effectively testing your template, you can register it on the platform from the Administration Panel. Go to Administration > Templates page and click on Register Template. Inside the page, you will need to link the committed template.yaml file.

Register existing component

warning

Make sure the URL for the template.yaml does not target a branch containing slashes (e.g. feature/branch-name) since Witboost does not currently support this format of branches.

Configuration-based registration

You can also add template files to the catalog through static location configuration. This allows to register templates that cannot be deleted from the platform, as they will be re-registered every time Witboost is updated or restarted. For example:

ui:
  appConfig:
    catalog:
      locations:
        - type: url
          target: https://github.com/agile-lab-dev/witboost-data-product-template/blob/master/template.yaml
          rules:
            - allow: [Template]

Practice Shaper​

Use Case Templates are nodes of the Practice Shaper graph. Their role is to help in creating instances of system and component types.

As extensively described in the Practice Shaper documentation, every template should define a spec.generates property referencing the system type or component type of the system/component instances it generates.

warning

The spec.generates property is mandatory when the template instantiates a system or component and includes a fetch:template action.

fetch:template uses the value of spec.generates to automatically fill the spec.instanceOf property of the generated system or component instance — through the readonly.__instanceOf__ parameter in case of skeleton entities.