Skip to main content

Custom Entities

Learn how to create and manage custom data objects beyond the built-in Users entity.

What are Custom Entities?​

Custom Entities (also known as Custom Objects) allow you to define and store any type of structured data in Joryio. Think of them as custom database tables that you can create through the UI.

Common use cases:

  • Products - Store product catalogs with pricing, SKUs, descriptions
  • Orders - Track order history and purchase data
  • Inventory - Manage stock levels and warehouse data
  • Content - Store articles, videos, or other content
  • Locations - Store store or office locations
  • Deals - Track sales opportunities
  • Subscriptions - Manage subscription plans and tiers

Key Features​

Flexible Schema Definition​

  • Define custom fields with 18+ field types
  • Configure validation rules per field
  • Add indexes for search performance
  • Control field visibility and display order

Full CRUD Operations​

  • Create, read, update, and delete records
  • Bulk import capabilities
  • Search and filter records
  • Export data

Advanced Capabilities​

  • Audit Trail - Track all changes to records
  • Versioning - Keep history of record modifications
  • Soft Delete - Mark records as deleted instead of removing them
  • Relationships - Link entities together (future feature)

Getting Started​

Creating Your First Entity​

  1. Navigate to Entities from the main menu

  2. Click "Create Entity"

  3. Configure basic settings:

    • Display Name (e.g., "Products")
    • Internal Name (e.g., "products") - lowercase, underscores only
    • Description
    • Display Field - which field to show in lists

  4. Add fields for your data structure

  5. Configure settings (optional)

  6. Click "Create"

Example: Products Entity​

Let's create a Products entity to store your product catalog:

Entity Settings:

  • Display Name: Products
  • Internal Name: products
  • Display Field: name
  • Description: Product catalog with pricing and inventory

Fields:

  1. SKU (String)

    • Required: Yes
    • Unique: Yes
    • Indexed: Yes

  2. Name (String)

    • Required: Yes
    • Max Length: 255

  3. Description (Markdown)

    • Required: No

  4. Price (Currency)

    • Required: Yes
    • Min: 0

  5. Stock Quantity (Integer)

    • Required: Yes
    • Min: 0

  6. Image URL (Image URL)

    • Required: No

  7. Category (String)

    • Indexed: Yes

  8. Active (Boolean)

    • Default: true

Field Types​

Joryio supports 18+ field types:

Text Types​

  • String - Short text (names, titles)
  • Email - Email addresses with validation
  • Phone - Phone numbers
  • URL - Web addresses with validation
  • Markdown - Rich text with markdown support
  • HTML - Raw HTML content
  • JSON - Structured JSON data

Numeric Types​

  • Number - Decimal numbers
  • Integer - Whole numbers only
  • Currency - Money values with decimal precision
  • Percentage - Percentage values

Date/Time Types​

  • Date - Date only (no time)
  • DateTime - Date and time

Other Types​

  • Boolean - True/false values
  • Image URL - URLs to images (renders thumbnail)
  • File URL - URLs to files

Future Types​

  • Reference - Link to another entity (coming soon)
  • Array - Multiple values (coming soon)

Field Validation​

Configure validation rules for each field:

Common Validations​

  • Required - Field must have a value
  • Unique - No duplicate values allowed
  • Min/Max - For numbers (e.g., price >= 0)
  • Min/Max Length - For strings (e.g., SKU between 5-20 characters)
  • Pattern - Regular expression validation
  • Enum - Limit to specific values

Examples​

Email Field:

Type: Email
Required: Yes
Validation: Email format automatically validated

Price Field:

Type: Currency
Required: Yes
Min: 0
Max: 999999

SKU Field:

Type: String
Required: Yes
Unique: Yes
Min Length: 5
Max Length: 20
Indexed: Yes

Managing Records​

Adding Records​

  1. Open your entity from the Entities list
  2. Click "Add Record"
  3. Fill in the form (auto-generated from your schema)
  4. Click "Create"

The form automatically adapts to your field types:

  • String fields → Text inputs
  • Number fields → Numeric inputs
  • Date fields → Date pickers
  • Boolean fields → Checkboxes
  • And more...

Viewing Records​

Records are displayed in a dynamic table with columns for each field:

  • Sort by any column
  • Search across all fields
  • Paginate through large datasets
  • See type-specific rendering (dates, currency, images)

Editing Records​

  1. Click the edit icon on any record
  2. Modify the fields
  3. Click "Update"

All changes are tracked if audit trail is enabled.

Deleting Records​

  1. Click the delete icon on any record
  2. Confirm deletion

If soft delete is enabled, records are marked as deleted but not removed from the database.

Change history​

Every entity keeps a per-record audit trail you can browse in the UI. A History button on the records page (and on each individual record) opens a drawer listing every create, update, and delete: which fields changed, who made the change, when, and the before/after values. Use it to see how a record evolved or to investigate an unexpected value.

Entity Settings​

Audit Trail​

When enabled, Joryio tracks:

  • Who created/modified each record
  • What changed
  • When changes occurred

Access audit logs through the API or admin interface.

Versioning​

Keep complete history of all record changes:

  • Revert to previous versions
  • Compare versions
  • Track data evolution over time

