steedos-objects

Steedos Objects | Steedos 对象定义

Overview | 概述

Steedos objects are the foundation of your data model. Each object represents a database table. Objects are defined using .object.yml files, with related metadata (fields, list views, permissions, buttons) in separate files within subfolders.

Steedos 对象是数据模型的基础。每个对象代表一个数据库表。对象使用 .object.yml 文件定义，相关元数据（字段、列表视图、权限、按钮）在子文件夹的独立文件中定义。

IMPORTANT: When adding lookup/master_detail fields that reference built-in objects, you MUST use the correct API names. Built-in object names often differ from common expectations — e.g. Department is organizations (not departments), Division is company (not divisions). Load the steedos-builtin-objects skill for the authoritative name list.

File Location | 文件位置

Modern Format (Recommended) | 现代格式（推荐）

Each object has its own folder with separate metadata files:

steedos-packages/
└── my-package/
    └── main/default/
        └── objects/
            └── orders/
                ├── orders.object.yml           # Object definition
                ├── fields/                      # Field definitions
                │   ├── order_number.field.yml
                │   ├── customer.field.yml
                │   ├── status.field.yml
                │   └── total_amount.field.yml
                ├── listviews/                   # List view definitions
                │   ├── all.listview.yml
                │   ├── my_orders.listview.yml
                │   └── pending.listview.yml
                ├── permissions/                 # Permission definitions
                │   ├── user.permission.yml
                │   └── admin.permission.yml
                └── buttons/                     # Button definitions
                    ├── submit_order.button.yml
                    └── standard_delete.button.yml

Note: Triggers and functions are in separate top-level folders:

main/default/
├── triggers/
│   └── orders_validate.trigger.yml
└── functions/
    └── approve_order.function.yml

Object Definition | 对象定义

Minimal Object | 最小对象定义

# objects/products/products.object.yml
name: products
label: 产品
custom: true

Every object must have a name field. At minimum, define a name field:

每个对象必须有一个名称字段。至少需要定义一个 name 字段：

# objects/products/fields/name.field.yml
name: name
type: text
label: 产品名称
required: true
searchable: true

Fields, list views, and permissions are defined in separate files under the object folder.

Complete Object | 完整对象定义

# objects/orders/orders.object.yml
name: orders
label: 订单
icon: orders
custom: true
version: 2
is_enable: true
enable_search: true
enable_files: true
enable_api: true
enable_audit: true
enable_trash: true
enable_enhanced_lookup: true
enable_inline_edit: true
enable_dataloader: true

Core Properties | 核心属性

Basic Properties | 基本属性

Feature Flags | 功能开关

Field Groups | 字段分组

Organize fields into collapsible groups in the UI:

# objects/orders/orders.object.yml
field_groups:
  - group_name: Basic Information
  - group_name: Shipping Details
    collapsed: true
  - group_name: Approval Info
    collapsed: true
    visible_on: "{{status != 'draft'}}"

Name Field (Required) | 名称字段（必填）

Every object must have a name field — this is the human-readable identifier displayed in lookup results, related lists, breadcrumbs, and record titles. There are two ways to provide it:

每个对象必须有一个名称字段——它是在查找结果、相关列表、面包屑和记录标题中显示的人类可读标识。有两种方式提供：

Option 1: Define a name field (default) | 方式一：定义 name 字段（默认）

If you define a field with name: name, it is automatically used as the name field:

# objects/products/fields/name.field.yml
name: name
type: text
label: 产品名称
required: true
searchable: true
index: true

Option 2: Use is_name: true on another field | 方式二：在其他字段上设置 is_name: true

When the record title is not a simple text field (e.g., an autonumber or a lookup), mark a different field with is_name: true:

当记录标题不是简单文本字段时（例如自动编号或查找字段），在其他字段上标记 is_name: true：

# objects/orders/fields/order_number.field.yml
name: order_number
type: autonumber
label: 订单号
formula: 'ORD-{YYYY}{MM}{DD}-{0000}'
is_name: true
readonly: true
sort_no: 100

