files()

Downloads the files of a document object from the server via std.StoreInCacheById. When version_guid is provided, the files of a specific previous version are retrieved via std.GetDocVersion instead. The document can be passed as a model instance or directly as a numeric ID. Files can optionally be converted before transfer or have annotations burned in.

1. Signature

  • 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. Parameters

Parameter Default Description

model

—

ECMDocumentModel instance (its id is used) or a plain int document ID.

flags

1

Controls which files are transferred:

0 — document files and the DIA file are transferred.
1 — only the document files themselves (default).
2 — only the DIA file of the object.

convert

NONE

Optional conversion applied before transfer (StoreInCacheByIdConversion):

NONE — no conversion (default).
PDF — documents with main type 1, 2, 3, or 4 are converted to PDF.
MULTIPAGE_TIFF — TIFF documents with main type 2 or 3 are merged into a single multi-page TIFF file.

when_cold_then_tiff

False

When True, ASCII COLD files are returned in TIFF format. Only evaluated when convert=NONE.

add_annotations

False

When True, image annotations are burned into the returned files. Only used when version_guid is None.

version_guid

None

Optional GUID of a specific document version. When provided, the files of that version are returned via std.GetDocVersion instead of the current files. The GUID can be obtained from history() — it is the guid attribute of a VERSION_CREATED entry. When set, flags, convert, when_cold_then_tiff, and add_annotations are ignored.

3. Return value

A list of JobResponseFile objects. Small files are kept as a byte array in memory; larger files are written to a temporary file on the filesystem.

Properties and methods of JobResponseFile:

Property / Method Description

.name

Filename including extension (e.g. "invoice.pdf").

.extension

File extension (e.g. ".pdf").

.size()

File size in bytes.

.bytes()

File content as bytes. For file-path type, the content is read from disk and cached in memory on first call.

.store(path=None)

Write the file to disk. Without path, the system temporary directory is used. Returns the storage path.

4. Exceptions

ValueError

model is an ECMDocumentModel instance with id = None.

5. Examples

5.1. Load files from a model instance

  • 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. Load files by plain ID

If the document ID is known, the object does not need to be fully loaded:

  • 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. Load as PDF

Documents with main types 1–4 are converted to PDF on the server before transfer:

  • Sync

  • Async

from ecmind_blue_client import StoreInCacheByIdConversion

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

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

5.4. Load as multi-page TIFF

TIFF documents (main types 2 or 3) are merged into a single multi-page TIFF file:

  • Sync

  • Async

from ecmind_blue_client import StoreInCacheByIdConversion

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

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

5.5. Load with burned-in annotations

  • 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. Load files from a previous version

The version_guid is obtained from the object’s history. Look for entries with action 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:
    # Load files from the oldest version
    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. Download all files from a query result

  • Sync

  • Async

import os

output_dir = "/tmp/invoices"
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/invoices"
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. See also

  • get() — Load a single document by its ID

  • insert() — Create a new document with a file

  • update() — Replace the file of an existing document

  • history() — Read the modification history (source of version_guid)