Skip to main content

Custom General Information fields

Overview​

In the Marketplace, in the Data Product or Output Port details page, the General Information section shows key information of a Data Product or an Output Port through a set of fields. Those fields are defined and filled by three sources:

  • Core fields: which are provided by default on installation, but can be overridden by the platform team trough the gridInfo and sideInfo configuration properties
  • Root-level fields: which are fields automatically parsed by witboost from the root level of the data product or output port descriptor
  • Additional fields: which are additional fields configured by the platform team that are shown after the Core fields on the main grid

All fields shown in the General Info sections are configurable. You can define which fields are shown in the main grid layout on the left trough the gridInfo property and which are shown on the right side on the screen by filling the sideInfo property. You can either hide some field leveraging the excludeDescriptorPaths configuration property, replace an existing field by supplying a different value through the additionalGeneralInfo property key or add brand new fields by still using the additionalGeneralInfo configuration property.

Additional fields defined in the configuration always take precedence over root-level fields and core fields. In particular, fields are matched through their labels. If two fields have the same label then one of the two will take precedence with this order: additional fields defined in the configuration > core witboost fields > root level fields.

Configuration file​

The sections of the configuration file affected are shown below:

...
# Configurations for the witboost modules
mesh:
  # Marketplace module configurations
  marketplace:
    ...
    # UI configurations
    ui:
      ...
      dataProductPage:
        ...
        generalInfo:
          # This is a list of first level fields paths that you want to avoid displaying in the data product page's general information card
          excludeDescriptorPaths:
            - fieldOne
            - fieldTwo
        # Defines what fields to be shown inside the data product General Information card's main grid.
        gridInfo:
        # It contains a list of fields, specifying for each additional field:
            # The string label to be displayed for the field.
          - label: My field
            # The string value: the values in double brackets will be resolved with the values from the data product descriptor using Nunjucks.
            # It is important to enforce the string type for this field inside the yaml by using the single quotes as shown to avoid errors.
            value: 'the values are {{ specific.dbName }} and {{ specific.viewName }}'
            # The field type: string | date. Changing the field type will change the way the field will be rendered in the UI.
            type: string
            # Optional field to specify an external URL. If present, the field will be automatically rendered as a link (you don't need to change the type).
            # As shown for the value field, it can contain static string and/or values to be resolved from the descriptor, by using the same notation.
            href: '{{ specific.myCustomLink }}'
            # Optional field (default value is 1) that defines how many columns this field should fill on the main grid.
            # To prevent wasting space with empty holes on the grid, the number of columns the field will occupy in the final layout may be greater (but never less)
            colSpan: 2
        # Defines what fields to be shown inside the data product General Information card's right side column.
        sideInfo:
        # It contains a list of fields, specifying for each additional field:
            # The string label to be displayed for the field.
          - label: My field
            # The string value: the values in double brackets will be resolved with the values from the data product descriptor using Nunjucks.
            # It is important to enforce the string type for this field inside the yaml by using the single quotes as shown to avoid errors.
            value: 'the values are {{ specific.dbName }} and {{ specific.viewName }}'
            # The field type: string | date. Changing the field type will change the way the field will be rendered in the UI.
            type: string
            # Optional field to specify an external URL. If present, the field will be automatically rendered as a link (you don't need to change the type).
            # As shown for the value field, it can contain static string and/or values to be resolved from the descriptor, by using the same notation.
            href: '{{ specific.myCustomLink }}'
        # Optional field used to add custom fields to be shown inside the data product General Information card.
        additionalGeneralInfo:
        # It contains a list of custom fields, specifying for each additional field:
            # The string label to be displayed for the field.
          - label: My custom field
            # The string value: the values in double brackets will be resolved with the values from the data product descriptor using Nunjucks.
            # It is important to enforce the string type for this field inside the yaml by using the single quotes as shown to avoid errors.
            value: 'the values are {{ specific.dbName }} and {{ specific.viewName }}'
            # The field type: string | date. Changing the field type will change the way the field will be rendered in the UI.
            type: string
            # Optional field to specify an external URL. If present, the field will be automatically rendered as a link (you don't need to change the type).
            # As shown for the value field, it can contain static string and/or values to be resolved from the descriptor, by using the same notation.
            href: '{{ specific.myCustomLink }}'
            # Optional field (default value is 1) that defines how many columns this field should fill on the main grid.
            # To prevent wasting space with empty holes on the grid, the number of columns the field will occupy in the final layout may be greater (but never less)
            colSpan: 1
      # Output Port page configurations
      outputPortPage:
        ...
        # Same as gridInfo property in dataProductPage
        gridInfo:
          ...
        # Same as sideInfo property in dataProductPage
        sideInfo:
          ...
        # Same as additionalGeneralInfo property in dataProductPage
        additionalGeneralInfo:
          ...
...

Defining a field​