# objects/permission_objects/fields/permission_set.field.yml
name: permission_set
type: master_detail
label: 权限集
reference_to: permission_set
required: true
is_name: true

Resolution priority: is_name: true takes precedence over a field named name. If neither exists, the object will have no display name and lookups/related lists will show blank values.

优先级规则：is_name: true 优先于名为 name 的字段。如果两者都不存在，对象将没有显示名称，查找/相关列表将显示空白值。

Standard Fields | 标准字段

Steedos automatically adds these system fields to every object (no need to define):

Complete Example | 完整示例

Object with Separate Files | 带独立文件的对象

Object definition:

# objects/orders/orders.object.yml
name: orders
label: 订单
icon: orders
custom: true
version: 2
is_enable: true
enable_search: true
enable_files: true
enable_api: true
enable_audit: true
enable_trash: true
enable_enhanced_lookup: true
field_groups:
  - group_name: Basic Information
  - group_name: Financial
  - group_name: Shipping
    collapsed: true

Field files:

# objects/orders/fields/order_number.field.yml
name: order_number
type: autonumber
label: 订单号
formula: 'ORD-{YYYY}{MM}{DD}-{0000}'
is_name: true
readonly: true
sort_no: 100

# objects/orders/fields/customer.field.yml
name: customer
type: lookup
label: 客户
reference_to: customers
required: true
index: true
sort_no: 200

# objects/orders/fields/status.field.yml
name: status
type: select
label: 状态
required: true
index: true
sort_no: 300
options:
  - label: 草稿
    value: draft
  - label: 已提交
    value: submitted
  - label: 已批准
    value: approved
  - label: 已完成
    value: completed
  - label: 已取消
    value: cancelled

# objects/orders/fields/total_amount.field.yml
name: total_amount
type: currency
label: 总金额
scale: 2
readonly: true
group: Financial
sort_no: 400

List view file:

# objects/orders/listviews/all.listview.yml
name: all
label: 所有订单
is_enable: true
shared: true
filter_scope: space
crud_mode: table
columns:
  - field: order_number
  - field: customer
  - field: total_amount
  - field: status
  - field: created
sort:
  - field_name: created
    order: desc
searchable_fields:
  - field: order_number
  - field: customer

Permission file:

# objects/orders/permissions/user.permission.yml
name: orders.user
permission_set_id: user
allowCreate: true
allowRead: true
allowEdit: true
allowDelete: false
viewAllRecords: true
modifyAllRecords: false

Button file:

# objects/orders/buttons/submit_order.button.yml
name: submit_order
label: 提交
type: amis_button
on: record_only
is_enable: true
visible: true
amis_schema: |-
  {
    "type": "button",
    "label": "Submit",
    "level": "primary",
    "visibleOn": "${status == 'draft'}",
    "onEvent": {
      "click": {
        "actions": [
          {
            "actionType": "ajax",
            "api": {
              "url": "/api/v1/orders/functions/submit_order",
              "method": "post",
              "requestAdaptor": "api.data = { id: api.body.recordId }",
              "messages": { "success": "Order submitted" }
            }
          },
          { "actionType": "broadcast", "args": { "eventName": "steedos:record:reload" } }
        ]
      }
    }
  }

Naming Conventions | 命名规范

⚠️ Object Name Prefix Rule | 对象名称前缀规范

All custom objects MUST be prefixed with {org_code}_{project_code}_ to avoid naming conflicts across packages and organizations.

所有自定义对象的 name 必须以 {组织简码}_{项目简码}_ 开头，防止不同包和组织间的命名冲突。

Format: {org_code}_{project_code}_{object_name}

# ✅ Good — prefixed with org_code + project_code
name: steedos_crm_contracts
name: steedos_crm_customers
name: acme_hr_employees

# ❌ Bad — no prefix, risks conflict
name: contracts
name: customers
name: employees

⚠️ When a user does not specify a prefix, ASK for their organization code and project code before generating object files. Do NOT invent a prefix.

