Timvero SDK reference guide

@Entity
@Table
@Audited
@Indexed
public class Client extends AbstractAuditable<UUID> implements NamedEntity, HasDocuments {

    @Embedded
    @Valid
    private IndividualInfo individualInfo;

    @Embedded
    @Valid
    private ContactInfo contactInfo;

    // getters and setters...
}

public class ClientForm {

    @Valid
    @NotNull
    private IndividualInfoForm individualInfo;

    @Valid
    @NotNull
    private ContactInfoForm contactInfo;

    // getters and setters...
}

@Controller
public class ClientController extends EntityController<UUID, Client, ClientForm> {
    // Inherits all CRUD functionality automatically
}

@Controller
public class CreateClientAction extends EntityCreateController<UUID, Client, ClientForm> {
    @Override
    protected boolean isOwnPage() {
        return false;
    }
}

@Controller
public class EditClientAction extends EditEntityActionController<UUID, Client, ClientForm> {
    // Handles the edit button functionality
}

@Service
public class ClientFormService extends EntityFormService<Client, ClientForm, UUID> {
    // Inherits entity-form mapping and persistence operations
}

@Mapper
public interface ClientFormMapper extends EntityToFormMapper<Client, ClientForm> {
    // MapStruct automatically generates implementation for bidirectional mapping
}

<th:block th:insert="~{/form/components :: text(
    #{client.individualInfo.fullName},
    'individualInfo.fullName',
    'v-required v-name')}" />

<th:block th:insert="~{/form/components :: text(
    #{client.contactInfo.email},
    'contactInfo.email',
    'v-required v-email')}" />

User Input → Form Validation → Controller → Service → Mapper → Entity → Database
                     ↓
             Template Rendering ← Form Object ← Mapper ← Entity ← Database Query

public class ClientForm {
    @NotBlank
    @Size(min = 2, max = 100, message = "Name must be between 2 and 100 characters")
    private String fullName;

    @NotBlank
    @Email(message = "Please provide a valid email address")
    private String email;

    @NotBlank
    @Phone(message = "Please provide a valid phone number")
    private String phone;

    @PastOrPresent(message = "Birth date cannot be in the future")
    private LocalDate dateOfBirth;
}

@Component
public class ClientWelcomeChecker extends EntityChecker<Client> {

    @Override
    protected void registerListeners(CheckerListenerRegistry<Client> registry) {
        // Trigger when a new client is created
        registry.entityChange().inserted();
    }

    @Override
    protected boolean isAvailable(Client client) {
        // Only for clients with complete contact information
        return client.getContactInfo() != null
            && client.getContactInfo().getEmail() != null;
    }

    @Override
    protected void perform(Client client) {
        // Send welcome email to new clients
        emailService.sendWelcomeEmail(client);
        log.info("Welcome email sent to client: {}", client.getIndividualInfo().getFullName());
    }
}

// 1. Make Client support documents
@Entity
public class Client extends AbstractAuditable<UUID> implements HasDocuments {
    // Existing client implementation
}

// 2. Configure document types
@Configuration
public class ClientDocumentConfiguration {

    public static final EntityDocumentType ID_DOCUMENT = new EntityDocumentType("ID_DOCUMENT");
    public static final EntityDocumentType PROOF_OF_ADDRESS = new EntityDocumentType("PROOF_OF_ADDRESS");

    @Bean
    DocumentTypeAssociation<Client> clientRequiredDocuments() {
        return DocumentTypeAssociation.forEntityClass(Client.class)
            .required(ID_DOCUMENT)
            .required(PROOF_OF_ADDRESS)
            .build();
    }
}

// 3. Add document management tab
@Controller
@Order(1000)
public class ClientDocumentsTab extends EntityDocumentTabController<Client> {

    @Override
    public boolean isVisible(Client client) {
        return true; // Always show documents tab for clients
    }
}

// 1. Create a data source subject interface
public interface CreditCheckSubject {
    String getNationalId();
    String getFullName();
}

// 2. Implement the interface in your entity
@Entity
public class Client implements CreditCheckSubject {

    @Override
    public String getNationalId() {
        return getIndividualInfo().getNationalId();
    }

    @Override
    public String getFullName() {
        return getIndividualInfo().getFullName();
    }
}

