This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Reference

Data Models

1 - AAA - User Model

Reference

YAML Model

_user:j.doe:
    #_action: create|create_update|delete|enable|disable
    external_id: id#545
    email: j.doe@a.a.com
    mobile: '0101010101'
    firstname: John
    lastname: Doe
    displayname: John DOE
    description: TESTDOE
    is_enabled: true
    want_notifications: true
    want_24: true
    want_email: true
    groups:
      - demogroup_1
      - demogroup_2

2 - AAA - Group Model

Reference

YAML Model

_group:demogroup_1:
	  displayname: Demo Group 1
	  description: Demo Group 1 for tests
	  subgroups: 
	    - mysubgroup01
	    - mysubgroup02
	  users: 
	    - f.kafka
	    - b.evans

3 - AAA - Role Model

Reference

YAML Model

_role:role1:
	  displayname: Demo Role 1
	  description: Demo Group 1 for tests
	  subgroups: 
	    - group03
	    - group04
	  users: 
	  	# not recommended ; use subgroups instead
	    - t.robinson
	  permissions:
	  	- p_user_read
	  	- p_user_write

Predefined Roles for Cavaliba Apps

Cavaliba Appls comes with a set of predefined Roles, which provide reasonable permissions package.

You can create additional roles and assign custom sets of permissions.

4 - DATA - Class/Schema

DataClass and Schema

A Schema describes a DataClass with global and custom fields.

Global Fields for all classes

These fields are default fields, alwas available to all DataClass schema.

  • keyname - unique name of the class ; slug, no special chars ; must be unique

  • _displayname - a short string for humans

  • _page - string, page name in the Web UI displaying the list of available classes

  • _order - int, display order in the Web UI

  • _icon - string, name of a FontAwsome Icon to display in UI

  • role…. - strings, name of a Cavaliba Role to control authorizations on that class/schema

    • _role_show : the class is visible in the UI
    • _role_access :
    • _role_read : Instances of this class can be viewed
    • _role_create : Instances of this class can be created
    • _role_update : Instances of this class can be updated (if they exist)
    • _role_delete : Instances of this class can be deleted
    • _role_onoff : Instances can be enabled/disabled in this class
    • _role_import : Allow import (YAML/JSON) of instances from this class
    • _role_export : Allow export (YAML/JSON) of instances from this class

Custom Fields

Each DataClass 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 below.

Field name must be a valid slug string (unique, no special chararcter) within the DataClass schema.

Available field types:

  • string
  • int
  • float
  • date
  • boolean
  • ipv4
  • text
  • enumerate
  • sirene_data
  • sirene_group
  • sirene_user

YAML Example

The _action attribute describes the operation to be performed on the object.


_schema:test_class:
    #_action: create
    _displayname: TestClass
    _is_enabled: yes
    _order: 900
    _page: Test        
    _icon: fa-question
    _role_show: role_data_test_ro
    _role_access: role_data_test_ro
    _role_read: role_data_test_ro
    _role_create: role_data_test_rw
    _role_update: role_data_test_rw
    _role_delete: role_data_test_rw
    _role_onoff: role_data_test_rw
    _role_import: role_data_test_admin
    _role_export: role_data_test_admin

    description:
       displayname: Description
       dataformat: string
       dataformat_ext: ""
       cardinal_min: 0
       cardinal_max: 1
       default : ""
    mystring:
        displayname: MyString
        dataformat: string
        description: description ...            
        order: 100
        page: Strings
    myint:
        displayname: MyInt
        dataformat: int
        order: 200
        description: description ...            
        page: Numbers
    myfloat:
        displayname: MyFloat
        dataformat: float
        description: description ...
        order: 210
        page: Numbers
    myboolean:
        displayname: MyBoolean
        dataformat: boolean
        description: check to activate !
        order: 300
        page: Booleans
    mydate:
        displayname: MyDate
        description: format YYYY-MM-DD
        dataformat: date
        order: 400
        page: Other
    myipv4:
        displayname: MyIPV4
        dataformat: ipv4
        description: A.B.C.D or A.B.C.D/mask
        order: 410
        page: Other

