Metadata

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

JSON Schema provides autocompletion for IDEs. It works in PhpStorm and VSCode with no setup required.

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
• logicDefs – dynamic logic 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
  • clientIcons
  • clientRecord
  • 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 or string.

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

will return the string value "varchar".

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

will return an associative array with definitions of all fields.

Path defined as string:

<?php
$metadata->get("entityDefs.Account.fields");

Frontend

Metadata object (module ID: metadata) is accessible from all view objects by method #getMetadata. It's also available via DI. It works the same way as the backend's one.

const fields = this.getMetadata().get(`entityDefs.Account.fields`);

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

The primary method of customization in EspoCRM is defining custom metadata. A developer creates custom JSON files in the custom directory. These files then merged with core metadata. Since metadata is merged recursively, you can extend JSON objects and arrays.

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

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

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