Metadata-Version: 2.4
Name: ecmind-blue-studio
Version: 1.0.0a2
Summary: ECMind blue Studio, admin interface for the ecmind-blue-client
Author: ECMind GmbH
Author-email: ECMind GmbH <info@ecmind.ch>
License-Expression: MIT
License-File: LICENSE
Requires-Dist: fastapi
Requires-Dist: uvicorn
Requires-Dist: jinja2
Requires-Dist: pydantic-settings
Requires-Dist: itsdangerous
Requires-Dist: python-multipart
Requires-Dist: ecmind-blue-client==1.0.0
Requires-Python: >=3.13
Project-URL: Homepage, https://ecmind.ch/
Project-URL: Repository, https://gitlab.ecmind.ch/open/ecmind_blue_studio
Description-Content-Type: text/markdown

# 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
- Simple query language for folders, registers and documents with subqueries,
  Klausel-style conditions, code completion and diagnostics
- Security statements for users, groups, roles, membership and the rights export
- Result tables per object type with file download
- 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](https://docs.astral.sh/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.

## 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.

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](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 Clerk = #USER# and InvoiceDate >= #DATE#-1y6m
select document Invoice columns InvoiceNo, Amount, folder.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
```

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.

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, and file download.

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](SPECS.md) - full specification and decision log
- [TODO.md](TODO.md) - backlog
- [CHANGELOG.md](CHANGELOG.md) - notable changes

## License

MIT, see [LICENSE](LICENSE). Bundled third-party libraries, fonts, icons and tools are
acknowledged in [THIRD-PARTY-NOTICES.md](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](THIRD-PARTY-NOTICES.md).