# ---

    my_sirene_group:
        displayname: MysireneGroup
        dataformat: sirene_group
        description: select cavaliba UserGroup object(s)
        order: 500
        page: Objects
        cardinal_max: 0

# ---

    my_sirene_app:      
        displayname: MySireneData(app)
        dataformat: sirene_data
        dataformat_ext: app
        description: Select Cavaliba Data object(s)
        order: 510
        page: Objects
        cardinal_max: 0
# ---

    my_enumerate_ok_ko:      
        displayname: MyEnumerate_OK_KO
        dataformat: enumerate
        dataformat_ext: enum_OK_KO
        description: Choose a value
        order: 505
        page: Static-Enum
        cardinal_min: 0
        cardinal_max: 1

    my_enumerate_ok_ko_na:
        displayname: MyEnumerate_OK_KO_NA
        dataformat: enumerate
        dataformat_ext: enum_OK_KO_NA
        description: Choose a value
        order: 510
        page: Static-Enum
        cardinal_min: 0
        cardinal_max: 1



    my_enumerate_abc:      
        displayname: MyEnumerate_ABC
        dataformat: enumerate
        dataformat_ext: enum_ABC
        description: Choose an enum_ABC value
        order: 520
        page: Static-Enum
        cardinal_min: 0
        cardinal_max: 1

    my_enumerate_abc_multi:      
        displayname: MyEnumerate_ABC_Multi
        dataformat: enumerate
        dataformat_ext: enum_ABC
        description: Choose enum_ABC values
        order: 525
        page: Static-Enum
        cardinal_min: 0
        cardinal_max: 0


    my_enumerate_abcde:      
        displayname: Maturite_ABCDE
        dataformat: enumerate
        dataformat_ext: maturite_ABCDE
        description: Choose an maturite_ABCDE value
        order: 530
        page: Static-Enum
        cardinal_min: 0
        cardinal_max: 1

    my_enumerate_abcde_multi:      
        displayname: Maturite_ABCDE_Multi
        dataformat: enumerate
        dataformat_ext: maturite_ABCDE
        description: Choose maturite_ABCDE values
        order: 535
        page: Static-Enum
        cardinal_min: 0
        cardinal_max: 0

# ---

    my_user:      
        displayname: My Sirene User
        dataformat: sirene_user
        description: Select a Cavaliba User
        order: 550
        page: Orga
        cardinal_min: 0
        cardinal_max: 1

    my_user_multi:
        displayname: My Sirene User Multi
        dataformat: sirene_user
        description: Select one or more Cavaliba Users
        order: 551
        page: Orga
        cardinal_min: 0
        cardinal_max: 0

5 - DATA - Authorizations

Data Reference

Data Authorization model

User access to Data Ressources requires a combination of two authorizations:

  1. Global - Operations Authorization on All Data Ressources (access/read/write/…) ; given by Permissions.

  2. Class/Schema - Operations Authorizations on specific Class/Schema ; given by Roles attached to Class/Schema

Global permissions

Global operations on all Data objects is controlled by a small set Permissions.

     ("p_data_access", "Access UI", "", False),
     ("p_data_class_ro", "Access RO on classes", "", False),
     ("p_data_class_rw", "Access RWD on classes", "", False),
     ("p_data_schema_ro", "Schema RO", "", False),
     ("p_data_schema_rw", "Schema RWD", "", False),
     ("p_data_instance_ro", "Global RO on instances", "", False),
     ("p_data_instance_rw", "Global RWD on instances", "", False),
     ("p_data_import", "Use file or YAML import tool", "", False),
     ("p_data_admin", "Other sensitive actions on data app", "", False),

you may provide thes Permissions to users through standard Role/Group. You can use Built-in Roles.

Built-in Roles

Give the following Roles to Users and Groups to provide Global Authorization.


