ECMind blue Studio

A admin interface for the DMS enaio(r) (OPTIMAL SYSTEMS GmbH), exposing the ecmind-blue-client features. Query folders, registers and documents with a simple query language in a Monaco editor, inspect results and download files. Works fully offline against your DMS infrastructure; all frontend assets are vendored.

Features (work in progress)

• Browser-like vertical tabs, each with a query editor and a result view
• Object definition explorer: every cabinet, type and index field with its full configuration, a filter over all of it, prefilled statements per object type and the native asobjdef.xml as download
• Job call monitor: the live server job stream with filters per server, job, computer, application and user, and the full parameters of a single call with base64 payloads decoded; every value in the detail header filters the stream to itself, and any captured call can be sent to a new tab as a ready to run statement
• Raw job calls from the editor: execute krn.GetServerInfo set Flags = 0 runs any server job with typed parameters, input files and its response files previewable and downloadable
• Simple query language for folders, registers and documents with subqueries, Klausel-style conditions, code completion and diagnostics
• Batch values: let id = #UUID7# names a value for the whole batch and print @res.Count, @res.TotalHits shows what a statement answered
• Security statements for users, groups, roles, membership and the rights export
• Registry statements that read and write the servers' own configuration, all configured servers at once or one by name, with the server in every row
• Result tables per object type with file download and a document preview: text formats in a Monaco editor with syntax colouring, find, formatting and copy, PDF and images in the browser's own viewer; a save button turns the edited text into an update statement in a new tab
• English/German localization with automatic detection
• Per-login configuration in the DMS: theme, language and saved queries follow the user to any browser, with a storage dialog to inspect, export, import or delete the stored JSON

Requirements

• Python >= 3.13 and uv
• A DMS application server (default: 127.0.0.1:4000)
• A technical account with the system role "Kontextwechsel" (switch context)

Setup

uv sync
copy .env.example .env
# edit .env: servers, technical account, session secret

Run

uv run uvicorn ecmind_blue_studio.main:app --reload --host 127.0.0.1 --port 8099

Then open http://127.0.0.1:8099 and log in with a DMS user.

Deployment notes

• Keep .env private (chmod 600 .env): it holds the DMS password and the cookie-signing secret. The session file (EBS_SESSION_FILE) is created 0600 by the application itself and holds only hashed session ids.
• Behind TLS, set EBS_COOKIE_SECURE=true so the session cookie carries the Secure flag. The login form additionally refuses cross-origin posts: the Origin host must match Host or X-Forwarded-Host, so a reverse proxy must forward one of the two (nginx: proxy_set_header Host $host;).
• GET /health is open for liveness probes and names the exact version only to signed-in users. GET /health/ready performs throwaway logins and is restricted to localhost by the client address; do not route it through a reverse proxy, where every caller looks local.
• Spilled response files (answers above EBS_RESPONSE_SPILL_MB) land in a 0700 directory per service account under the system temp directory and are removed on expiry, logout and shutdown.

Object definition

The first tab cannot be closed and shows what the DMS server knows about its own data model: cabinets with their folders, registers and documents, the index mask fields of every type with data type, database column and names in the configured languages, and the complete configuration of a single field. The filter box searches all of it at once, six buttons per object type open a prefilled select, count, insert, update, upsert or delete statement in a new tab, and the download button hands out the native asobjdef.xml.

It needs the system role "DMS: Supervisor" (18) or "Editor: Starten" (11); without one of them the tab is not shown.

Job calls

The second fixed tab shows the live job stream of the configured servers, the same feed the Enterprise Manager displays. Press Listen and every finished job appears as one line with its timestamp, computer, user, job name, application and file counts; a green check for success, a red warning for a failure, and optionally a blue play line when the job starts. Filter by server, by job (a popup over every namespace the server offers), by computer, application or user, or reduce the stream to failures only. Clicking a line shows the call the way the Enterprise Manager prints it, with base64 payloads decoded and XML indented. Every value in that header is a link: the job and the server narrow the stream itself, the computer, application and user filter the lines already on screen, and the last link opens the call in a new tab as a ready to run execute statement, with every parameter filled in and the user it originally ran for.

