Skip to content
OTOBO Community Guide

CI modeling with YAML in the OTOBO ticket system

This chapter shows how you can define and extend your Configuration Items (CIs) in the OTOBO ticket system using YAML – from page and layout structure to dynamic fields and field types.

1. Structure of CI definitions

Section titled “1. Structure of CI definitions”

Every CI definition in OTOBO consists of several main components:

- Class:
    Name: <CI-Class>
    Categories:
      - All
      - <Additional Categories>
    NumberModule: AutoIncrement
    PermissionGroup: itsm-configitem
    VersionStringModule: Incremental
  Definition: |
    Pages:
      - Name: Summary
        Layout:
          Columns: 3
          ColumnWidth: 1fr 1fr 1fr
        Interfaces:
          - Agent
          - Customer
        Content:
          - Section: General Fields::General Information
            RowStart: 1
            ColumnStart: 1
          - Section: ITSM Model::Model
            RowStart: 1
            ColumnStart: 2
          - Section: CMDB Description::Description
            RowStart: 2
            ColumnStart: 1
            ColumnSpan: 2
  DynamicFields: { … }

1.1 Pages

Section titled “1.1 Pages”
  • Name: Label of the tab in the Agent Zoom.
  • Interfaces: Control who sees the tab (Agent, Customer, …).
  • Content: List of sections, with position (RowStart, ColumnStart, optionally Span).

1.2 Layout

Section titled “1.2 Layout”
  • Columns: Number of columns in the tab.
  • ColumnWidth: Proportional width specifications (e.g., 1fr 2fr 1fr).

1.3 Roles

Section titled “1.3 Roles”

Roles define reusable sections and field lists:

- Definition: |
    Sections:
      General Information:
        Content:
          - Header: General Information
          - DF: System-Name
          - DF: System-Version
      Relations:
        Type: ConfigItemLinks
        Header: Relations
  RoleName: CMDB General Fields
  • RoleName: Unique name of the role.
  • Sections: Contains one or more sections with field references (DF:).

2. DynamicFields and field types

Section titled “2. DynamicFields and field types”

With DynamicFields, you can extend your CI classes with individual attributes. Each field receives a name, type, and configuration:

DynamicFields:
  DynamicFieldName:
    FieldType: Text
    Label: My Label
    Name: System-Name
    ObjectType: ITSMConfigItem
    Config:
      DefaultValue: 'demo'
      MultiValue: '0'
      PossibleNone: '1'
      Tooltip: ''


  System-LifecycleStatus:
    FieldType: Dropdown
    Label: Lifecycle status of system
    Name: System-LifecycleStatus
    ObjectType: ITSMConfigItem
    Config:
      DefaultValue: ''
      MultiValue: '0'
      PossibleNone: '1'
      PossibleValues:
        demo: demo
        productive: productive
      Tooltip: ''

2.1 Important field types

Section titled “2.1 Important field types”
FieldTypeDescription
TextSimple single-line field
TextAreaMulti-line free text field
DateDate field (with restrictions via YearsInPast/...)
DropdownSelection field (Single/Multi via MultiValue)
AgentLDAP user/agent lookup
ConfigItemLink to another CI (relation type definable)
ScriptTemplateToolkitCalculated field via template (e.g., sums)

2.2 Configuration options

Section titled “2.2 Configuration options”
  • DefaultValue: Default value when creating a new item.
  • MultiValue: '0' (single selection) or '1' (multiple).
  • PossibleNone: '1' to allow an empty selection.
  • PossibleValues: Key-value pairs for dropdown fields.
  • EditFieldMode: e.g., Dropdown, AutoComplete.
  • ReferenceFilterList, ReferencedObjectType: For lookup fields.

3. Example

Section titled “3. Example”
- Class:
    Name: CIName
    Categories:
      - All
      - IT
    NumberModule: AutoIncrement
    PermissionGroup: itsm-configitem
    VersionStringModule: Incremental
  Definition: |
    Pages:
      - Name: Intro
        Layout:
          Columns: 2
          ColumnWidth: 1fr 1fr
        Interfaces:
          - Agent
        Content:
          - Section: CMDB General Fields::Information
            RowStart: 1
            ColumnStart: 1
          - Section: CMDB General Fields::Risks
            RowStart: 2
            ColumnStart: 1
      - Name: Details
        Layout:
          Columns: 1
          ColumnWidth: 1fr
        Interfaces:
          - Agent
        Content:
          - Section: CMDB General Fields::Software
            RowStart: 1
            ColumnStart: 1
  DynamicFields:
    System-Name: { … }
    System-Version: { … }
    System-LifecycleStatus: { … }

4. Tips and best practices

Section titled “4. Tips and best practices”
  • Modularity: Use roles for recurring sections.
  • Clarity: Group related fields into their own pages.
  • Documentation: Comment your YAML files and maintain version triggers.
  • Testing: Validate new fields in a test instance first.

With this structure, you can flexibly adapt the OTOBO CMDB to your organizational requirements and keep it transparent at all times.

Frequently asked questions

How do you structure a Configuration Item (CI) definition in OTOBO using YAML?

