Metadata

Metadata is intended for storing application data such as fields, relationships, front-end controllers, views, panels, dashlets etc.

JSON Schema is available here. It provides autocompletion for IDEs (works by default in PhpStorm and VSCode).

In this article:

• Reference
• Accessing
• How it's stored
• Extending

Reference

• scopes – general parameters for scopes and entity types
• entityDefs – entity defs (fields, links, indexes)
• aclDefs – access control for scopes and entity types
• selectDefs – Select-framework defs for entity types
• recordDefs – CRUD-specific defs for entity types
• clientDefs – front-end defs for entity types
• entityAcl – access restriction for specific fields and links for entity types
• pdfDefs – PDF generation defs for entity types
• notificationDefs – notification defs for entity types
• streamDefs – stream defs for entity types
• fields – field types
• dashlets
• authenticationMethods – authentication methods
• integrations
• app – application definitions
  • acl – access control
  • aclPortal – access control for portals
  • actions – Action framework
  • addressFormats
  • adminPanel – Administration panel
  • api
  • appParams – AppParams framework
  • authentication
  • authentication2FAMethods – 2-factor authentication methods
  • cleanup
  • client – front-end client
  • clientNavbar – front-end navbar
  • clientRoutes – front-end routes
  • complexExpression
  • config
  • consoleCommands
  • containerServices
  • currency
  • currencyConversion
  • databasePlatforms
  • dateTime
  • defaultDashboardLayouts
  • defaultDashboardOptions
  • emailTemplate
  • entityManager
  • entityManagerParams
  • entityTemplateList
  • entityTemplates
  • export
  • fieldProcessing
  • file
  • fileStorage
  • formula
  • hook – Hook framework
  • image
  • jsLibs – JS libs
  • language
  • layouts
  • linkManager
  • mapProviders
  • massActions
  • metadata
  • orm
  • pdfEngines
  • popupNotifications
  • portalContainerServices
  • reactions
  • rebuild
  • record
  • recordId
  • regExpPatterns
  • relationships
  • scheduledJobs
  • select
  • smsProviders
  • templateHelpers
  • templates
  • webSocket

Accessing

Backend

The Metadata instance (of Espo\Core\Utils\Metadata class) is available as a container service.

Path to a needed parameter is specified with an array.

<?php
// entityDefs > Account > fields > type
$value = $metadata->get(['entityDefs', 'Account', 'fields', 'name', 'type']);

will return the string value "varchar".

<?php
$metadata->get(['entityDefs', 'Account', 'fields']);

will return an associative array with definitions of all fields.

Frontend

Metadata object is accessible from all view objects by method #getMetadata. It works the same way as the backend's one.

this.getMetadata().get(['entityDefs', 'Account', 'fields', 'name', 'type']);

How it's stored

Metadata is stored in JSON files that can be located in different places:

• application/Espo/Resources/metadata – core;
• application/Espo/Modules/{ModuleName}/Resources/metadata – internal modules;
• custom/Espo/Modules/{ModuleName}/Resources/metadata – custom modules;
• custom/Espo/Custom/Resources/metadata – instance specific customizations, customizations made via the admin UI are stored here.

When you access data by a path clientDefs.Account.views.edit the first lexeme clientDefs corresponds to a dir name, the second Account – to a file name Account.json. All the following lexemes correspond to a path in the JSON object.

{
    "views": {
        "edit": "crm:views/account/views/edit" 
    }
}

All JSON files from these directories get merged recursively into a single file and stored in an application cache.

Extending

Since metadata is merged recursively, you can easily redefine JSON objects and arrays in the custom directory.

You can append values to existing arrays by using the __APPEND__ string as the first element of an array. This will preserve array values rather than override them.

custom/Espo/Custom/Resources/metadata/entityDefs/Account.json:

{
    "fields": {
        "employeeCount": {
          "type": "int"
        },
        "type": {
            "options": [
                "__APPEND__",
                "Dealer",
                "Lawyer"
            ]
        }
    }
}