Salesforce

Overview

The package ships two LWC components for rendering Message__c records and a pre-built record page that wires them together. After installation, one manual activation step is required before they become visible to users.

Included Components

Email Message Renderer (Pendula4E__emailMessageRenderer)

Renders email messages stored on Message__c records. Displays:

• Subject, From, To, and Reply-To addresses
• Message timestamp and delivery status badge (delivered, opened, sent, failed)
• HTML email body with automatic XSS sanitization via lightning-formatted-rich-text
• Toggle between HTML and plain text views

Target: lightning__RecordPage on Message__c only

SMS Message Renderer (Pendula4E__smsMessageRenderer)

Renders SMS messages stored on Message__c records. Displays:

• Inbound and outbound messages as styled chat bubbles
• Error details for failed message deliveries

Target: lightning__RecordPage on Message__c only

Included Record Page

Message Record Page (Message_Record_Page)

A pre-built Lightning record page for the Message__c object. Layout:

The Email Preview and SMS Preview tabs are conditionally shown based on the record's Channel__c field, so only the relevant renderer is visible for a given message.

Activation Steps

1. Activate the record page in Lightning App Builder (required)

The Message_Record_Page flexipage is deployed with the package but is not automatically assigned. It must be activated manually:

1. Go to Setup → User Interface → Lightning App Builder
2. Locate Message Record Page in the list
3. Click Edit, then click Activation...
4. Choose the assignment scope:
   • Org Default — applies to all users viewing Message__c records
   • App Default — restricts to a specific Lightning app
   • App, Record Type, and Profile — for fine-grained control
5. Save the activation

Until this step is completed, Salesforce uses the system default record page and neither renderer will appear.

2. Post-install handler (automatic — no action required)

On a fresh install, the PostInstallHandlerV2 Apex class automatically creates the default Settings__c custom settings record for the org. This requires no manual action.

3. Configure CSP Trusted Sites for external email images (conditional)

Salesforce's Content Security Policy blocks externally hosted images by default. If Message__c records contain email bodies with <img src="https://..."> URLs from external domains, those images will not render until the domains are trusted.

To enable external image display:

