Documentation Home

Creating a New Custom Entity


This tutorial explains how you can add a new custom entity to a custom Broadleaf application.

For this example, we will create a simple Account entity with properties for name and account number.

This tutorial will serve as the basis for other tutorials including one that shows you how to add a new section and edit screen to the Admin.


Let's start with an interface we want to implement.

package com.mycompany.tutorial;

public interface Account {

    Long getId();

    void setId(Long id);

    String getName();

    void setName(String name);

    String getAccountNumber();

    void setAccountNumber(String accountNumber);


Next, let's add a bare-bones JPA implementation for this class.

Step One - Implement The Class

Below is a quick example that implements the new entity. This is really just JPA.

package com.mycompany.tutorial;

import javax.persistence.Column;
import javax.persistence.Entity;
import javax.persistence.Id;
import javax.persistence.Table;

@Table(name = "ACCOUNT")
public class AccountImpl implements Account {

    @Column(name = "ACCOUNT_ID")
    protected Long id;

    @Column(name = "NAME")
    protected String name;

    @Column(name = "ACCOUNT_NBR")
    protected String accountNumber;

    public Long getId() {
        return id;

    public void setId(Long id) { = id;

    public String getName() {
        return name;

    public void setName(String name) { = name;

    public String getAccountNumber() {
        return accountNumber;

    public void setAccountNumber(String accountNumber) {
        this.accountNumber = accountNumber;

Step Two Register the Class in persistence.xml

The new entity needs to be registered with your Broadleaf application's persistence.xml.

The Broadleaf DemoSite manages this file in the core project. The following shows a single line edit to the file located in '/core/src/main/resources/META-INF/persistence-core.xml' in the DemoSite core project.

<?xml version="1.0" encoding="UTF-8"?>
<persistence xmlns=""

    <persistence-unit name="blPU" transaction-type="RESOURCE_LOCAL">

        <!-- Added this line -->


Step Three Add an ID Generator

For most (if not all) entities in a Broadleaf application, you'll want to use an ID generator. The ID Generator provides an efficient way to generate ids and is required for entities to be managed in the Broadleaf Admin.

To add, this make the following change to the .java file from Step 1.

    @GeneratedValue(generator= "AccountId")
        parameters = {
            @Parameter(name="segment_value", value="AccountImpl"),
            @Parameter(name="entity_name", value="com.mycompany.tutorial.AccountImpl")
    @Column(name = "ACCOUNT_ID")
    protected Long id;


At this point, all we have is a JPA domain, but you can test by building and running your DemoSite and then checking to see if the Account table was created in your database.

As long as you are compiling and starting ok, you can move on to the - Admin Customization dealing with creating new admin sections.