It needs the system role "DMS: Supervisor" (18) or "Administrator: Starten" (1). The monitor runs on the technical connection, which is why the roles are checked on the server and not only in the browser. Job parameters are shown unmasked.

Query language

Each tab has a Monaco editor with completion, hover and live diagnostics for a simple query language (see SPECS.md section 4). Ctrl+Enter runs the query, Shift+Alt+F formats it, Alt+N opens a tab and Alt+W closes it. Internal field names work without brackets:

select document Invoice, DeliveryNote where Status = 'open' order by InvoiceDate desc limit 100
select document Invoice in (register Correspondence where Subject = 'Dunning*') where InvoiceNo != ''
select document Invoice where InvoiceNo != '' and Customer.CustomerNo = 'C-10*'
select folder Customer contains (document Invoice where Status = 'overdue')
select folder Customer where Invoice.Status = 'overdue' and Blocked = false
select document Invoice where Clerk = #USER# and InvoiceDate >= #DATE#-1y6m
select document Invoice columns InvoiceNo, Amount, Customer.CompanyName
select document Invoice columns InvoiceNo, {OBJECT_FILESIZE}, {OBJECT_MODIFYTIME}, {OBJECT_DOCPAGECOUNT}
count document Invoice where Status = 'open'

System fields (OBJECT_ID, OBJECT_LINKS, OBJECT_FILESIZE, OBJECT_COUNT, OBJECT_MODIFYUSER and more, see SPECS.md) work in where, order by and columns; document-only fields are rejected on folder and register queries with a live editor marker.

The editor also flags object types the signed-in user cannot see, and completion notes them in its list. The DMS answers a query on such a type with an empty result and no error at all, so the hint is shown before the run. It stays a warning and never blocks the query: a type you can see may return no rows as well.

Data statements update, create and delete objects, always with the rights of the signed-in user:

update document Invoice 4711 set Status = 'paid'
update document Invoice 4711, 4712 set Status = 'paid'
delete document Invoice 6524, 6522 purge
insert document Invoice into 55 set InvoiceNo = 'R-9' file 'scan.pdf'
upsert document Invoice into 55 set InvoiceNo = 'R-9', Amount = 12.5 search InvoiceNo
variant 4711 set Status = 'draft' file 'v2.pdf'
delete document Invoice where Status = 'void' purge
insert document Invoice into 55 set InvoiceNo = 'R-9', Positions = (Article = 'A-100', Qty = 5), (Article = 'B-200', Qty = 3)
update document Invoice 4711 set Positions = (Article = 'A-100', Qty = 7) replacetables

A single insert, update or variant shows what it wrote: the objects are read back from the server and rendered as a result table below the confirmation, with the usual row actions. A large update (more objects than one result page) and statement batches keep the plain confirmation, because reading every object back costs a roundtrip each.

Table fields take a comma separated list of rows, each row a list of Column = value pairs. On update and upsert the statement has to say whether the rows replace the table (replacetables) or extend it (appendtables) - the mode belongs to the whole statement, so replacing one table and appending to another needs two statements. The table popup in a result row carries an "Edit table" button that opens a new tab with exactly such a statement, filled with the rows currently stored.

Files referenced by file '...' are attached to the tab with the paperclip button; file #BROWSE# instead opens the file dialog every time the statement update and delete also take a list of object ids, and every listed object gets its own copy of the file; a failing object does not stop the others, and the result lists what was written and what failed. On an id based update the set clause is optional, so update document Invoice 6523 file 'scan.pdf' replaces only the file and update document Invoice 6523 file #NULL# only removes it. Prefilled document statements (edit button, object definition page) end with file #BROWSE# as a reminder; delete the line for metadata-only changes. File content can also be written inline, with an optional extension after the closing quotes so the DMS knows the file type: file '''<data> </data>'''.xml stores the text, file b64'''iVBOR...'''.png decodes base64 (line breaks and spaces are ignored), and file #NULL# removes the document file on an update. Without an extension, text becomes a txt and base64 a bin file:

