Introduction

The campaign mechanism is designed to automate marketing and product-related processes in a digital bank or financial platform. It enables the execution of targeted actions based on predefined conditions and for selected customer groups.

Purpose of the Mechanism

• Mass generation of personalized product offers (e.g., loans or services)

• Pilot launches of new products for limited audiences

• A/B testing of different offer strategies

• Automation of marketing scenarios and initiatives

Campaign Capabilities

• Support for both manual and automatic launches (via schedule)

• Flexible customer filtering using JavaScript or Python scripts

• Binding to specific products (via product codes)

• Repeatable executions on a recurring basis (restartable)

• Integration with application processes

• UI interfaces for managing and tracking campaigns

Architecture and Component Overview

• Campaign — entity that describes a campaign (extends HistoryEntity)

• CampaignExecution — instance of a campaign launch (extends BaseEntity)

• CampaignService — service for managing campaigns

• CampaignExecutionService — service for executing campaigns and selecting customers

• Producer / Consumer — components for automatic campaign triggering

• ScriptManager — engine for executing customer filtering scripts

• EntityChecker — mechanism for post-processing executions (e.g., creating applications)

• UI — controllers, actions, tabs, templates (Thymeleaf)

High-Level Flow

1. Campaign Creation: Set up via UI with name, launch type, filtering expression, products, and schedule parameters

2. Launch Configuration: Choose mode — manual or scheduled automatic with periodicity

3. CampaignExecution Creation: A new execution entity is created for each launch

4. Customer Selection by Expression: During execution, the script selects matching customers

5. Execution and Post-Processing: Customers receive offers, and applications are created (via Checker)

---

📌 Useful Classes from the timveroOS Platform:

Component	Purpose
HistoryEntity	Automatic versioning, hiding of outdated records
BaseEntity	Base class for all simple entities
EntityChecker	Entity lifecycle handling (e.g., actions after status = FINISHED)
SynchronousAccessRepository	The getSync(id) method locks access to the object until the transaction completes
TransactionUtils.afterTransaction(...)	Allows triggering actions after a successful commit
ScriptManager	Compilation and execution of JavaScript/Python expressions with secure sandbox support

---

💡 Developer Recommendations

• Do not call setActive(false) directly — versioning is handled automatically by HistoryEntityFormService.

• Always check executionType before launching — only active and valid-status campaigns should be executed.

• Avoid calling runExecution(...) outside a new transaction — use CampaignExecutionConsumer or TransactionTemplateBuilder instead.

• Always validate the result of ScriptManager.compile(...) for expressions — a ScriptException may be thrown.

• In Producer/Consumer, always use requiresNew() — to prevent overlap with external transactions.

---

🧪 Checklist for Implementing a New Campaign

✅ Model	Create a Campaign, add fields and relationships
✅ UI	Configure forms, tabs, and templates
✅ Controller	Add CampaignController, CampaignFormService
✅ Execution	Implement execution via CampaignService / ExecutionService
✅ Script	Test the expression in the UI
✅ Post-processing	Add an EntityChecker if application creation or other actions are needed

---

🛠 Possible Extensions to Add

• Client notifications after application creation

• Execution history and filter logs tracking

• Campaign metrics (number of clients, response rate, etc.)

• Dashboard for visualizing campaign progress and statuses

• Configurable triggers for campaign launches