OTOBO Skins & Themes – Customize Agent Interface Design

In this guide: Change the OTOBO agent interface appearance with custom skins and CSS.

Related: Customer portal branding · OTOBO GUI overview · System configuration

It is possible to change the appearance of the OTOBO ticket system by creating a new skin.

Changing the OTOBO skin - theme setting

Every Agent can choose which skin they want to use. After the OTOBO installation, only the default skin is available. The OTOBO skin defines the design of the interface. In their personal settings, users can find the option to replace their current skin with another one.

Creating a new skin

Changing CSS

If you have a Docker OTOBO installation, the agent skins are located here:

/var/lib/docker/volumes/otobo_opt_otobo/_data/var/httpd/htdocs/skins/Agent/

For a non-Docker installation, the path is:

$OTOBO_HOME/var/httpd/htdocs/skins/Agent/$SKIN_NAME/

New folder

If no skin has been added yet, you will only find the “default” folder in this path. To add a new skin, you must first add a new folder. For example, “my_skin”.

Changing the design

To change the design, you can create a “css” folder inside the “my_skin” folder. Skins work by always loading the standard CSS skin. In your own skin, you can then override the values from the standard skin. For example, by overriding CSS classes from the default skin:

CSS from the standard skin: Skin/default/Core.css

.Navigation {
  height: 100px;
}

