Skip to content

About

DOM (department structure) and BOM (bill of materials) entity types for EspoCRM with interactive, zoomable charts, material totals and XLSX/CSV export. English and Ukrainian included.

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

3 Commits

Folders and files

Repository files navigation

FrameVAS - BOM & DOM for EspoCRM

EspoCRM 9.0+ PHP 8.3+ Languages

English | Українська

BOM & DOM adds two entity types to the EspoCRM Entity Manager: DOM for a department structure and BOM for a bill of materials. Records of these entities are shown as interactive charts you can zoom, move around and expand: an org chart with departments, heads and workers, or a multi-level bill of materials with quantities, units and rolled-up material totals.

Features

  • Two entity types – DOM (Department Structure) and BOM (Bill of Materials) in Entity Manager → Create Entity, next to Base, Person and Company.
  • Chart view mode – a Chart button next to List (and Kanban) in the list view, and a chart panel on every record.
  • Navigation – zoom with the mouse wheel, pinch or the + / − buttons, move by dragging, fit to screen, center on the top item, expand or collapse everything, search, fullscreen.
  • Layouts – top-to-bottom or left-to-right, standard or compact; defaults are set per entity.
  • Large structures – a few levels load at a time; expanding a branch loads the next ones.
  • Card fields – choose extra fields for the cards in a Chart Card layout, just like the List and Detail layouts.
  • DOM: workers and heads – department cards show the head and the workers, as cards, avatars or a count.
  • BOM: quantities and units – quantity per parent and total quantity on every card; units from the built-in list, a text field or another entity (for example, from a units-of-measure extension).
  • Material totals – rolled-up quantities of everything needed to build an item, for any quantity, with configurable columns and XLSX/CSV export through EspoCRM's standard export.
  • Quick view and editing – click a card to open the record; changes appear on the chart as soon as you save.
  • Loop protection – a unit can't be placed under itself, and an item can't contain itself.
  • Image export – save the chart as PNG or SVG.
  • Themes – follows light and dark themes, including theme switchers.
  • Translations – English and Ukrainian included, editable in the Label Manager.

Requirements

  • EspoCRM 9.0 or newer (tested on EspoCRM 9.0 and 10.0)
  • PHP 8.3 or newer

Installation

  1. Download the latest extension package (.zip) from the Releases page.
  2. In EspoCRM, go to Administration → Extensions.
  3. Click Upload, choose the downloaded file and click Install.
  4. Go to Administration → Clear Cache.
  5. Reload the page in your browser.

Updating

Install a newer package over the installed one. Your settings are kept.

Quick start

Department structure (DOM)

  1. Create the entity. Go to Administration → Entity Manager → Create Entity, choose the type DOM (Department Structure), enter a name and labels, and save. EspoCRM adds the C prefix to custom entity names, so Department becomes CDepartment.
  2. Add records. Create the top unit (for example, your company), then departments and units, and set each one's Parent.
  3. Add workers (optional). In Entity Manager → your entity → Relationships, create a One-to-Many or Many-to-Many relationship to the people who work in the departments (Users, Employees, Contacts…). For department heads, create a Many-to-One relationship.
  4. Connect them. In Administration → Chart Settings, choose the Workers relationship, the Head relationship and how workers are shown.
  5. Open the chart. Open the entity's list and click the Chart button next to the List button, or open a record and use its Structure panel.

Bill of materials (BOM)

  1. Create the entity. Go to Administration → Entity Manager → Create Entity, choose the type BOM (Bill of Materials) and save.
  2. Add items. Create products, assemblies, components and raw materials.
  3. Add components. Edit an item and add its parts in the Components field, with the quantity needed for one unit.
  4. Open the chart. Open an item and use its Bill of Materials panel, or open the list and click Chart.

Entity types

Both types are created with all standard fields (Name, Description, Assigned User, Teams, Created/Modified), plus:

Type Field Description
DOM Code Short code of the unit, shown under the name.
DOM Parent / Sub-units The structure. A unit can't be placed under itself or one of its own sub-units.
DOM Order Position among siblings on the chart; lower numbers come first.
BOM Part Number Article or SKU, shown under the name.
BOM Item Type Product, Assembly, Component or Raw Material; colors the card.
BOM Unit Built-in list of units (pcs, kg, m, l…); options can be edited in the Entity Manager.
BOM Image Picture shown on the card.
BOM Components Parts of the item, each with a quantity. An item can't contain itself.
BOM Used In The items that use this one (relationship panel).

The BOM list view also gets the filters Top-level products, Assemblies and Raw materials.

Chart toolbar

Button Action
− / + Zoom out / zoom in
Fit to screen Shows the whole visible chart
Center view Moves back to the top item at 100% zoom
Expand all / Collapse all Opens or closes every loaded branch
Load all levels BOM: loads every level at once, up to the Max cards per load limit
Left to right / Top to bottom Switches the chart direction
Compact layout Packs the last level of cards into columns
Find on chart Highlights matching cards; press Enter for the next match
Material totals BOM record panel: opens the rolled-up material list
Export Saves the chart as PNG or SVG
Fullscreen Shows the chart on the whole screen; record windows still open on top

