Entities

Introduction

Entities in CargoXplorer define the core data structures used throughout the system. They represent key business objects like orders, contacts, and accounting transactions. App Modules can define new custom entity types or extend existing ones to add additional fields and functionality.

When to Define Custom Entities

• You need to store and manage data that doesn't fit into existing entity types
• You want to add custom fields to extend existing entities like Orders or Contacts
• You're building a new module that requires its own data model

Key Concepts

Entity Definition

An entity definition includes:

• name - Unique identifier for the entity
• entityKind - The type of entity (e.g. Order, Contact, Custom)
• displayName - Localized labels for the UI
• fields - The data fields that make up the entity

Custom Fields

Custom fields allow you to extend entities with additional data points. They can be added to both custom and existing entity types.

Entity Extensions

Existing entity types like Order can be extended to add new fields without creating an entirely new entity.

Entity Types

Entity Type	Description	Use Case
Order	Represents a customer order or shipment	Tracking shipments, deliveries, warehouse operations
Contact	Stores information about customers, vendors, etc.	Managing customer data, vendor details
AccountingTransaction	Records financial transactions	Invoices, payments, journal entries
Custom	User-defined entity for custom data needs	Industry-specific data models

How to Define an Entity

1. In your App Module YAML file, add an entities section
2. Define each entity with a name, entity kind, and fields
3. For custom fields, set isCustomField: true
4. To extend an existing entity, set extension: true

Example:

entities:
  - name: "ParcelShipment"
    entityKind: Order
    extension: true
    displayName:
      en-US: "Parcel Shipment"
    fields:
      - name: "trackingNumber"
        displayName:
          en-US: "Tracking Number"
        fieldType: "text"
        isCustomField: true

Field Types

Field Type	Description	Example Use
text	Stores string data	Names, descriptions
number	Numeric values	Quantities, measurements
date	Date/time values	Ship dates, deadlines
boolean	True/False values	Active, enabled, visible
list	List of options	Status codes
entityName	References another entity	Linking to another entity

Fields Definition

fields:
  - name: "originCountry"
    displayName:
      en-US: "Origin Country"
    fieldType: "Country"
    isCustomField: true
    props:
      filterComponent: Countries/Select
      allowOrderBy: false
      allowFilter: false

Key Attributes:

• name: Unique identifier for the field
• displayName: Localized label for the field
• fieldType: Type of data the field holds
• isCustomField: Whether the field is a custom field. If fieldName is not system field, then isCustomField is required.
• props: Additional properties for the field

Common Props

• showAs: How the field is displayed in the Grid and Form (component)
• allowOrderBy: Whether the field can be used for ordering
• allowFilter: Whether the field can be used for filtering
• isInactive: Whether the field is inactive
• filter: # Filter Component definition
  • component: Component to use for filtering
  • props: Additional properties for the filter component

Virtual Fields / GraphQL Resolvers

Virtual fields are fields that are not stored in the database, but are calculated at runtime using a GraphQL resolver.

fields:
  - name: "getSummary" # name of the field
    displayName: "Summary"
    fieldType: "text"
    isCustomField: true
    props:
      allowOrderBy: false
      allowFilter: false

Best Practices

• Use clear, descriptive names for entities and fields
• Leverage existing entities where possible before creating custom ones
• Add custom fields to extend entities rather than duplicating data
• Use entity references to create relationships between data
• Include localized display names for multi-language support