Back to Documentation

Creating and Managing Records

This guide walks you step by step through working with structured data in Sutram: defining metadata fields, assembling a record category, creating records, and maintaining them. If you haven't read the concept yet, start with Records and Metadata: structured data in Sutram.

Before you begin: Records require a paid plan (starting with Pro). Defining categories and metadata is an owner or admin action; creating records is also open to members.

Overview of the flow

Setting up a record type takes three steps, done once; after that, creating records is fast and repeatable.

1. Define the fields       →  Metadata Definitions
2. Assemble the mold       →  Record Category
3. Create the entries      →  Records

Step 1: Define the metadata fields

Fields are defined once and reused across multiple categories.

  1. In the project settings, open Metadata Definitions (Tag Definitions)
  2. Create each field by providing:
    • a key (identifier, e.g., autor)
    • a label (the displayed name, e.g., "Author")
    • a type: text, enum, boolean, date, or computed
  3. For enum fields, list the allowed values (e.g., electrical, mechanical, civil)
  4. For automatic numbering, create a computed field

Note: only owner and admin manage metadata definitions.

Step 2: Assemble the record category

The category is the mold that gathers the fields and defines the slug.

  1. In the project settings, open Record Categories (Folder Categories)
  2. Create a category and give it a name (e.g., "Invoice")
  3. Add the metadata fields it uses, marking which are required and setting the order
  4. Configure the slug:
    • if you use numbering, indicate which fields form the numeric base (computed_from)
    • indicate which fields make up the final slug (slug_from)
  5. Save

From here on, every record created with this category will have its fields validated and its slug generated automatically.

Step 3: Create a record

  1. In the Content tab, navigate to the folder where the record should live
  2. Click New record and choose the category
  3. Fill in the metadata fields — the required ones are validated on the spot
  4. Confirm

Sutram generates the slug automatically and creates the record (a Record that corresponds to a folder with its metadata). Records that share the same numeric base receive distinct sequential numbers, with no collisions.

Step 4: Edit and maintain

  • Update metadata: open the record and edit the fields. If you change a field that makes up the slug, the identifier may be recalculated.
  • Change just one field: you can adjust a single metadata value without rewriting the others.
  • Delete: removing a record deletes the folder and all its content — the action cannot be undone.

Doing all of this with AI (MCP)

All of these operations can also be performed by an AI assistant connected via the Sutram MCP Server — useful for creating records in bulk, standardizing metadata, or migrating content. Examples of what to ask:

  • "Create a record category 'Contract' with the fields party, amount, date, and status."
  • "Register these 20 contracts as records, filling in the metadata from the spreadsheet."

The reference for the Records tools is in the Sutram MCP Server Guide. Before creating records in bulk, ask the AI to check the fields the category requires.

Tips

  • Start small — define the essential fields first; you can add more later.
  • Enum > free text for known values — avoids discrepancies like "Civil" vs "civ eng".
  • Plan the slug before creating in bulk — the slug_from fields become the record's durable address.
  • Reuse fields — the same field (e.g., autor) can serve multiple categories.

Frequently Asked Questions

Q: Who can create categories and who can create records?

A: Categories and metadata definitions are managed by owner and admin. Creating and editing records is also open to members. Viewers only read.

Q: Can I add a new field to a category that's already in use?

A: Yes. Categories evolve; existing records remain valid. Just be careful when touching fields that make up the slug, since that affects how the identifier is computed.

Q: Can the slug repeat?

A: No. The numeric base (computed_from) guarantees unique sequential numbering within each key, so two records never collide.

Next Steps

  • Records and Metadata — the concept behind what you just did
  • Wiki and Knowledge Graph — how records feed the wiki and the graph
  • Sutram MCP Server Guide — the reference for the Records tools for use with AI

Document Version: 1.0 Last Updated: July 2026 Author: Sutram Development Team

Back to Documentation