// 3. Create the data source implementation
@Service("creditCheck")
public class CreditCheckDataSource implements MappedDataSource<CreditCheckSubject, CreditReport> {

    @Override
    public Class<CreditReport> getType() {
        return CreditReport.class;
    }

    @Override
    public Content getData(CreditCheckSubject subject) throws Exception {
        // Call external credit check API
        String response = creditCheckApi.checkCredit(
            subject.getNationalId(),
            subject.getFullName()
        );
        return new Content(response.getBytes(), MediaType.APPLICATION_JSON_VALUE);
    }

    @Override
    public CreditReport parseRecord(Content data) throws Exception {
        return objectMapper.readValue(data.getData(), CreditReport.class);
    }
}

@Entity
@Table
@Audited
public class Participant extends AbstractAuditable implements NamedEntity, GithubDataSourceSubject, HasDocuments,
    ProcessEntity, DocusignSigner, HasPendingDecisions, HasMetric {

    public static final String DECISION_OWNER_TYPE = "PARTICIPANT";

    @Column(nullable = false)
    @Enumerated(value = EnumType.STRING)
    private ParticipantStatus status = ParticipantStatus.NEW;

    @ElementCollection(fetch = FetchType.EAGER)
    @Enumerated(EnumType.STRING)
    private Set<ParticipantRole> roles;

    @ManyToOne(fetch = EAGER)
    @JoinColumn(nullable = false, updatable = false)
    private Application application;

    @ManyToOne(fetch = EAGER)
    @JoinColumn(nullable = false, updatable = false)
    private Client client;

    @Column(nullable = false)
    @Enumerated(STRING)
    private Employment employment;

    @Column(nullable = false)
    @Enumerated(STRING)
    private Periodicity howOftenIncomeIsPaid;

    @Embedded
    private MonetaryAmount totalAnnualIncome;

    @Embedded
    private MonetaryAmount monthlyOutgoings;

    @Column
    private String githubUsername;
    // getters and setters...
}

public enum ParticipantStatus implements InEnum<ParticipantStatus> {
    NEW,
    IN_PROCESS,
    MANUAL_APPROVAL,
    APPROVED,
    DECLINED,
    VOID;

    public boolean isActive() {
        return !this.in(DECLINED, VOID);
    }
}

public enum Employment {

    EMPLOYED,
    HOMEMAKER,
    UNEMPLOYED,
    RETIRED,
    SELF_EMPLOYED

}

public enum Periodicity {

    MONTHLY,
    FORTNIGHTLY,
    WEEKLY,
    UNDEFINED

}

V{version}__{description}.sql

V250530170222__init.sql
V250609220043__participantStatus.sql

    create table participant (
        id uuid not null,
        created_at timestamp(6) with time zone not null,
        updated_at timestamp(6) with time zone not null,
        employment varchar(255) not null,
        how_often_income_is_paid varchar(255) not null,
        monthly_outgoings_currency varchar(3),
        monthly_outgoings_number numeric(19,2),
        total_annual_income_currency varchar(3),
        total_annual_income_number numeric(19,2),
        created_by uuid,
        updated_by uuid,
        -- Foreign key to application table
        application_id uuid not null,
        -- Foreign key to client table
        client_id uuid not null,
        primary key (id)
    );

    -- Foreign key constraints for participant table
    -- Links participant to their associated loan application
    alter table if exists participant 
       add constraint FKa8akyngsbkcpy4ev19q53x56h 
       foreign key (application_id) 
       references application;

    -- Links participant to their client profile containing personal information
    alter table if exists participant 
       add constraint FKcmejtugfqk653qthh0jalsx54 
       foreign key (client_id) 
       references client;

-- Migration: Add participant status functionality

-- Add status column to audit table (for historical tracking)
alter table if exists aud_participant 
   add column status varchar(255);

-- Add status column to main participant table
alter table if exists participant 
   add column status varchar(255);

-- Set default status for all existing participants
update participant set status = 'NEW';

-- Make status column mandatory after setting default values
alter table if exists participant 
   alter column status set not null;

@NotNull          // Field cannot be null
@NotBlank         // String field cannot be null, empty, or whitespace only
@Email            // Valid email format
@PastOrPresent    // Date must be in the past or present
@Valid            // Cascade validation to nested objects
@Phone            // Custom phone validation (platform-specific)

