Excel Features

Q-Framework provides Excel download/upload features automatically from entity declarations alone. No separate Excel processing code is required.

Auto-Generated Excel APIs

The following APIs are automatically generated for every @QfEntity declaration.

GET  /api/app/products/excel/download         # Download all data as Excel
GET  /api/app/products/excel/sample           # Download sample upload template
POST /api/app/products/excel/upload           # Upload Excel (bulk create)
GET  /api/app/products/excel/upload/{jobId}   # Check upload job status
DEL  /api/app/products/excel/upload/{jobId}   # Cancel upload job

---

Excel Download

@QfEntity(
    appKey = "app",
    name = @QfI18n(defaultMessage = "Product", texts = { @QfI18nText(locale = "ko", message = "상품") })
)
public class ProductEntity {

    @QfListAttribute(sortable = true)   // list-displayed fields become Excel columns
    @QfDisplayLabel(text = "Product Name")
    private String name;

    @QfListAttribute(sortable = true)
    @QfDisplayLabel(text = "Price")
    private Integer price;

    @QfListAttribute(sortable = true)
    @QfCodeGroup(code = "PRODUCT_CATEGORY")
    @QfDisplayLabel(text = "Category")
    private String category;
}

Fields with @QfListAttribute are automatically mapped to Excel columns. The localized display name from @QfDisplayLabel is used as the column header.

Download Request

GET /api/app/products/excel/download?search=laptop&category=ELECTRONICS

Downloads data matching the current search conditions as an Excel file.

---

Excel Sample Download

Download a sample file for use when uploading.

GET /api/app/products/excel/sample

The sample file includes:

• Column headers (localized display names)
• One row of example data
• Allowed values for code-based fields (separate sheet)
• Required field indicators (red headers)

---

Excel Upload

Asynchronous Processing

Large data uploads are processed asynchronously.

# 1. Submit upload request
POST /api/app/products/excel/upload
Content-Type: multipart/form-data
Body: file=products.xlsx

# Response
{
  "success": true,
  "data": {
    "jobId": "job-abc-123",
    "status": "PENDING",
    "totalRows": 1000
  }
}

# 2. Poll for status
GET /api/app/products/excel/upload/job-abc-123

# Response
{
  "success": true,
  "data": {
    "jobId": "job-abc-123",
    "status": "IN_PROGRESS",
    "totalRows": 1000,
    "processedRows": 350,
    "failedRows": 2,
    "errors": [
      {
        "row": 45,
        "field": "price",
        "message": "Price must be 0 or greater.",
        "value": "-1000"
      }
    ]
  }
}

Cancel Upload Job

DELETE /api/app/products/excel/upload/job-abc-123

---

Frontend Excel UI

<template>
  <!-- Excel download/upload buttons rendered automatically -->
  <QfEntityView
    client-app="app"
    entity="product"
  />
</template>

The QfEntityView component automatically includes Excel download/upload buttons. Upload progress display is also handled automatically.

---

Excel Configuration

qf:
  excel:
    max-upload-rows: 10000      # maximum uploadable rows
    max-file-size: 10MB         # maximum file size
    batch-size: 100             # batch processing unit size
    async-threshold: 500        # row count threshold to switch to async

---

Next Steps

• SPI Extensions — Customize Excel processing
• Annotation Reference — Complete annotation list