Netridium — Admin & Builder Guide

For IT, workspace admins, consultants, and accountants who set up Netridium, connect data sources, and build the AI tools their users run.

The core idea: you build a capability once — your users run it with one click and get a finished report or action back. They never see the prompt or the code, only a button, a short form, and a result.

Related guides: USER_GUIDE.md (for your end users) · LOGICSCRIPT_TYPES.md (Prompt vs LSPL vs Script) · PROMPT_INPUTS.md (input forms) · CONNECTOR_SETUP_FOR_ADMINS.md (connector specifics).

1. Concepts

• Workspace (tenant). Your isolated environment. All data, connectors, tools,

  users, and results belong to one workspace and never cross into another.

• AI Tool. A reusable tool you build. It runs against your connected

  systems and returns a result (Excel, PDF, HTML, chart, text, or JSON).

• Connector. A secure connection to one of your systems of record (NetSuite,

  Salesforce, Maxio, QuickBooks Online, Xero, Google Drive).

• Run / Report. One execution of an AI Tool and its saved result, kept in

  History.

• Roles & permissions. Control who can see and who can run each AI Tool.

2. First-time setup

1. Sign in and confirm your workspace details under Settings.
2. Connect your systems (section 3) — at least one connector is required to

   build a tool.

3. Build your first AI Tool (section 4) and run it to confirm the data

   flows.

4. Set up roles and invite users (sections 7–8) so the right people can run it.
5. Optionally configure notifications, scheduling, and your own AI key.

3. Connecting your systems

Open Connectors and add one per system. Each workspace connects its own accounts; credentials are encrypted and never shared across workspaces.

• OAuth connectors (Salesforce, QuickBooks Online, Xero, Google Drive) — click

  Connect and authorize in the provider's login screen. No copying API keys. Choose read-only or read-write access where the provider supports it.

• Endpoint connectors (Maxio, NetSuite) — provide the connection URL and token

  for the system's data service.

• Read-only vs write. Connectors are read-only by default. Grant write access

  explicitly, per connector, only when a tool genuinely needs to change data. A tool can never modify data through a connector that isn't write-enabled.

See CONNECTOR_SETUP_FOR_ADMINS.md for provider-by-provider steps.

4. Building an AI Tool

Go to AI Tools → New. Give it a title, an optional description and folder (for organizing the catalog), and pick the connector(s) it may use.

Choose a type

Full comparison: LOGICSCRIPT_TYPES.md.

• Prompt: write what you want the report to contain.
• LSPL: write the script's steps (FUNC / DO / IF / AI.call / VALIDATE

  / RETURN). The AI executes them in order.

• Script: write Python, or click Generate Python to have Netridium draft a

  runnable script from a natural-language description (it uses your connectors' real tools so names and parameters are correct).

Add inputs (optional)

In the Inputs section, define the values a user supplies before each run — text, number, yes/no, date, or a dropdown. At run time the user fills a short form; the values flow into the tool (and validation runs first). Reference a value in a Prompt or LSPL as {{key}}. See PROMPT_INPUTS.md.

Options

• Read-only — Prompt and LSPL always run read-only (read or list data only);

  they can never change data. Only Python Scripts can write, and only when the connector allows it. To write data, use a Script.

• Model tier (Prompt) — Fast for simple jobs, Smart for hard ones, or the

  workspace default.

• Batch processing (Prompt) — run at roughly half the cost when speed isn't

  critical.

• Timeout override, folder, and show links (clickable record IDs/URLs in

  result tables).

Save, then run

Save your changes, then click Run to test it. If the tool has inputs, fill the form first. Watch the live status; when it completes, you're taken to the result. You must save before running, so what executes is always the saved version.

5. Running, history & results

• Run a tool from the catalog, from My Reports, or from the editor.
• Every run shows live status and is saved to History with its inputs,

  result, and cost. Re-open or re-run any past report.

• Cancel a run that's in progress if you need to.
• Results render in the browser — searchable tables, clickable record links — and

  download with one click.

6. Scheduling

Open an AI Tool's Schedule page (admin only) to run it automatically on a recurring cadence — daily, weekly, or monthly, at a time and timezone you pick. Scheduled runs appear in History with a Scheduled badge and can email the right people when they finish.

7. Roles & permissions

Under Roles, control access per AI Tool:

• View — who can see the tool exists.
• Run — who can execute it.

Create roles for groups of users, then grant each role the tools it should have. Admins can run everything; everyone else is gated by their role. Publish a tool to exactly the right people — and revoke or change it for all of them at once.

8. Users & invitations

Under Users, invite teammates by email and assign them a role. New members can be required to be approved before they gain access. Each person only ever sees the tools their role permits — never the prompts or code behind them.

9. Sharing results

From a completed report, open Share to create a secure link. Shared links always open an access-controlled viewer (never a raw file), and you choose whether clickable source-system links are shown. Sharing stays governed.

10. Notifications

In Settings, choose when the workspace emails users and admins:

• On completion — off, unattended only (scheduled & batch runs), or *all

  runs*.

• On failure — on by default.

Recipients are the run's user plus the workspace's admins. Links in the email point at the in-app viewer, so access still requires a login.

11. AI key (BYOK) & cost

• Bring your own key. A workspace can run on its own AI provider key from

  Settings, keeping spend and data flow under its control.

• Usage & cost. Every run records its token usage and estimated cost; review it

  per workspace. Per-run budgets and caps prevent runaway jobs.

12. Moving tools between workspaces

Export your AI Tools to a portable file and import them into another workspace — ideal for consultants and MSPs who build once and deliver to many clients. On import, connector references are matched to that workspace's own connectors; anything missing is reported so you can wire it up.

13. Audit & governance

• Every meaningful action — who ran what against which data, every connector call,

  every admin change — is recorded in the audit log.

• Tools default to read-only; data-changing actions require explicit per-connector

  write access.

• Python tools run in an isolated sandbox with no access to platform secrets;

  credentials are injected per call and torn down when the run ends.

Builder best practices

• Be explicit about the output ("return an Excel sheet with columns X, Y, Z").

  It makes results consistent run-to-run.

• Start read-only. Only enable writes when a tool truly needs them, on the one

  connector that needs them.

• Use inputs instead of hard-coding values, so one tool serves many cases.
• Name and folder tools clearly — your users browse them by name.
• Test before you publish — run it yourself, confirm the result, then grant the

  Run permission.

14. Where things live (quick map)

AI Tool Inputs (pre-run parameters)

An AI Tool can declare a small set of inputs that are collected from the user before a run starts. The user fills a short form, clicks Run, and the values are woven into the AI Tool when it executes. The run itself is unchanged — still fire-and-finalize (queue → run → result); the inputs form is the only point of human interaction, and it happens up front.

This is a cross-cutting feature: it works on the Prompt (ai_mcp) type today, and the upcoming LSPL type reuses the same mechanism.

Use it for governed, user-initiated tools — e.g. "email this template to a chosen recipient," or "reconcile these specific accounts" — where the script is fixed but a few values change per run.

Defining inputs (admins / consultants)

Open an AI Tool in Edit and find the Inputs (optional) section. Click Add input for each value you want to collect. Each input has:

Field types

Incomplete rows (no key or label) are dropped on save, so a half-filled row never breaks anything. Save validates keys, uniqueness, and that a Dropdown has options.

Using inputs in the AI Tool body

Reference any input by its key inside double braces:

Draft a friendly reminder email to {{recipient}} about invoice {{invoice_no}}.
Keep the tone {{tone}}.

When the run executes, the worker does two things with the supplied values:

1. Placeholder substitution — every {{key}} in the prompt text is replaced

   with the value (whitespace inside the braces is tolerated: {{ key }} works).

2. Appended block — the values are also added at the end of the prompt as a

   labelled list, so the model still sees them even if you didn't use a placeholder for every field:

   ## Inputs provided for this run
   - recipient: sarah@example.com
   - invoice_no: 98231
   - tone: warm

You can rely on either approach. Placeholders give you precise control over wording; the appended block is a safety net.

Running with inputs (end users)

Clicking Run on an AI Tool that declares inputs opens a dialog to collect the values; fill them in and submit to launch the run. This works from every entry point — the AI Tool catalog, the editor's Run, and the My Reports Run/re-run button.

Scripts with no inputs run in one click (no dialog) and show their live status in place.

Validation happens both in the dialog (required fields) and on the server (types, required, and that a Dropdown value is one of the allowed options). Unknown values are ignored, so a stale form can't smuggle extra data into a run.

Run buttons are labelled "Run" everywhere (a re-run is just another Run). A run's status is live and survives navigating away and back: a still- running report keeps showing its status in the catalog and My Reports lists, reconnecting from the report's id rather than transient page state.

The values used for a run are stored on the run record (report_history.inputs), so History reflects exactly what each run was launched with.

Examples

All three are Prompt (ai_mcp) AI Tools — the type that supports inputs today. Each shows the inputs you'd define, the prompt body that references them, and what reaches the model at run time.

Example 1 — Templated reminder email

A tool that emails a chosen recipient using a fixed template with a few fill-in-the-blanks.

Inputs

Prompt body

Draft a payment reminder email to {{recipient}} for {{customer_name}}.
It concerns invoice {{invoice_no}}, which is due {{due_date}}.
Use a {{tone}} tone. Return the subject and body as text.

What the model receives (after substitution + the appended block):

Draft a payment reminder email to sarah@example.com for Acme Co.
It concerns invoice 98231, which is due 2026-07-01.
Use a friendly tone. Return the subject and body as text.

## Inputs provided for this run
- recipient: sarah@example.com
- customer_name: Acme Co.
- invoice_no: 98231
- due_date: 2026-07-01
- tone: friendly

Example 2 — Account reconciliation for a period

Pick the accounts and the date range; the AI Tool pulls the data via its connectors and returns a status + comments.

Inputs

Prompt body

Reconcile the following account(s) for the period {{period_start}} to
{{period_end}}: {{accounts}}.
Compare transactions across the connected sources, flag any mismatches, and
return a short status (balanced / discrepancies found) followed by comments.

Here include_notes has no {{placeholder}} — it still reaches the model in the "Inputs provided for this run" block, so the prompt can react to it.

Example 3 — Top-N customers report (no required text)

A reusable report where only a count and a category change per run.

Inputs

Prompt body

List the top {{limit}} customers by MRR for the "{{product_family}}" product
family as an Excel sheet with columns: customer, plan, MRR.

A Number input arrives as a real number (e.g. 25, not "25"), so the prompt can use it directly.

How it works (implementation)

Inputs are also carried through AI Tool export/import, so a parameterized script moves between tenants intact.

Limits / not yet supported

• Dynamic option sources — Dropdown options are a static list today. Pulling

  choices from a connector query (e.g. "pick from your Xero accounts") or a tenant user picker is a planned follow-up.

• Injection path — values are injected for the Prompt (ai_mcp) path. The

  Script (python) path receives its data differently and is not wired to these inputs; the LSPL type will reuse this mechanism when it lands.

See AGENT_DESIGN.md for where this fits in the broader plan (it is "Phase 2 — pre-run parameters").

AI Tool types: Prompt vs LSPL vs Script

An AI Tool is a reusable, governed tool an admin or consultant builds and an end user runs with one click. There are three types, distinguished by who owns the control flow — the plan for what happens in what order:

They share the same plumbing: per-tenant connectors, the run queue, live status, pre-run inputs, and the same downloadable output (Excel / HTML / text / PDF / image / JSON). They differ in how the work is expressed and executed.

At a glance

Prompt (natural language)

You describe the outcome; Claude orchestrates your connectors' tools, analyzes the data, and picks the best output format. The model owns the whole task — it decides which tools to call and in what order — and answers in one pass.

List all active subscriptions grouped by product, with MRR per group,
as an Excel sheet.

• Strengths: fastest to author; great for ad-hoc and "fetch + present" reports;

  the model adapts when data is messy.

• Trade-offs: least predictable — two runs can take different paths or vary in

  shape. Pin it down with an explicit output instruction when consistency matters.

LSPL (LogicScript Prompt Language)

You write a structured script in LSPL; the AI runs it in direct-execution mode — it reads each line and acts on it rather than generating code. It reasons at each AI.call, branches at each IF, checks each VALIDATE, and produces the outputs the script names. You own the plan and the guardrails; the AI fills in the judgement.

FUNC run(ticket)
  VALIDATE
    ticket.subject not empty
  DO
    classification = AI.call("Classify this ticket: priority, category, resolvable?")
    LOG "Classification: {classification}"
    IF classification.canResolve IS yes
      reply = AI.call("Draft a resolution for the customer.")
      RETURN reply
    EMIT NeedsHuman { reason: "low confidence" }
  RETURN "escalated"

• Strengths: explicit, scannable, and unambiguous — the branches, validation,

  and output format live in the script, so two runs (or two readers) follow the same steps. Repeatable and reusable across many inputs without rewriting prose.

• Trade-offs: more structure to author than a one-line Prompt; the AI still

  supplies the reasoning at each step, so the content of each step can vary.

• Always read-only: LSPL never changes data — like Prompt, it can only read or

  list. Data writes belong in a Python Script, where the author writes the exact write call. LSPL also requires at least one connector.

LSPL is interesting because the same script also works in code-generation mode ("implement this in Python"). In Netridium we use direct-execution mode: the AI is the runtime. See AGENT_DESIGN.md.

Script (Python)

You write Python that runs deterministically in a sandbox. It calls your connectors explicitly, can transform data however you like, optionally calls the model via prompt() / agent(), and returns its result with emit(...). You own every step.

rows = await mcp("Maxio").call("advancedBillingShowCustomers", {"per_page": 20})
emit({"type": "excel", "sheets": [{"name": "Customers", "data": rows}]})

• Strengths: total control and repeatability; exact transforms, custom logic,

  and behavior the AI shouldn't decide. Can write back where the connector permits.

• Trade-offs: you write (and maintain) code; least "describe it and go." A

  Generate helper can draft the Python from a natural-language description.

Which should I use?

• Reach for a Prompt when the request is essentially "get this data and show it"

  and you're happy for the model to figure out the how. Quickest path to a report.

• Reach for LSPL when the process matters — you want defined steps, explicit

  branches, validation, and a consistent shape across runs — but the work still needs the AI's judgement at each step (classify, draft, decide). It's the middle ground: structured like code, executed by the AI like a prompt.

• Reach for a Script when you need determinism and precise control — exact

  calculations, data reshaping, multi-source logic, or steps the AI must not improvise — and you're comfortable writing Python.

A rough rule: Prompt = "what I want," LSPL = "the steps to take," Script = "exactly how to do it."

One-line summaries (for docs / UI copy)

• Prompt — *Describe what you want in plain English; the AI pulls from your

  connectors and returns the result.*

• LSPL — *Write the steps as a structured AI Tool; the AI executes them in

  order, reasoning at each step — repeatable and unambiguous.*

• Script — *Write Python for full, deterministic control; call your connectors

  and emit the result.*

Related

• PROMPT_INPUTS.md — pre-run input parameters (works for

  Prompt and LSPL).

• AGENT_DESIGN.md — why LSPL is its own type, and the policy

  that Prompt + LSPL are always read-only (data writes live in Python Scripts).

Connector setup (for client-account admins)

How to connect your data sources so your team's AI Tools can pull from them. This guide is for admins of a client workspace — connectors are admin-only.

Where connectors live

In your workspace, open Connectors (left nav). The page has:

• Connection cards at the top — one-click OAuth for Salesforce, Xero,

  and QuickBooks Online. Click Connect, authorize, done.

• An "Add connector" button — for Google Drive, Maxio, and

  NetSuite, which you add as a row and then either connect (OAuth) or paste credentials into.

Only workspace admins can add or connect connectors. In a demo workspace the whole page is read-only.

How connectors are used

• A connector becomes available to AI Tools — both Prompt (natural

  language) and Script (Python) types — by the name shown on the Connectors page.

• Connectors are used read-only by default. Prompt and LSPL AI Tools are

  always read-only (restricted to read/list tools); only Python Scripts can write data, and only when the connector allows it. See Allowing writes.

• Some connectors require a one-time platform setup by Netridium (the OAuth

  app) before you can connect — those are called out below. If you see "… OAuth isn't configured", ask Netridium to finish that setup.

Salesforce

What you get: query your Salesforce org with SOQL, list/describe objects, read records (and create/update records when connected read-write).

Prerequisite: Netridium must have configured the platform Salesforce Connected App (System Manager → Settings). If Connect errors with "Salesforce OAuth isn't configured", that step is pending.

Connect:

1. On the Connectors page, find the Salesforce card.
2. Pick Read-only (recommended) or Read-write (only if Scripts need to

   create/update records).

3. Click Connect Salesforce → log in to Salesforce → Allow.
4. You return to the Connectors page; the card shows Connected with your org

   name. The org is now a connector you can add to an AI Tool.

Reconnect / disconnect: use Reconnect (e.g. after a password change or if the card shows Needs re-authorization) or Disconnect on the card.

Xero

What you get: query your Xero accounting org (invoices, contacts, accounts, etc.), with create/update when connected read-write.

Prerequisite: Netridium-configured Xero app. (One Xero org per workspace.)

Connect:

1. On the Connectors page, find the Xero card.
2. Choose Read-only or Read-write.
3. Click Connect Xero → authorize in Xero → pick the organisation.
4. The card shows Connected with the org name.

QuickBooks Online

What you get: query your QuickBooks company (customers, invoices, accounts, etc.), with create/update when connected read-write.

Prerequisite: Netridium-configured Intuit app. (One company per workspace.)

Connect:

1. On the Connectors page, find the QuickBooks Online card.
2. Choose Read-only or Read-write.
3. Click Connect QuickBooks → authorize in Intuit → choose the company.
4. The card shows Connected with the company name.

Google Drive

What you get: search and read files in your Google Drive from an AI Tool (and create files if you enable writes).

Prerequisite: Netridium-configured Google OAuth app (or bring your own — see Advanced below).

Set up:

1. Click Add connector → Type: Google Drive.
2. Give it a Display name (e.g. "Company Drive").
3. Leave Allow Drive writes off for read-only (recommended). Turn it on only

   if a Script needs to create files (this requests broader Google permission and requires connecting after saving).

4. Click Add connector to save.
5. Back on the Connectors page, click Connect on the row → choose your Google

   account → Allow. The row then shows Connected.

Advanced (your own Google app): expand "Advanced: use your own Google OAuth app" in the Add form to enter your own Client ID/Secret (and optionally a refresh token). The redirect URI to register is shown in the form.

Maxio

What you get: Maxio Advanced Billing & Core data (subscriptions, invoices, customers, etc.).

Maxio uses OAuth — you don't paste a token.

Set up:

1. In Maxio, get your MCP server URL (looks like

   https://your-tenant.mcp.maxio.com/v2/mcp/...).

2. Click Add connector → Type: Maxio.
3. Give it a Display name, paste the MCP Server URL. Leave API Token

   blank.

4. Click Add connector to save.
5. On the Connectors page, click Connect on the Maxio row → authorize with

   Maxio. The row shows Connected.

Maxio's server requires OAuth — a pasted token alone is rejected with a 401. Use the Connect button after saving.

NetSuite

What you get: Oracle NetSuite ERP via the NetSuite AI Connector Service.

NetSuite uses a static bearer token (no Connect step).

Set up:

1. In NetSuite's AI Connector Service, get your MCP server URL, an

   Authorization Token (bearer), and your Account ID.

2. Click Add connector → Type: NetSuite.
3. Fill in Display name, MCP Server URL, Authorization Token, and

   NetSuite Account ID (e.g. 1234567, or 1234567_SB1 for a sandbox).

4. Click Add connector to save. It's ready to use — no separate Connect step.

If the token expires or rotates, Edit the connector and paste the new one (leave the token field blank to keep the existing one).

Allowing writes

Connectors are read-only by default, which is the safe choice for reporting. To let an AI Tool create or update data:

• Google Drive — check Allow Drive writes when adding (or editing) the

  connector, then Connect to grant the broader Google permission.

• Salesforce / Xero / QuickBooks Online — Connect (or Reconnect) the card

  with Read-write access instead of Read-only.

Even then, write tools are exposed conservatively: an AI Tool marked read-only never gets them, and every tool call is recorded in the audit log. Grant read-write only to workspaces and people who need it.

Reconnecting & troubleshooting

After connecting, test it: open an AI Tool, add the connector, and run a simple read (e.g. "list 5 records"). If it returns data, you're set.