@Controller
public class CreateClientAction extends EntityCreateController<UUID, Client, ClientForm> {

    @Override
    protected boolean isOwnPage() {
        return false;
    }
}
@Controller
public class EditClientAction extends EditEntityActionController<UUID, Client, ClientForm> {

}

@Service
public class ClientFormService extends EntityFormService<Client, ClientForm, UUID> {

@Mapper
public interface ClientFormMapper extends EntityToFormMapper<Client, ClientForm> {
@Mapper(uses = ParticipantFormMapper.class)
public interface ApplicationFormMapper extends EntityToFormMapper<Application, ApplicationForm> {
@Mapper
public interface ParticipantFormMapper extends EntityToFormMapper<Participant, ParticipantForm> {

EditClientAction<UUID, Client, ClientForm>
    ↓
ClientFormService.prepareEditModel(UUID id)
    ↓
ClientFormMapper.entityToForm(Client entity)
    ↓
ClientForm (ready for template rendering)

CreateClientAction<UUID, Client, ClientForm>
    ↓
ClientFormService.save(ClientForm form)
    ↓
ClientFormMapper.formToEntity(ClientForm form)
    ↓
Client entity (persisted to database)

        <h2 class="form-group__title" th:text="#{client.clientInfo}">Personal
            Information</h2>
        <th:block
            th:insert="~{/form/components :: text(#{client.individualInfo.fullName},
                'individualInfo.fullName', 'v-required v-name')}"
            th:with="maxlength = 120" />
        <th:block
            th:insert="~{/form/components :: text(#{client.individualInfo.nationalId},
                'individualInfo.nationalId', 'v-required')}" />
        <th:block
            th:insert="~{/form/components :: date (#{client.individualInfo.birthDate},
                'individualInfo.dateOfBirth', '')}"
            th:with="maxDate = ${#dates.createNow()}" />
        <th:block
            th:insert="~{/form/components :: select(#{client.address.stateOfResidence},
                'individualInfo.residenceCountry', ${countries})}" />

        <h2 class="form-group__title" th:text="#{client.contactInfo}">Contact
            Information</h2>
        <th:block
            th:insert="~{/form/components :: text(#{client.contactInfo.email},
                'contactInfo.email', 'v-required v-email')}" />
        <th:block
            th:insert="~{/form/components :: text(#{client.contactInfo.phone},
                'contactInfo.phone', 'v-required v-phone')}" />

        <h2 th:text="#{application.borrowerInfo}">Borrower
            Information</h2>
        <th:block
            th:insert="~{/form/components :: select(#{participant.employment},
                'borrowerParticipant.employment', ${employmentTypes})}" />
        <th:block
            th:insert="~{/form/components :: select(#{participant.howOftenIncomeIsPaid},
                'borrowerParticipant.howOftenIncomeIsPaid', ${periodicities})}" />

        <h2 class="mt-10" th:text="#{participant.financialInfo}">Financial
            Information</h2>
        <th:block
            th:insert="~{/form/components :: amount(#{participant.totalAnnualIncome},
                'borrowerParticipant.totalAnnualIncome', 'v-required')}" />
        <th:block
            th:insert="~{/form/components :: amount(#{participant.monthlyOutgoings},
                'borrowerParticipant.monthlyOutgoings', '')}" />

// Armenian name validation (Armenian letters, spaces, hyphens only)
$.validator.addMethod('armenianName', function(value, element) {
  const ARMENIAN_NAME_REGEX = /^[\u0531-\u0556\u0561-\u0587\s\-']+$/;
  return this.optional(element) || ARMENIAN_NAME_REGEX.test(value);
});

// Tax identification number validation (Armenian format)
$.validator.addMethod('armenianTaxId', function(value, element) {
  const TAX_ID_REGEX = /^\d{8}$/;
  return this.optional(element) || TAX_ID_REGEX.test(value);
});

// Armenian postal code validation
$.validator.addMethod('armenianPostal', function(value, element) {
  const POSTAL_REGEX = /^\d{4}$/;
  return this.optional(element) || POSTAL_REGEX.test(value);
});

$.validator.addClassRules({
  'v-armenian-name': {armenianName: true, maxlength: 256},
  'v-armenian-tax-id': {armenianTaxId: true},
  'v-armenian-postal': {armenianPostal: true},
});

<!-- Required text field with name validation -->
<th:block th:insert="~{/form/components :: text(
  #{client.individualInfo.fullName},
  'individualInfo.fullName',
  'v-required v-name')}" />

