Template

Every system or component on witboost is associated to an use case template id that identifies the template it has been created from.

To run an edit operation on a specific system or component, the platform team should declare which fields are allowed to be edited by the users for that entity.

The EditTemplate entity kind allows to define a set of input params and link them to one or more use case template ids. When a user heads to an entity page and an EditTemplate related to the entity's use case template id is found, then they will have the possibility to proceed to the editor wizard where the first step will render an input form based on the params definition stored into the EditTemplate entity.

Entity definition

To define a new EditTemplate entity, the Platform Team has to create a edit-template.yaml file with the following properties in a git repository:

field	type	description
apiVersion	string	fixed to witboost.com/v1
kind	string	fixed to EditTemplate
metadata	EntityMetadata	witboost entity standard metadata (e.g. metadata.name)
spec.domain	string (optional)	Entity domain
spec.owner	string (optional)	Entity owner
spec.useCaseTemplateId	list[string] (optional)	This EditTemplate will be associated to each deployment unit entity with useCaseTemplateId among the provided ones
spec.useCaseTemplateRef	list[string] (optional)	Complete reference (type:namespace/name) to one or more use case template entities (e.g. template:default/dataproduct-template). spec.useCaseTemplateId will be automatically filled with the useCaseTemplateIds of the referenced templates.
spec.parameters	object	Definition of the editable input params
spec.steps	list[object]	Steps definition to create the edit template. In the case of EditTemplate kind, only one is used, the fetch:template action

note

In the table above a dot (.) in the field name indicates a relation between an object and its property. E.g.

spec:
  domain: domain-value
  owner: owner-value

note

If no spec.domain is specified, the EditTemplate entity will be available for all users if RBAC is enabled.

note

You can fill both spec.useCaseTemplateId and spec.useCaseTemplateRef arrays. The resulting EditTemplate entity will process and merge their elements in a single spec.useCaseTemplateId array.

Property spec.parameters sticks to the same templating language used inside the definition of a use case template (property spec.parameters inside template.yaml).

Sample edit-template.yaml

The following sample represents an EditTemplate entity that allows the user to edit only the email field of an entity.

# it is important to use this apiVersion
apiVersion: witboost.com/v1
kind: EditTemplate
metadata:
  name: edit-template-dp
  title: Edit Template test
  description: Edit Template definition of a Data Product
  tags:
    - edit-data-product
spec:
  owner: agile_lab
  useCaseTemplateId:
    - urn:dmb:utm:aws-cdp-outputport-Impala-template:0.0.0
    # you can add other useCaseTemplateIds
  # you can also define templates by their entity ref:
  # useCaseTemplateRef:
  # - template:default/metadata.name
  parameters:
    - title: Data Product new details
      properties:
        email:
          title: Email
          type: string
          description: Set a new email
    # you can add additional parameters too
  steps:
    # only this action is actually used
    - id: template
      name: Fetch Skeleton + Template
      # do not edit the action name
      action: fetch:template
      input:
        # remember to link this EditTemplate to the actual skeleton
        url: ./edit-skeleton
        targetPath: .
        copyWithoutRender:
          - .gitlab-ci.yml
        values:
          # remember to link all parameters to the values passed to the skeleton
          email: '${{ parameters.email }}'

This specification will create an EditTemplate entity, associated with each entity with a use case template id equal to urn:dmb:utm:aws-cdp-outputport-impala-template:0.0.0. When a user opens the editor wizard on one of these entities, they will be presented with the form in the following image:

Templating language

To better understand the templating language for editor parameters and the available input field types check this page and this one.

tip

To test a form definition and preview how it will be rendered, you can exploit the Template Editor located at https://<witboost-url>/wb-scaffolder/edit. It is not specifically intended for editor templates but it can serve as a good visual preview tool.

warning

Remember to be consistent with your pickers: for example, if in the creation template, the picker that creates the tags field was defined as a CustomUrlPicker, but then in the EditTemplate you define that a standard array picker will edit the tags field, witboost will complain.

Create edit skeleton