ROLES_BUILTIN = {
    'role_data_ro': [
        "p_data_access",
        "p_data_class_ro",
        "p_data_schema_ro",
        "p_data_instance_ro",

    ],
    # class: create/update/delete/onoff
    'role_data_rw': [
        "p_data_access", 
        "p_data_class_rw",
        "p_data_schema_rw",
        "p_data_instance_rw",
    ],
    # class: import/export
    'role_data_admin': [
        "p_data_access", 
        "p_data_class_rw",
        "p_data_schema_rw",
        "p_data_instance_rw",
        "p_data_import",
        "p_data_admin",
    ],
}

Per Class/Schema Authorizations

Per Class/Schema Authorization is provided by Roles and is mandatory in addition to Global Authorization.

Each class has a set of _role attributes to define which Role controls allowed operation on the Class and its Instances.

# role definitions ...

_role:role_data_test_ro:
    displayname: Role DATA test RO
    subgroups:
      - usergroup1


_role:role_data_test_rw:
    displayname: Role DATA test RW
    subgroups:
      - usergroup2

_role:role_data_test_admin:
    displayname: Role DATA test ADMIN
    subgroups:
      - usergroup3

# .. can be used in specific Class/Schema definition:

_schema:test_class:
    
    _role_show: role_data_test_ro
    _role_access: role_data_test_ro
    _role_read: role_data_test_ro
    _role_create: role_data_test_rw
    _role_update: role_data_test_rw
    _role_delete: role_data_test_rw
    _role_onoff: role_data_test_rw
    _role_import: role_data_test_admin
    _role_export: role_data_test_admin

Per Instance Authorization

Not implemented.

Per Field Authorization

Not implemented.

6 - DATA - DataViews

Reference

A DataView describes a subset of a DataClass to be presented to the users in the Web Interface.

You can define multiple DataViews per DataClass for different type of users.

DataView objects

DataViews are implemented as regular DataClass objects and can thus be managed from the Web UI, REST API, console CLI, import/export, etc.

DataViews

# optional Role definitions to manage DataView authorizations
_role:role_data_view_ro:
    displayname: Role data:data_view:ro
    subgroups:
      - admin_cavaliba

_role:role_data_view_rw:
    displayname: Role data:data_view:rw
    subgroups:
      - admin_cavaliba

_role:role_data_view_admin:
    displayname: Role data:data_view:admin
    subgroups:
      - admin_cavaliba

# DataView definition as a specific DataClass structure

_schema:data_view:
    _displayname: Data Views
    _is_enabled: yes
    _icon: fa-table
    _order: 810
    _page: Internal
    _role_show: role_data_view_ro
    _role_access: role_data_view_ro
    _role_read: role_data_view_ro
    _role_create: role_data_view_rw
    _role_update: role_data_view_rw
    _role_delete: role_data_view_rw
    _role_onoff: role_data_view_rw
    _role_import: role_data_view_admin
    _role_export: role_data_view_admin
    description:
        #_action: create_or_update          
        displayname: Description
        order: 100
        dataformat: string
        dataformat_ext: ""
        cardinal_min: 0
        cardinal_max: 1
        default : ""
    # DataClass on which a DataView operates
    classname:
        displayname: classname
        cardinal_min: 0
        cardinal_max: 1
        order: 110
        dataformat: string
    # nested YAML structure with columns and operations on columns
    content:
        displayname: content
        cardinal_min: 0
        cardinal_max: 1
        order: 120
        dataformat: text
        dataformat_ext: yaml

Content format

The classname attribute defines the DataClass on which the DataView will operate.

The content attribute in the DataView object defines what and how to present the DataClass data. It is a nested YAML structure which lists columns to be displayed and operator to apply on each of these columns.

keyname, displayname and last_update are common attributes to all DataClass. They can be omitted from the DataViews columns. If none is requested , Cavaliba adds keyname by default.

Each entry is the name of a column as it will be displayed.

If the from operator is added to a column entry, it indicates wich DataClass attribute should provide content for that column.

An invalid from value will create an empty value for that column.

the intend use of the column/from combination is to provide nicer column names to users.

Some new operators may be added in the future, like aggregate values or computed values from other columns.

# DataView content attribute 
columns:
- keyname
- displayname
- last_update
- city
- zipcode
- my_enumerate_ok_ko
- my_enumerate_ok_ko_na
- my_enumerate_abc
- my_enumerate_abc_multi
- my_enumerate_abcde
- my_enumerate_abcde_multi
- newcol
- ZipAgain:
    from: zipcode
