Skip to content

The open alternative to Salesforce, designed for AI.

Add fallback values to campaign variables (#27915)

neo7737cae53a45d4c
diff --git a/packages/twenty-server/src/modules/emailing/constants/campaign-variable-pattern.constant.ts b/packages/twenty-server/src/modules/emailing/constants/campaign-variable-pattern.constant.ts
deleted file mode 100644
index 1ec7b2cf35d..00000000000
--- a/packages/twenty-server/src/modules/emailing/constants/campaign-variable-pattern.constant.ts
+++ /dev/null
@@ -1,2 +0,0 @@
-export const CAMPAIGN_VARIABLE_PATTERN =
- /\{\{\s*([a-zA-Z][a-zA-Z0-9_]*(?:\.[a-zA-Z][a-zA-Z0-9_]*)*)\s*\}\}/g;
diff --git a/packages/twenty-server/src/modules/emailing/services/campaign-tracking-content.service.ts b/packages/twenty-server/src/modules/emailing/services/campaign-tracking-content.service.ts
index a1ea586850b..4b1d1e0f324 100644
--- a/packages/twenty-server/src/modules/emailing/services/campaign-tracking-content.service.ts
+++ b/packages/twenty-server/src/modules/emailing/services/campaign-tracking-content.service.ts
@@ -7,7 +7,11 @@ import { Repository } from 'typeorm';
import { isNonEmptyString } from '@sniptt/guards';
import { toPlainText } from 'twenty-emails';
import { ApiPath } from 'twenty-shared/types';
-import { isDefined } from 'twenty-shared/utils';
+import {
+ formatTemplateVariableWithFallback,
+ isDefined,
+ type TemplateVariableWithFallback,
+} from 'twenty-shared/utils';
import { buildLogDriverUnsubscribeBaseUrl } from 'src/engine/core-modules/emailing-domain/drivers/log/utils/build-log-driver-unsubscribe-base-url.util';
import { EmailingDomainDriver } from 'src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-driver.type';
@@ -54,7 +58,7 @@ type PrepareBatchArgs = {
emailingDomainId: string;
template: EmailingDomainEmailTemplate;
plainTextSourceHtml: string;
- variableNames: string[];
+ campaignVariables: TemplateVariableWithFallback[];
recipients: TrackingRecipient[];
};
@@ -76,7 +80,7 @@ export class CampaignTrackingContentService {
emailingDomainId,
template,
plainTextSourceHtml,
- variableNames,
+ campaignVariables,
recipients,
}: PrepareBatchArgs): Promise<TrackedCampaignBatch> {
const untracked = {
@@ -138,7 +142,7 @@ export class CampaignTrackingContentService {
const shortLinkIdByIdentity = await this.registerShortLinks({
workspaceId,
urlTemplates,
- variableNames,
+ campaignVariables,
recipients: recipients.filter(isTracked),
});
@@ -160,7 +164,7 @@ export class CampaignTrackingContentService {
baseUrl,
recipient,
urlTemplates,
- variableNames,
+ campaignVariables,
shortLinkIdByIdentity,
isOpenTrackingEnabled,
})
@@ -216,12 +220,12 @@ export class CampaignTrackingContentService {
private async registerShortLinks({
workspaceId,
urlTemplates,
- variableNames,
+ campaignVariables,
recipients,
}: {
workspaceId: string;
urlTemplates: string[];
- variableNames: string[];
+ campaignVariables: TemplateVariableWithFallback[];
recipients: TrackingRecipient[];
}): Promise<Map<string, string>> {
const linkByIdentity = new Map<
@@ -232,7 +236,7 @@ export class CampaignTrackingContentService {
for (const urlTemplate of urlTemplates) {
const authoredTemplateUrl = this.restoreAuthoredUrl({
urlTemplate,
- variableNames,
+ campaignVariables,
});
for (const recipient of recipients) {
@@ -267,7 +271,7 @@ export class CampaignTrackingContentService {
baseUrl,
recipient,
urlTemplates,
- variableNames,
+ campaignVariables,
shortLinkIdByIdentity,
isOpenTrackingEnabled,
}: {
@@ -275,7 +279,7 @@ export class CampaignTrackingContentService {
baseUrl: string;
recipient: TrackingRecipient;
urlTemplates: string[];
- variableNames: string[];
+ campaignVariables: TemplateVariableWithFallback[];
shortLinkIdByIdentity: Map<string, string>;
isOpenTrackingEnabled: boolean;
}): Record<string, string> {
@@ -293,7 +297,7 @@ export class CampaignTrackingContentService {
urlTemplates.forEach((urlTemplate, index) => {
const authoredTemplateUrl = this.restoreAuthoredUrl({
urlTemplate,
- variableNames,
+ campaignVariables,
});
const { url } = this.resolveLinkUrl({
urlTemplate,
@@ -374,17 +378,19 @@ export class CampaignTrackingContentService {
private restoreAuthoredUrl({
urlTemplate,
- variableNames,
+ campaignVariables,
}: {
urlTemplate: string;
- variableNames: string[];
+ campaignVariables: TemplateVariableWithFallback[];
}): string {
return urlTemplate.replace(
CAMPAIGN_BATCH_VARIABLE_TAG_PATTERN,
(tag: string, variableIndex: string) => {
- const variableName = variableNames[Number(variableIndex)];
+ const campaignVariable = campaignVariables[Number(variableIndex)];
- return isDefined(variableName) ? `{{${variableName}}}` : tag;
+ return isDefined(campaignVariable)
+ ? formatTemplateVariableWithFallback(campaignVariable)
+ : tag;
},
);
}
diff --git a/packages/twenty-server/src/modules/emailing/services/message-campaign-batch-delivery.service.ts b/packages/twenty-server/src/modules/emailing/services/message-campaign-batch-delivery.service.ts
index c6edd550f76..8fd66864cf7 100644
--- a/packages/twenty-server/src/modules/emailing/services/message-campaign-batch-delivery.service.ts
+++ b/packages/twenty-server/src/modules/emailing/services/message-campaign-batch-delivery.service.ts
@@ -309,7 +309,7 @@ export class MessageCampaignBatchDeliveryService {
}): Promise<void> {
const { workspaceId, campaignId, emailingDomainId } = data;
- const { template, plainTextSourceHtml, variableNames } =
+ const { template, plainTextSourceHtml, campaignVariables } =
await compileCampaignBatchTemplate({
subjectTemplate: campaign.subject ?? '',
bodyTemplate: campaign.bodyTemplate ?? '',
@@ -338,7 +338,7 @@ export class MessageCampaignBatchDeliveryService {
replacementsByDeliveryId.set(
recipient.messageId,
- buildCampaignBatchReplacements({ variableNames, variables }),
+ buildCampaignBatchReplacements({ campaignVariables, variables }),
);
}
@@ -348,7 +348,7 @@ export class MessageCampaignBatchDeliveryService {
emailingDomainId,
template,
plainTextSourceHtml,
- variableNames,
+ campaignVariables,
recipients: claimedRecipients.map((recipient) => ({
deliveryId: recipient.messageId,
email: recipient.email,
diff --git a/packages/twenty-server/src/modules/emailing/services/message-campaign-draft.service.ts b/packages/twenty-server/src/modules/emailing/services/message-campaign-draft.service.ts
index e02bf5cf56a..c2af48ef135 100644
--- a/packages/twenty-server/src/modules/emailing/services/message-campaign-draft.service.ts
+++ b/packages/twenty-server/src/modules/emailing/services/message-campaign-draft.service.ts
@@ -19,8 +19,8 @@ import { UserRoleService } from 'src/engine/metadata-modules/user-role/user-role
import { WorkspaceOrmManager } from 'src/engine/twenty-orm/workspace-orm.manager';
import { CampaignVariableService } from 'src/modules/emailing/services/campaign-variable.service';
import { MessageCampaignWorkspaceEntity } from 'src/modules/emailing/standard-objects/message-campaign.workspace-entity';
-import { collectCampaignVariableNames } from 'src/modules/emailing/utils/collect-campaign-variable-names.util';
-import { collectCampaignVariableNamesFromString } from 'src/modules/emailing/utils/collect-campaign-variable-names-from-string.util';
+import { collectCampaignVariableNamesOrThrow } from 'src/modules/emailing/utils/collect-campaign-variable-names-or-throw.util';
+import { collectCampaignVariableNamesFromStringOrThrow } from 'src/modules/emailing/utils/collect-campaign-variable-names-from-string-or-throw.util';
import { buildEmailingRolePermissionConfig } from 'src/modules/emailing/utils/build-emailing-role-permission-config.util';
export type SaveDraftCampaignArgs = {
@@ -75,10 +75,10 @@ export class MessageCampaignDraftService {
const variablesUsed = [
...new Set([
...(isDefined(stampedDocument)
- ? collectCampaignVariableNames(stampedDocument)
+ ? collectCampaignVariableNamesOrThrow(stampedDocument)
: []),
...(isDefined(subject)
- ? collectCampaignVariableNamesFromString(subject)
+ ? collectCampaignVariableNamesFromStringOrThrow(subject)
: []),
]),
].sort();
diff --git a/packages/twenty-server/src/modules/emailing/services/message-campaign.service.ts b/packages/twenty-server/src/modules/emailing/services/message-campaign.service.ts
index e730c428d7f..51247190eb3 100644
--- a/packages/twenty-server/src/modules/emailing/services/message-campaign.service.ts
+++ b/packages/twenty-server/src/modules/emailing/services/message-campaign.service.ts
@@ -37,7 +37,7 @@ import { MessageCampaignLifecycleService } from 'src/modules/emailing/services/m
import { MessageCampaignWorkspaceEntity } from 'src/modules/emailing/standard-objects/message-campaign.workspace-entity';
import { type PreparedCampaignSend } from 'src/modules/emailing/types/prepared-campaign-send.type';
import { type SendCampaignResult } from 'src/modules/emailing/types/send-campaign-result.type';
-import { collectCampaignVariableNamesFromTemplates } from 'src/modules/emailing/utils/collect-campaign-variable-names-from-templates.util';
+import { collectCampaignVariableNamesFromTemplatesOrThrow } from 'src/modules/emailing/utils/collect-campaign-variable-names-from-templates-or-throw.util';
import { renderCampaignEmail } from 'src/modules/emailing/utils/render-campaign-email.util';
import { sendableCampaignSchema } from 'src/modules/emailing/zod-schemas/sendable-campaign.zod-schema';
import { getDomainFromEmail } from 'src/utils/get-domain-from-email';
@@ -258,6 +258,14 @@ export class MessageCampaignService {
fromAddress,
});
+ await this.campaignVariableService.assertKnownVariables(
+ workspaceId,
+ collectCampaignVariableNamesFromTemplatesOrThrow({
+ subject,
+ bodyTemplate: html,
+ }),
+ );
+
const variables =
await this.campaignVariableService.buildVariablesForPerson(
workspaceId,
@@ -382,7 +390,7 @@ export class MessageCampaignService {
await this.campaignVariableService.assertKnownVariables(
workspaceId,
- collectCampaignVariableNamesFromTemplates({
+ collectCampaignVariableNamesFromTemplatesOrThrow({
subject: sendableCampaign.data.subject,
bodyTemplate: sendableCampaign.data.bodyTemplate,
}),
diff --git a/packages/twenty-server/src/modules/emailing/tools/save-campaign-tool.schema.ts b/packages/twenty-server/src/modules/emailing/tools/save-campaign-tool.schema.ts
index a6b5b880535..e4d79690983 100644
--- a/packages/twenty-server/src/modules/emailing/tools/save-campaign-tool.schema.ts
+++ b/packages/twenty-server/src/modules/emailing/tools/save-campaign-tool.schema.ts
@@ -29,6 +29,7 @@ export const SaveCampaignToolInputZodSchema = z.object({
'A document is {type: "doc", content: [...blocks]}. Blocks: paragraph and heading (level 1-3) hold inline text, variableTag chips ({attrs: {variable: "{{firstName}}"}}) and hardBreak; section wraps blocks in a styled band; columns holds 2-4 column children; button is a call-to-action with an href; image, divider, bulletList/orderedList and html (raw HTML) complete the set. ' +
'Style attributes are objects of camelCase CSS properties, e.g. {"paddingTop": "12px", "backgroundColor": "#f4f4f5"}. Use longhand box properties (paddingTop/Right/Bottom/Left). ' +
'Per-recipient variables reference person fields by path, e.g. {{name.firstName}}, {{emails.primaryEmail}}, {{city}} or any custom person field; {{firstName}}, {{lastName}}, {{fullName}}, {{email}} and {{personId}} also work. They apply in text, button and link URLs and raw HTML, and unknown names are rejected with the available list. ' +
+ 'Give a variable a fallback for recipients whose value is empty with the Liquid default filter, e.g. {{name.firstName | default: "there"}}; the fallback is double-quoted and a double quote inside it is written \\". Any other {{...}} is rejected as malformed. ' +
'To modify an existing body, read the record first, edit the parsed document and send the whole result back.',
),
});
diff --git a/packages/twenty-server/src/modules/emailing/utils/__tests__/build-campaign-batch-replacements.util.spec.ts b/packages/twenty-server/src/modules/emailing/utils/__tests__/build-campaign-batch-replacements.util.spec.ts
index 99c79fb902a..f70e4a20869 100644
--- a/packages/twenty-server/src/modules/emailing/utils/__tests__/build-campaign-batch-replacements.util.spec.ts
+++ b/packages/twenty-server/src/modules/emailing/utils/__tests__/build-campaign-batch-replacements.util.spec.ts
@@ -4,7 +4,7 @@ import { buildCampaignBatchReplacements } from 'src/modules/emailing/utils/build
describe('buildCampaignBatchReplacements', () => {
it('escapes a value for the html body and leaves it raw for the text body', () => {
const replacements = buildCampaignBatchReplacements({
- variableNames: ['name.firstName'],
+ campaignVariables: [{ name: 'name.firstName' }],
variables: { 'name.firstName': '<img onerror="x">' },
});
@@ -18,7 +18,7 @@ describe('buildCampaignBatchReplacements', () => {
it('percent-encodes a value destined for a url so it cannot leave its attribute', () => {
const replacements = buildCampaignBatchReplacements({
- variableNames: ['name.firstName'],
+ campaignVariables: [{ name: 'name.firstName' }],
variables: { 'name.firstName': '" onmouseover="alert(1)' },
});
@@ -32,7 +32,7 @@ describe('buildCampaignBatchReplacements', () => {
it('strips the scheme separator from a url value so it cannot become executable', () => {
const replacements = buildCampaignBatchReplacements({
- variableNames: ['website'],
+ campaignVariables: [{ name: 'website' }],
variables: { website: 'javascript:alert(1)' },
});
@@ -43,7 +43,7 @@ describe('buildCampaignBatchReplacements', () => {
it('substitutes an empty string for a variable the recipient has no value for', () => {
const replacements = buildCampaignBatchReplacements({
- variableNames: ['jobTitle'],
+ campaignVariables: [{ name: 'jobTitle' }],
variables: {},
});
@@ -54,7 +54,7 @@ describe('buildCampaignBatchReplacements', () => {
it('keeps each variable on its own pair of tags', () => {
const replacements = buildCampaignBatchReplacements({
- variableNames: ['first', 'second'],
+ campaignVariables: [{ name: 'first' }, { name: 'second' }],
variables: { first: 'Ada', second: 'Lovelace' },
});
@@ -65,7 +65,7 @@ describe('buildCampaignBatchReplacements', () => {
it('leaves a tag the recipient has no replacement for untouched rather than blanking it', () => {
const replacements = buildCampaignBatchReplacements({
- variableNames: ['known'],
+ campaignVariables: [{ name: 'known' }],
variables: { known: 'yes' },
});
@@ -75,10 +75,47 @@ describe('buildCampaignBatchReplacements', () => {
});
});
+describe('fallback variables', () => {
+ it('uses the fallback for a recipient whose value is only whitespace', () => {
+ const replacements = buildCampaignBatchReplacements({
+ campaignVariables: [{ name: 'jobTitle', fallback: 'there' }],
+ variables: { jobTitle: ' \n ' },
+ });
+
+ expect(applyReplacementTags('Hi {{v_t_0}}', replacements)).toBe('Hi there');
+ });
+
+ it('keeps the recipient value when there is one', () => {
+ const replacements = buildCampaignBatchReplacements({
+ campaignVariables: [{ name: 'jobTitle', fallback: 'there' }],
+ variables: { jobTitle: 'CTO' },
+ });
+
+ expect(applyReplacementTags('Hi {{v_t_0}}', replacements)).toBe('Hi CTO');
+ });
+
+ it('escapes the fallback for html and percent-encodes it for urls like a value', () => {
+ const replacements = buildCampaignBatchReplacements({
+ campaignVariables: [{ name: 'jobTitle', fallback: "<b>R&D</b> 'lead'" }],
+ variables: {},
+ });
+
+ expect(applyReplacementTags('{{v_h_0}}', replacements)).toBe(
+ '&lt;b&gt;R&amp;D&lt;/b&gt; &#39;lead&#39;',
+ );
+ expect(applyReplacementTags('{{v_t_0}}', replacements)).toBe(
+ "<b>R&D</b> 'lead'",
+ );
+ expect(applyReplacementTags('{{v_u_0}}', replacements)).toBe(
+ encodeURIComponent("<b>R&D</b> 'lead'"),
+ );
+ });
+});
+
describe('inherited object properties', () => {
it('treats a variable named after an Object prototype member as absent rather than its function', () => {
const replacements = buildCampaignBatchReplacements({
- variableNames: ['toString'],
+ campaignVariables: [{ name: 'toString' }],
variables: {},
});
@@ -87,7 +124,7 @@ describe('inherited object properties', () => {
it('leaves a prototype-named tag untouched instead of resolving it off Object.prototype', () => {
const replacements = buildCampaignBatchReplacements({
- variableNames: ['known'],
+ campaignVariables: [{ name: 'known' }],
variables: { known: 'yes' },
});
diff --git a/packages/twenty-server/src/modules/emailing/utils/__tests__/collect-campaign-variable-names-from-string-or-throw.util.spec.ts b/packages/twenty-server/src/modules/emailing/utils/__tests__/collect-campaign-variable-names-from-string-or-throw.util.spec.ts
new file mode 100644
index 00000000000..d0ccaa04403
--- /dev/null
+++ b/packages/twenty-server/src/modules/emailing/utils/__tests__/collect-campaign-variable-names-from-string-or-throw.util.spec.ts
@@ -0,0 +1,38 @@
+import { EmailingDomainExceptionCode } from 'src/engine/core-modules/emailing-domain/exceptions/emailing-domain.exception';
+import { collectCampaignVariableNamesFromStringOrThrow } from 'src/modules/emailing/utils/collect-campaign-variable-names-from-string-or-throw.util';
+
+describe('collectCampaignVariableNamesFromStringOrThrow', () => {
+ it('should collect the name of a variable with a fallback', () => {
+ expect([
+ ...collectCampaignVariableNamesFromStringOrThrow(
+ 'Hi {{name.firstName | default: "Mr. \\"X\\""}} at {{companyName}}',
+ ),
+ ]).toEqual(['name.firstName', 'companyName']);
+ });
+
+ it.each([
+ ['{{jobTitle | there}}', '{{jobTitle | there}}'],
+ ['{{jobTitle | "there"}}', '{{jobTitle | "there"}}'],
+ ['{{jobTitle | default: there}}', '{{jobTitle | default: there}}'],
+ ["{{jobTitle | default: 'there'}}", "{{jobTitle | default: 'there'}}"],
+ ['{{jobTitle | default: “there”}}', '{{jobTitle | default: “there”}}'],
+ ['{{jobTitle | default: {there}}}', '{{jobTitle | default: {there}}'],
+ ['{{jobTitle there', '{{jobTitle there, welcome'],
+ ])(
+ 'should reject the malformed variable %s',
+ (variable, reportedVariable) => {
+ expect(() =>
+ collectCampaignVariableNamesFromStringOrThrow(
+ `Hi ${variable}, welcome`,
+ ),
+ ).toThrow(
+ expect.objectContaining({
+ code: EmailingDomainExceptionCode.MESSAGE_CAMPAIGN_NOT_SENDABLE,
+ message: expect.stringContaining(
+ `Malformed campaign variable: ${reportedVariable}.`,
+ ),
+ }),
+ );
+ },
+ );
+});
diff --git a/packages/twenty-server/src/modules/emailing/utils/__tests__/collect-campaign-variable-names.util.spec.ts b/packages/twenty-server/src/modules/emailing/utils/__tests__/collect-campaign-variable-names-or-throw.util.spec.ts
similarity index 67%
rename from packages/twenty-server/src/modules/emailing/utils/__tests__/collect-campaign-variable-names.util.spec.ts
rename to packages/twenty-server/src/modules/emailing/utils/__tests__/collect-campaign-variable-names-or-throw.util.spec.ts
index 931b18b7bbe..bf0148c67d9 100644
--- a/packages/twenty-server/src/modules/emailing/utils/__tests__/collect-campaign-variable-names.util.spec.ts
+++ b/packages/twenty-server/src/modules/emailing/utils/__tests__/collect-campaign-variable-names-or-throw.util.spec.ts
@@ -1,6 +1,6 @@
-import { collectCampaignVariableNames } from 'src/modules/emailing/utils/collect-campaign-variable-names.util';
+import { collectCampaignVariableNamesOrThrow } from 'src/modules/emailing/utils/collect-campaign-variable-names-or-throw.util';
-describe('collectCampaignVariableNames', () => {
+describe('collectCampaignVariableNamesOrThrow', () => {
it('should collect variables from every substitution site', () => {
const document = {
type: 'doc',
@@ -48,7 +48,7 @@ describe('collectCampaignVariableNames', () => {
],
};
- expect([...collectCampaignVariableNames(document)].sort()).toEqual([
+ expect([...collectCampaignVariableNamesOrThrow(document)].sort()).toEqual([
'email',
'firstName',
'fullName',
@@ -62,7 +62,7 @@ describe('collectCampaignVariableNames', () => {
it('should collect nothing from a document without variables', () => {
expect(
- collectCampaignVariableNames({
+ collectCampaignVariableNamesOrThrow({
type: 'doc',
content: [
{ type: 'paragraph', content: [{ type: 'text', text: 'Hi' }] },
@@ -73,7 +73,7 @@ describe('collectCampaignVariableNames', () => {
it('should deduplicate repeated variables', () => {
expect([
- ...collectCampaignVariableNames({
+ ...collectCampaignVariableNamesOrThrow({
type: 'doc',
content: [
{
@@ -86,4 +86,24 @@ describe('collectCampaignVariableNames', () => {
}),
]).toEqual(['firstName']);
});
+
+ it('should collect the variable name of a variable with a fallback so unknown names are still checked', () => {
+ expect([
+ ...collectCampaignVariableNamesOrThrow({
+ type: 'doc',
+ content: [
+ {
+ type: 'paragraph',
+ content: [
+ { type: 'text', text: 'Hi {{ jobTitle | default: "there" }}' },
+ {
+ type: 'variableTag',
+ attrs: { variable: '{{notAField | default: "x"}}' },
+ },
+ ],
+ },
+ ],
+ }),
+ ]).toEqual(['jobTitle', 'notAField']);
+ });
});
diff --git a/packages/twenty-server/src/modules/emailing/utils/__tests__/compile-campaign-batch-template.util.spec.ts b/packages/twenty-server/src/modules/emailing/utils/__tests__/compile-campaign-batch-template.util.spec.ts
index 8038d97d863..a2e52fcf1b7 100644
--- a/packages/twenty-server/src/modules/emailing/utils/__tests__/compile-campaign-batch-template.util.spec.ts
+++ b/packages/twenty-server/src/modules/emailing/utils/__tests__/compile-campaign-batch-template.util.spec.ts
@@ -23,17 +23,17 @@ const deliverToRecipient = async ({
bodyTemplate: string;
variables: Record<string, string>;
}) => {
- const { template, variableNames } = await compileCampaignBatchTemplate({
+ const { template, campaignVariables } = await compileCampaignBatchTemplate({
subjectTemplate,
bodyTemplate,
});
const replacements = buildCampaignBatchReplacements({
- variableNames,
+ campaignVariables,
variables,
});
return {
- variableNames,
+ campaignVariables,
subject: applyReplacementTags(template.subject, replacements),
html: applyReplacementTags(template.html ?? '', replacements),
text: applyReplacementTags(template.text, replacements),
@@ -101,14 +101,17 @@ describe('compileCampaignBatchTemplate', () => {
});
it('gives a variable used twice a single slot and the same value in both bodies', async () => {
- const { variableNames, html, text } = await deliverToRecipient({
+ const { campaignVariables, html, text } = await deliverToRecipient({
bodyTemplate: paragraphDocument(
'{{firstName}} {{lastName}}, this is for {{firstName}}.',
),
variables: { firstName: 'Ada', lastName: 'Lovelace' },
});
- expect(variableNames).toEqual(['firstName', 'lastName']);
+ expect(campaignVariables).toEqual([
+ { name: 'firstName' },
+ { name: 'lastName' },
+ ]);
expect(html).toContain('Ada Lovelace, this is for Ada.');
expect(text).toContain('Ada Lovelace, this is for Ada.');
});
@@ -126,4 +129,67 @@ describe('compileCampaignBatchTemplate', () => {
expect(text).toBe('');
}
});
+
+ it('renders the fallback for a recipient with an empty value in subject, html and text', async () => {
+ const { subject, html, text } = await deliverToRecipient({
+ subjectTemplate: 'Hi {{jobTitle | default: "there"}}',
+ bodyTemplate: serializeDocument([
+ {
+ type: 'paragraph',
+ content: [
+ { type: 'text', text: 'Hello ' },
+ {
+ type: 'variableTag',
+ attrs: { variable: '{{jobTitle | default: "<b>R&D</b>"}}' },
+ },
+ ],
+ },
+ ]),
+ variables: { jobTitle: ' ' },
+ });
+
+ expect(subject).toBe('Hi there');
+ expect(html).toContain('Hello &lt;b&gt;R&amp;D&lt;/b&gt;');
+ expect(text).toContain('Hello <b>R&D</b>');
+ });
+
+ it('renders a variable with and without a fallback independently', async () => {
+ const { html } = await deliverToRecipient({
+ bodyTemplate: paragraphDocument(
+ '[{{jobTitle}}] [{{ jobTitle | default: "there" }}] [{{jobTitle|default:"there"}}]',
+ ),
+ variables: {},
+ });
+
+ expect(html).toContain('[] [there] [there]');
+ });
+
+ it('percent-encodes a fallback used inside a link href', async () => {
+ const { html } = await deliverToRecipient({
+ bodyTemplate: serializeDocument([
+ {
+ type: 'paragraph',
+ content: [
+ {
+ type: 'text',
+ text: 'Read more',
+ marks: [
+ {
+ type: 'link',
+ attrs: {
+ href: 'https://example.com/?city={{city | default: "New York & co"}}',
+ },
+ },
+ ],
+ },
+ ],
+ },
+ ]),
+ variables: { city: '' },
+ });
+
+ expect(html).toContain(
+ 'href="https://example.com/?city=New%20York%20%26%20co"',
+ );
+ });
});
diff --git a/packages/twenty-server/src/modules/emailing/utils/__tests__/render-campaign-template.util.spec.ts b/packages/twenty-server/src/modules/emailing/utils/__tests__/render-campaign-template.util.spec.ts
new file mode 100644
index 00000000000..ba0ef1170e9
--- /dev/null
+++ b/packages/twenty-server/src/modules/emailing/utils/__tests__/render-campaign-template.util.spec.ts
@@ -0,0 +1,43 @@
+import { renderCampaignTemplate } from 'src/modules/emailing/utils/render-campaign-template.util';
+
+describe('renderCampaignTemplate', () => {
+ it('renders a plain variable exactly as before, blank when the value is empty', () => {
+ expect(
+ renderCampaignTemplate(
+ 'Hi {{jobTitle}} for {{ city }}',
+ { jobTitle: 'CTO', city: '' },
+ { escapeValues: false },
+ ),
+ ).toBe('Hi CTO for ');
+ });
+
+ it('renders the fallback when the value is only whitespace', () => {
+ expect(
+ renderCampaignTemplate(
+ 'Hi {{jobTitle | default: "there"}}',
+ { jobTitle: ' \t ' },
+ { escapeValues: false },
+ ),
+ ).toBe('Hi there');
+ });
+
+ it('renders the value instead of the fallback when the value is set', () => {
+ expect(
+ renderCampaignTemplate(
+ 'Hi {{ jobTitle|default:"there" }}',
+ { jobTitle: ' CTO ' },
+ { escapeValues: false },
+ ),
+ ).toBe('Hi CTO ');
+ });
+
+ it('escapes the fallback like a value', () => {
+ expect(
+ renderCampaignTemplate(
+ '<p>{{jobTitle | default: "<script>alert(\'x\')</script> & co"}}</p>',
+ {},
+ { escapeValues: true },
+ ),
+ ).toBe('<p>&lt;script&gt;alert(&#39;x&#39;)&lt;/script&gt; &amp; co</p>');
+ });
+});
diff --git a/packages/twenty-server/src/modules/emailing/utils/build-campaign-batch-replacements.util.ts b/packages/twenty-server/src/modules/emailing/utils/build-campaign-batch-replacements.util.ts
index 706750872d4..d66733f2922 100644
--- a/packages/twenty-server/src/modules/emailing/utils/build-campaign-batch-replacements.util.ts
+++ b/packages/twenty-server/src/modules/emailing/utils/build-campaign-batch-replacements.util.ts
@@ -1,18 +1,19 @@
+import { type TemplateVariableWithFallback } from 'twenty-shared/utils';
+
import { escapeHtml } from 'src/engine/core-modules/emailing-domain/utils/escape-html.util';
+import { resolveCampaignVariableValue } from 'src/modules/emailing/utils/resolve-campaign-variable-value.util';
export const buildCampaignBatchReplacements = ({
- variableNames,
+ campaignVariables,
variables,
}: {
- variableNames: string[];
+ campaignVariables: TemplateVariableWithFallback[];
variables: Record<string, string>;
}): Record<string, string> => {
const replacements: Record<string, string> = {};
- for (const [index, variableName] of variableNames.entries()) {
- const value = Object.prototype.hasOwnProperty.call(variables, variableName)
- ? (variables[variableName] ?? '')
- : '';
+ for (const [index, campaignVariable] of campaignVariables.entries()) {
+ const value = resolveCampaignVariableValue({ campaignVariable, variables });
replacements[`v_h_${index}`] = escapeHtml(value);
replacements[`v_t_${index}`] = value;
diff --git a/packages/twenty-server/src/modules/emailing/utils/collect-campaign-variable-names-from-string-or-throw.util.ts b/packages/twenty-server/src/modules/emailing/utils/collect-campaign-variable-names-from-string-or-throw.util.ts
new file mode 100644
index 00000000000..a0c148905ef
--- /dev/null
+++ b/packages/twenty-server/src/modules/emailing/utils/collect-campaign-variable-names-from-string-or-throw.util.ts
@@ -0,0 +1,49 @@
+import { msg } from '@lingui/core/macro';
+import {
+ findMalformedTemplateVariable,
+ isDefined,
+ parseTemplateVariableWithFallback,
+ TEMPLATE_VARIABLE_PATTERN,
+} from 'twenty-shared/utils';
+
+import {
+ EmailingDomainException,
+ EmailingDomainExceptionCode,
+} from 'src/engine/core-modules/emailing-domain/exceptions/emailing-domain.exception';
+
+export const collectCampaignVariableNamesFromStringOrThrow = (
+ value: unknown,
+): Set<string> => {
+ const names = new Set<string>();
+
+ if (typeof value !== 'string') {
+ return names;
+ }
+
+ const malformedTemplateVariable = findMalformedTemplateVariable(value);
+
+ if (isDefined(malformedTemplateVariable)) {
+ const expectedSyntax = '{{jobTitle}} or {{jobTitle | default: "there"}}';
+
+ throw new EmailingDomainException(
+ `Malformed campaign variable: ${malformedTemplateVariable}. Expected ${expectedSyntax}`,
+ EmailingDomainExceptionCode.MESSAGE_CAMPAIGN_NOT_SENDABLE,
+ {
+ userFriendlyMessage: msg`This campaign has a variable written in the wrong format: ${malformedTemplateVariable}. Write it as ${expectedSyntax}.`,
+ },
+ );
+ }
+
+ for (const [rawTemplateVariable] of value.matchAll(
+ TEMPLATE_VARIABLE_PATTERN,
+ )) {
+ const campaignVariable =
+ parseTemplateVariableWithFallback(rawTemplateVariable);
+
+ if (isDefined(campaignVariable)) {
+ names.add(campaignVariable.name);
+ }
+ }
+
+ return names;
+};
diff --git a/packages/twenty-server/src/modules/emailing/utils/collect-campaign-variable-names-from-string.util.ts b/packages/twenty-server/src/modules/emailing/utils/collect-campaign-variable-names-from-string.util.ts
deleted file mode 100644
index eb93de645a1..00000000000
--- a/packages/twenty-server/src/modules/emailing/utils/collect-campaign-variable-names-from-string.util.ts
+++ /dev/null
@@ -1,17 +0,0 @@
-import { CAMPAIGN_VARIABLE_PATTERN } from 'src/modules/emailing/constants/campaign-variable-pattern.constant';
-
-export const collectCampaignVariableNamesFromString = (
- value: unknown,
-): Set<string> => {
- const names = new Set<string>();
-
- if (typeof value !== 'string') {
- return names;
- }
-
- for (const match of value.matchAll(CAMPAIGN_VARIABLE_PATTERN)) {
- names.add(match[1]);
- }
-
- return names;
-};
diff --git a/packages/twenty-server/src/modules/emailing/utils/collect-campaign-variable-names-from-templates-or-throw.util.ts b/packages/twenty-server/src/modules/emailing/utils/collect-campaign-variable-names-from-templates-or-throw.util.ts
new file mode 100644
index 00000000000..aaf8eb71871
--- /dev/null
+++ b/packages/twenty-server/src/modules/emailing/utils/collect-campaign-variable-names-from-templates-or-throw.util.ts
@@ -0,0 +1,31 @@
+import { type EmailDocumentNode, parseJson } from 'twenty-shared/utils';
+
+import { collectCampaignVariableNamesOrThrow } from 'src/modules/emailing/utils/collect-campaign-variable-names-or-throw.util';
+import { collectCampaignVariableNamesFromStringOrThrow } from 'src/modules/emailing/utils/collect-campaign-variable-names-from-string-or-throw.util';
+
+export const collectCampaignVariableNamesFromTemplatesOrThrow = ({
+ subject,
+ bodyTemplate,
+}: {
+ subject: string;
+ bodyTemplate: string;
+}): Set<string> => {
+ const names = new Set<string>(
+ collectCampaignVariableNamesFromStringOrThrow(subject),
+ );
+
+ const parsedBody = parseJson<EmailDocumentNode>(bodyTemplate);
+
+ const collected =
+ typeof parsedBody === 'object' &&
+ parsedBody !== null &&
+ parsedBody.type === 'doc'
+ ? collectCampaignVariableNamesOrThrow(parsedBody)
+ : collectCampaignVariableNamesFromStringOrThrow(bodyTemplate);
+
+ for (const name of collected) {
+ names.add(name);
+ }
+
+ return names;
+};
diff --git a/packages/twenty-server/src/modules/emailing/utils/collect-campaign-variable-names-from-templates.util.ts b/packages/twenty-server/src/modules/emailing/utils/collect-campaign-variable-names-from-templates.util.ts
deleted file mode 100644
index 54db409efba..00000000000
--- a/packages/twenty-server/src/modules/emailing/utils/collect-campaign-variable-names-from-templates.util.ts
+++ /dev/null
@@ -1,31 +0,0 @@
-import { type EmailDocumentNode, parseJson } from 'twenty-shared/utils';
-
-import { collectCampaignVariableNames } from 'src/modules/emailing/utils/collect-campaign-variable-names.util';
-import { collectCampaignVariableNamesFromString } from 'src/modules/emailing/utils/collect-campaign-variable-names-from-string.util';
-
-export const collectCampaignVariableNamesFromTemplates = ({
- subject,
- bodyTemplate,
-}: {
- subject: string;
- bodyTemplate: string;
-}): Set<string> => {
- const names = new Set<string>(
- collectCampaignVariableNamesFromString(subject),
- );
-
- const parsedBody = parseJson<EmailDocumentNode>(bodyTemplate);
-
- const collected =
- typeof parsedBody === 'object' &&
- parsedBody !== null &&
- parsedBody.type === 'doc'
- ? collectCampaignVariableNames(parsedBody)
- : collectCampaignVariableNamesFromString(bodyTemplate);
-
- for (const name of collected) {
- names.add(name);
- }
-
- return names;
-};
diff --git a/packages/twenty-server/src/modules/emailing/utils/collect-campaign-variable-names.util.ts b/packages/twenty-server/src/modules/emailing/utils/collect-campaign-variable-names-or-throw.util.ts
similarity index 52%
rename from packages/twenty-server/src/modules/emailing/utils/collect-campaign-variable-names.util.ts
rename to packages/twenty-server/src/modules/emailing/utils/collect-campaign-variable-names-or-throw.util.ts
index 706e9287243..d3d22b56d3e 100644
--- a/packages/twenty-server/src/modules/emailing/utils/collect-campaign-variable-names.util.ts
+++ b/packages/twenty-server/src/modules/emailing/utils/collect-campaign-variable-names-or-throw.util.ts
@@ -3,15 +3,15 @@ import {
transformEmailDocumentStrings,
} from 'twenty-shared/utils';
-import { collectCampaignVariableNamesFromString } from 'src/modules/emailing/utils/collect-campaign-variable-names-from-string.util';
+import { collectCampaignVariableNamesFromStringOrThrow } from 'src/modules/emailing/utils/collect-campaign-variable-names-from-string-or-throw.util';
-export const collectCampaignVariableNames = (
+export const collectCampaignVariableNamesOrThrow = (
node: EmailDocumentNode,
): Set<string> => {
const names = new Set<string>();
transformEmailDocumentStrings(node, (value) => {
- for (const name of collectCampaignVariableNamesFromString(value)) {
+ for (const name of collectCampaignVariableNamesFromStringOrThrow(value)) {
names.add(name);
}
diff --git a/packages/twenty-server/src/modules/emailing/utils/compile-campaign-batch-template.util.ts b/packages/twenty-server/src/modules/emailing/utils/compile-campaign-batch-template.util.ts
index 3362f3d3c71..e12b8d8a1e2 100644
--- a/packages/twenty-server/src/modules/emailing/utils/compile-campaign-batch-template.util.ts
+++ b/packages/twenty-server/src/modules/emailing/utils/compile-campaign-batch-template.util.ts
@@ -4,6 +4,8 @@ import {
isDefined,
parseCanonicalEmailDocument,
parseJson,
+ replaceTemplateVariables,
+ type TemplateVariableWithFallback,
} from 'twenty-shared/utils';
import { compileOutboundEmailContent } from 'src/engine/core-modules/email/utils/compile-outbound-email-content.util';
@@ -13,7 +15,6 @@ import {
EmailingDomainExceptionCode,
} from 'src/engine/core-modules/emailing-domain/exceptions/emailing-domain.exception';
import { type EmailingDomainEmailTemplate } from 'src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-email-template.type';
-import { CAMPAIGN_VARIABLE_PATTERN } from 'src/modules/emailing/constants/campaign-variable-pattern.constant';
const CAMPAIGN_BATCH_TAG_PREFIXES = {
htmlEscaped: 'v_h',
@@ -51,25 +52,31 @@ export const compileCampaignBatchTemplate = async ({
}): Promise<{
template: EmailingDomainEmailTemplate;
plainTextSourceHtml: string;
- variableNames: string[];
+ campaignVariables: TemplateVariableWithFallback[];
}> => {
- const variableNames: string[] = [];
-
- const indexOfVariable = (variableName: string): number => {
- const existingIndex = variableNames.indexOf(variableName);
+ const campaignVariables: TemplateVariableWithFallback[] = [];
+
+ const indexOfVariable = (
+ campaignVariable: TemplateVariableWithFallback,
+ ): number => {
+ const existingIndex = campaignVariables.findIndex(
+ ({ name, fallback }) =>
+ name === campaignVariable.name &&
+ fallback === campaignVariable.fallback,
+ );
if (existingIndex !== -1) {
return existingIndex;
}
- return variableNames.push(variableName) - 1;
+ return campaignVariables.push(campaignVariable) - 1;
};
const toTags = (value: string, tagFamily: CampaignBatchTagFamily): string =>
- value.replace(
- CAMPAIGN_VARIABLE_PATTERN,
- (_match, variableName) =>
- `{{${CAMPAIGN_BATCH_TAG_PREFIXES[tagFamily]}_${indexOfVariable(variableName)}}}`,
+ replaceTemplateVariables(
+ value,
+ (campaignVariable) =>
+ `{{${CAMPAIGN_BATCH_TAG_PREFIXES[tagFamily]}_${indexOfVariable(campaignVariable)}}}`,
);
const subject = toTags(subjectTemplate, 'raw');
@@ -78,7 +85,7 @@ export const compileCampaignBatchTemplate = async ({
return {
template: { subject, text: '', html: '' },
plainTextSourceHtml: '',
- variableNames,
+ campaignVariables,
};
}
@@ -115,6 +122,6 @@ export const compileCampaignBatchTemplate = async ({
plainTextSourceHtml: isDefined(plainTextSourceHtml)
? plainTextSourceHtml
: '',
- variableNames,
+ campaignVariables,
};
};
diff --git a/packages/twenty-server/src/modules/emailing/utils/render-campaign-template.util.ts b/packages/twenty-server/src/modules/emailing/utils/render-campaign-template.util.ts
index 0a19456ce54..97c2753165c 100644
--- a/packages/twenty-server/src/modules/emailing/utils/render-campaign-template.util.ts
+++ b/packages/twenty-server/src/modules/emailing/utils/render-campaign-template.util.ts
@@ -1,13 +1,15 @@
+import { replaceTemplateVariables } from 'twenty-shared/utils';
+
import { escapeHtml } from 'src/engine/core-modules/emailing-domain/utils/escape-html.util';
-import { CAMPAIGN_VARIABLE_PATTERN } from 'src/modules/emailing/constants/campaign-variable-pattern.constant';
+import { resolveCampaignVariableValue } from 'src/modules/emailing/utils/resolve-campaign-variable-value.util';
export const renderCampaignTemplate = (
template: string,
variables: Record<string, string>,
{ escapeValues }: { escapeValues: boolean },
): string =>
- template.replace(CAMPAIGN_VARIABLE_PATTERN, (_match, variableName) => {
- const value = variables[variableName] ?? '';
+ replaceTemplateVariables(template, (campaignVariable) => {
+ const value = resolveCampaignVariableValue({ campaignVariable, variables });
return escapeValues ? escapeHtml(value) : value;
});
diff --git a/packages/twenty-server/src/modules/emailing/utils/resolve-campaign-variable-value.util.ts b/packages/twenty-server/src/modules/emailing/utils/resolve-campaign-variable-value.util.ts
new file mode 100644
index 00000000000..d61872d6128
--- /dev/null
+++ b/packages/twenty-server/src/modules/emailing/utils/resolve-campaign-variable-value.util.ts
@@ -0,0 +1,21 @@
+import { isNonEmptyString } from '@sniptt/guards';
+import {
+ isDefined,
+ type TemplateVariableWithFallback,
+} from 'twenty-shared/utils';
+
+export const resolveCampaignVariableValue = ({
+ campaignVariable: { name, fallback },
+ variables,
+}: {
+ campaignVariable: TemplateVariableWithFallback;
+ variables: Record<string, string>;
+}): string => {
+ const value = Object.prototype.hasOwnProperty.call(variables, name)
+ ? (variables[name] ?? '')
+ : '';
+
+ return isDefined(fallback) && !isNonEmptyString(value.trim())
+ ? fallback
+ : value;
+};
diff --git a/packages/twenty-server/test/integration/emailing/save-campaign-variable-validation.integration-spec.ts b/packages/twenty-server/test/integration/emailing/save-campaign-variable-validation.integration-spec.ts
new file mode 100644
index 00000000000..d65cb841e8e
--- /dev/null
+++ b/packages/twenty-server/test/integration/emailing/save-campaign-variable-validation.integration-spec.ts
@@ -0,0 +1,40 @@
+import { getAppProviderByClassName } from 'test/integration/utils/get-app-provider-by-class-name.util';
+
+import { SEED_APPLE_WORKSPACE_ID } from 'src/engine/workspace-manager/dev-seeder/core/constants/seeder-workspaces.constant';
+import { USER_WORKSPACE_DATA_SEED_IDS } from 'src/engine/workspace-manager/dev-seeder/core/utils/seed-user-workspaces.util';
+import { type MessageCampaignDraftService } from 'src/modules/emailing/services/message-campaign-draft.service';
+
+const saveDraftWithVariable = (variable: string) =>
+ getAppProviderByClassName<MessageCampaignDraftService>(
+ 'MessageCampaignDraftService',
+ ).saveDraft({
+ workspaceId: SEED_APPLE_WORKSPACE_ID,
+ userWorkspaceId: USER_WORKSPACE_DATA_SEED_IDS.JANE,
+ subject: 'Hello',
+ body: {
+ type: 'doc',
+ content: [
+ {
+ type: 'paragraph',
+ content: [
+ { type: 'text', text: 'Hi ' },
+ { type: 'variableTag', attrs: { variable } },
+ ],
+ },
+ ],
+ },
+ });
+
+describe('Saving a campaign draft with variables', () => {
+ it('should reject a fallback written without the default filter', async () => {
+ await expect(
+ saveDraftWithVariable('{{jobTitle | "there"}}'),
+ ).rejects.toThrow('Malformed campaign variable: {{jobTitle | "there"}}');
+ });
+
+ it('should reject an unknown variable even when it has a fallback', async () => {
+ await expect(
+ saveDraftWithVariable('{{notAPersonField | default: "there"}}'),
+ ).rejects.toThrow('Unknown campaign variables: notAPersonField');
+ });
+});
diff --git a/packages/twenty-shared/src/utils/index.ts b/packages/twenty-shared/src/utils/index.ts
index 66acebd78ad..acb7327a7d6 100644
--- a/packages/twenty-shared/src/utils/index.ts
+++ b/packages/twenty-shared/src/utils/index.ts
@@ -242,6 +242,12 @@ export { pascalToKebab } from './strings/pascalToKebab';
export { stringifySafely } from './strings/stringifySafely';
export { uncapitalize } from './strings/uncapitalize';
export { getSubdomainSlugFromDisplayName } from './subdomain/getSubdomainSlugFromDisplayName';
+export { findMalformedTemplateVariable } from './template-variable/find-malformed-template-variable';
+export { formatTemplateVariableWithFallback } from './template-variable/format-template-variable-with-fallback';
+export { parseTemplateVariableWithFallback } from './template-variable/parse-template-variable-with-fallback';
+export { replaceTemplateVariables } from './template-variable/replace-template-variables';
+export { TEMPLATE_VARIABLE_PATTERN } from './template-variable/template-variable-pattern';
+export type { TemplateVariableWithFallback } from './template-variable/template-variable-with-fallback';
export type { CanvasTheme } from './tiptap/canvas-theme';
export { CANVAS_THEME_DEFAULTS } from './tiptap/canvas-theme';
export { convertEmailBodyToEmailDocument } from './tiptap/convert-email-body-to-email-document';
diff --git a/packages/twenty-shared/src/utils/template-variable/__tests__/find-malformed-template-variable.test.ts b/packages/twenty-shared/src/utils/template-variable/__tests__/find-malformed-template-variable.test.ts
new file mode 100644
index 00000000000..ee288153bc7
--- /dev/null
+++ b/packages/twenty-shared/src/utils/template-variable/__tests__/find-malformed-template-variable.test.ts
@@ -0,0 +1,31 @@
+import { findMalformedTemplateVariable } from '../find-malformed-template-variable';
+
+describe('findMalformedTemplateVariable', () => {
+ it('should find nothing when every variable is well formed', () => {
+ expect(
+ findMalformedTemplateVariable(
+ 'Hi {{name.firstName | default: "there"}}, {{jobTitle}} at {company}',
+ ),
+ ).toBeUndefined();
+ });
+
+ it('should return the first malformed variable', () => {
+ expect(
+ findMalformedTemplateVariable(
+ 'Hi {{name.firstName}}, {{jobTitle | there}} and {{oops!}}',
+ ),
+ ).toBe('{{jobTitle | there}}');
+ });
+
+ it('should catch a variable with braces in its fallback', () => {
+ expect(
+ findMalformedTemplateVariable('Hi {{jobTitle | default: {there}}}'),
+ ).toBe('{{jobTitle | default: {there}}');
+ });
+
+ it('should catch a variable that is never closed', () => {
+ expect(findMalformedTemplateVariable('Hi {{jobTitle there')).toBe(
+ '{{jobTitle there',
+ );
+ });
+});
diff --git a/packages/twenty-shared/src/utils/template-variable/__tests__/format-template-variable-with-fallback.test.ts b/packages/twenty-shared/src/utils/template-variable/__tests__/format-template-variable-with-fallback.test.ts
new file mode 100644
index 00000000000..301b774dcef
--- /dev/null
+++ b/packages/twenty-shared/src/utils/template-variable/__tests__/format-template-variable-with-fallback.test.ts
@@ -0,0 +1,32 @@
+import { formatTemplateVariableWithFallback } from '../format-template-variable-with-fallback';
+import { parseTemplateVariableWithFallback } from '../parse-template-variable-with-fallback';
+
+describe('formatTemplateVariableWithFallback', () => {
+ it('should write a bare variable when the fallback is empty', () => {
+ expect(
+ formatTemplateVariableWithFallback({ name: 'jobTitle', fallback: '' }),
+ ).toBe('{{jobTitle}}');
+ });
+
+ it('should write the fallback as a Liquid default filter', () => {
+ expect(
+ formatTemplateVariableWithFallback({
+ name: 'name.firstName',
+ fallback: 'there',
+ }),
+ ).toBe('{{name.firstName | default: "there"}}');
+ });
+
+ it('should round-trip a fallback containing quotes, backslashes and pipes', () => {
+ const templateVariableWithFallback = {
+ name: 'jobTitle',
+ fallback: 'the "boss" C:\\temp\\ | <b>',
+ };
+
+ expect(
+ parseTemplateVariableWithFallback(
+ formatTemplateVariableWithFallback(templateVariableWithFallback),
+ ),
+ ).toEqual(templateVariableWithFallback);
+ });
+});
diff --git a/packages/twenty-shared/src/utils/template-variable/__tests__/parse-template-variable-with-fallback.test.ts b/packages/twenty-shared/src/utils/template-variable/__tests__/parse-template-variable-with-fallback.test.ts
new file mode 100644
index 00000000000..4853584ee01
--- /dev/null
+++ b/packages/twenty-shared/src/utils/template-variable/__tests__/parse-template-variable-with-fallback.test.ts
@@ -0,0 +1,59 @@
+import { parseTemplateVariableWithFallback } from '../parse-template-variable-with-fallback';
+
+describe('parseTemplateVariableWithFallback', () => {
+ it('should read a variable without a fallback', () => {
+ expect(parseTemplateVariableWithFallback('{{ name.firstName }}')).toEqual({
+ name: 'name.firstName',
+ });
+ });
+
+ it('should read a Liquid default filter as the fallback', () => {
+ expect(
+ parseTemplateVariableWithFallback('{{jobTitle | default: "there"}}'),
+ ).toEqual({
+ name: 'jobTitle',
+ fallback: 'there',
+ });
+ expect(
+ parseTemplateVariableWithFallback(
+ '{{ name.firstName|default:"Note: x | y" }}',
+ ),
+ ).toEqual({ name: 'name.firstName', fallback: 'Note: x | y' });
+ });
+
+ it('should unescape quotes and backslashes in the fallback', () => {
+ expect(
+ parseTemplateVariableWithFallback(
+ '{{jobTitle | default: "the \\"boss\\" \\\\o/"}}',
+ ),
+ ).toEqual({ name: 'jobTitle', fallback: 'the "boss" \\o/' });
+ });
+
+ it('should reject near-miss fallback syntax', () => {
+ expect(
+ parseTemplateVariableWithFallback('{{jobTitle | there}}'),
+ ).toBeUndefined();
+ expect(
+ parseTemplateVariableWithFallback('{{jobTitle | "there"}}'),
+ ).toBeUndefined();
+ expect(
+ parseTemplateVariableWithFallback('{{jobTitle | default: there}}'),
+ ).toBeUndefined();
+ expect(
+ parseTemplateVariableWithFallback("{{jobTitle | default: 'there'}}"),
+ ).toBeUndefined();
+ expect(
+ parseTemplateVariableWithFallback('{{jobTitle | default: “there”}}'),
+ ).toBeUndefined();
+ expect(
+ parseTemplateVariableWithFallback('{{jobTitle | default: {there}}}'),
+ ).toBeUndefined();
+ });
+
+ it('should reject anything that is not exactly one variable', () => {
+ expect(
+ parseTemplateVariableWithFallback('Hi {{jobTitle}}'),
+ ).toBeUndefined();
+ expect(parseTemplateVariableWithFallback('{{job-title}}')).toBeUndefined();
+ });
+});
diff --git a/packages/twenty-shared/src/utils/template-variable/__tests__/replace-template-variables.test.ts b/packages/twenty-shared/src/utils/template-variable/__tests__/replace-template-variables.test.ts
new file mode 100644
index 00000000000..d64528c48dd
--- /dev/null
+++ b/packages/twenty-shared/src/utils/template-variable/__tests__/replace-template-variables.test.ts
@@ -0,0 +1,21 @@
+import { replaceTemplateVariables } from '../replace-template-variables';
+
+describe('replaceTemplateVariables', () => {
+ it('should replace each variable with what the callback returns for it', () => {
+ expect(
+ replaceTemplateVariables(
+ 'Hi {{name.firstName | default: "there"}} at {{companyName}}',
+ ({ name, fallback }) => `[${name}:${fallback ?? '-'}]`,
+ ),
+ ).toBe('Hi [name.firstName:there] at [companyName:-]');
+ });
+
+ it('should leave text that is not a variable untouched', () => {
+ expect(
+ replaceTemplateVariables(
+ 'Hi {{jobTitle | there}} at {company}',
+ () => 'X',
+ ),
+ ).toBe('Hi {{jobTitle | there}} at {company}');
+ });
+});
diff --git a/packages/twenty-shared/src/utils/template-variable/find-malformed-template-variable.ts b/packages/twenty-shared/src/utils/template-variable/find-malformed-template-variable.ts
new file mode 100644
index 00000000000..531f020d6f8
--- /dev/null
+++ b/packages/twenty-shared/src/utils/template-variable/find-malformed-template-variable.ts
@@ -0,0 +1,25 @@
+import { replaceTemplateVariables } from './replace-template-variables';
+
+export const findMalformedTemplateVariable = (
+ template: string,
+): string | undefined => {
+ const templateWithoutValidVariables = replaceTemplateVariables(
+ template,
+ () => '',
+ );
+ const malformedStartIndex = templateWithoutValidVariables.indexOf('{{');
+
+ if (malformedStartIndex === -1) {
+ return undefined;
+ }
+
+ const malformedEndIndex = templateWithoutValidVariables.indexOf(
+ '}}',
+ malformedStartIndex,
+ );
+
+ return templateWithoutValidVariables.slice(
+ malformedStartIndex,
+ malformedEndIndex === -1 ? undefined : malformedEndIndex + 2,
+ );
+};
diff --git a/packages/twenty-shared/src/utils/template-variable/format-template-variable-with-fallback.ts b/packages/twenty-shared/src/utils/template-variable/format-template-variable-with-fallback.ts
new file mode 100644
index 00000000000..7a71820c460
--- /dev/null
+++ b/packages/twenty-shared/src/utils/template-variable/format-template-variable-with-fallback.ts
@@ -0,0 +1,11 @@
+import { isNonEmptyString } from '@sniptt/guards';
+
+import { type TemplateVariableWithFallback } from './template-variable-with-fallback';
+
+export const formatTemplateVariableWithFallback = ({
+ name,
+ fallback,
+}: TemplateVariableWithFallback): string =>
+ isNonEmptyString(fallback)
+ ? `{{${name} | default: "${fallback.replace(/["\\]/g, '\\$&')}"}}`
+ : `{{${name}}}`;
diff --git a/packages/twenty-shared/src/utils/template-variable/parse-template-variable-with-fallback.ts b/packages/twenty-shared/src/utils/template-variable/parse-template-variable-with-fallback.ts
new file mode 100644
index 00000000000..c384913a5f1
--- /dev/null
+++ b/packages/twenty-shared/src/utils/template-variable/parse-template-variable-with-fallback.ts
@@ -0,0 +1,41 @@
+import { isNonEmptyArray } from '@/utils/array/isNonEmptyArray';
+import { isDefined } from '@/utils/validation/isDefined';
+
+import { type TemplateVariableWithFallback } from './template-variable-with-fallback';
+
+const STANDALONE_TEMPLATE_VARIABLE_PATTERN = /^{{([^{}]+)}}$/;
+
+const TEMPLATE_VARIABLE_NAME_PATTERN = /^[a-zA-Z]\w*(?:\.[a-zA-Z]\w*)*$/;
+
+const DEFAULT_FILTER_PATTERN = /^default\s*:\s*"((?:[^"\\]|\\["\\])*)"$/;
+
+export const parseTemplateVariableWithFallback = (
+ rawTemplateVariable: string,
+): TemplateVariableWithFallback | undefined => {
+ const [, templateVariableContent] =
+ rawTemplateVariable.match(STANDALONE_TEMPLATE_VARIABLE_PATTERN) ?? [];
+
+ if (!isDefined(templateVariableContent)) {
+ return undefined;
+ }
+
+ const [rawName = '', ...rawFilterParts] = templateVariableContent.split('|');
+ const name = rawName.trim();
+
+ if (!TEMPLATE_VARIABLE_NAME_PATTERN.test(name)) {
+ return undefined;
+ }
+
+ if (!isNonEmptyArray(rawFilterParts)) {
+ return { name };
+ }
+
+ const [, escapedFallback] =
+ rawFilterParts.join('|').trim().match(DEFAULT_FILTER_PATTERN) ?? [];
+
+ if (!isDefined(escapedFallback)) {
+ return undefined;
+ }
+
+ return { name, fallback: escapedFallback.replace(/\\(["\\])/g, '$1') };
+};
diff --git a/packages/twenty-shared/src/utils/template-variable/replace-template-variables.ts b/packages/twenty-shared/src/utils/template-variable/replace-template-variables.ts
new file mode 100644
index 00000000000..6a921a09ab3
--- /dev/null
+++ b/packages/twenty-shared/src/utils/template-variable/replace-template-variables.ts
@@ -0,0 +1,20 @@
+import { isDefined } from '@/utils/validation/isDefined';
+
+import { parseTemplateVariableWithFallback } from './parse-template-variable-with-fallback';
+import { TEMPLATE_VARIABLE_PATTERN } from './template-variable-pattern';
+import { type TemplateVariableWithFallback } from './template-variable-with-fallback';
+
+export const replaceTemplateVariables = (
+ template: string,
+ replaceTemplateVariable: (
+ templateVariable: TemplateVariableWithFallback,
+ ) => string,
+): string =>
+ template.replace(TEMPLATE_VARIABLE_PATTERN, (rawTemplateVariable) => {
+ const templateVariable =
+ parseTemplateVariableWithFallback(rawTemplateVariable);
+
+ return isDefined(templateVariable)
+ ? replaceTemplateVariable(templateVariable)
+ : rawTemplateVariable;
+ });
diff --git a/packages/twenty-shared/src/utils/template-variable/template-variable-pattern.ts b/packages/twenty-shared/src/utils/template-variable/template-variable-pattern.ts
new file mode 100644
index 00000000000..5dee2a44d76
--- /dev/null
+++ b/packages/twenty-shared/src/utils/template-variable/template-variable-pattern.ts
@@ -0,0 +1 @@
+export const TEMPLATE_VARIABLE_PATTERN = /{{[^{}]+}}/g;
diff --git a/packages/twenty-shared/src/utils/template-variable/template-variable-with-fallback.ts b/packages/twenty-shared/src/utils/template-variable/template-variable-with-fallback.ts
new file mode 100644
index 00000000000..75a00ed2056
--- /dev/null
+++ b/packages/twenty-shared/src/utils/template-variable/template-variable-with-fallback.ts
@@ -0,0 +1,4 @@
+export type TemplateVariableWithFallback = {
+ name: string;
+ fallback?: string;
+};