You could, for example, override it with: /* Skin/my_skin/Core.css

.Navigation {
  height: 30px;
}

Afterwards, you need to create a configuration file in the folder $OTOBO-HOME/Kernel/Config/Files/XML/{skinName}.xml. This should have the following structure:

<?xml version="1.0" encoding="utf-8" ?>
<otobo_config version="2.0" init="Changes">
    <ConfigItem Name="AgentLogo" Required="0" Valid="1">
        <Description Translatable="0">The logo shown in the header of the agent interface. The URL to the image must be
            a relative URL to the skin image directory.
        </Description>
        <Group>Framework</Group>
        <SubGroup>Frontend::Agent</SubGroup>
        <Setting>
            <Hash>
                <Item Key="URL">
                    https://softoft.de/Otobo_Wortmarke_Sub_Digital_Blau_156hoch-zugeschnitten-300x113.png
                </Item>
                <Item Key="StyleTop">13px</Item>
                <Item Key="StyleRight">75px</Item>
                <Item Key="StyleHeight">67px</Item>
                <Item Key="StyleWidth">244px</Item>
            </Hash>
        </Setting>
    </ConfigItem>

    <ConfigItem Name="Loader::Agent::Skin###001-softoftSkin" Required="0" Valid="1">
        <Description Translatable="0"></Description>
        <Group>Framework</Group>
        <SubGroup>Frontend::Agent</SubGroup>
        <Setting>
            <Hash>
                <Item Key="InternalName">softoftSkin</Item>
                <Item Key="VisibleName">softoftSkin</Item>
                <Item Key="Description"></Item>
                <Item Key="HomePage"></Item>
            </Hash>
        </Setting>
    </ConfigItem>
</otobo_config>

Available skins / themes

There are already skins created by other companies.

OTOBO Dark Skin / Theme

Link to the skin / theme: Github Dark Skin

Modern Skin / Theme by Efflux

Github link to the skin / theme: Efflux Modern Skin

FAQ: OTOBO Skins & Themes

Where are OTOBO agent skins stored?

In a Docker install under /var/lib/docker/volumes/otobo_opt_otobo/_data/var/httpd/htdocs/skins/Agent/, otherwise under $OTOBO_HOME/var/httpd/htdocs/skins/Agent/$SKIN_NAME/.

How do I create a custom OTOBO skin?

Add a new folder (e.g. my_skin) next to default, create a css folder inside it, and override the CSS classes you want to change. Register the skin via an XML config file under $OTOBO_HOME/Kernel/Config/Files/XML/{skinName}.xml.

Will my custom skin survive an OTOBO update?

To make changes persistent, package your skin files into an OPM package rather than editing the live filesystem directly. This way the skin is reinstalled cleanly after updates.

Can each agent choose their own skin?

Yes. Every agent can select an available skin in their personal preferences. Newly installed skins appear there once registered via SysConfig.

Is there a dark theme for OTOBO?

Yes — see the community OTOBO Dark Skin and the Efflux Modern Skin listed above.

Frequently asked questions

How do agents change their OTOBO skin or theme?

Agents can change their OTOBO skin through their personal settings within the agent interface. After the initial OTOBO installation, only the default skin is available. However, once additional skins are created and properly registered, they become selectable options. The chosen skin dictates the overall visual design of the agent interface, including colors, fonts, and layout elements, allowing for a personalized user experience. This feature empowers individual agents to select a theme that best suits their visual preferences or workflow needs.

Quellen / Sources:

• OTOBO Skins & Themes – Customize Agent Interface Design
• Skins — OTOBO Developer Guide 11.0 documentation

What are the key steps to create a custom OTOBO agent skin?

Creating a custom OTOBO agent skin involves several steps to define its appearance and make it available in the system. First, you need to establish the skin's folder structure. For a non-Docker installation, this means creating a new folder (e.g., my_skin) within $OTOBO_HOME/var/httpd/htdocs/skins/Agent/. Inside this new folder, create a css directory. Customization is achieved by overriding default CSS classes; for example, you can modify .Navigation properties by defining them in your skin's Core.css file. Finally, the new skin must be registered by creating an XML configuration file, such as {skinName}.xml, in $OTOBO-HOME/Kernel/Config/Files/XML/. This XML file contains essential metadata like InternalName and VisibleName, making the skin selectable in the agent interface.

Quellen / Sources:

• OTOBO Skins & Themes – Customize Agent Interface Design
• Skins — OTOBO Developer Guide 11.0 documentation

Does OTOBO offer a dark theme, and where can I find community-contributed skins?

Yes, OTOBO users can benefit from community-contributed dark themes and other modern skins to customize their agent interface. A popular option is the OTOBO Dark Skin, which provides a visually distinct, darker aesthetic for the dashboard and other interface elements. This skin, along with others like the Modern Skin by Efflux, can typically be found on platforms like GitHub. These skins are often distributed as OPM packages, allowing for easy installation via the OTOBO Package Manager. They offer a great way to enhance the user experience beyond the default OTOBO theme, catering to different visual preferences or reducing eye strain in low-light environments.

Quellen / Sources:

• OTOBO Skins & Themes – Customize Agent Interface Design
• relkai/otobo-dark-skin - GitHub
• Efflux Modern Skin - GitHub

How can I ensure my custom OTOBO skin persists through system updates?

To ensure that your custom OTOBO skin remains intact and functional after system updates, it is highly recommended to package your skin files into an OPM (OTOBO Package Manager) package. Directly modifying the live filesystem for skin elements can lead to your changes being overwritten or lost during an OTOBO upgrade. By creating an OPM package, your skin becomes a properly managed extension of OTOBO. This allows for a clean reinstallation of the skin after updates, ensuring its continued availability and functionality without manual intervention. The OPM system is designed to handle such customizations robustly, making it the best practice for deploying custom skins.

Quellen / Sources:

• OTOBO Skins & Themes – Customize Agent Interface Design
• Skins — OTOBO Developer Guide 11.0 documentation
• relkai/otobo-dark-skin - GitHub

Where are OTOBO agent skin files located on the server?

The location of OTOBO agent skin files varies depending on your installation type. For Docker-based OTOBO installations, you will typically find the agent skins at the following path: /var/lib/docker/volumes/otobo_opt_otobo/_data/var/httpd/htdocs/skins/Agent/. If you have a non-Docker OTOBO installation, the skins are located relative to your OTOBO home directory, specifically at $OTOBO_HOME/var/httpd/htdocs/skins/Agent/$SKIN_NAME/. Within these directories, each custom skin will have its own folder (e.g., default, my_skin), containing the CSS and other assets that define its visual appearance. Understanding these paths is crucial for both creating new skins and troubleshooting existing ones.

Quellen / Sources:

• OTOBO Skins & Themes – Customize Agent Interface Design
• Skins — OTOBO Developer Guide 11.0 documentation