EDK Authoring

Limited Release. The EDK is currently in limited release and is not available to all customers. Commands, generated file layouts, and package APIs may change before general availability. Confirm you’re on the latest EDK version before starting new projects.

Authoring in the EDK means editing TypeScript source that represents the entities in your Elementum organization. This page covers how to pull existing entities into your workspace, the structure of the generated files, and how to write changes using the EDK’s builders and typed @catalog references.

If you haven’t set up your workspace yet, start with the Getting Started guide. You need a completed elementum pull org --data-only before you can pull individual entities.

Pull Existing Entities

The EDK is designed for iterating on Apps and Elements that already exist in your organization — not for creating them from scratch. Create new objects in the Elementum platform first, then pull them into your EDK workspace to continue authoring in TypeScript.

Starting in the platform lets Elementum assign the initial namespace, handle, and layout defaults, and gives the EDK a clean, deployed starting point. Creating an App or Element directly in EDK source is not the recommended workflow.

pull org --data-only creates the organization workspace but does not pull every App and Element as editable source. Pull the specific entities you plan to modify with the commands below.

Pull an App

Pulling an App requires its aspect ID. You can look this up from the CLI with elementum list apps, or find it in the platform using your browser’s developer tools:

Find the App's aspect ID

Open the App in the Elementum platform, then open your browser’s developer tools and switch to the Network tab. Filter the requests for graphql?apollo_op=GetAspectNamespace.In the response, copy the id value nested under aspect. The response contains two IDs — one for the organization and one for the aspect — so make sure you copy the one under aspect, and leave out the surrounding quotation marks.

Pull the App into your workspace

Run pull app with the ID you copied:

elementum pull app --id <app-aspect-id>

Depending on how much the App contains — automations, related objects, and so on — this can take some time. When it finishes, the App appears as a TypeScript file in your workspace under apps/.

Pull an Element

elementum pull element --id <element-id>

Workspace Structure

After pull org and a few pull commands, your workspace looks like this:

<instance>/
└── <organization>/
    ├── generated/
    │   ├── catalog.ts
    │   ├── mapping.json
    │   └── state.<environment>.json
    ├── apps/
    │   └── <appRef>/
    │       ├── <appRef>.ts
    │       ├── generated/catalog.ts
    │       ├── agents/
    │       ├── automations/
    │       ├── skills/
    │       ├── flows/
    │       ├── search-tables/
    │       └── approvalChains/
    └── elements/
        └── <elementRef>/
            ├── <elementRef>.ts
            ├── generated/catalog.ts
            └── search-tables/

Each entity you pull becomes a folder under apps/ or elements/, with the entity’s TypeScript definition at the top and sub-folders for its child entities.

Rules of the Workspace

These rules protect deployed identities and keep planning reliable:

Identity bindings live in generated/state.<environment>.json. Do not hand-edit state or mapping files — they map your source to deployed UUIDs and are regenerated by the EDK.
Generated catalogs expose typed references for authoring. The generated/catalog.ts files back the @catalog alias so you can reference fields, automations, and agents by their handle-tokens.
Do not place UUIDs in authored entity source. UUIDs belong in generated state only. Use @catalog handle-tokens everywhere else.
Preserve existing refNames and handles unless you’re performing a deliberate identity migration. Changing a refName typically replaces the entity and can orphan existing records or relationships.

Modify Entities with Builders and `@catalog`

The EDK exposes builder functions for each entity type. Import the builder you need from the appropriate subpath of @elementumai/edk, and reference other entities through the @catalog alias:

import { defineAutomation, defineWorkflow } from "@elementumai/edk/automations";
import catalog from "@catalog";

Reference fields, automations, agents, and other entities by their handle-tokens — never by UUID:

catalog.serviceRequestItsm.fields.status
catalog.managedEntities.fields.entityName
catalog.knowledgeItsm.automations.publishNewArticle

Because @catalog is typed, TypeScript will flag broken references before you plan. If a field or automation you expect to see is missing from @catalog, run pull org or pull again to refresh the generated catalog.

Type-Check Your Changes

Run the standalone TypeScript check whenever you make changes:

npx tsc --noEmit

A project-level tsconfig.json is required for this command to produce useful output. The EDK also performs entity-specific TypeScript checks during plan, but tsc --noEmit catches most authoring mistakes faster and without hitting the platform.

A clean tsc --noEmit does not guarantee that all referenced platform handles exist in the deployed environment. TypeScript only sees what’s in your generated catalog. If a handle is present in your source but not yet deployed, plan will report it as blocked — see Debug blocked plans.

Work with the Authoring Agent

The EDK Authoring skill teaches your IDE’s coding agent how to build EDK projects correctly. When you delegate authoring work to an agent, give it enough context to make good decisions:

The business outcome and process lifecycle — what the change is meant to accomplish.
The exact workspace and target App or Element — for example, dev/my-org/apps/knowledgeItsm.
An instruction to inspect current source, generated catalogs, and deployment state first — before writing new code.
A requirement to preserve deployed identities — no new refNames for existing entities, and use @catalog for all cross-references.
A requirement to run plan before apply — never apply without a reviewed plan.
Whether new Automations should be DRAFT or ACTIVE — the agent will otherwise guess.
Permission boundaries — for example, “no apply until I’ve reviewed the plan output.”
Available models and supporting entities — tell the agent which models your organization has and which other Elements or Apps the change depends on. Pulling related entities into the workspace gives the agent the full context it needs to build a complete process.

The EDK Authoring slash command in your code editor loads the current skill prompt automatically. Following that with the items above gives the agent the specific business and environment context the skill can’t infer on its own.

Next Steps

Plan and Apply

Preview the structural diff, deploy new fields in stages, and verify convergence.

CLI Reference

Every elementum command grouped by prefix, with usage and flags.

Workflow Design

Elementum Development Kit

Rules & Automation

Record Management

Pull Existing Entities

Pull an App

Pull an Element

Workspace Structure

Rules of the Workspace

Modify Entities with Builders and `@catalog`

Type-Check Your Changes

Work with the Authoring Agent

Next Steps

Plan and Apply

CLI Reference

​Pull Existing Entities

​Pull an App

​Pull an Element

​Workspace Structure

​Rules of the Workspace

​Modify Entities with Builders and @catalog

​Type-Check Your Changes

​Work with the Authoring Agent

​Next Steps

Plan and Apply

CLI Reference

Pull Existing Entities

Pull an App

Pull an Element

Workspace Structure

Rules of the Workspace

Modify Entities with Builders and `@catalog`

Type-Check Your Changes

Work with the Authoring Agent

Next Steps