Appearance

Examples & Use Cases ​

The $ai API, combined with Record Behaviors and our Secure Document Lifecycle, unlocks a new frontier of application development. This page provides practical, production-ready examples for common business challenges, demonstrating how to build powerful, AI-native workflows in minutes.

Example 1: Automated Invoice Data Entry with Structured JSON ​

Goal: When a user uploads a PDF invoice, automatically extract key details and a structured list of all line items, storing the line items in a json field for flexible, schema-less data handling and powerful search.

This single script automates a core accounting function that would take weeks to build on a legacy platform.

Step 1: The SCL Data Model ​

First, we define our purchase_order table. Note the use of the document type for the upload and, crucially, the json type for the line_items. This is a modern, flexible approach that avoids the need for a separate related table.

ruby
# file: tables.scl

table purchase_order, purchase_orders {
  default :id, :timestamps

  # Fields to be populated by our AI script
  optional po_number, :string
  optional vendor_name, :string
  optional total_amount, :decimal
  
  # The field for the uploaded invoice PDF
  required invoice_pdf, :document

  # A JSON field to store a structured array of line items.
  # Simple Platform's GraphQL to SQL Compiler and 
  # universal search can index and query inside this field.
  optional line_items, :jsonb
}

Step 2: The Record Behavior Script ​

This script, attached to the purchase_order table, orchestrates the entire extraction process.

javascript
// file: purchase_order_behavior.js

export default async ({ $form, $ai }) => {
  // Only run this logic when the 'invoice_pdf' field is updated in the UI.
  if ($form.event !== 'update' || !$form.updated('invoice_pdf')) {
    return;
  }

  const invoiceHandle = $form('invoice_pdf').value();
  if (!invoiceHandle) return;

  // Define the exact JSON structure we want the AI to return.
  // This schema perfectly matches our SCL definition, including the nested array for line_items.
  const schema = {
    type: "object",
    properties: {
      po_number: { type: "string", description: "The purchase order or invoice number." },
      vendor_name: { type: "string", description: "The name of the vendor or company that issued the invoice." },
      total_amount: { type: "number", description: "The final, grand total of the invoice." },
      line_items: {
        type: "array",
        description: "A list of all individual line items from the invoice.",
        items: {
          type: "object",
          properties: {
            description: { type: "string" },
            quantity: { type: "integer" },
            unit_price: { type: "number" }
          },
          required: ["description", "quantity", "unit_price"]
        }
      }
    },
    required: ["po_number", "vendor_name", "total_amount", "line_items"]
  };

  try {
    // Show an informational message to the user while the AI is working.
    $form('invoice_pdf').info("AI is processing your document...");

    // Call the AI engine to extract the data.
    const { data: extractedData } = await $ai.extract(invoiceHandle, {
      prompt: "Extract all key details and line items from this invoice document.",
      model: 'large', // Use a powerful model for complex document parsing.
      schema: schema
    });

    // Populate the form with the guaranteed, structured JSON data.
    $form('po_number').set(extractedData.po_number);
    $form('vendor_name').set(extractedData.vendor_name);
    $form('total_amount').set(extractedData.total_amount);
    
    // Set the entire line_items array directly into the JSON field.
    // The platform handles the serialization automatically.
    $form('line_items').set(extractedData.line_items);
    
    $form('invoice_pdf').info("Document processed successfully!");

  } catch (error) {
    $form('invoice_pdf').error(`AI processing failed: ${error.message}`);
  }
}

The Simple Advantage: First-Class JSON

Unlike legacy platforms where storing structured, nested data requires complex workarounds or separate tables, Simple treats json as a first-class citizen. The data you extract with AI can be stored directly, and our Data API Gateway can even index and run queries against the contents of your JSON fields, giving you the best of both relational and document-based worlds.

Example 2: Intelligent Support Ticket Summarization ​

Goal: When a support agent is handling a long, complex customer issue, automatically generate a concise, one-sentence summary to be used in dashboards and reports.

Step 1: The SCL Data Model ​

A simple support_ticket table with a detailed description and a field for the AI-generated summary.

ruby
# file: tables.scl

table support_ticket, support_tickets {
  default :id, :timestamps

  required title, :string
  required full_description, :string {
    length 5000 # A long text field
  }
  
  # This field will be populated by our AI script.
  optional short_summary, :string {
    length 255
  }
}

Step 2: The Record Behavior Script ​

This script runs on the update event, but only when the full_description changes, making it highly efficient.

javascript
// file: support_ticket_behavior.js

export default async ({ $form, $ai }) => {
  // Only run when the full_description field is modified.
  if ($form.event !== 'update' || !$form.updated('full_description')) {
    return;
  }

  const description = $form('full_description').value();
  
  // Only generate a summary if the description is reasonably long.
  if (description && description.length > 100) {
    try {
      $form('short_summary').info("AI is generating a summary...");

      const { data: summary } = await $ai.summarize(description, {
        prompt: "Summarize this customer support issue into a single, non-technical sentence suitable for a management dashboard.",
        model: 'lite' // A fast, cost-effective model is perfect for summarization.
      });

      $form('short_summary').set(summary).info(null); // Set the value and clear the info message.

    } catch (error) {
      // Don't block the user, just log the error and clear the info message.
      console.error("AI summarization failed:", error);
      $form('short_summary').info(null);
    }
  }
}

Next Steps ​