insert document Invoice into 5693
  set InvoiceNo = 'R-9'
  file b64'''
iVBORw0KGgoAAAANSUhEUgAAABAAAAARCAYAAADUryzE...
  '''.png;
select document Invoice

let names a value for the rest of a batch and print shows one row of values, which is what makes a batch readable and re-usable:

let id = #UUID7#;
insert document Invoice into 55 set InvoiceNo = 'R-9', Ident = @id;
insert document Note into 55 set Text = @id;
print 'filed as', @id, #DATETIME#

execute dms.GetResultList set Flags = 0, XML = '''<DMSQuery/>''' as res;
print @res.Count, @res.TotalHits

A declaration also names a file: let f = #BROWSE# or an inline block. Such a name stands in a file clause, of a write statement and of a job call alike, and carries the file's attributes as members, so one picked file or one inline block reaches several statements and can be read without being carried:

let f = #BROWSE#;
insert document Invoice into 55 set InvoiceNo = #FILEBASE#, Size = @f.filesize file @f;
update document Invoice 4711 set Scan = @f.filesha256 file @f

An attachment name stays a plain value on purpose: 'scan.pdf' already means the same file in every statement, so there is nothing to declare.

#UUID4# and #UUID7# generate an identifier at every use, so an insert gets a fresh one and an id list gets one per object; declaring it with let is how one value reaches several statements. #UUID7# is ordered by the millisecond it was made in, #UUID4# is random. A print takes literals, variables and bindings, and @res.* prints every member the statement it names reported, which is how one finds out what a job really answers. Both statements may stand anywhere in a batch, where they render as one line each; on their own they render a one-row table that exports like any other result.

Security statements administer the DMS users, groups and roles in the same language, again with the rights of the signed-in user, so the server enforces the role for configuring the security system:

select user where locked = false order by username limit 100
select user where group = 'Sales'
select group where user = #USER#
insert user KOL set display_name = 'Roland Koller', password = 'Start.2026', change_pwd = true
add user KOL to group Sales
export security group Sales, Marketing

select user KOL shows one account with every attribute, count group the number alone, and delete user KOL forward to MEY hands the portfolios and mails over before the account goes. User and group rows carry the same edit button as DMS rows: it opens a new tab with an update user or update group statement holding the current values. The password is never part of it, and never part of a result or a log.

A rights change is not in effect until it is reloaded

A membership or account write lands in the database at once, but the server answers every rights decision from the model it holds in memory. Until that is re-read, the change is invisible: a search runs with the old rights, the object type the new group grants is simply absent from the answer, and nothing reports an error -- the hit list is empty and the result document does not even mention the type. So the write is done and not yet effective, the way a registry write is set and not yet saved:

add user KOL to group Sales reload
reload security
reload security on 'srv1'

reload security runs mng.UpdateSecuritySystem, and a write that ends in reload runs it for that statement alone. Which to use is a question of how many changes there are: the job re-reads the whole model, so twenty writes want one reload after them and not twenty. A write without the flag says in its result that it is not in effect yet; a batch that changes rights and then reads warns, naming the statement that reads too early.

The job takes no server parameter, so a single call would land on whichever machine the pool picked and leave the rest of a cluster answering from a stale model. Both forms therefore address every configured server unless an on clause names one, and the result carries a line per server. The reload is idempotent, so asking a machine that was already current costs a re-read and nothing else.

Behind the system role "Administrator: Sicherheitssystem konfigurieren" (4), or the two roles the execute verb needs, since those can call the job directly anyway. The call carries the signed-in user in $$$SwitchContextUserName$$$, so the server checks as well: a user without role 4 gets -1040906164 from the job itself, verified against 12.0.801.

Free SQL with DMS names

sql passes everything after the verb to the server database, with one exception: a {...} reference is resolved against the object definition first, so a statement can name types and fields instead of object48 and feld4.

sql SELECT {original_filename} FROM {PostDoc} WHERE {Status} = 'done'