⚠️ 如果用户未指定前缀，在生成对象文件前必须询问其组织简码和项目简码，不得自行编造前缀。

General Rules | 通用规则

# Object names: lowercase, prefixed, plural, underscores for multi-word
name: steedos_crm_customers    # Good
name: steedos_crm_sales_orders # Good
name: customers                # Bad - missing prefix
name: SalesOrders              # Bad - no CamelCase
name: sales-orders             # Bad - no hyphens

# Field names: lowercase, underscores
customer_name          # Good
orderDate              # Bad - no camelCase

Object Relationships | 对象关系

• lookup: One-to-many (no cascade delete)
• master_detail: Parent-child (cascade delete, child inherits sharing)

See the object-fields skill for detailed relationship field configuration.

Icon Reference | 图标参考

⚠️ CRITICAL: The icon value MUST be chosen from the valid icon list below. NEVER invent or guess icon names. If no icon matches the object's domain, use custom or record as a safe default.

The object icon property uses Salesforce Lightning Design System (SLDS) icons — the same icon set as the application icon_slds property.

对象的 icon 属性使用 Salesforce Lightning Design System (SLDS) 图标——与应用的 icon_slds 属性使用相同的图标集。

⚠️ 重要：icon 值必须从下方有效值列表中选取，严禁自行编造图标名称。如果没有匹配的图标，使用 custom 或 record 作为默认值。

Common Icons by Category | 常用图标分类

Valid icon Values | 有效的 icon 值

⚠️ ONLY the values listed below are valid. Any value NOT in this list will cause a broken icon. When in doubt, use custom or record.

The following is the complete and exhaustive list of valid icon values (same as application icon_slds):

以下是 icon 的完整且唯一有效值列表（与应用的 icon_slds 相同），不在此列表中的值会导致图标无法显示：

A: account, account_info, action_list_component, actions_and_buttons, activation_target, activations, address, agent_home, agent_session, aggregation_policy, all, announcement, answer_best, answer_private, answer_public, apex, apex_plugin, app, approval, apps, apps_admin, article, asset_action, asset_action_source, asset_audit, asset_downtime_period, asset_object, asset_relationship, asset_state_period, asset_warranty, assigned_resource, assignment, attach, avatar, avatar_loading

B: bot, bot_training, branch_merge, brand, budget, budget_allocation, bundle_config, bundle_policy, business_hours, buyer_account, buyer_group

C: calculated_insights, calibration, call, call_coaching, call_history, campaign, campaign_members, cancel_checkout, canvas, capacity_plan, care_request_reviewer, carousel, case, case_change_status, case_comment, case_email, case_log_a_call, case_milestone, case_transcript, case_wrap_up, catalog, category, change_request, channel_program_history, channel_program_levels, channel_program_members, channel_programs, chart, checkout, choice, client, cms, coaching, code_playground, code_set, code_set_bundle, collection, collection_variable, connected_apps, constant, contact, contact_list, contact_request, contract, contract_line_item, contract_payment, coupon_codes, currency, currency_input, custom, custom_component_task, custom_notification, customer_360, customer_lifecycle_analytics, customer_portal_users, customers

D: dashboard, dashboard_component, dashboard_ea, data_integration_hub, data_mapping, data_model, data_streams, datadotcom, dataset, date_input, date_time, decision, default, delegated_account, device, discounts, display_rich_text, display_text, document, document_reference, drafts, duration_downscale, dynamic_record_choice

E: education, einstein_replies, email, email_chatter, employee, employee_asset, employee_contact, employee_job, employee_job_position, employee_organization, empty, endorsement, entitlement, entitlement_policy, entitlement_process, entitlement_template, entity, entity_milestone, environment_hub, event, events, expense, expense_report, expense_report_entry

F: feed, feedback, field_sales, file, filter, filter_criteria, filter_criteria_rule, first_non_empty, flow, folder, forecasts, form, formula, fulfillment_order