<!-- Required email field -->
<th:block th:insert="~{/form/components :: text(
  #{client.contactInfo.email},
  'contactInfo.email',
  'v-required v-email')}" />

<!-- Required positive amount field -->
<th:block th:insert="~{/form/components :: amount(
  #{participant.totalAnnualIncome},
  'borrowerParticipant.totalAnnualIncome',
  'v-required v-positive')}" />

## Quick Search (uses Lucene backend by default)
hibernate.search.enabled=true
hibernate.search.backend.directory.root=/index

## Quick Search with Elasticsearch
hibernate.search.enabled=true
hibernate.search.backend.type=elasticsearch
hibernate.search.backend.hosts=localhost:9200
hibernate.search.backend.protocol=http

@Entity
@Indexed
public class Client extends AbstractAuditable<UUID> {

    @FullTextField  // Natural language search
    private String fullName;

    @KeywordField   // Exact matches only
    private String nationalId;

    @IndexedEmbedded  // Include nested fields
    private ContactInfo contactInfo;
}

@Configuration
@ConditionalOnProperty("hibernate.search.enabled")
public class ClientSearchConfig {

    @Bean
    FastSearchEntity<Client> clientSearchEntity() {
        return new FastSearchEntity<>(Client.class, Client::getDisplayedName);
    }
}

@Bean
FastSearchEntity<Client> clientSearchEntity() {
    return new FastSearchEntity<>(Client.class, Client::getDisplayedName);
}

@Bean
FastSearchEntity<Client> clientSearchEntity() {
    return new FastSearchEntity<>(Client.class, client -> {
        String name = client.getIndividualInfo().getFullName();
        String id = client.getIndividualInfo().getNationalId();
        return name + " (" + id + ")";
    });
}

@Bean
FastSearchEntity<Client> clientSearchEntity() {
    FastSearchEntity<Client> entity = new FastSearchEntity<>(Client.class, Client::getDisplayedName);
    entity.setLayoutTemplateName("/client/search :: client-result");
    return entity;
}

@Configuration
@ConditionalOnProperty("hibernate.search.enabled")
public class SearchConfig {

    @Bean
    FastSearchEntity<Client> clientSearchEntity() {
        return new FastSearchEntity<>(Client.class, Client::getDisplayedName);
    }

    @Bean
    FastSearchEntity<Application> applicationSearchEntity() {
        return new FastSearchEntity<>(Application.class, app ->
            "Application #" + app.getId());
    }
}

public interface EntityCounter<T> {
    boolean isEntityMarked(T entity);
    String getName();
}

package com.timvero.example.admin.application.counter;

import com.timvero.example.admin.application.entity.Application;
import com.timvero.example.admin.application.entity.ApplicationStatus;
import com.timvero.ground.entity_marker.counter.EntityCounter;
import org.springframework.core.annotation.Order;
import org.springframework.stereotype.Component;

@Component
@Order(2000)
public class ApplicationManualReviewCounter implements EntityCounter<Application> {

    @Override
    public boolean isEntityMarked(Application entity) {
        return entity.getStatus() == ApplicationStatus.MANUAL_REVIEW;
    }

    @Override
    public String getName() {
        return "applicationManualReview";
    }
}

package com.timvero.example.admin.credit.counter;

import com.timvero.example.admin.credit.entity.ExampleCredit;
import com.timvero.example.admin.credit.label.CreditPaidLabel;
import com.timvero.ground.entity_marker.counter.EntityCounter;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.core.annotation.Order;
import org.springframework.stereotype.Component;

@Component
@Order(3000)
public class CreditActiveAndPaidCounter implements EntityCounter<ExampleCredit> {

    @Autowired
    private CreditPaidLabel creditPaidLabel;

    @Override
    public boolean isEntityMarked(ExampleCredit entity) {
        return creditPaidLabel.isEntityMarked(entity);
    }

    @Override
    public String getName() {
        return "creditActiveAndPaid";
    }
}

package com.timvero.example.admin.credit.label;


import static com.timvero.example.admin.credit.CreditCalculationConfiguration.ACTIVE;