goes to the database as SELECT feld1 FROM object48 WHERE feld4 = 'done'. The tables the statement names decide what a bare field means, and either spelling does: sql SELECT {Status} FROM object48 works too. Where that is not enough, name the type: {PostDoc.Status}. A SQL alias narrows it as well (p.{Status} ... FROM {PostDoc} p).

System fields resolve to their own columns ({OBJECT_CRDATE} becomes angelegt), and a table field resolves to its row table, so its rows can be joined in:

sql SELECT i.{InvoiceNo}, p.{Qty}
    FROM {Invoice} i JOIN {Invoice.Positions} p ON p.id = i.id

This is a name substitution and never a rewrite. Only the text inside the braces is replaced, and only ever by an identifier out of the definition, so the join, the clauses and the literals are exactly what you wrote, and a reference cannot smuggle SQL in. Braces inside a string, a quoted identifier or a comment stay the database's, and so does anything that is not identifier shaped, which is why ODBC escapes such as {fn concat(a,b)} still pass through.

Completion offers both spellings side by side, so the physical schema and the DMS names are one list: object48 next to {PostDoc}, feld4 next to {PostDoc.Status}, and object48list1 labelled as the table field it holds. Either spelling finds both, and each shows what the other one is. Hover tells which column a reference stands for, and an unknown name is an editor marker rather than a server error. Everything outside the braces is still unvalidated and never reformatted.

Server registry

The enaio registry lives per server machine, so two application servers of one pool can disagree about a setting and nothing in the studio used to show that. Registry statements read and write it with the server as a column of every row; leaving the on clause out addresses every configured server, which is what turns "is this the same everywhere?" into one statement:

select registry
select registry where path = 'Security\*'
select registry on 'srv1' where key = 'Services\Fulltext'
select registry where name = 'HelpURL' order by server
count  registry where path = 'Services\*'