- newcol_invalid:
    from: non_existent_col
    other_operator: tobedone

DataView Example

The follwing YAML snippet create a DataView on the site objects to present some relevant geographical informations.

It says:

  • create a user available DataView for the DataClass site objects.
  • show a table with the following columns: address, region, …
  • some of the columns will have a different name than the underlying DataClass attribute

data_view:site_postal:
  #_action: create_or_update
  classname: site
  is_enabled: true
  displayname: MySiteView_postal
  description: This View displays Geographical information about sites
  content: |
    columns:
      - Site Name:
          from: keyname
      - address
      - Zip Code
          from: zipcode
      - Site city:
          from: city
      - country

7 - DATA - Enumerate

Reference

Enumerate are predefined lists of values which can be used as Field attributes when defining DataClass models. Enumerate values have various additional options : display widget, description or intended use, etc.

When editing DataClass objects, user will be presented with a list of available values only.

When displaying a DataClass objets, nice widgets can be presented to users.

Enumerate usecase examples:

  • status : OK, KO, N/A
  • maturity_level : Good, Medium, Average, Bad, Terrible, NotAvailable, Unkown, ToBeChecked, …
  • grade : A,B,C,D,E
  • fruits : apple, pear, mango, …
  • publish_status : draft, published, retracted
  • color : red, blue, yellow

Enumerate objects

Enumerate are implemented as regular DataClass objects and can thus be managed from the Web UI, REST API, console CLI, import/export, etc.

# optional Role definitions to manage DataView authorizations
_role:role_data_enumerate_ro:
    displayname: Role data:data_enumerate:ro
    subgroups:
      - admin_meteosi


_role:role_data_enumerate_rw:
    displayname: Role data:data_enumerate:rw
    subgroups:
      - admin_meteosi

_role:role_data_enumerate_admin:
    displayname: Role data:data_enumerate:admin
    subgroups:
      - admin_meteosi

# Enumerate definition as a specific DataClass structure
_schema:data_enumerate:
    _displayname: Data Enumerates
    _is_enabled: yes
    _icon: fa-table
    _order: 810
    _page: Internal
    _role_show: role_data_enumerate_ro
    _role_access: role_data_enumerate_ro
    _role_read: role_data_enumerate_ro
    _role_create: role_data_enumerate_rw
    _role_update: role_data_enumerate_rw
    _role_delete: role_data_enumerate_rw
    _role_onoff: role_data_enumerate_rw
    _role_import: role_data_enumerate_admin
    _role_export: role_data_enumerate_admin
    description:
        #_action: create_or_update          
        displayname: Description
        order: 100
        dataformat: string
        dataformat_ext: ""
        cardinal_min: 0
        cardinal_max: 1
        default : ""
    # nested YAML content, with values, widget, see below
    content:
        displayname: content
        cardinal_min: 0
        cardinal_max: 1
        page: input
        order: 120
        dataformat: text
        dataformat_ext: yaml

Enumerate Content format

The content attribute defines available values and their options.

- value: "A"
  is_enabled: True
  widget: "green_circle"
  description: "A value to use when eveything is good"
- value: "A"
  widget: "green_circle"
  description: "A value to use when eveything is good"
- value: "Z"
  is_enabled: False     
  description: "deprecated; not available"

Available Widget values

        "red_circle":    "🔴",
        "orange_circle": "🟠",
        "yellow_circle": "🟡",
        "green_circle":  "🟢",
        "purple_circle": "&#1F7E3;",
        "brown_circle":  "&#1F7E4;",
        "blue_circle":   "🔵",
        "white_circle":  "◯",
        "black_circle":  "⬤",
        "default" : ""

Using Enumerate in DataClass models