Click a card to open the record in a quick view window. After you edit and save it there, the chart updates in place and keeps your zoom, position and open branches.

Chart Settings

Go to Administration → Chart Settings on the bottom. Each DOM and BOM entity has its own panel.

Option Type Description
Card subtitle field DOM, BOM Field shown under the name on each card.
Card fields DOM, BOM Opens the Chart Card layout (see below).
Levels open by default DOM, BOM How many levels are open when the chart loads.
Chart direction DOM, BOM Top to bottom (default) or Left to right.
Compact layout DOM, BOM Whether the chart opens in the compact layout.
Workers relationship DOM Relationship from a department to the people working in it.
Worker title field / Worker photo field DOM What worker cards show. For Users, the profile photo is used automatically.
Show workers as DOM Cards under the department, Avatars inside the department card or Count only.
Workers per load DOM How many workers load at a time; more load on demand.
Head relationship / Head title field DOM The person who leads the department, shown on its card.
Card image field BOM Image field shown on the card.
Max cards per load BOM Limit for one load; larger structures load further on expand.
Unit field / Unit display field BOM Where units come from (see Units).
Material totals columns BOM Extra columns of the Material totals window and its export.

Users can still change the direction and the compact layout with the toolbar buttons.

Card fields

Each DOM and BOM entity has a Chart Card layout in Entity Manager → your entity → Layouts. Move fields to Enabled and put them in order; they appear on the cards as Label: value lines (up to 10). Dates and numbers follow each user's format settings. Multiple-link, attachment, image, file and address fields are not shown on cards.

Workers in the record window

To see and edit a department's workers in its quick view window, as with BOM components:

  1. In Entity Manager → your DOM entity → Relationships, edit the workers relationship and tick Link Multiple Field.
  2. Add the new field to the Detail (Small) layout.

Each worker belongs to one department in a one-to-many relationship, so adding a worker here moves them from their previous department.

Material totals

On a BOM item's chart panel, Material totals lists everything needed to build the item: each component's total quantity across all levels, for any quantity you enter. Switch between Raw materials (items without components) and All items.

  • Item, Total quantity, Unit and Levels are always shown. Choose extra columns and their order in Chart Settings → Material totals columns (default: Part Number).
  • Export XLSX and Export CSV use EspoCRM's standard export: translated headers, number formats, a title row, and item names linked to their records. Levels is shown in the window only.
  • Exporting needs the Export permission in the user's role, like any other export.

Units

By default, units come from the built-in Unit list. To use units from another entity – for example, one added by a units-of-measure extension:

  1. Create a Many-to-One relationship from your BOM entity to the units entity.
  2. In Chart Settings, choose that relationship as the Unit field.
  3. Optionally choose a Unit display field, such as the unit's symbol (kg), instead of its name (Kilogram).

The chosen unit is used on the cards, in Material totals and in the export.

Permissions

  • Charts show only the records the user can read; fields hidden by roles stay hidden on cards and in totals.
  • Editing works through the standard record windows, with the user's normal permissions.
  • Chart Settings are available to administrators only.

API

Method Endpoint Description
GET /api/v1/BomDomChart/{entityType}/tree Chart data. Parameters: rootId, rootIds, levels.
GET /api/v1/BomDomChart/{entityType}/expand Next levels or the next page of workers for a branch.
GET /api/v1/BomDomChart/{entityType}/totals Material totals. Parameters: rootId, quantity.
POST /api/v1/BomDomChart/{entityType}/totals/export Material totals file. Body: rootId, quantity, onlyLeaves, format (xlsx or csv). Returns an attachment ID.
PUT /api/v1/BomDomChart/{entityType}/settings Chart settings (administrators only).

Uninstalling

DOM and BOM entities depend on the extension, so remove them first in Administration → Entity Manager; the uninstaller refuses to run while they exist. Then go to Administration → Extensions, find FrameVAS - BOM & DOM and click Uninstall.

Translations

English and Ukrainian are included, and every text can be changed in Administration → Label Manager: the BomDomChart scope holds the chart, settings and message texts, and each DOM or BOM entity holds its field and option labels.

To add a language, copy files/custom/Espo/Modules/BomDomCharts/Resources/i18n/en_US and files/custom/Espo/Modules/BomDomCharts/Core/Templates/i18n/en_US to folders with the EspoCRM language code (e.g. de_DE), translate the values (keep keys and placeholders like {user} unchanged) and clear the cache.

Third-party libraries

The charts use d3 7.9.0 (ISC), d3-flextree 2.1.2 (WTFPL) and d3-org-chart 3.1.1 (MIT). Their licenses are in files/client/custom/modules/bom-dom-charts/lib/LICENSES.txt.

About

DOM (department structure) and BOM (bill of materials) entity types for EspoCRM with interactive, zoomable charts, material totals and XLSX/CSV export. English and Ukrainian included.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages