Embedded Table Field Type

Description:
The embedded_table field type allows you to include a table within your case schema where each row represents a set of fields. This is useful for capturing lists of items or repeated data structures, such as order line items, contact lists, or any data that naturally fits into a tabular format.

YAML Definition 

- name: items
  type: embedded_table
  display_name: "Items"
  item_type: "item"
  fields:
  - name: product_name
    type: string
    display_name: "Product Name"
    required: true
  - name: quantity
    type: number
    display_name: "Quantity"
    default_value: 1
    required: true
  - name: price
    type: currency
    display_name: "Price"
    symbol: "$"
    precision: 2
    required: true
  - name: total
    type: currency
    display_name: "Total"
    symbol: "$"
    precision: 2
    readonly: true

Attributes

  • name (string): Required.
    The unique identifier for the field.

  • type (string): Required.
    Must be set to embedded_table for embedded table fields.

  • display_name (string): Optional.
    The label displayed in the user interface. If not provided, a formatted version of name is used.

  • item_type (string): Optional.
    A label for the items within the table, used for identification and display purposes.

  • fields (array): Required.
    An array of field definitions that specify the columns of the table. Each field within fields is defined similarly to top-level fields, with their own name, type, and other attributes.

  • required (boolean): Optional.
    If true, the field must have at least one row before submission.

  • readonly (boolean): Optional.
    If true, the table is read-only, and users cannot add, remove, or edit rows.

  • hidden (boolean): Optional.
    If true, the field is hidden from the user interface.

Example

Suppose you want to capture a list of order items within a sales order case.

- name: order_items
  type: embedded_table
  display_name: "Order Items"
  item_type: "item"
  fields:
  - name: product_code
    type: string
    display_name: "Product Code"
    required: true
  - name: description
    type: string
    display_name: "Description"
    required: true
  - name: unit_price
    type: currency
    display_name: "Unit Price"
    symbol: "$"
    precision: 2
    required: true
  - name: quantity
    type: number
    display_name: "Quantity"
    default_value: 1
    required: true
  - name: line_total
    type: currency
    display_name: "Line Total"
    symbol: "$"
    precision: 2
    readonly: true

In this example:

  • order_items: The name of the embedded table field capturing order line items.
  • fields: Defines the columns in the table, such as product_code, description, unit_price, quantity, and line_total.
  • line_total: A calculated field that can be set via business logic to unit_price * quantity.

Usage Notes

  • Data Structure:
    • The embedded table stores data as an array of objects, where each object represents a row containing values for the defined fields.
    • Access individual fields within rows using array notation, e.g., order_items[0].product_code.
  • Field Definitions:
    • Fields within the embedded table are defined similarly to top-level fields and support most field types, including string, number, currency, date, boolean, select, and more.
  • Adding and Removing Rows:
    • Users can add new rows to the table by clicking an “Add new row” button.
    • Each row can be removed individually unless the table is marked as readonly.
  • Validation:
    • If the table is marked as required, ensure that at least one row is present.
    • Individual fields within the table can also be marked as required, enforcing validation on a per-row basis.
  • Readonly Fields:
    • Setting readonly to true on the embedded table prevents users from modifying the table, useful for displaying data calculated or populated elsewhere.
  • Calculations and Business Logic:
    • Calculated fields within the table (e.g., line_total) can be populated using business logic or rules that operate on the data entered in other fields of the row.
    • Ensure that such logic is implemented in the application’s backend or via scripts.
  • Display and Layout:
    • The table adjusts its layout based on screen size, ensuring usability on different devices.
    • Each column corresponds to a field defined in the fields array.
  • Use Cases:
    • Order Items: Capturing products or services in an order or invoice.
    • Contact Lists: Managing multiple contacts associated with a case.
    • Task Lists: Defining a set of tasks or steps within a case.
  • Performance Considerations:
    • For tables with a large number of rows, consider implementing pagination or limiting the number of rows to maintain performance.
  • Internationalization:
    • Ensure that date formats, currency symbols, and number formats are appropriate for the user’s locale.
  • Nested Tables:
    • Avoid nesting embedded tables within other embedded tables, as this may complicate the user interface and data handling.

By using the embedded_table field type, you can effectively capture and manage structured, repeating data within your cases, enhancing the data modeling capabilities of your Caseblocks application.

Copyright © 2024 Caseblocks Limited.