files()

Lädt die Dateien eines Dokumentobjekts vom Server über std.StoreInCacheById. Wenn version_guid angegeben wird, werden die Dateien einer bestimmten früheren Version über std.GetDocVersion abgerufen. Das Dokument kann als Modell-Instanz oder direkt als numerische ID übergeben werden. Optional können Dateien vor der Übertragung konvertiert oder Annotationen eingebrannt werden.

1. Signatur

  • Sync

  • Async

ecm.dms.files(
    model: ECMDocumentModel | int,
    *,
    flags: int = 1,
    convert: StoreInCacheByIdConversion = StoreInCacheByIdConversion.NONE,
    when_cold_then_tiff: bool = False,
    add_annotations: bool = False,
    version_guid: str | None = None,
) -> list[JobResponseFile]
await ecm.dms.files(
    model: ECMDocumentModel | int,
    *,
    flags: int = 1,
    convert: StoreInCacheByIdConversion = StoreInCacheByIdConversion.NONE,
    when_cold_then_tiff: bool = False,
    add_annotations: bool = False,
    version_guid: str | None = None,
) -> list[JobResponseFile]

2. Parameter

Parameter Standard Beschreibung

model

—

ECMDocumentModel-Instanz (deren id wird verwendet) oder eine plain int-Dokument-ID.

flags

1

Steuert, welche Dateien übertragen werden:

0 — Dokumentdateien und die DIA-Datei werden übertragen.
1 — Nur die Dokumentdateien selbst (Standard).
2 — Nur die DIA-Datei des Objekts.

convert

NONE

Optionale Konvertierung vor der Übertragung (StoreInCacheByIdConversion):

NONE — Keine Konvertierung (Standard).
PDF — Dokumente der Haupttypen 1, 2, 3 oder 4 werden als PDF übertragen.
MULTIPAGE_TIFF — TIFF-Dokumente der Haupttypen 2 oder 3 werden zu einer einzelnen mehrseitigen TIFF-Datei zusammengeführt.

when_cold_then_tiff

False

Bei True werden ASCII-COLD-Dateien als TIFF zurückgegeben. Wird nur ausgewertet, wenn convert=NONE.

add_annotations

False

Bei True werden Bild-Annotationen in die zurückgegebenen Dateien eingebrannt. Wird nur verwendet, wenn version_guid gleich None ist.

version_guid

None

Optionale GUID einer bestimmten Dokumentversion. Wenn angegeben, werden die Dateien dieser Version über std.GetDocVersion zurückgegeben anstelle der aktuellen Dateien. Die GUID kann über history() ermittelt werden — sie ist das guid-Attribut eines VERSION_CREATED-Eintrags. Wenn gesetzt, werden flags, convert, when_cold_then_tiff und add_annotations ignoriert.

3. Rückgabewert

Liste von JobResponseFile-Objekten. Kleine Dateien werden als Byte-Array im Speicher gehalten, größere Dateien werden in eine temporäre Datei auf dem Dateisystem geschrieben.

Eigenschaften und Methoden von JobResponseFile:

Eigenschaft / Methode Beschreibung

.name

Dateiname inkl. Endung (z.B. "rechnung.pdf").

.extension

Dateiendung (z.B. ".pdf").

.size()

Dateigröße in Bytes.

.bytes()

Dateiinhalt als bytes. Bei Dateipfad-Typ wird der Inhalt beim ersten Aufruf gelesen und im Speicher gecacht.

.store(path=None)

Schreibt die Datei auf den Datenträger. Ohne path wird das Systemverzeichnis für temporäre Dateien verwendet. Gibt den Speicherpfad zurück.

4. Ausnahmen

ValueError

model ist eine ECMDocumentModel-Instanz mit id = None.

5. Beispiele

5.1. Dateien einer Modell-Instanz laden

  • Sync

  • Async

document = ecm.dms.get(InvoiceDocument, 12345)
for f in ecm.dms.files(document):
    print(f.name, f.size())
    content = f.bytes()
document = await ecm.dms.get(InvoiceDocument, 12345)
for f in await ecm.dms.files(document):
    print(f.name, f.size())
    content = f.bytes()

