1Editor shell tour
Every system opens in the same shell: a toolbar across the top, a strip of 11 tabs (System Details · Connection · OAuth · Automation · Delegation · Designer · YAML Editor · MCP Tools · Fulfillment · API Docs · ⚡ AI Assist), and the active tab's body below. The newest tab — AI Assist — lets you describe a connector in plain English and have the YAML drafted for you.
| Element | Purpose |
|---|---|
| ← Back to Systems | Aria-label "Back to Systems". Returns to /systems (or /system-editor depending on host configuration). |
| Title | Reads "Create New System" in create mode or "Edit System: <name>" in edit mode. |
| Command badge | Total command count for this system. Click to focus the Designer tab. |
| System | Type toggle | Switches between editing the system instance and the system type template. Aria-label "Context Mode Toggle". |
| ⌘ Command palette | Aria-label "Open Command Palette". Opens with Ctrl + K. Searchable list of every action in the editor. |
| 🧪 Test | Aria-label "Test System". Opens the Test System modal — see Testing & API Docs. |
| 💾 Save | Saves changes. Label switches to "Save Type" in Type context. Aria-label "Save System (Ctrl+S)". |
| 11-tab strip | The eleven tabs of the editor (System Details, Connection, OAuth, Automation, Delegation, Designer, YAML Editor, MCP Tools, Fulfillment, API Docs, and the new ⚡ AI Assist). Cyclable with Ctrl + 1 through Ctrl + 4 for the four most common (Details, Designer, Editor, API Docs). |
2System vs Type — what's the toggle?
Two contexts, one editor
EmpowerNow lets you edit two different things in the same shell:
- System — a concrete instance: "our production EntraID tenant". This holds connection URLs, credentials, OAuth client info, and any per-tenant overrides.
- Type — a template that defines what an EntraID system looks like: standard commands, schema, fulfillment map. Multiple system instances can share a type.
The toggle (aria-label "Context Mode Toggle") flips between the two. The Save button label updates accordingly: Save System vs Save Type.
What appears in each context
| Tab | System context | Type context |
|---|---|---|
| System Details | Name, version, description, tags, system type | Type metadata, default commands, schema |
| Connection | URL, auth, credentials | Hidden (template-level) |
| OAuth / Delegation | Per-instance settings | Hidden |
| Designer | Commands inherited from type + overrides | Type-defining commands |
| Fulfillment | Hidden | Resource kinds, operations, validation |
| YAML Editor | Full system YAML | Full type YAML |
Most operators only ever edit System instances. Edit Type when you're authoring a reusable connector template (for example, a custom GraphQL adapter you want to share across tenants).
3Set metadata on System Details
The first tab — System Details — holds the system's identity and the OpenAPI/MCP cards.
| Field | Aria-label | Notes |
|---|---|---|
| Name | "System Name" | URL slug. Lowercase, no spaces. Cannot be changed after first save without re-creating. |
| Description | "System Description" | Plain English. Shown on cards in the list. |
| Version | "System Version" | Optional semver-style label tracking your own changes — independent of platform versioning. |
| Tags | "System Tags" | Comma-separated. Used by search and the mind-map clustering. |
| System Type | "System Type" | Pick a template (scim, oauth-rest, soap, jdbc, etc.). The Designer and Connection tabs adapt to the chosen type. |
4Import an OpenAPI spec
If the system you're connecting to publishes an OpenAPI (Swagger) spec, you can bootstrap commands automatically. The OpenAPI card sits on the System Details tab.
Open the import wizard
Click Import OpenAPI on the OpenAPI card (aria-label "Import OpenAPI Specification"). The wizard opens in a modal (aria-label "API Import Wizard") with four steps:
- Method — choose URL, file upload, or paste raw JSON / YAML.
- Configure — provide the URL or content, select the base server, optionally tag the imported commands.
- Preview — the wizard parses the spec and lists every operation it found, grouped by tag/path.
- Apply — confirm and apply: each operation becomes a command in the Designer.
What gets created
For each operation: a command with the correct path, method, parameters, and request/response schemas. Names are derived from the spec's operationId when present, otherwise from the path + method.
Existing commands are not overwritten unless you explicitly choose to replace.
The "Replace Specification" option drops the previous spec entirely. Use it when you have a clean v2 spec; otherwise prefer Import + manual reconciliation.
Test the spec before applying
Once a spec is loaded the OpenAPI card surfaces a Test API button (aria-label "Test API") that runs a sanity check against the base server. Use this to confirm the spec's URLs are reachable from the EmpowerNow side before you commit.
5MCP instance & Direct API toggles
Two switches near the bottom of System Details affect how AI agents and clients can talk to this system.
| Field | Effect |
|---|---|
MCP instance provider mcp-instance-provider | If set, this system is exposed as an MCP server with the given provider id. Agents can discover and call its commands as MCP tools. |
MCP instance name mcp-instance-name | Human-readable name for the MCP instance. Shown in MCP client lists. |
Allows direct API allows-direct-api-toggle | When on, callers can invoke commands via the platform's CRUD-style direct API in addition to via workflows. Use for systems where third-party services need a stable HTTP path. |
System Details turns the system into an MCP server. The MCP Tools tab and the per-command MCP section (inside the Command Modal) decide which commands are exposed and how. See Commands & Designer.
6The YAML Editor tab
Every system has a single YAML document that fully describes it. The YAML Editor tab gives you a Monaco-powered text editor for that document.
When to use it
- Quick bulk edits (renaming many parameters, changing a header across commands).
- Pasting a full system definition from another tenant.
- Reviewing the canonical structure before committing changes back via source control.
Most day-to-day editing happens on the Designer tab; YAML is the fall-through option.
YAML errors block the Designer
If your YAML doesn't parse, the Designer tab shows a "YAML parse error" banner with the exact line and won't let you make graphical edits. Fix the YAML first.
7YAML Editor toolbar
| Button | Aria-label | What it does |
|---|---|---|
| Import OpenAPI | "Import OpenAPI Specification" | Opens the same wizard as on System Details. Auth-wrapped: only visible if your role has api-import rights. |
| Format | "Format YAML" | Re-indents and reflows the document. |
| Copy | "Copy YAML" | Copies the entire document to the clipboard. |
| Paste | "Paste YAML" | Replaces the editor contents from the clipboard. Confirms first. |
| Test API | "Test API" | Quick smoke-test against the connection without leaving the editor. |
| Context | — | Switches between System and Type YAML, mirroring the System | Type toggle in the header. |
| ? | "Keyboard shortcuts help" | Pops the shortcuts overlay. |
| Save | "Save System (Ctrl+S)" / "Save Type (Ctrl+S)" | Persists the current YAML. |
| Character count | — | Live counter showing the document length, useful when the connector type imposes a limit. |
8The Command Palette
Open it
Press Ctrl + K (or click the palette icon in the toolbar — aria-label "Open Command Palette"). A searchable overlay appears (aria-label "Command Palette") listing every action in the editor: switch to a tab, jump to a command, run Test, format YAML, etc.
Useful palette commands
- Go to Designer · Go to Connection · Go to YAML — fast tab navigation.
- Add Command — opens the Command Modal directly.
- Test System — opens the Test System modal.
- Format YAML · Save — same as the toolbar buttons but keyboard-accessible.
9Save (Ctrl+S)
The Save buttons
Two equivalent ways to persist:
- The 💾 Save button in the editor toolbar.
- Keyboard: Ctrl + S (when not focused on a text field that handles the key itself).
The label adapts: Save System in System context, Save Type in Type context.
What gets saved
Whatever you've edited across all tabs since the last save. The editor batches changes so a single save commits Connection, OAuth, Designer edits, and YAML changes together.
Ctrl + 1–4 jumps to the four most-used tabs (System Details, Designer, YAML Editor, API Docs). The editor performs a silent save when leaving the metadata tab if you have unsaved changes there.
What blocks save
- Required field empty (Name, System Type).
- YAML doesn't parse.
- Your role lacks
system-editor:system·edit(button is disabled). - Fulfillment validation fails — see Commands & Designer.
10Save conflict — someone else edited the same system
EmpowerNow uses optimistic concurrency: each save sends a version tag, and the server rejects the save if the version on disk has moved ahead.
What you'll see
Reload vs overwrite
- ⟲ Reload — discards your edits and pulls the latest server version. Safer; recommended unless you know exactly what the other edit changed.
- ⚠ Overwrite — replaces the server version with yours. Use only when you're certain your version is the correct one (e.g. you copy-pasted from source control).
There is no merge UI today. Coordinate out-of-band before overwriting, or reload, redo, and re-save.