The columns are server, key, name, path and value, all of them text, with the usual * and ? wildcards. Both path separators work: Security/* is translated to the backslash the server insists on. An entry whose name ends in Pwd, Password or Secret shows *** and never its value, in a result, an export or a log alike; PwdDecryption and PasswordExpirationInterval are settings rather than secrets and stay readable.

A write names one entry by its absolute path, never a wildcard, and reports the previous value beside the new one for every server it reached:

update registry on 'srv1' set 'Security\HelpURL' = 'Test'
update registry create set 'Security\NewEntry' = 'x'
update registry set 'HelpURL' = 'https://help.example' save
reload registry on 'srv1'

krn.RESetRegValue changes the running server's memory and nothing else, so a write is not persisted unless the statement ends in save - the result says so, and reload registry throws an unsaved change away right now. A path the server does not know is refused unless the statement says create, and one failing entry does not stop the others. One unreachable server never ends the run: it is reported beside the rows the others returned.

There is no delete: the server API has no job that removes a registry entry.

Behind the same system roles as the job call monitor, "DMS: Supervisor" (18) or "Administrator: Starten" (1), enforced on the server. Like execute, these statements run on the technical connection, because the krn.RE* jobs have no rights model of their own; a read carries the signed-in user into the server's job log so it records who looked.

Server threads and queues

A thread pool belongs to one kernel process, so this is the registry's problem again: krn.JobThreadGetInfo takes no server parameter, and the pool would answer a different machine on every run. So the server is a column of every row here too, and leaving the on clause out asks all of them:

select threads
select threads where running = true
select threads where idle = false order by avgjob desc
select threads on 'srv1' where queue = 'dms'
select threads where jobname = 'wfm.*' columns queue, number, jobname, username
count  threads where running = true

select queues
select queues where jobswaiting > 0
select queues columns queue, numthreads, priority, jobsposted, namespaces

Unlike the registry's text columns these are typed, which is what makes order by avgjob desc sort numerically and where start > datetime'...' mean what it looks like. Beside the twenty fields the server reports there are five derived ones, because the raw fields do not answer what you actually ask: running (a job on the thread right now), idle (a thread never used), avgjob (the mean job in milliseconds), and duration and queuewait for the last job, both empty for as long as it is still running.

Two of the server's own fields read differently than the vendor documentation suggests, and the studio follows the measurement rather than the document: jobsummary is the total time that thread has ever worked, not the last job's runtime, which is why avgjob exists; and sql is documented but was empty on every server probed, so nothing relies on it.

The call stack of one thread reads as the server writes one in its own error messages, innermost frame first:

select callstack of thread 4940 on 'srv1'

And one running job can be interrupted:

break thread 4940 on 'srv1'
break thread 4940 job 1057423 on 'srv1'

A break is a request, not a result. The server accepts one for any job and only interrupts jobs that support being interrupted, so the statement reads the thread again afterwards and says which of the two happened: stopped, or accepted and still running. In a batch the second counts as a failed statement. A thread with no job is not asked at all. on is required here and names exactly one server, because a thread id means nothing on another machine.

Behind the same system roles as the registry family, "DMS: Supervisor" (18) or "Administrator: Starten" (1). That gate matters for a plain read: the snapshot carries session GUIDs, client station names and the user every job runs as. A read carries the signed-in user into the server's job log so it records who looked.

Job calls from the editor

execute calls any server job directly, with a typed parameter list:

execute krn.GetServerInfo set Flags = 0, Info = 3

execute dms.GetResultList
  set Flags = 16,
    XML = '''<DMSQuery requesttype="LOL" pagesize="10">
  <Archive>
    <ObjectType internal_name="Invoice">
      <Fields field_schema="MIN"/>
    </ObjectType>
  </Archive>
</DMSQuery>''',
    Encoding = 'UTF-8'

The type of a parameter comes from the literal, so nothing has to be declared: 'text' is a string, 42 an integer, 12.5 a double, true a boolean, datetime'...' a timestamp. A base64 parameter is written in plain text between ''' quotes, which is what keeps an XML payload readable in the editor; b64'''...''' carries real binary. The suffix after a text block names its encoding when the job wants something other than UTF-8: '''...'''.utf16. Where the literal cannot say it, a cast does: bigint 4294967296, string '4711'.

A job call hands what it answered to the next statement of a batch. as <name> binds the call, and its members are the output parameters, by their own names, next to returncode:

// the members of a job call binding are whatever the job answered
execute krn.SessionLogin set UserName = 'kol', Password = 'secret' as login;
insert document Note into 4711 set Text = @login.UserGUID

The braces form takes a name no identifier can spell, such as krn.RunScript's $ScriptResult$: @run.{$ScriptResult$}. Nothing declares what a job answers, so no type travels with the value: it is made to fit where it lands, text that spells a number reaching a number field and a number reaching a text field, and only what cannot be converted fails that one statement. Completion offers the outputs the reference documents for that job; a name it does not document is a warning and still runs, because the server is what decides.

Input files come from the tab's attachments, a #BROWSE# pick or inline content, the same way a write statement takes them, except that a job takes a list: file 'a.pdf', 'b.pdf'. Response files are listed under the result with a preview for text, PDF and image formats and a download for anything; a text file opens in the same editor the result rows use.

The result is the block the job call monitor shows for a call, so the two read the same. JSON gives the whole call as one record with text buffers decoded, XML gives the raw payload the job returned, and the delimited formats flatten the output parameters. A non-zero return code is not an error but the answer: it is rendered with the server's own message, exactly as the monitor renders a failed call.

Completion knows the jobs the server actually implements: execute offers the engines, execute krn. their jobs, and picking one writes the whole statement with every required parameter and a tab stop on each value. The parameter names, types and descriptions come from the enaio Server-API reference, so they are documentation rather than gospel: a job the reference has never heard of still runs, with a warning and no help.

Unlike every other statement this one does not run as the signed-in user. It goes out on the pool's own connection, like the job call monitor, because writing the caller's identity into the parameter list would aim a job meant for a named user at whoever happens to be signed in. A statement that wants a user context says so itself:

execute dms.GetResultList
  set {$$$SwitchContextUserName$$$} = 'administrator',
      Flags = 16,
      XML = '''<DMSQuery/>'''

The braces are needed because $ is not part of a name; the GUID and ID forms ({$$$SwitchContextUserGUID$$$}, {$$$SwitchContextUserID$$$}) work the same way. The role gate is therefore the whole access control: "DMS: Supervisor" (18) or "Administrator: Starten" (1), checked on the server, not just hidden.

Results render as a table by default or as JSON, JSONL, XML, CSV, TSV or TSV quoted, sql results included. Every text format opens in an editable editor, so the output can be trimmed before copy or download hands it to the next step. TSV sanitizes tabs and line breaks inside values to keep one record per line, TSV quoted keeps them and quotes like CSV instead. Every result row offers details (metadata, variants and versions), an edit button that opens a prefilled update statement, file download and, where the format allows it, a preview. A text document (txt, log, md, csv, tsv, json, xml, html, svg, yaml, ini, sql, js, ts, css, bat, ps1, py) opens in a Monaco editor with the colouring of its format, find, a format button for JSON and XML and a copy button for the buffer; PDF and images keep the browser's own viewer. The download button always hands out the archived file, never what was edited on screen. Text is decoded from UTF-8, a BOM, BOM-less UTF-16 or Windows-1252, and a file above EBS_PREVIEW_MAX_BYTES (20 MB) shows its first bytes and says so.

The save button writes the edited buffer back: the modal closes and a new tab opens with the statement prefilled and the caret in it. It never runs by itself

• the write is the Ctrl+Enter you press.

// PostDoc #4711 (.xml)
update document PostDoc 4711
  file '''<Root>
  <Line>edited</Line>
</Root>'''.xml

No set clause, so a save touches the file and no index field. A comment line above the statement explains anything the shape does not say by itself: a text block goes out as UTF-8, so a file stored as Windows-1252 or UTF-16 comes back re-encoded; a text carrying ''', which a text block has no escape for, goes out as base64 instead; and a text too long for EBS_QUERY_MAX_CHARS is attached to the new tab as a file, with the statement naming it. A preview cut short by EBS_PREVIEW_MAX_BYTES cannot be saved at all - the button is disabled and says why, because writing a prefix back would overwrite the document with part of itself. Response files of an execute run have no object to update, so they have no save button.

Statement batches (separated by ;) stream their results statement by statement, report the executed command and the upsert action per row, and can be cancelled mid run; the stop button in the toolbar also aborts long running queries. A query starting with a comment line names its tab, the question button in the toolbar lists all keyboard shortcuts, the info button next to it opens the about dialog, and the tab rail shows the connected DMS servers above the user menu.

Per-login configuration

Theme, language, table lines and saved queries live in one JSON document in the DMS, in the user data record ecmind_blue_studio of the signed-in user (slot EBS_USERDATA_SLOT, default 80). They are not kept in the browser, so a second machine shows the same setup, and a browser reset loses nothing. If the DMS refuses user data for a login, the app runs on the defaults and every write is blocked with an error rather than falling back to storage that can vanish.

"Settings storage" in the user menu shows the stored document in an editor and can download it, load a JSON file into the editor, save manual changes or delete the whole record from the DMS.

Open tabs are the exception: they stay in browser storage, shared by all windows of the browser, so closing and reopening the browser brings back the last set of queries. Which tab is in front stays per window.

Tests

uv run pytest                            # unit and endpoint tests
$env:EBS_LIVE_TESTS = "1"; uv run pytest -m live   # against a local DMS (PowerShell)

Documentation

• SPECS.md - full specification and decision log
• TODO.md - backlog
• CHANGELOG.md - notable changes

License

MIT, see LICENSE. Bundled third-party libraries, fonts, icons and tools are acknowledged in THIRD-PARTY-NOTICES.md.

The MIT license covers this software only and grants no rights to the DMS itself. Operators must make sure their use of the DMS is covered by their own license agreement with the DMS vendor or reseller. See the DMS licensing section of THIRD-PARTY-NOTICES.md.