import com.timvero.example.admin.credit.entity.ExampleCredit;
import com.timvero.ground.entity_marker.label.EntityLabel;
import java.util.Optional;
import javax.money.MonetaryAmount;
import org.springframework.core.annotation.Order;
import org.springframework.stereotype.Component;

@Component
@Order(2000)
public class CreditPaidLabel implements EntityLabel<ExampleCredit> {

    @Override
    public boolean isEntityMarked(ExampleCredit entity) {
        if (entity.getActualSnapshot() == null) {
            return false;
        }
        Optional<MonetaryAmount> totalDebt = entity.getActualSnapshot().getDebt().getTotal();
        return entity.getActualSnapshot().getStatus().equals(ACTIVE) && totalDebt.isEmpty();
    }

    @Override
    public String getName() {
        return "paid";
    }
}

@Component
@Order(1000)  // Lower numbers = higher priority (appear first)
public class MyEntityCounter implements EntityCounter<MyEntity> {

    @Override
    public boolean isEntityMarked(MyEntity entity) {
        // Your counting logic here
        return entity.getStatus() == MyEntityStatus.NEEDS_ATTENTION;
    }

    @Override
    public String getName() {
        return "myEntityCounter";  // Used for templates and i18n
    }
}

counter.applicationManualReview=Applications for Manual Review
counter.creditActiveAndPaid=Active and Paid Loans
counter.myEntityCounter=My Custom Counter

@Order(1000)  // Appears first
public class HighPriorityCounter implements EntityCounter<Entity> { ... }

@Order(2000)  // Appears second
public class MediumPriorityCounter implements EntityCounter<Entity> { ... }

@Order(3000)  // Appears third
public class LowPriorityCounter implements EntityCounter<Entity> { ... }

<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<th:block th:fragment="entity(entities)">
    <ul class="counter-list">
        <li
            class="counter-list__item"
            th:each="entity,iterStat : ${entities}"
        >
            <button class="clickable counter-list__btn" th:href="@{${url} + '/' + ${entity.id}}" th:object="${entity}">
                <p class="d-flex justify-content-between w-100">
                    <span class="text-left text-prompt w-75" th:text="*{displayedName}"></span>
                    <span th:text="*{#ldates.format(createdAt, 'MM/dd/yyyy')}"></span>
                </p>
            </button>
        </li>
    </ul>
</th:block>
</html>

<div class="counters-wrapper">
    <div class="counter__item" th:each="entity,iterStat : ${counterList}" th:object="${entity}">
        <th:block th:insert="~{:: counterCard(${entity})}"/>
        <section
            th:data-for-counter="${entity}"
            th:data-counter-url="'/counter/' + ${entity} + '?count=10'"
            class="mt-5">
        </section>
        <button class="counter__item-btn js-show-full-counter-list" th:text="#{common.viewAll}"></button>
    </div>
</div>

<th:block th:fragment="counterCard(counterName)">
    <div class="counterCard">
        <div class="counterCard-title">
            <h4 th:text="#{'counter.' + ${counterName}}"></h4>
            <div class="d-flex flex-column align-items-end">
                <span class="d-flex counter">
                    <span
                        th:data-name="${counterName}"
                        th:data-title="#{'counter.' + ${counterName}}">
                    </span>
                </span>
            </div>
        </div>
    </div>
</th:block>

// Good: Simple property checks
public boolean isEntityMarked(Application app) {
    return app.getStatus() == ApplicationStatus.MANUAL_REVIEW;
}

// Avoid: Complex database queries in counter logic
public boolean isEntityMarked(Application app) {
    // Don't do this - too expensive for counting
    List<Document> docs = documentRepository.findByApplicationId(app.getId());
    return docs.stream().anyMatch(doc -> doc.getStatus() == DocumentStatus.MISSING);
}

@Component
public class MyCounter implements EntityCounter<MyEntity> {

    @Autowired
    private MyComplexLabel complexLabel;  // Reuse existing logic

    @Override
    public boolean isEntityMarked(MyEntity entity) {
        return complexLabel.isEntityMarked(entity);  // Delegate
    }
}

// If your counter needs related entities, optimize the query
@Query("SELECT e FROM MyEntity e " +
       "JOIN FETCH e.relatedEntity " +
       "WHERE e.status = :status")
