Schema – cavaliba.com

`CTRL K`

Documentation
Data
Schema

# Schema

Schema are definitions of top-level asset families : Devices, Applications, Laptops, Projects, Customers, Books, Facilities, Cooking Receipes, Invoices, etc.

## Create a simple Schema

To manage laptops (for example), you can define a simple Schema:

    - classname: _schema
      keyname: laptop
      displayname: User Laptops

Go to the import tool from the left sidebar, and paste this YAML snippet. Clic on import. You can now manage `laptops` objects from the UI.

You can also use the `CLI` command :

    $ cavaliba load files/import/laptop.yaml

To create a first laptop object in the new Schema, either use the Web UI (edit), or import the following YAML snippet:

    - classname: laptop
      keyname: pc0001
      displayname: Evan's laptop

## Schema Reference

    - classname: _schema
      _action: create/delete/update/enable/disable
      keyname: string
      displayname: string
      is_enabled: boolean
      order: int
      page: string

      _options:

          p_admin:  PERMISSION_NAME
          p_read:   PERMISSION_NAME
          p_create: PERMISSION_NAME
          p_update: PERMISSION_NAME
          p_delete: PERMISSION_NAME

          keyname_mode: edit(*) | auto
          keyname_label: STRING
          displayname_label: STRING
          icon: STRING                  # FontAwsome4_iconname (ex. fa-question)

          notify:
            - template: SIRENE_TEMPLATE_KEYNAME
              label: BUTTON_LABEL
            - template: _template
              label: BUTTON_LABEL
            - template: _self
              label: BUTTON_LABEL
            - template: ~
              label: BUTTON_LABEL

      FIELDNAME_1:
          (...)

## Reserved Schema names

Some internal/builtin schema names are reserved and are not available for user-defined schemaes:

- _schema
- user/_user
- group/_group
- role/_role
- permission/_permission
- _apikey
- _enumerate
- _dataview

## Builtin Fields

All Schema share a small number of builtin fields.

- keyname - primary key - unique name of the Schema ; no special chars ; must be unique. Some options exists to hide/auto-generate keyname if a user friendly value is not needed. Keyname uniqueness and lookups are case-insensitive: `Server01` and `server01` are treated as the same keyname.
- displayname - a short label for humans to read
- is_enabled - true/false ; disabled objects are not available to regular users.
- _options - dictionary of Schema options. See below
- page - string, page name in the Web UI displaying the list of available DataClasses
- order - int, display order in the Web UI

## Schema _options

- icon - string, name of a FontAwsome Icon to display in UI
- permissions… - a set of permissions to control authorizations on instances
- keyname_label : User friendly label for builtin keyname field.
- keyname_mode : either edit (default) or auto (automatic uuid string)
- displayname_label : User friendly label for builtin displayname field.
- notify : list of Sirene notification shortcuts shown in the instance burger menu and action dropdown. Requires `p_sirene_new` permission. Each entry has:
  - `template` : keyname of a `sirene_template` instance, or one of the special values below
  - `label` : button label shown in the menu

### notify — special template values

`template` value | Behaviour
--- | ---
`KEYNAME` | Opens new Sirene message pre-filled from the named `sirene_template`, with source instance field values substituted into placeholders
`_self` | For `sirene_template` schema only — opens new message pre-filled from the instance itself
`_template` | Opens a template picker page listing all available `sirene_template` instances
`~` (YAML null) | Opens a blank new Sirene message form

### notify — placeholder substitution

When a message is created from a `sirene_template` with a source instance, the following placeholders are replaced in the message title, email body, and SMS body at form-creation time (before the user reviews or sends the message):

Placeholder | Replaced with
--- | ---
`$keyname$` | Source instance keyname
`$displayname$` | Source instance displayname
`$FIELDNAME$` | First value of the named field on the source instance

The existing `$C$` (category) and `$S$` (severity) placeholders still apply and run after instance-field substitution.

### notify — example

    - classname: _schema
      keyname: server
      _options:
        icon: fa-server
        notify:
          - template: tpl_maintenance
            label: "Notify Maintenance"
          - template: tpl_incident
            label: "Notify Incident"
          - template: _template
            label: "Choose template..."
          - template: ~
            label: "Blank message"

With a `sirene_template` whose title is `"Maintenance on $displayname$ ($environment$)"`, clicking “Notify Maintenance” on server instance `prod-web-01` (environment: Production) pre-fills the message title as `"Maintenance on prod-web-01 (Production)`.

### field_hide_from_detail

Added in version 4.0.0

List of field names to exclude from the instance detail view.

    - classname: _schema
      keyname: server
      _options:
        field_hide_from_detail:
          - internal_ref
          - raw_payload

Fields listed here are hidden in the detail UI only. They remain accessible via the API, exports, and all other views. An empty list (the default) hides nothing. Unknown field names are silently ignored.

### field_hide_from_edit

Added in version 4.0.0

List of field names to exclude from the instance create and edit form.

    - classname: _schema
      keyname: server
      _options:
        field_hide_from_edit:
          - internal_ref
          - raw_payload

Fields listed here are hidden in the create and edit form UI only. They remain accessible via the API, exports, and all other views. An empty list (the default) hides nothing.

Note: this option applies to both the create form and the edit form, since both use the same underlying view. Unknown field names are silently ignored.

## Schema Fields

Each Schema can have zero or more custom fields. These fields can be single-valued or multi-valued. They have a type from one of the available field types.

Field name must be a valid slug string (unique, no special character) within the Schema.

See Field Types

## Schema Example

This example create a Schema to manage user Laptops.

    # Asset = User Laptops

    - classname: _schema
      keyname: laptop
      displayname: User Laptops
      is_enabled: yes
      order: 200
      page: Data

      _options:
         icon: fa-laptop

      serial:
            displayname: serial_number
            page: General
            order: 100
            dataformat: string

      name:
            displayname: hostname
            page: General
            order: 110
            dataformat: string

      os:
            displayname: Operating System
            page: General
            order: 120
            dataformat: enumerate
            dataformat_ext: enumerate_os

      site:
            displayname: Site
            dataformat: schema
            dataformat_ext: site
            order: 130
            page: General
            cardinal_min: 0
            cardinal_max: 1

      owner:
            displayname: User
            dataformat: schema
            dataformat_ext: user
            order: 140
            page: General
            cardinal_min: 0
            cardinal_max: 0

      purchase_date:
            displayname: Purchase date
            dataformat: date

      waranty_end_date:
            displayname: Waranty end date
            dataformat: date

      bitlocker:
            displayname: Bitlocker
            page: Security
            order: 500
            dataformat: boolean

Field and Types