5.2. Dateien per plain ID laden

Ist die Dokument-ID bekannt, muss das Objekt nicht vollständig geladen werden:

  • Sync

  • Async

for f in ecm.dms.files(12345):
    print(f.name, f.size())
for f in await ecm.dms.files(12345):
    print(f.name, f.size())

5.3. Als PDF laden

Dokumente der Haupttypen 1–4 werden vor der Übertragung serverseitig als PDF konvertiert:

  • Sync

  • Async

from ecmind_blue_client import StoreInCacheByIdConversion

files = ecm.dms.files(12345, convert=StoreInCacheByIdConversion.PDF)
pdf = files[0]
print(pdf.name)          # z.B. "rechnung.pdf"
pdf.store("/tmp/rechnung.pdf")
from ecmind_blue_client import StoreInCacheByIdConversion

files = await ecm.dms.files(12345, convert=StoreInCacheByIdConversion.PDF)
pdf = files[0]
pdf.store("/tmp/rechnung.pdf")

5.4. Als mehrseitige TIFF-Datei laden

TIFF-Dokumente (Haupttypen 2 oder 3) werden zu einer einzigen mehrseitigen TIFF-Datei zusammengeführt:

  • Sync

  • Async

from ecmind_blue_client import StoreInCacheByIdConversion

files = ecm.dms.files(12345, convert=StoreInCacheByIdConversion.MULTIPAGE_TIFF)
tiff = files[0]
tiff.store("/tmp/dokument.tiff")
from ecmind_blue_client import StoreInCacheByIdConversion

files = await ecm.dms.files(12345, convert=StoreInCacheByIdConversion.MULTIPAGE_TIFF)
tiff = files[0]
tiff.store("/tmp/dokument.tiff")

5.5. Mit eingebrannten Annotationen laden

  • Sync

  • Async

files = ecm.dms.files(12345, add_annotations=True)
for f in files:
    f.store(f"/tmp/{f.name}")
files = await ecm.dms.files(12345, add_annotations=True)
for f in files:
    f.store(f"/tmp/{f.name}")

5.6. Dateien einer früheren Version laden

Die version_guid wird aus der Objekthistorie ermittelt. Suchen Sie nach Einträgen mit der Aktion VERSION_CREATED:

  • Sync

  • Async

from ecmind_blue_client.ecm import ECMHistoryAction

history = ecm.dms.history(12345)
versions = [e for e in history.entries if e.action == ECMHistoryAction.VERSION_CREATED]
if versions:
    # Dateien der ältesten Version laden
    old_version = versions[-1]
    files = ecm.dms.files(12345, version_guid=old_version.guid)
    for f in files:
        print(f.name, f.size())
from ecmind_blue_client.ecm import ECMHistoryAction

history = await ecm.dms.history(12345)
versions = [e for e in history.entries if e.action == ECMHistoryAction.VERSION_CREATED]
if versions:
    old_version = versions[-1]
    files = await ecm.dms.files(12345, version_guid=old_version.guid)
    for f in files:
        print(f.name, f.size())

5.7. Alle Dateien eines Abfrageergebnisses herunterladen

  • Sync

  • Async

import os

output_dir = "/tmp/rechnungen"
os.makedirs(output_dir, exist_ok=True)

for doc in ecm.dms.select(InvoiceDocument).where(InvoiceDocument.Year == 2024).stream():
    for f in ecm.dms.files(doc):
        f.store(os.path.join(output_dir, f"{doc.system.id}_{f.name}"))
import os

output_dir = "/tmp/rechnungen"
os.makedirs(output_dir, exist_ok=True)

async for doc in ecm.dms.select(InvoiceDocument).where(InvoiceDocument.Year == 2024).stream():
    for f in await ecm.dms.files(doc):
        f.store(os.path.join(output_dir, f"{doc.system.id}_{f.name}"))

6. Siehe auch

  • get() — Einzelnes Dokument anhand seiner ID laden

  • insert() — Neues Dokument mit Datei anlegen

  • update() — Datei eines bestehenden Dokuments ersetzen

  • history() — Änderungshistorie lesen (Quelle der version_guid)