List<MyEntity> findEntitiesForCounter(@Param("status") EntityStatus status);

// Good: Focused on one criteria
public class ApplicationManualReviewCounter implements EntityCounter<Application> {
    public boolean isEntityMarked(Application app) {
        return app.getStatus() == ApplicationStatus.MANUAL_REVIEW;
    }
}

// Avoid: Multiple unrelated criteria
public class MixedCriteriaCounter implements EntityCounter<Application> {
    public boolean isEntityMarked(Application app) {
        return app.getStatus() == ApplicationStatus.MANUAL_REVIEW ||
               app.getAmount().isGreaterThan(THRESHOLD) ||
               app.getCreatedAt().isBefore(CUTOFF_DATE);  // Too many different concerns
    }
}

// Good: Clear business meaning
public String getName() {
    return "applicationManualReview";  // Clear what this counts
}

// Avoid: Generic or unclear names
public String getName() {
    return "counter1";  // What does this count?
}

// Applications
@Order(1000) public class ApplicationSubmittedCounter { ... }
@Order(1100) public class ApplicationManualReviewCounter { ... }
@Order(1200) public class ApplicationApprovedCounter { ... }

// Credits
@Order(2000) public class CreditActiveCounter { ... }
@Order(2100) public class CreditOverdueCounter { ... }
@Order(2200) public class CreditPaidCounter { ... }

# Good: Clear business context
counter.applicationManualReview=Applications Requiring Review
counter.overduePayments=Overdue Payments
counter.incompleteDocumentation=Missing Documentation

# Avoid: Technical or vague labels
counter.status1=Status 1 Items
counter.items=Items
counter.counter=Counter

Solution: Ensure counter class is annotated with @Component and is in a
package scanned by Spring component scanning.

Solution: Debug the isEntityMarked() method with test data. Check that your
criteria match actual entity states in the database.

Solution: Add counter.{counterName}=Display Label to messages_en.properties
file. Ensure the counter name matches exactly.

Solution: Use @Order annotation with appropriate numeric values. Lower
numbers appear first on the dashboard.

Solution: Profile the isEntityMarked() method. Move complex logic to
entity labels or optimize database queries used by the counter.

Solution: Ensure workflow completion events properly trigger entity
updates. Consider adding @Transactional annotations with proper
propagation to avoid race conditions.

public class LaunchpadEntityDto {
    private Long targetEntityId;      // Primary entity ID
    private Object parentEntity;      // Parent/container entity
    private String parentDisplayName; // Parent entity display name
    private Object targetEntity;      // Target entity with pending decisions
    private String targetDisplayName; // Target entity display name
    private String roleDescription;   // Context description (roles, status, etc.)
    private String templatePath;      // Path to Launchpad template fragment
}

@Component
public class ParticipantLaunchpadService implements DecisionEntityExtractor {

    @Autowired
    private ParticipantRepository repository;

    @Override
    public String getDecisionOwnerType() {
        return Participant.DECISION_OWNER_TYPE;
    }

    @Override
    public LaunchpadEntityDto getByHolderId(Long holderId) {
        Participant participant = repository.findByPendingDecisionHolderId(holderId)
            .orElseThrow(() -> new RuntimeException("No target entity with holder id " + holderId));
        Application application = participant.getApplication();

        String roles = participant.getRoles().stream()
            .map(role -> EnumUtils.getLocalizedValue(role, LocaleContextHolder.getLocale()))
            .collect(Collectors.joining(", "));

        return new LaunchpadEntityDto(participant.getId(), application, application.getDisplayedName(),
            participant, participant.getDisplayedName(), roles,
            "/participant/launchpad-body");
    }
}

@Entity
public class Participant extends AbstractAuditable<UUID> implements HasPendingDecisions {

    public static final String DECISION_OWNER_TYPE = "PARTICIPANT";

    @OneToOne(cascade = CascadeType.ALL)
    @JoinColumn(nullable = false, updatable = false)
    private PendingDecisionHolder pendingDecisionHolder =
        new PendingDecisionHolder(DECISION_OWNER_TYPE);

