Script — code
Updated
What it is#
A shared envelope container for user code bound to an object: scriptType distinguishes whether this is an event handler, transaction script, command, driver, and so on. The code file (.cs) is ONLY the user partial; the other half (framework) is in .generated/Frameworks/ (not in git).
JSON envelope#
<Name>.script.json (envelope) + <Name>.cs (body) are an inseparable pair; committing only one half is forbidden (gitignore once swallowed a job's code file and left an orphaned Job; import failed on an FK, and CI now runs check_script_pairs.py).
{
"kind": "Script",
"object": {
"scriptType": "EventHandler",
"objectType": "Dictionary",
"objectName": "Country",
"objectMetaId": "<GUID Dictionary>",
"executionOrder": 0,
"metaId": "<GUID Script>", "name": "CountryEventHandler", "modelId": "<GUID Model>"
}
}
objectType/objectName/objectMetaId is the binding to the owner; scriptType determines which kind of class is expected in .cs (see the table below); executionOrder is the place in the chain when there are several handlers for one object.
C# base by scriptType#
scriptType |
Class | Is the base declared? |
|---|---|---|
EventHandler (dictionary) |
<Name>EventHandler : TypedDictionaryEventHandler<Name> |
yes |
EventHandler (document) |
<Name>EventHandler : TypedDocumentEventHandler<Name> |
yes |
EventHandler (table part) |
<Name>EventHandler : TypedTablePartEventHandler<<Name>TablePartRow> |
yes |
Service |
public partial class <Name> — contract I<Name> is derived from methods |
no |
EventHandler (Data Entity) |
<Name>EventHandler : TypedDataEntityEventHandler<Name> + MapFromSource/MapToSource |
yes |
Transactional (Tx) |
public partial class <NameTx> + GetTransactions(...) |
no |
| Command | <Name>Command : DocumentCommandBase<Document> + ExecuteAsync(...) |
no |
| Totals driver | public partial class <Name>TotalDriver |
no |
| Integration test | class X : IntegrationTestScriptBase, methods with [IntegrationTest("…")] |
yes |
The full table with signatures is in the root CLAUDE.md, §"Scripts — class templates"; exact hook signatures are in .generated/Frameworks/.
Events / Chain of Command#
The owner is the handler in the object model itself; it is link 0 and does not call next. A handler for an object owned by another model must declare [ExtensionOf("ObjectName")] on the class (otherwise ZOCOC004) and call next from every override (otherwise ZOCOC001). The chain order is (owner, layer, name): same-named extensions of one layer are linked alphabetically, not guessed.
Example#
CountryEventHandler — scriptType: EventHandler, link 0 on Country; GoodsIssueTx in Inventory — scriptType: Transaction on the Posted subtype.