bin/espocrm-tags-select-only-claude-code.md

Task: Disable the inline "Create" button on the Tags relationship panels in EspoCRM

Goal

This EspoCRM instance has a custom many-to-many relationship to a custom Tag entity. It is exposed as a "Tags" bottom relationship panel on three entity types: Opportunity, Contact, and Account. On each of these three entities the link is named cTags.

Right now the Tags panel offers a Create (+) button plus a three-dots (⋯) menu that contains the actions View list and Select. We want to remove only the inline Create (+) button on these Tags panels, so that users can attach existing Tag records only (a controlled tag vocabulary), using the ⋯ → Select action. Creating new tags must still be possible, but only via the Tag entity's own list view — never inline from a record's Tags panel. This must apply to all users, including regular (non-admin) users.

Do not change anything else (no other panels, fields, ACLs, or entities).

Environment

• EspoCRM runs as a rootless Podman pod named espocrm_pod on this server. The web container is expected to be espocrm_ctr (confirm with podman ps).
• EspoCRM application root inside the web container: /var/www/html. The app runs as user www-data.
• Customizations live under /var/www/html/custom/Espo/Custom/Resources/metadata/ and survive upgrades. This path must be on the persisted volume/bind-mount so the change is not lost when the container is recreated.

Mechanism

EspoCRM reads relationship-panel options from clientDefs.<EntityType>.relationshipPanels.<linkName>. Setting "create": false for a panel hides its Create (+) button while keeping the ⋯ menu actions (View list / Select). EspoCRM deep-merges metadata, so we add only this single key per entity and do not redefine the whole panel.

Confidence note on the key name: it is almost certainly create. Before relying on it, verify against this version's frontend source, e.g.:

grep -rn "'create'\|\"create\"\|create:" /var/www/html/client/src/views/record/panels/relationship.js
grep -rn "relationshipPanels" /var/www/html/client/src/views/record/

Look at how the relationship panel decides whether to show the create action. If this version uses a different key (e.g. createDisabled), use the verified key instead and adjust the JSON below accordingly.

Steps

1. Confirm container and link name.

   • podman ps → identify the web container (expected espocrm_ctr).
   • Confirm each of Opportunity, Contact, Account has a many-to-many link named cTags pointing to entity Tag, e.g.:

     podman exec espocrm_ctr sh -lc "grep -rn 'cTags' /var/www/html/custom/Espo/Custom/Resources/metadata/entityDefs/"
     

2. Add the override for each of the three entities. For Opportunity, Contact, and Account, ensure the file /var/www/html/custom/Espo/Custom/Resources/metadata/clientDefs/<EntityType>.json contains this key:

   {
       "relationshipPanels": {
           "cTags": {
               "create": false
           }
       }
   }
   

   • Target files:
     • /var/www/html/custom/Espo/Custom/Resources/metadata/clientDefs/Opportunity.json
     • /var/www/html/custom/Espo/Custom/Resources/metadata/clientDefs/Contact.json
     • /var/www/html/custom/Espo/Custom/Resources/metadata/clientDefs/Account.json
   • If a file already exists, MERGE this key into the existing JSON (preserve all other keys; if relationshipPanels already exists, add cTags to it). Do not overwrite.
   • If a file or the directory does not exist, create it. Produce valid JSON.

3. Fix ownership so the web user owns the new/changed files (run as root inside the container):

   podman exec espocrm_ctr chown -R www-data:www-data /var/www/html/custom/Espo/Custom/Resources/metadata/clientDefs
   

4. Clear cache and rebuild (run as the web user):

   podman exec -u www-data espocrm_ctr php command.php rebuild
   

   If command.php is not present in this version, use:

   podman exec -u www-data espocrm_ctr bin/command rebuild
   

   (Alternatively, an admin can run Administration → Rebuild in the web UI.)

5. Verify in the browser (ideally as a regular non-admin user, and also as admin):

   • Open an Opportunity, a Contact, and an Account record. The Tags panel must now have no Create (+) button. The three-dots (⋯) menu must still offer View list and Select, so existing tags can still be attached via ⋯ → Select.
   • The Tag entity's own list view must still have its Create button (deliberate tag creation still works there).
   • Attaching an existing tag via ⋯ → Select must still work.

Rollback

Remove the added relationshipPanels.cTags key from the three clientDefs files (or delete the files if they contained only this key), then rebuild again.