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 useCaseTemplateId s 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 |
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
If no spec.domain
is specified, the EditTemplate
entity will be available for all users if RBAC is enabled.
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.
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.
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
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.
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:
You cannot link to the same useCaseTemplateId
(so, the Template
) more than one EditTemplate
. If you do that, you will see in the page, 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:
- wait for witboost to automatically fetch and sync the changes (it is usually done every 90 seconds)
Builder
>Software Catalog
> Filter forEditTemplates
> 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 forEditTemplates
- 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 acanEdit
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 inedit-template.yaml
- or every template that generates entitys with one of the use case template ids inspec.useCaseTemplateId
- features a clickable wizard icon that redirects toEditTemplate
entity page.
noteThe 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. - Check: every use case template listed in the
-
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.
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.