Once the edit-template.yaml file is ready, it's time to build also the skeletoned catalog-info.yaml that will be merged with the old one. This file follows the same logic as described in step two of yaml creation. In the case of the edit operation, this file will contain only the values the platform team wants to change from the original catalog-info.yaml. An example, coherent with the edit-template.yaml sample defined above, would be the following one, defined under edit-skeleton/catalog-info.yaml:

spec:
  mesh:
    email: ${{ values.email | dump }}

The following is an example of how a repository would look after all the required files are defined:

• repository
  • edit-template.yaml
  • edit-skeleton
    • catalog-info.yaml

note

Users will not only be able to edit, but also to delete or add a field: if the platform team defines a new field in the EditTemplate, it will be added to the catalog info when the picker is filled by the user. On the other hand, if the user leaves blank a picker in the edit phase, the catalog-info will not contain that field anymore

Entity registration

Once both edit-template.yaml and its related catalog-info.yaml skeleton are defined, it is time to register the EditTemplate to witboost.

Automated way

When an edit-template.yaml is placed in the same folder as an already registered witboost use case template's template.yaml file (Template entity), it will be automatically fetched by witboost and the related EditTemplate entity will be registered (or refreshed).

Manual way

It's also possible to manually register EditTemplate entities from the Catalog Import page https://<witboost-url>/catalog-import (Builder > Templates > Register Existing entity button) by referencing the edit-template.yaml git location.

tip

You can link multiple useCaseTemplateIds to the same EditTemplate (for example, you could have an EditTemplate that edits only the email field, so it could be useful to link it to more than one Template).

However, the vice-versa is not possible:

caution

You cannot link to the same useCaseTemplateId (so, the Template) more than one EditTemplate. If you do that, you will see in the UI, under Builder -> Templates this warning: By clicking the Wizard Off icon, you will be redirected to the Template entity page where you can see all the relations, so that it is easier to notice which are the duplicates (see the editableBy relations). and in the Entity page, linked to the useCaseTemplateId, if you open the Edit menu, you will see something like this

Template reloading

In order to reflect the modifications made on the edit-template.yaml to the witboost EditTemplate entity you have two options:

1. wait for witboost to automatically fetch and sync the changes (it is usually done every 90 seconds)
2. Builder > Software Catalog > Filter for EditTemplates > Open the target entity page > Click on the refresh icon

Documentation

EditTemplate entities can be documented exactly like other witboost entities. Check this section for additional details.

The documentation can then be read from the EditTemplate catalog page (Docs tab).

Edit Template Checklist

The following checklist can be used to verify if an EditTemplate entity has been loaded successfully and is semantically correct.

• Go to Builder > Software Catalog > Filter for EditTemplates

  • Check: the target entity is found
  • Open the entity page
    • Check: no errors are displayed
    • Check: in the relations graph, the edit template is linked to the existing Templates with a canEdit relation.
    • Check: in case you documented the entity, the Docs tab correctly renders it.

• Go to Builder > Templates

  • Check: every use case template listed in the spec.useCaseTemplateRef field in edit-template.yaml - or every template that generates entitys with one of the use case template ids in spec.useCaseTemplateId - features a clickable wizard icon that redirects to EditTemplate entity page.
  note

  The wizard icon on a use case template card indicates that every entity created starting from that use case template is suitable for the editor operation; the edit input parameters are defined by the EditTemplate entity referenced by the icon hyperlink.

• Open the editor input wizard of one of the target entities

  • Check: the input form in the first step of the wizard is correctly rendered and it's the desired one.

Entity removal

An EditTemplate entity can be unregistered from the Software Catalog (Builder > Software Catalog > Filter for EditTemplates > Find the target entity) just like any other catalog entity.

caution

If you unregister an entity whose edit-template.yaml is placed in the same folder of a witboost use case template's template.yaml file, it will be automatically reloaded by witboost (see the Automated entity registration section above). In this case, please remember to first remove edit-template.yaml from the repository before deleting the related entity from the Software Catalog.