1. Go to Setup → Security → CSP Trusted Sites
2. Click New Trusted Site
3. Enter a name and the image domain (e.g. https://images.example.com)
4. Enable the Connect directive
5. Save, then refresh the Message record page

Image format support:

If CSP configuration is not desired, images can be converted to base64 data URIs in Apex before the Message__c record is created or updated, which requires no CSP changes.

Adding Renderers to a Custom Record Page

If the included Message_Record_Page is not used, both components can be placed manually on any Message__c record page via Lightning App Builder:

1. Open the target record page in Setup → Lightning App Builder
2. In the component panel, search for Email Message Renderer or SMS Message Renderer (under the Pendula4E namespace)
3. Drag the component to the desired region
4. Optionally add a visibility rule on Channel__c to show only the relevant renderer
5. Save and activate the page

The Pendula managed package adds a custom lookup field, Pendula Message (P4E_Message__c), to the standard Salesforce Event object. This field is populated on every Activity Sync event and provides a direct navigable link from an Event record in the Activity Timeline view, back to the associated Message__c record.

Why This Field Exists

When Activity Sync creates Event records, the standard WhatId field is used to link the event to the Message__c record. However, Salesforce does not allow WhatId to be set when WhoId references a Lead — this is a hard platform constraint.

The P4E_Message__c lookup field works around this by providing an explicit, separate link to the Message__c record that is not subject to the WhoId/WhatId constraint. It is populated for all recipient types:

This field also enables correct upsert behaviour for Lead events. Because Lead events have no WhatId, the package uses P4E_Message__c to identify and update existing events rather than inserting duplicates on each status change.

Post-Install Setup

The field is added to the Event object automatically on package installation. In Salesforce metadata, custom fields on activity objects (Event, Task) are stored under the Activity object — this is a platform convention. The field is accessible on Event records as Pendula4E__P4E_Message__c regardless of where it is stored in metadata. To make it visible to users viewing Event records you must manually add it to the relevant Event page layout(s) in your org:

1. Go to Setup > Object Manager > Event > Page Layouts
2. Open the page layout(s) used by your sales or service users
3. Drag the Pendula Message field onto the layout
4. Save

There is no standard way for a managed package to modify a subscriber org's existing page layouts without risk of overwriting customisations, so this step must be performed by an administrator.

Field-Level Security

The field is included in the following package permission sets with the permissions shown:

Users who view Event records but do not have one of the above permission sets assigned will not see the field unless their profile grants access. Grant field-level read access via a profile or supplemental permission set as needed.

Behaviour on Message Deletion

The field uses a SetNull delete constraint. If the referenced Message__c record is deleted, the P4E_Message__c field on any linked Event records is set to null — the Event records themselves are not deleted.

Upgrade Behaviour

For orgs upgrading from a version without this field:

• Existing Event records will have P4E_Message__c = null
• The next time a Message__c record is updated (triggering the Activity Sync logic), the corresponding Event is updated and P4E_Message__c is populated at that point
• Lead events that were previously never updated (due to the missing upsert key) will be correctly updated from that point forward

The Pendula_Activity_Sync_Integration permission set grants the dedicated Salesforce integration user the permissions required to connect a Pendula tenant to Salesforce and run Activity Sync.

Assign this permission set to the Salesforce user whose credentials are used to authenticate Pendula via OAuth 2.0. It should not be assigned to end users.

What the Permission Set Covers

System Permissions

Pendula4E Object Permissions

All custom fields on Message__c and Message_Event__c are granted read and edit access. All custom fields on Message_Recipient__c are granted read access.

The three Message__c record types are granted visibility: Inbound_SMS, Outbound_Email, Outbound_SMS.

Recipient Matching — Standard Object Permissions

For Pendula to match inbound and outbound messages to Salesforce records, the integration user requires read access to the following standard objects and fields.

Person Accounts

Person Account field permissions are not included in this permission set.

Person Accounts is an optional Salesforce feature. Because this package is installed across customer orgs that may or may not have Person Accounts enabled, including Account.PersonEmail and Account.PersonMobilePhone field permissions in the packaged permission set would cause installation to fail in orgs where Person Accounts is not enabled.

The package handles this at runtime — Utils.isPersonAccountEnabled() is checked before any Person Account recipient matching is attempted, so no errors occur in orgs without the feature.

If your org uses Person Accounts

You must grant the integration user read access to Account.PersonEmail and Account.PersonMobilePhone separately, outside of the managed package.

The recommended approach is to create a supplemental permission set in your own org:

1. Go to Setup → Permission Sets → New
2. Label: Pendula Activity Sync — Person Accounts (or similar)
3. Under Object Settings → Account, set object access to Read
4. Enable View All Records
5. Under field permissions, grant Read Access to:
   • PersonEmail
   • PersonMobilePhone
6. Save and assign to the Pendula integration user

Verifying whether Person Accounts is enabled

In Setup, search for Person Accounts. If the feature is enabled, you will see a Person Accounts configuration page. Alternatively, check whether the Account object has a PersonEmail field via Object Manager → Account → Fields & Relationships.

Assigning the Permission Set

1. Go to Setup → Users, find the Pendula integration user
2. Click Permission Set Assignments → Edit Assignments
3. Add Pendula Activity Sync Integration
4. If your org uses Person Accounts, also assign the supplemental permission set described above
5. Save

Relationship to Other Permission Sets

This permission set is intended solely for the Pendula integration (service) user. It is separate from the permission sets used by human Salesforce users:

The Pendula Console component can be placed on any Salesforce record page — not just Contact, Lead, User, or Person Account pages. When placed on objects like Case, Opportunity, or custom objects, it resolves related person entities (Contacts, Leads, Users, Person Accounts) by following relationship paths you configure.

Configuration is done by creating Recipient Lookup Path custom metadata records. No code changes are required.

How It Works

1. A user opens a record page (e.g. a Case) that has the Pendula Console component
2. The component reads all active Recipient Lookup Path records for that object type
3. It follows each configured relationship path to find related person entities
4. If multiple people are found, a dropdown arrow appears next to the recipient name — the user clicks it to switch between conversation partners

On person entity pages (Contact, Lead, User, Person Account), the page record itself is always auto-included as the first recipient. Custom Metadata Types (CMDT) paths can add more.

Creating Recipient Lookup Path Records

Navigate to Setup → Custom Metadata Types → Recipient Lookup Path → Manage Records → New.

Fields

Relationship Path Syntax

The Relationship Path field supports three patterns.

Pattern 1: Direct Lookup

Use when the source object has a lookup field that points directly to a Contact, Lead, or User.

Syntax: <LookupFieldApiName>

Example: ContactId on Case points to a Contact. The resolver queries:

SELECT Id, Name, MobilePhone FROM Contact WHERE Id = <value of Case.ContactId>

Pattern 2: Parent → Children

Use when you need to traverse through an intermediate object. The source record has a lookup to a parent, and the parent has child records of the target entity type.

Syntax: <LookupFieldApiName>.<ChildRelationshipName>

Example: AccountId.Contacts on Case — first resolve the Case's AccountId, then find all Contacts under that Account. The resolver queries:

SELECT Id, Name, MobilePhone FROM Contact WHERE AccountId = <value of Case.AccountId> LIMIT <Max Results>

The second segment (Contacts) is the child relationship name as defined on the parent object, not a field API name. You can find it in Setup → Object Manager → [Parent Object] → Fields & Relationships → [Lookup Field] → Child Relationship Name.

Pattern 3: Self Children

Use when the source object itself is the parent and you want its child records. The path is simply the child relationship name on the source object.

Syntax: <ChildRelationshipName>

Example: Contacts on Account — finds all Contacts that belong to the Account. The resolver queries:

SELECT Id, Name, MobilePhone FROM Contact WHERE AccountId = <source Account Id> LIMIT <Max Results>

The resolver detects that Contacts is a child relationship name (not a lookup field) on Account and uses the source record's own Id as the parent.

Person Account Paths

For Person Accounts, set Target Entity to PersonAccount and use the lookup field that points to the Account.

Syntax: <LookupFieldApiName> (direct) or <LookupFieldApiName>.PersonContact

The resolver automatically checks IsPersonAccount = true and returns PersonMobilePhone instead of MobilePhone. In orgs without Person Accounts enabled, these paths return no results (no errors).

Examples with Standard Objects

Case

A typical Case configuration resolves the primary contact, all contacts under the related account, the case owner, and a person account if applicable.

Behaviour:

• If the Case has a ContactId set and no other contacts on the Account → single recipient, no dropdown
• If the Case has a ContactId and the Account has 3 Contacts → 3 recipients shown (the primary contact appears once thanks to deduplication), dropdown arrow visible
• If the Case has no ContactId and no Account → no recipients resolved

Account

An Account page can resolve its own child Contacts directly using the child relationship name.

Behaviour:

• If the Account has 3 Contacts → 3 recipients shown, dropdown arrow visible
• If the Account is a Person Account → the Person Account is auto-included at sort order 0 (before the CMDT paths)
• The Contacts path uses the child relationship name directly — no intermediate lookup needed

Opportunity

Contact (adding related people)

On a Contact page, the Contact itself is auto-included as the first recipient (sort order 0). You can add more:

Behaviour:

• The Contact page record appears first as "Contact" (auto-included, sort order 0)
• The Created By user appears second (sort order 1)
• The Contact Owner appears third (sort order 2)
• Other Contacts under the same Account appear with sort order 3
• The page Contact is deduplicated from the Account Contacts list
• The dropdown arrow appears because there are multiple recipients

Lead

On a Lead page, the Lead is auto-included. Additional paths:

Custom Objects

For a custom object Project__c with lookup fields to Contact and Account:

Note: for custom lookup fields, use the field API name including the __c suffix (e.g. Primary_Contact__c). For parent→children paths with custom relationships, the child relationship name typically ends in __r (e.g. Account__c.Project_Members__r).

Finding the Right API Names

Lookup Field API Name (first segment)

1. Go to Setup → Object Manager → [Your Object] → Fields & Relationships
2. Find the lookup field (e.g. "Contact" on Case)
3. The Field Name column shows the API name (e.g. ContactId)
4. For custom fields, the API name ends in __c (e.g. Primary_Contact__c)

Child Relationship Name (second segment)

1. Go to Setup → Object Manager → [Parent Object] (e.g. Account)
2. Go to Fields & Relationships
3. Find the lookup field on the child object that creates the relationship (e.g. the AccountId field on Contact)
4. Click it → the Child Relationship Name is shown (e.g. Contacts)
5. For custom relationships, this typically ends in __r

Deduplication

If the same person is resolved by multiple paths (e.g. a Contact found via both ContactId and AccountId.Contacts), they appear only once in the dropdown. The first occurrence (lowest sort order) wins.

On person entity pages, the page record is always included with sort order 0 and is deduplicated from any CMDT results.

Limits and Considerations

• Max 2-hop traversal: Paths support at most one intermediate object (e.g. AccountId.Contacts). Three-hop paths like AccountId.ParentId.Contacts are not supported.
• Governor limits: Each path executes 1 SOQL query. With 5 paths configured, that's ~6 queries total (including the source record query). Well within the 100-query limit per transaction. If you configure many paths, use Is Active and Max Results to tune.
• Field-Level Security: All queries run in USER_MODE, so users only see records and fields they have access to.
• Person Accounts: Paths targeting Person Accounts silently return no results in orgs where Person Accounts are not enabled. No errors.
• Caching: Results are cached by the Lightning Data Service. Changes to relationships (e.g. reassigning a Case contact) are reflected after a page refresh or when the user clicks the Refresh option in the Console settings menu.