G: generic_loading, global_constant, goals, group_loading, groups, guidance_center

H: hierarchy, high_velocity_sales, historical_adherence, holiday_operating_hours, home, household

I: identifier, immunization, incident, individual, insights, instore_locations, investment_account, invocable_action, iot_context, iot_orchestrations

J: javascript_button, job_family, job_position, job_profile

K: kanban, key_dates, knowledge

L: lead, lead_insights, lead_list, letterhead, lightning_component, lightning_usage, link, list_email, live_chat, live_chat_visitor, location, location_permit, log_a_call, logging, loop

M: macros, maintenance_asset, maintenance_plan, maintenance_work_rule, marketing_actions, med_rec_recommendation, med_rec_statement_recommendation, medication, medication_dispense, medication_ingredient, medication_reconciliation, medication_statement, merge, messaging_conversation, messaging_session, messaging_user, metrics, multi_picklist, multi_select_checkbox

N: network_contract, news, note, number_input

O: observation_component, omni_supervisor, operating_hours, opportunity, opportunity_contact_role, opportunity_splits, orchestrator, order_item, orders, outcome, output

P: partner_fund_allocation, partner_fund_claim, partner_fund_request, partner_marketing_budget, partners, password, past_chat, patient_medication_dosage, payment_gateway, people, performance, person_account, person_language, person_name, photo, picklist_choice, picklist_type, planogram, poll, portal, portal_roles, portal_roles_and_subordinates, post, practitioner_role, price_book_entries, price_books, pricebook, pricing_workspace, problem, procedure, procedure_detail, process, process_exception, product, product_consumed, product_consumed_state, product_item, product_item_transaction, product_quantity_rules, product_request, product_request_line_item, product_required, product_service_campaign, product_service_campaign_item, product_transfer, product_transfer_state, product_warranty_term, product_workspace, products, promotion_segments, promotions, promotions_workspace, propagation_policy, proposition

Q: qualifications, question_best, question_feed, queue, quick_text, quip, quip_sheet, quotes

R: radio_button, read_receipts, recent, recipe, record, record_create, record_delete, record_lookup, record_signature_task, record_update, recycle_bin, related_list, relationship, reply_text, report, report_type, resource_absence, resource_capacity, resource_preference, resource_skill, restriction_policy, return_order, return_order_line_item, reward, rtc_presence

S: sales_cadence, sales_cadence_target, sales_channel, sales_path, sales_value, salesforce_cms, scan_card, schedule_objective, scheduling_constraint, scheduling_policy, screen, search, section, segments, selling_model, serialized_product, serialized_product_transaction, service_appointment, service_appointment_capacity_usage, service_contract, service_crew, service_crew_member, service_report, service_request, service_request_detail, service_resource, service_territory, service_territory_location, service_territory_member, service_territory_policy, settings, shift, shift_pattern, shift_pattern_entry, shift_preference, shift_scheduling_operation, shift_template, shift_type, shipment, skill, skill_entity, skill_requirement, slack, slider, sms, snippet, snippets, sobject, sobject_collection, social, solution, sort, sort_policy, sossession, stage, stage_collection, steps, store, store_group, story, strategy, survey, swarm_request, swarm_session, system_and_global_variable

T: tableau, task, task2, team_member, template, text, text_template, textarea, textbox, thanks, thanks_loading, timesheet, timesheet_entry, timeslot, today, toggle, topic, topic2, tour, tour_check, trailhead, trailhead_alt, travel_mode

U: unified_health_score, unmatched, user, user_role

V: variable, variation_attribute_setup, variation_products, video, visit_templates, visits, visualforce_page, voice_call

W: waits, warranty_term, webcart, work_capacity_limit, work_capacity_usage, work_contract, work_forecast, work_order, work_order_item, work_plan, work_plan_rule, work_plan_template, work_plan_template_entry, work_queue, work_step, work_step_template, work_type, work_type_group, workforce_engagement

Usage Examples | 使用示例

# CRM object
name: accounts
icon: account