A Configuration Item (CI) definition in OTOBO is structured using YAML, comprising several main components that collectively define the CI's behavior and appearance. At the top level, you define the Class with properties like Name, Categories (e.g., All, IT), NumberModule (e.g., AutoIncrement), PermissionGroup (e.g., itsm-configitem), and VersionStringModule (e.g., Incremental). Below this, the Definition section outlines the UI structure, primarily through Pages. Each page specifies its Name, Layout (columns, width), Interfaces (who sees it, e.g., Agent, Customer), and Content (sections with their positions). Finally, the DynamicFields section allows for the extension of CI classes with custom attributes, each having a FieldType, Label, Name, ObjectType, and a Config block for detailed settings. This modular approach ensures comprehensive control over CI modeling.

Quellen / Sources:

What are "Pages" and "Layout" in OTOBO CI YAML, and how do they control the user interface?

In OTOBO CI YAML, "Pages" and "Layout" are crucial for defining the user interface and presentation of Configuration Items in the Agent Zoom. Each Page corresponds to a distinct tab within the CI's detail view and is identified by its Name. You can specify which user groups or interfaces see a particular page using the Interfaces property, typically including Agent or Customer. The Content of a page is a list of Section references, each positioned using RowStart, ColumnStart, and optionally ColumnSpan to arrange elements on the grid. The Layout block within a page defines the visual arrangement of these sections, including the Columns property for the total number of columns and ColumnWidth for their proportional sizing (e.g., 1fr 1fr 1fr for three equally wide columns). This allows for a highly customizable and organized display of CI information, tailoring the UI to specific user needs.

Quellen / Sources:

How are DynamicFields defined and configured within an OTOBO CI YAML definition to extend CI classes?

DynamicFields are essential for extending OTOBO CI classes with individual, custom attributes beyond the default set, allowing for highly specific data capture. Within the DynamicFields section of your YAML definition, each field is defined by a unique DynamicFieldName. Key properties include FieldType (e.g., Text, Dropdown), Label (the display name in the UI), Name (the internal system name), and ObjectType (typically ITSMConfigItem). A crucial Config block allows for fine-tuning the field's behavior. Here, you can set a DefaultValue, control MultiValue selection ('0' for single, '1' for multiple), enable PossibleNone to allow an empty selection, define PossibleValues as key-value pairs for dropdowns, and specify Tooltip text for user guidance. Other options like EditFieldMode, ReferenceFilterList, and ReferencedObjectType provide further customization for lookup fields. This granular configuration ensures that CI forms precisely match your asset and CMDB requirements.

Quellen / Sources:

What are some key `FieldType` options available for DynamicFields in OTOBO CI YAML, and what are their uses?

OTOBO CI YAML offers a variety of FieldType options for DynamicFields, each designed for specific data input and display needs, enabling comprehensive CI attribute management. Some important types include:

  • Text: A simple single-line input field suitable for short textual data like names or identifiers.
  • TextArea: A multi-line field for longer free-form text, ideal for descriptions or notes.
  • Date: For capturing date values, often with configuration options to restrict the range (e.g., YearsInPast).
  • Dropdown: Provides a selection list, highly configurable for single or multiple choices via MultiValue and with PossibleValues defined as key-value pairs.
  • Agent: Facilitates a lookup for OTOBO agents or LDAP users, useful for assigning responsibilities.
  • ConfigItem: Creates a link to another Configuration Item, allowing for the definition of relation types between CIs.
  • ScriptTemplateToolkit: A powerful type for calculated fields, enabling complex logic like sums, conditional displays, or dynamic content generation using templates.
    These types, combined with their extensive configuration options, allow for highly tailored CI data capture and presentation.

Quellen / Sources:

How do "Roles" contribute to modularity and reusability in OTOBO CI YAML definitions?

"Roles" in OTOBO CI YAML are a powerful mechanism to introduce modularity and promote the reusability of sections and field lists across different CI definitions. Instead of duplicating common sets of fields or UI sections, you can define them once within a RoleName block. A role typically contains Sections, each with a Header and a Content list that references specific DynamicFields using DF: <DynamicFieldName>. For instance, a CMDB General Fields role might define sections for "General Information" and "Relations," which can then be easily included in multiple CI page definitions by referencing Section: <RoleName>::<SectionName>. This approach significantly reduces redundancy in your YAML files, simplifies maintenance, and ensures consistency in how information is presented and captured across various Configuration Item types within your CMDB. It makes CI definitions cleaner, more manageable, and easier to update.

Quellen / Sources:

What are the recommended best practices for managing and maintaining CI YAML definitions in OTOBO?

For effective management and maintenance of CI YAML definitions in OTOBO, several best practices are recommended to ensure a robust and transparent CMDB. Firstly, embrace Modularity by utilizing roles for recurring sections and field groups. This approach significantly reduces redundancy, improves consistency across different CI types, and simplifies updates. Secondly, prioritize Clarity by grouping related fields logically into their own pages, making the CI interface intuitive and easy to navigate for agents and customers. Thirdly, ensure thorough Documentation by adding comments directly to your YAML files and maintaining version triggers. This aids in understanding the purpose of configurations, tracking changes, and providing historical context for future modifications. Lastly, always practice rigorous Testing by validating any new fields or structural changes in a dedicated test instance before deploying them to your production environment. These practices collectively ensure a flexible, transparent, and robust OTOBO CMDB that can adapt to evolving organizational requirements.

Quellen / Sources: