Role guide: developer

This guide is for the person who takes the requests configuration alone can't satisfy: you decide where a piece of logic belongs, build it in Setup or from your own tools, prove it works, and move it safely to the organization that uses it. Your work sits at the top of the customization ladder — expressions and business rules where declarative tools still reach, scripts and workflows where they don't, and the developer surface (data API, MCP endpoint and CLI) when xMatix has to talk to the rest of your stack.

Overview

A developer in xMatix does three kinds of work:

• Extend the save and the buttons. Business rules, automation scripts, workflows and approval processes, all attached to an entity's save pipeline or to an action a user runs.
• Prove and watch. Test runs, the entity's Execution Plan and dry run, test scenarios, run history, user tracing and the job monitor tell you what your logic really did.
• Connect and promote. The data API and MCP endpoint let other systems and AI assistants work on your records; the CLI and DeltaPacks move configuration between organizations.

Every one of these runs on the same platform services and the same security model as the product's own screens. Nothing you build or call gives anyone more access than their security profile already grants.

Where you work

Almost everything you build is authored inside Setup:

The Scripts register is your inventory of code in the organization. Status shows Active or Disabled, and Active version shows which saved version the runtime executes. A script runs only when it is not disabled, has an active version, and has at least one enabled binding that matches the record's entity, phase and change kind.

Outside Setup you reach the same platform from your own tools: the data API (REST over every entity, running the same actions and automation as the screens), the MCP endpoint (the platform's tools for AI assistants) and the CLI (scripts, rules, workflows, metadata and packages as files in git).

Your path

1. The customization ladder — where code sits, and why it is the last rung, not the first.
2. What runs when you save a record — the lifecycle phases, the Execution Plan and dry run; read this before writing any logic.
3. The data model — entities, fields, relations and record types.
4. Entity behavior — views, validations, actions and field mappings on an entity.
5. Expressions — the expression language shared by rules, filters and formulas.
6. Business rules — declarative save-time logic; exhaust this before scripting.
7. Your first automation script — create, version, bind, test and observe a script.
8. Workflows and approval processes — work that spans more than one save.
9. Sandboxes and DeltaPacks — build away from production and promote reviewed configuration.
10. Developer documentation — the section index, then the data API, the MCP endpoint and the CLI quickstart.
11. Troubleshooting the developer surface — sign-in, push, drift and API errors.

Prerequisites

• A security profile with the Setup capabilities for your areas — see Permissions. Without them the matching Setup entries are hidden.
• Ordinary record access on the entities you work with. Capabilities open Setup screens; they don't let you read or write records. Testing a script or calling the API needs the entity grants too.
• A place to build that isn't production. A sandbox, where your subscription includes sandboxes, or a separate test organization.
• For the CLI, the .NET 10 SDK on your machine and, on Linux, a running keyring for the token cache (CLI authentication).
• For the MCP endpoint, an administrator must switch on Allow external assistants — it is off until then.

Procedure

This is the routine for one change, from request to production.

Step 1 — Place the request on the ladder

Decide what kind of logic the request needs before you open an editor. A default, a conditional requirement, a blocking message or a status guard on one record is a business rule. Logic that crosses records, calls an external system or sits behind a custom button is a script. Work that waits or runs over several steps is a workflow, and human sign-off is an approval process. A business rule that can do the job is the better choice, because any administrator can read and adjust it.

Step 2 — Read the entity and its Execution Plan

Go to Setup → Design Studio → Entities, open the entity, expand Logic and open Execution Plan. Select Insert, Update or Delete to see the ladder for that operation: each phase lists the business rules, workflows and scripts on their sequence slots, and Platform steps shows the product's own handlers. Note the field logical names you will use — code and API payloads use logical names, never on-screen labels.

Step 3 — Build where users can't see it half-finished

Create or refresh a sandbox under Setup → Platform → Sandboxes & DeltaPacks → Sandboxes, or work in a separate test organization. A sandbox is an isolated copy with its own sign-in address; see Sandboxes and DeltaPacks for what each copy option brings across.

Step 4 — Build the logic

• A business rule: go to Setup → Process Studio → Business rules, create the rule on the entity, set its conditions and actions, and save.
• A script: go to Setup → Process Studio → Scripts and select New. Enter Name, Label and Description, keep Disabled on while you write, and save. Open the script, write the body on the Script tab and save: a body that compiles becomes the active version straight away, and one that fails to compile is saved but not activated. On the Bindings tab add a binding with an Entity and a Type — Lifecycle (choose the Lifecycle Phase and Change Kinds) or Server Action (choose the Entity Action). The moment the script is enabled and an enabled binding exists, it is live for that trigger.
• A workflow: go to Setup → Process Studio → Workflows and build it in the designer. In the designer, saving a published workflow with Publish changes puts it live at once.

Step 5 — Test it

• On the script's Runs tab, use the test panel: choose the entity, give a sample record or an existing record id, pick the phase and change kind, and select Run Test. The test runs this script's active version only — no binding needs to match and other scripts don't run — so also confirm the wiring with a real save. Side effects are real: data the script writes is saved and messages it sends go out.
• In the Execution Plan, select Dry run to push one save through the real lifecycle and roll it back. You can simulate a new record, an existing record or an action on a record.
• For regression checks, add a scenario under Setup → Platform → Testing with New scenario, and use Run all after a release or a configuration change.

Step 6 — Observe it running

• Every test, every failed run and every cancelled run is kept on the script's Runs tab with its status (Pending, Running, Succeeded, Failed or Cancelled), error, log and step trace, and the record it saw. Copy as Test Input turns a failure into a repeatable test, and Re-run replays a failed run.
• Successful live runs are kept only while user tracing is on. Go to Setup → Platform → Monitoring → Tracing, choose the user (yourself by default) and a duration of 15 min, 30 min or 60 min, and select Start tracing. Then repeat the save as that user.
• Asynchronous work and scheduled jobs appear under Setup → Platform → Monitoring → Jobs.

Step 7 — Promote the change

Choose one route and stick to it for the change:

• DeltaPack. In the sandbox, go to Sandboxes & DeltaPacks → DeltaPacks, select New DeltaPack, set the Target tenant, then Add items — business rules, automation scripts, custom components, approval processes, entities and fields, layouts and the rest. On the target, someone with the inbound capability reviews it under Inbound DeltaPacks and selects Apply to this tenant. A DeltaPack carries configuration, never business records.
• CLI. Pull the reviewed configuration into git and push it to the target with the CLI — migrate plan and apply for a reviewed repository, or the per-kind commands for scripts, rules, workflows and metadata. A script pushed without --activate is staged as a version without going live.

Step 8 — Connect other systems

For an integration, ask an administrator for a dedicated user whose profile grants exactly the entities, fields and actions the integration needs, then call the data API as that user. Routes use the version segment 1.0 (/api/1.0/...). For AI assistants, use the MCP endpoint; for a new external system, start from connector authoring and Connect an external system.

Example

A sales operations lead asks that no order can be saved with a negative total, and that a confirmation message is sent to a partner system each time an order is created.

1. Place it. The first half is a single-record validation, so it is a business rule. The second half calls an external system, so it is a script bound asynchronously after the save.
2. Read the plan. In the sandbox, the developer opens Design Studio → Entities → Order → Logic → Execution Plan, selects Insert and sees which phases already carry steps.
3. Build. They create a business rule on Order that blocks the save with "Total must be positive." Then they create a script named OrderPartnerNotify, keep it Disabled, write the body that posts the order number to the partner, save until it compiles, and add a Lifecycle binding on Order, phase After Save, change kind Insert, with Run Async on.
4. Test. Dry run with a negative total shows the rule's message. A Run Test with a sample order shows a Succeeded run with the outbound call in the log.
5. Enable and watch. They switch Disabled off, start Tracing for themselves for 30 minutes and save a real order; the run appears on the Runs tab and the job under Jobs.
6. Promote. They add the business rule and the script to a DeltaPack targeting production. A colleague applies it from Inbound DeltaPacks.

Training

Practice exercise

In a sandbox or test organization, create a script that does nothing but write a log line, with Disabled on. Save a body that compiles, add a Lifecycle binding on Account for the Validate phase and the Update change kind, and select Run Test on the Runs tab with an existing account's id. Then switch Disabled off and edit an account.

Expected result: the test run appears on Runs even while the script is disabled, because a test always runs the active version. The real account edit produces a run only after Disabled is off; it is listed as a successful live run only if you started Tracing for yourself first.

Quick reference

• Prefer a business rule; write a script only when a rule can't do the job.
• A script runs only when it is enabled, has an active version, and has a matching enabled binding.
• Saving a script body that compiles makes it live at once; use the CLI without --activate to stage a version.
• Run Test runs the active version only and has real side effects.
• Dry run in the Execution Plan simulates a whole save and rolls it back.
• Successful live runs are kept only while user tracing is on (15, 30 or 60 minutes).
• Use logical names in code and payloads; data API routes start /api/1.0/.
• Every API, MCP and CLI call acts as a user and gets exactly that user's rights.

Permissions

Setup areas are opened by capabilities, granted on a security profile's Entitlements tab under Setup → Access control → Profiles. A capability counts only when the user is also entitled to the feature it belongs to. Setup hides an entry from a user who lacks its capability.

Capabilities don't replace record access. To read or write the records your script, test or API call touches, the identity you work as still needs ordinary profile grants on those entities, and actions need their action grants. Data API, MCP and CLI calls run with exactly that identity's rights; the developer surface has no separate licence and no bypass.

Configuration

Set up a developer profile

1. Go to Setup → Access control → Profiles, open a profile close to what the developer needs and select Clone. Enter a Label and Name and keep the grant sets you want. User assignments are never copied.
2. On the new profile's Entitlements tab, tick the capabilities from the table above for the areas this developer works in, with their feature and product. Fix any dangling grant warning, then Save.
3. Check the entity, app and action grants cover the entities the developer tests against.
4. Assign the profile to the developer. Changes reach a signed-in user within about two minutes.

Separating DeltaPacks (authors, in the sandbox) from Inbound DeltaPacks (approvers, on production) between two profiles gives you a two-person promotion step.

Settings that shape developer work

Common problems

A Setup entry I need is missing

Your profile lacks the capability for it, or holds the capability without its feature. Ask an administrator to tick it on the profile's Entitlements tab and clear any dangling grant warning; it reaches you within about two minutes.

My script never runs

Check, in order: the script is Disabled; every binding is disabled; no binding matches the entity, phase and change kind of the save; the script has no active version. A body that failed to compile is saved but not activated, so check the Versions tab for Errors.

The test passed, but real saves do nothing

Run Test runs the active version without needing a binding, so a passing test proves the code, not the wiring. Check the binding's entity, phase and change kinds, and that the binding is not disabled.

I can't find my successful runs

Only tests, failed runs and cancelled runs are always kept. Start Tracing for the user, then repeat the save.

A button returns success but nothing happens

A server action with no bound script and no built-in handler succeeds silently. Check the Server Action binding points at the right Entity Action; the dispatch is keyed on the action's name.

"Server has a newer current version than your local copy."

The CLI refused a script push because someone saved a newer version in the product. Pull the script, merge your change and push again — see Troubleshooting the developer surface.

Common questions

Business rule, script or workflow — how do I choose?

Choose by reach, then by lifetime. If a business rule can express it, stop there: it is enforced on the server the same way and any administrator can read it. Logic that crosses records, calls out or sits behind a custom button is a script. Anything that waits, branches over time or spans several saves is a workflow, and human sign-off is an approval process. The customization ladder is the fuller guide, with examples of each rung.

Something fires on save and I don't know what — how do I find it?

Open the entity's Execution Plan and select the operation that misbehaved. It lists every business rule, workflow and script on its phase and sequence slot, and Platform steps adds the product's own handlers. Use Dry run to push one save through and roll it back. If a script is involved, its Runs tab shows the log and step trace; start Tracing first if the run succeeded. What runs when you save a record walks through the diagnosis step by step.

How do I move what I build between organizations?

Use a DeltaPack when you built in a sandbox: add the items in the sandbox, and someone with the inbound capability applies the pack on the target. Use the CLI when you want configuration in git with pull-request review and pipeline promotion. Both carry configuration only, never business records. Pick one route for a given change, so the target isn't updated twice from two sources.

Can an API integration see more than a user can?

No. Every data API, MCP and CLI call runs as the signed-in user, and that user's security profiles, record security and restriction rules are applied on the server. Design an integration by first deciding which user it acts as, then grant that user exactly what the integration needs.

Related topics

• Developer documentation — the data API, MCP endpoint, CLI and connectors.
• Extending Sense with your own capabilities — teaching the platform's AI your custom operations.
• Outbound integration — how data leaves xMatix.
• Security profiles — capabilities, entitlements and grants.
• Role guide: tenant administrator — the other half of the customization conversation.
• Role guides — every role guide and the shipped security profiles.