_schema:my_test_class:
    #_action: create
    _displayname: TestClass

    # (...)

    my_enumerate_abc:      
        displayname: MyEnumerate_ABC
        dataformat: enumerate
        dataformat_ext: enum_ABC
        description: Choose an enum_ABC value
        order: 520
        page: Static-Enum
        cardinal_min: 0
        cardinal_max: 1

    my_enumerate_abc_multi:      
        displayname: MyEnumerate_ABC_Multi
        dataformat: enumerate
        dataformat_ext: enum_ABC
        description: Choose enum_ABC values
        order: 525
        page: Static-Enum
        cardinal_min: 0
        cardinal_max: 0

    # (...)

Enumerate Examples

# ---------------------
# standard enumerates
# ---------------------
data_enumerate:enum_ABC:
  # ACTION
  is_enabled: True
  displayname: "ABC Scale"
  description: "Neutral ABC Scale"
  content: |
    - value: "A"
      widget: "green_circle"
      description: "A"

    - value: "B"
      widget: "orange_circle"

    - value: "C"
      widget: "red_circle"    


data_enumerate:maturite_ABCDE:
  # ACTION
  is_enabled: True
  displayname: "ABCDE Maturity scale"
  description: "Use for product assessment"
  content: |
    - value: "A - Perfect"
      #is_enabled: True
      widget: "green_circle"
      description: "Use if perfect"

    - value: "B - Correct"
      widget: "yellow_circle"

    - value: "C - Average"
      widget: "orange_circle"

    - value: "D - Bad"
      widget: "red_circle"

    - value: "E - Alert"
      widget: "black_circle"

    - value: "n/a"
      widget: "white_circle"

    - value: "to be checked"
      widget: "blue_circle"

    - value: "?"
      # no widget, text value will be displayed    


data_enumerate:enum_OK_KO:
  # ACTION
  is_enabled: True
  displayname: "OK/KO Scale"
  content: |
    - value: "OK"
      widget: "green_circle"
      description: "OK"

    - value: "KO"
      widget: "red_circle"    


data_enumerate:enum_OK_KO_NA:
  # ACTION
  is_enabled: True
  displayname: "OK/KO/NA Scale"
  content: |
    - value: "OK"
      widget: "green_circle"
      description: "OK"

    - value: "KO"
      widget: "red_circle"

    - value: "n/a"
      widget: "white_circle"

    - value: "?"

8 - Sirene - Models

Reference

Sirene Model

severity (built-in)


     "na"       # white
     "critical" # black
     "major"    # red
     "minor"    # yellow
     "info"     # blue
     "other"    # grey
     "ok"       # green

Categories

_sirene_category:incident:
  longname: Incident
  description: Incidents (outage)
  is_enabled: true

_sirene_category:maintenance:
  longname: Maintenance
  description: n/a
  is_enabled: true

Template

_sirene:test_template:
      title: Incident
      severity: ok
      category: info
      description: My description
      publicpage: public_ok
      has_privatepage: true
      body: |
        <p>Hello</p>
        <p>Incident on <b>test apps</b>.</p>
        <p>IT Team</p>        
      has_email: false
      has_sms: false
      notify_group: demo
      notify_site: site01, site02
      notify_sitegroup: region01
      notify_app: testapp, testapp2
      notify_customer: Acme_Corp

_sirene:maintenance:
    title: "IT Maintenance"
    severity: info
    category: maintenance
    publicpage: public_maintenance
    has_privatepage: true
    has_email: true
    has_sms: false    
    message: |
      <pre>
      Hi
      A maintenance is starting.
      Please check <a href="http://wwwW.cavaliba.com">Cavaliba</a> for updates.
      IT Team
      </pre>      
    has_email: true
    has_sms: false
    description: "Unspecified Maintenance"
    notify_group: 
      - usergroup_01
      - usergroup_03

Public Pages


_sirene_public:
  - name: public_ok
    is_default: yes
    is_enabled: true
    severity: ok
    title: "Nothing"
    message: |
      <p>No public notification.</p>
      <p>Please connect to access private messages.</p>
      <p>IT Team</p>      


  - name: public_major
    severity: major
    description: "Major outage ongoing"
    title: Major incident
    message: |
      <p>IT Services are unavailable.</p>
      <p>Please connect to access details.</p>
      <p>IT Team</p>