# Order management
name: orders
icon: orders

# HR object
name: employees
icon: employee

# Approval process
name: process_definition
icon: approval

# Custom settings
name: app_settings
icon: settings

Best Practices | 最佳实践

1. Always define a name field: Either a field named name or a field with is_name: true — without this, lookups and related lists show blank values
2. Use separate files: Put fields, listviews, permissions, and buttons in their own files for better version control
3. Label follows user's language: Write label in the language of the user's prompt. For internationalization, use the translations skill
4. Add indexes: Set index: true on frequently queried fields
5. Choose valid icons ONLY: The icon value MUST exist in the valid icon values list. Never invent icon names. Use custom or record if no specific icon fits. Common mappings: 质检/检验→observation_component, 巡检→visits, 设备→maintenance_asset, 工单→work_order, 审批→approval
6. Use field groups: Organize related fields into collapsible groups
7. Name objects as plurals: orders, customers, products (not singular)

---

List Views | 列表视图

Overview | 概述

List views define how records are displayed in table format. Each view is a separate .listview.yml file in the object's listviews/ subfolder.

File Location | 文件位置

objects/
└── orders/
    └── listviews/
        ├── all.listview.yml
        ├── my_orders.listview.yml
        ├── pending_approval.listview.yml
        └── high_value.listview.yml

List View Structure | 列表视图结构

# objects/orders/listviews/all.listview.yml
name: all
label: 所有订单
is_enable: true
shared: true
shared_to: space
filter_scope: space
crud_mode: table
columns:
  - field: order_number
  - field: customer
  - field: total_amount
  - field: status
  - field: created
sort:
  - field_name: created
    order: desc
searchable_fields:
  - field: order_number
  - field: customer
mobile_columns:
  - field: order_number
  - field: status

List View Properties | 列表视图属性

Columns | 列配置

columns:
  - field: name
  - field: description
    width: '300'
    wrap: true

Filters | 筛选器

# Single filter
filters:
  - ["status", "=", "active"]

# Multiple filters (AND)
filters:
  - ["status", "=", "active"]
  - ["total_amount", ">", 10000]

# Current user
filters:
  - ["owner", "=", "{userId}"]

# Date-based
filters:
  - ["created", ">=", "{last_n_days(7)}"]

Filter Operators | 筛选运算符

Sorting | 排序

sort:
  - field_name: status
    order: asc
  - field_name: created
    order: desc

List View Examples | 列表视图示例

All Records View | 全部记录视图

# objects/orders/listviews/all.listview.yml
name: all
label: 所有订单
is_enable: true
shared: true
shared_to: space
filter_scope: space
crud_mode: table
columns:
  - field: order_number
  - field: customer
  - field: order_date
  - field: total_amount
  - field: status
  - field: owner
  - field: created
sort:
  - field_name: created
    order: desc
searchable_fields:
  - field: order_number
  - field: customer
mobile_columns:
  - field: order_number
  - field: total_amount
  - field: status

My Records View | 我的记录视图

# objects/orders/listviews/my_orders.listview.yml
name: my_orders
label: 我的订单
is_enable: true
shared: true
filter_scope: mine
crud_mode: table
columns:
  - field: order_number
  - field: customer
  - field: total_amount
  - field: status
sort:
  - field_name: created
    order: desc

Filtered View | 筛选视图

# objects/orders/listviews/pending_approval.listview.yml
name: pending_approval
label: 待审批
is_enable: true
shared: true
filter_scope: space
crud_mode: table
filters:
  - ["status", "=", "submitted"]
columns:
  - field: order_number
  - field: customer
  - field: total_amount
  - field: submitted_at
  - field: owner
sort:
  - field_name: submitted_at
    order: asc

List View Best Practices | 列表视图最佳实践

1. Limit columns: 5-8 columns for readability
2. Add searchable_fields: Enable search on key fields
3. Mobile columns: Only essential fields for mobile
4. Meaningful filters: Create views that match common workflows
5. Default sort: Always specify a meaningful sort order