Actions#
CRM actions appear in the CRM category. User and contact fields accept a token name, a bracketed token, or a numeric ID.
Most actions write a result token. You can override the name; defaults are listed below. Successful actions that have a contact also set the canonical CRM tokens. See Tokens and Access.
Missing required entities, failed mapping, and relationship constraint
violations throw \InvalidArgumentException. That stops the ECA
execution and can surface as an error for webhook-style models.
Resolving users and contacts#
Configuration fields such as User and Contact may be:
- A token name (
crm_contact) - A bracketed token (
[crm_contact]) - A numeric entity ID
Mapping#
CRM: load mapped contact#
Plugin ID: eca_crm_load_mapped_contact
Loads the contact mapped to a user. If there is no mapping, the action succeeds and does not set the result token.
| Field | Description |
|---|---|
| User | User entity token or user ID |
| Name of token | Default: crm_contact |
Throws if no user can be resolved.
CRM: load mapped user#
Plugin ID: eca_crm_load_mapped_user
Loads the user mapped to a contact. If there is no mapping, the action succeeds and does not set the result token.
| Field | Description |
|---|---|
| Contact | Contact entity token or contact ID |
| Name of token | Default: crm_mapped_user |
Throws if no contact can be resolved.
CRM: map user to contact#
Plugin ID: eca_crm_map_user_contact
Maps a user to a person contact. Fails if a mapping already exists for the user or contact, or if the contact is not a person. That is intentional so webhook models can fail and retry.
| Field | Description |
|---|---|
| User | User entity token or user ID |
| Contact | Person contact token or ID |
| Name of token | Default: crm_contact (stores the mapped contact) |
Requires the mapping entity admin permission (typically administer crm).
CRM: ensure contact for user#
Plugin ID: eca_crm_ensure_contact_for_user
Reuses an existing mapping or runs CRM lookup/create according to user
mapping settings (ensureContactForUser()). If CRM returns a contact,
it is stored in the result token. If it returns nothing, the action
succeeds without setting the token.
This path can fire crm:mapping_requested before the mapping is saved.
| Field | Description |
|---|---|
| User | User entity token or user ID |
| Name of token | Default: crm_contact |
Requires the mapping entity admin permission.
CRM: unmap user from contact#
Plugin ID: eca_crm_unmap_user_contact
Deletes the mapping entity. It does not delete the contact.
Provide a user, a contact, or both. The user is tried first; if no mapping is found, the contact is used.
| Field | Description |
|---|---|
| User | User token or ID. Used if Contact is empty or as the first lookup. |
| Contact | Contact token or ID. Used if no mapping is found from User. |
Throws if no mapping is found. Requires the mapping entity admin permission.
Contact methods#
Add-method actions create a crm_contact_method, append it to the
contact field, and save the contact. They require update access on
the contact.
Shared fields:
| Field | Description |
|---|---|
| Contact | Contact entity token or contact ID |
| Detail | Method detail (for example main; token-selectable) |
| Set as primary | When checked, the new method is marked primary |
| Name of token | Default: crm_contact_method |
Throws if the contact cannot be resolved or lacks the method field.
CRM: add email to contact#
Plugin ID: eca_crm_add_email
Creates an email method and attaches it to emails. Extra field:
Email.
CRM: add telephone to contact#
Plugin ID: eca_crm_add_telephone
Creates a telephone method and attaches it to telephones. Extra
field: Telephone.
CRM: add address to contact#
Plugin ID: eca_crm_add_address
Creates an address method from Address module properties and attaches
it to addresses. Optional fields (all token-replaceable):
- Country code
- Administrative area
- Locality
- Dependent locality
- Postal code
- Sorting code
- Address line 1
- Address line 2
- Organization
- Given name
- Additional name
- Family name
Lookup#
CRM: find contact by email#
Plugin ID: eca_crm_find_contact_by_email
Loads the unique person contact that owns the email. If none or more than one contact matches, the action succeeds and leaves the token unset.
| Field | Description |
|---|---|
| Email address (token-replaceable) | |
| Name of token | Default: crm_contact |
Relationships#
CRM: create relationship#
Plugin ID: eca_crm_create_relationship
Creates a published relationship of the given type between two contacts. CRM entity constraints are validated before save. Violations are thrown as a single exception message.
| Field | Description |
|---|---|
| Relationship type | Type ID (token-selectable) |
| Contact A | Contact token or ID for position A |
| Contact B | Contact token or ID for position B |
| Start date | Optional YYYY-MM-DD |
| End date | Optional YYYY-MM-DD |
| Name of token | Default: crm_relationship |
Throws if type or either contact is missing, or if validation fails. Requires CRM create access for that relationship type.