Soft Delete​

Instead of permanently deleting records:

  • Mark as deleted with a flag
  • Preserve data for compliance
  • Restore deleted records if needed

Allow Duplicates​

By default, prevent duplicate records. Disable to allow:

  • Multiple records with same values
  • Useful for event logs or transactions

Searching and Filtering​

Search across all indexed fields:

  • Full-text search
  • Case-insensitive
  • Partial matches supported

Selection filter operators​

Selections filter records with per-field conditions: equals / not equals, greater/less than (or equal), contains, exists, and the multi-value pair Is one of / Is not one of - enter several values separated by commas (e.g. ER, ICU, NICU) and the record matches if its field equals any of them. Numeric values match whether the record stores them as a number or a string. Combine conditions with AND/OR.

Filters (via API)​

Apply complex filters through the API:

{
  filter: {
    price: { $gte: 10, $lte: 100 },
    category: "Electronics",
    active: true
  },
  sort: { price: -1 },
  limit: 20
}

Selection performance & index recommendations​

The Selections view includes a performance panel that lists your top selections by usage and recommends database indexes to speed up the ones you run most. Each recommendation carries a priority; a Create recommended indexes button applies them so frequently-used selections resolve faster.

Performance Tips​

Indexing​

Add indexes to fields you frequently:

  • Search by
  • Filter by
  • Sort by

Example: If you often search by SKU or filter by category, index those fields.

Field Order​

Set displayOrder to control:

  • Form field ordering
  • Table column ordering
  • User experience optimization

Hidden Fields​

Mark fields as hidden if they're:

  • Internal only
  • Not needed in default views
  • Technical metadata

Use Cases​

E-commerce​

Entities:

  • Products (SKU, name, price, images)
  • Orders (order ID, items, total, status)
  • Inventory (warehouse, quantity, location)
  • Categories (name, description, parent)

Workflow:

  • Import product catalog
  • Trigger campaigns based on low stock
  • Send order confirmations
  • Personalize product recommendations

Content Management​

Entities:

  • Articles (title, content, author, tags)
  • Videos (title, URL, duration, category)
  • Authors (name, bio, photo)

Workflow:

  • Store content library
  • Reference in email campaigns
  • Personalize content recommendations
  • Track content performance

SaaS Platform​

Entities:

  • Subscriptions (plan, price, features)
  • Features (name, description, tier)
  • Usage Metrics (metric, value, period)

Workflow:

  • Track subscription status
  • Trigger upgrade campaigns
  • Monitor feature usage
  • Calculate billing

Integration​

With Campaigns​

Reference entity data in email templates using the catalog filter:

Get all records from an entity:

{% assign products = 'products' | catalog %}

{% for product in products %}
  <h3>{{ product.name }}</h3>
  <p>Price: ${{ product.price }}</p>
  <img src="{{ product.image_url }}" />
{% endfor %}

Get records using a pre-configured selection (with filters/sorting):

{% assign featuredProducts = 'products' | catalog: 'featured_items' %}

{% for product in featuredProducts %}
  <h3>{{ product.name }}</h3>
  <p>Price: ${{ product.price }}</p>
{% endfor %}

Notes:

  • Without a selection: returns up to 50 records
  • With a selection: uses the selection's configured filters, sorting, and limit
  • Entity and selection names must match exactly as defined in your workspace

With Canvas (Journey Builder)​

Use entity data to:

  • Trigger journeys
  • Branch based on values
  • Personalize messages
  • Track conversions

With Segments​

Segment users based on entity relationships:

  • Users who purchased specific products
  • Users with active subscriptions
  • Users in specific locations

API Access​

Full REST API for programmatic access:

// List entities
GET /api/entities

// Create entity
POST /api/entities
{
  "name": "products",
  "displayName": "Products",
  "fields": [...]
}

// List records
GET /api/entities/:entityId/records

// Create record
POST /api/entities/:entityId/records
{
  "sku": "PROD-001",
  "name": "Widget",
  "price": 29.99
}

See Entities API Reference for complete documentation.

Best Practices​

Schema Design​

  1. Start simple - Add fields as needed
  2. Use meaningful names - Clear, descriptive field names
  3. Index smartly - Only index fields you'll search/filter by
  4. Validate data - Set appropriate validation rules
  5. Document purpose - Use descriptions for complex fields

Data Quality​

  1. Enforce uniqueness - Where applicable (SKUs, emails)
  2. Require critical fields - Don't make everything optional
  3. Set sensible defaults - Make data entry easier
  4. Validate formats - Use appropriate field types
  5. Clean regularly - Remove outdated records

Performance​

  1. Limit record count - Archive old data
  2. Use pagination - Don't load all records at once
  3. Index strategically - Balance query speed vs. storage
  4. Cache where possible - For frequently accessed data

Troubleshooting​

Can't Create Entity​

  • Check internal name format (lowercase, underscores only)
  • Verify name isn't already in use
  • Ensure you have permission

Records Not Appearing​

  • Check filters/search terms
  • Verify workspace selection
  • Check soft delete status

Slow Queries​

  • Add indexes to filtered fields
  • Reduce result set size
  • Optimize filter queries

Next Steps​