    @Override
    public PendingDecisionHolder getPendingDecisionHolder() {
        return pendingDecisionHolder;
    }
}

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:th="http://www.thymeleaf.org">
<th:block th:fragment="details" th:object="${entityDto.targetEntity}">
    <th:block th:insert="~{/launchpad/fragment/pending-decisions :: body(${entityDto})}"/>

    <div class="mt-20 border-top">
        <h4 class="mb-5 mt-5" th:text="#{participant.tab.details}"></h4>
        <article
            class="article  pl-10 pr-10"
            th:data-url="@{${@pathRegistry.getPath(entityDto.targetEntity) + '/tab/details'}}"
        ></article>
    </div>

    <div class="mt-20 border-top">
        <h4 class="mb-5 mt-5" th:text="#{participant.tab.profile}"></h4>
        <article
            class="article"
            th:data-url="@{${@pathRegistry.getPath(entityDto.targetEntity) + '/tab/profile'}}"
        ></article>
    </div>

    <div class="mt-20 border-top">
        <h4 class="mb-5 mt-5" th:text="#{participant.tab.documents}"></h4>
        <article
            class="article"
            th:data-url="@{${@pathRegistry.getPath(entityDto.targetEntity) + '/tab/documents'}}"
        ></article>
    </div>
</th:block>
</html>

<th:block th:insert="~{/launchpad/fragment/pending-decisions :: body(${entityDto})}"/>

<article th:data-url="@{${@pathRegistry.getPath(entityDto.targetEntity) + '/tab/details'}}">

@Component
public class ParticipantLaunchpadService implements DecisionEntityExtractor {
    // Implementation...
}

@Override
    public LaunchpadEntityDto getByHolderId(Long holderId) {
        Participant participant = repository.findByPendingDecisionHolderId(holderId)
            .orElseThrow(() -> new RuntimeException("No target entity with holder id " + holderId));
        Application application = participant.getApplication();

        String roles = participant.getRoles().stream()
            .map(role -> EnumUtils.getLocalizedValue(role, LocaleContextHolder.getLocale()))
            .collect(Collectors.joining(", "));

        return new LaunchpadEntityDto(participant.getId(), application, application.getDisplayedName(),
            participant, participant.getDisplayedName(), roles,
            "/participant/launchpad-body");
    }

private String buildContextualInfo(Participant participant) {
    // Custom logic to build additional context
    return participant.getStatus() + " | " +
           participant.getPendingDocumentsCount() + " docs pending";
}

@Component
public class ApplicationLaunchpadService implements DecisionEntityExtractor {
    @Override
    public String getDecisionOwnerType() {
        return Application.DECISION_OWNER_TYPE;
    }

    @Override
    public LaunchpadEntityDto getByHolderId(Long holderId) {
        // Implementation for application entities
    }
}

@Component
public class CreditLaunchpadService implements DecisionEntityExtractor {
    @Override
    public String getDecisionOwnerType() {
        return Credit.DECISION_OWNER_TYPE;
    }

    @Override
    public LaunchpadEntityDto getByHolderId(Long holderId) {
        // Implementation for credit entities
    }
}

// Good: Include parent application for participant context
return new LaunchpadEntityDto(
    participant.getId(),
    application,              // Parent context
    application.getDisplayedName(),
    participant,              // Target entity
    participant.getDisplayedName(),
    roles,
    templatePath
);

public String getDisplayedName() {
    return String.format("%s (%s)", fullName, roles.iterator().next());
}

String roles = participant.getRoles().stream()
    .map(role -> EnumUtils.getLocalizedValue(role, LocaleContextHolder.getLocale()))
    .collect(Collectors.joining(", "));

@Query("SELECT p FROM Participant p " +
       "JOIN FETCH p.application " +
       "JOIN FETCH p.roles " +
       "WHERE p.pendingDecisionHolder.id = :holderId")
Optional<Participant> findByPendingDecisionHolderId(@Param("holderId") Long holderId);

@Cacheable("participant-context")
public LaunchpadEntityDto getByHolderId(Long holderId) {
    // Implementation...
}

Solution: Ensure your DecisionEntityExtractor is registered as @Component
and getDecisionOwnerType() returns the correct entity type constant.

Solution: Verify template path in LaunchpadEntityDto matches actual file location.
Template must be in src/main/resources/templates/ directory.

Solution: Check that findByPendingDecisionHolderId query is correct and
entity properly implements HasPendingDecisions interface.