As you can see, it is possible to define fields to be shown trough the mainGrid, sideGrid and additionalGeneralInfo properties, that contain lists of custom fields that will be displayed in the UI. You need to specify the following information for each field:

  • label: this is a string field corresponding to the field name that will be displayed in the UI.
  • value: this is the field value. This field supports the syntax shown in the example above: you need to use the double curly brackets to resolve the specified values from the Data Product/Output port descriptor. The processing to resolve the values from the descriptor doesn't alter the remaining part of the string, so you can fully customize the displayed value by combining your string with values taken from the descriptor. As shown, it supports nested fields by using the dot notation and multiple fields from the descriptor within the same string. It is also important to highlight that, to prevent any error, you have to use the quotes for this field's value to enforce the string type inside the configuration YAML. The string will be processed using Nunjucks, so you can leverage its syntax to customize the value. For more details about the syntax and how it works, please refer to the Nunjucks documentation.
  • type: this is the field type. The supported types are string and date. Changing the field type will change the way the field will be rendered in the UI. This field is required as the previous ones, but if you provide a currently unsupported type (e.g. number), by default the field will be rendered as a string. We only support ISO 8601 date format for dates.
  • href: this is an optional field that allows you to specify an external URL. If present, the field will be automatically rendered as a link (you don't need to change the type). It uses the same syntax explained for the value field, so it can contain static strings and/or values to be resolved from the descriptor.
  • colSpan: this is an optional field that allows you to specify how many columns a field should occupy in the layout grid filled by gridInfo and additionalGeneralInfo(it has no effect on fields defined in sideInfo). To prevent wasting space with empty holes on the grid, the number of columns the field will occupy in the final layout may be greater (but never less) than the value specified. Default value is 1, unless maxCharactersBeforeColSpanExpansion is defined: in that case the default colSpan value will be 2 or 1 depending on wether the value length surpasses maxCharactersBeforeColSpanExpansion or not.

Every time a field defined this way has no value, it is not shown. For example, if you put a configuration such as:

dataProductPage:
  mainInfo:
    - label: This link will not be displayed
      value: 'Link to a non existing file'
      type: string
      href: '{{ nonExistingField }}'
  additionalGeneralInfo:
    - label: This string will not be displayed
      value: '{{ nonExistingField }}'
      type: string

You will see the fields only when the nonExistingField is defined at data product level, and they will not be displayed otherwise.

In case you have some composite fields like:

dataProductPage:
  mainInfo:
    - label: This is a composite value
      value: 'the value is: {{ specific.myField }}'
      type: string
  additionalGeneralInfo:
    - label: This is a composite link
      value: 'click me'
      type: string
      href: 'https://www.google.com/search?q={{ specific.myField }}'

the fields will be displayed anyway, since their values are non-empty even if the fields are not defined (the first one would have a value of '' and the second one an href 'https://www.google.com/search?q='). In this case we can leverage nunjucks to hide them when the fields are empty:

dataProductPage:
  mainInfo:
    - label: This is a composite value
      value: '{%if specific.myField %} the value is: {{ specific.myField }} {% endif %}'
      type: string
  additionalGeneralInfo:
    - label: This is a composite link
      value: 'click me'
      type: string
      href: '{%if specific.myField %} https://www.google.com/search?q={{ specific.myField }} {% endif %}'

$computedInfo​

The syntax used for defining the value and href fields can contain static strings and/or values to be resolved from the descriptor. However, some interesting information may not be in a Data Product/Output port descriptor and still be worth to be shown in the General Information page. For this reason, an extra property called $computedInfo is added to the descriptor when resolving the value and href values that contains may contain extra properties for Data Product and Output Port (not all of them may always be available).

note

If in the descriptor a property called exactly $computedInfo already exists, that will override the added $computedInfo described above and its fields won't be available.

Examples of $computedInfo for Data product​

dataProductPage:
  mainInfo:
    - label: Published Date
      value: '{{ $computedInfo.published_at }}'
      type: date
    - label: Published Date
      value: '{{ $computedInfo.domainHierarchy }}'
      type: string

Examples of $computedInfo for Output Port​

outputPortPage:
  mainInfo:
    - label: Endpoint
      value: 'Open Endpoint'
      type: string
      href: '{{ $computedInfo.endpointLink }}'

    - label: Domain
      value: '{{ $computedInfo.domainHierarchy }}'
      type: string

  sideInfo:
    - label: Data Product
      value: '{{ $computedInfo.DataProductInstance.DataProduct.name }}'
      type: string

    - label: Owner
      value: '{{ $computedInfo.DataProductInstance.DataProduct.data_product_owner_display_name }}'
      type: string

    - label: Environment
      value: '{{ $computedInfo.DataProductInstance.Environment.name }}'

Special Root-Level Fields​

witboost can recognize particular fields values among root-level fields in the descriptor and transform them to improve their readability. These are:

  • Groups and users references. whenever a group:<name of the group> or user:<username> is found in any of the root-level fields, they are converted into Name Of The Group <email of the group> or Name and Surname <email> (but only if an email and a display name is available for your configured authentication system).
  • URLs. If any of the root-level fields of the descriptor has a URL, the field is rendered as a clickable URL.
  • Dates. If any root-level field contains a ISO 8601 compliant date string then it is treated as a date.