> For the complete documentation index, see [llms.txt](https://docs.timvero.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.timvero.com/timveroos-how-to-library/introduction.md).

# Campaigns in timveroOS

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.timvero.com/timveroos-how-to-library/introduction.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.