Wichtigste Erkenntnisse
- Beschränken Sie Uploads auf die Dokumenttypen, die der gewählte Konvertierungspfad tatsächlich unterstützt.
- Konvertieren Sie die akzeptierte Quelle in PDF, bevor Sie sie in einen fall- oder projektspezifischen Box-Pfad exportieren.
- Bewahren Sie den Box-Zugriff in Template-Zugangsdaten auf, und behalten Sie die Ordnerauswahl unter vertrauenswürdiger Anwendungskontrolle.
Die Dokumentaufnahme beginnt oft mit einer Mischung aus DOCX-, PPTX-, ODT- und anderen Office-Formaten, während Prüfende ein stabiles PDF erwarten. Wird das Original direkt an einen Collaboration-Ordner gesendet, bleiben Konvertierungsregeln und Benennung uneinheitlich. Ein gespeicherter Workflow macht das PDF-Derivat und sein Ziel vorhersehbar, ohne Box zum Upload-Verarbeitungsdienst zu machen.
Worauf es besonders ankommt
- Lassen Sie create_sharing_link auf false, sofern nicht eine separate Autorisierungsentscheidung einen Freigabelink erlaubt.
- Verwenden Sie eindeutige Zielpfade, damit Wiederholungsversuche und gleichnamige Uploads keine unabhängigen Datensätze überschreiben.
- Erfassen Sie sowohl die Quellidentität als auch das exportierte PDF-Ergebnis im dauerhaften Dokumentendatensatz der Anwendung.
Einen engen Vertrag für die Dokumentenannahme wählen
Ein Ordner voller „Dokumente“ ist kein einziges technisches Format. Definieren Sie die Eingabeformate, das Byte-Limit, die erwartete Seitenzahl und die Anforderungen an die Wiedergabetreue, bevor Sie Uploads akzeptieren. /document/convert kann PDFs aus unterstützten Office-, Text-, HTML- und Präsentationsformaten erstellen.
Halten Sie bestehende PDFs aus diesem Konvertierungspfad heraus, denn /document/convert ist kein generisches PDF-zu-Beliebig-Tool. Akzeptiert das Produkt sowohl PDFs als auch konvertierbare Office-Dateien, leiten Sie sie gezielt weiter: Bewahren Sie akzeptierte PDFs unverändert auf und konvertieren Sie nur die Formate, die normalisiert werden müssen.
Das PDF-zu-Box-Template erstellen
Das Template empfängt ein hochgeladenes Dokument als :original, konvertiert es in PDF und übergibt nur dieses PDF an /box/store. Der Zielpfad enthält eine von der Anwendung freigegebene Fall- oder Projektkennung sowie eindeutige Assembly-Werte. So wird verhindert, dass zwei Nutzer, die report.docx hochladen, sich gegenseitig überschreiben.
Setzen Sie create_sharing_link auf false. Ein Collaboration-Freigabelink ist eine Autorisierungs- und Aufbewahrungsentscheidung, kein Nebeneffekt der Konvertierung. Benötigt das Produkt später einen solchen Link, erstellen Sie ihn erst, nachdem die Anwendung das Box-Ziel, die vorgesehene Zielgruppe sowie die Ablauf- oder Widerrufsrichtlinie bestätigt hat.
{
"allow_steps_override": false,
"auth": {
"max_number_of_files": 1,
"max_size": 104857600
},
"steps": {
":original": {
"robot": "/upload/handle"
},
"review_pdf": {
"use": ":original",
"robot": "/document/convert",
"format": "pdf"
},
"box_export": {
"use": "review_pdf",
"robot": "/box/store",
"credentials": "box-documents",
"path": "cases/${fields.case_id}/${unique_prefix}/${file.url_name}",
"create_sharing_link": false,
"result": true
}
}
}Pfade, Zugangsdaten und dauerhafte Identitäten kontrollieren
Speichern Sie den Box-Zugriff in Template-Zugangsdaten und referenzieren Sie den Namen der Zugangsdaten aus dem gespeicherten Template. Lassen Sie nicht zu, dass ein nicht vertrauenswürdiger Client Zugangsdaten, einen beliebigen Ordner oder einen abweichenden Pfad wählt. Der Server sollte den Nutzer anhand des Fall- oder Projektdatensatzes autorisieren und eine begrenzte Kennung bereitstellen, die das Template in seinen Pfad aufnehmen kann.
Ordnernamen sind Darstellung, keine dauerhafte Identität. Bewahren Sie die Anwendungsdokument-ID, die Quellversion, die Assembly-ID, die Box-Ergebnisidentität und die Workflow-Version gemeinsam auf. Diese Felder überstehen eine spätere Ordnerverschiebung und ermöglichen es Betreibern, eine Wiederholung von einer neuen Dokumentversion zu unterscheiden.
Anwendungsidentität
Die stabilen Kennungen für Dokument, Fall, Mandant und Version.
Verarbeitungsidentität
Die Workflow-Version und die Assembly-ID, die das PDF erzeugt haben.
Speicheridentität
Die vom erfolgreichen Export zurückgegebene Box-Dateiidentität und der Pfad.
Konvertierung prüfen, bevor das Dokument als fertig markiert wird
Eine grüne Assembly ist bei folgenreichen Dokumenten notwendig, aber nicht ausreichend. Lassen Sie die Anwendung den MIME-Typ und die Seitenzahl des exportierten PDFs prüfen, und verwenden Sie repräsentative Fixtures, um Schriftarten, Tabellen, Seitenumbrüche, Kopf- und Fußzeilen, Links und nicht-lateinischen Text zu überprüfen. Ein erfolgreicher /document/convert-Vorgang allein belegt nicht, dass das Ergebnis der Ausgangsanwendung entspricht. Entscheiden Sie, ob eine Abweichung den Workflow blockiert oder die Datei zur manuellen Prüfung weiterleitet.
Schließen Sie den Anwendungsdatensatz erst ab, wenn der Box-Export existiert und der erwarteten Assembly entspricht. Verarbeiten Sie Webhooks idempotent, und gleichen Sie aktive Datensätze mit dem Assembly Status ab, wenn eine Benachrichtigung verzögert oder ausgeblieben ist.
Speicher- und Wiederherstellungsfehler testen
Testen Sie widerrufene oder ungültige Zugangsdaten der Box Server Authentication App, einen fehlenden Zielordner, unzureichende Schreibberechtigung, gleichnamige Uploads, nicht unterstützte Quellformate, einen Konvertierungsfehler sowie eine erfolgreiche Konvertierung mit anschließendem Exportfehler. Der sichere Wiederholungsversuch sollte, wo immer möglich, die vorhandene Quelle und den Vorgangsstatus wiederverwenden, statt den Nutzer erneut zum Hochladen aufzufordern.
Definieren Sie die Aufbewahrung für den Quell-Upload, das PDF-Derivat und den Anwendungsdatensatz getrennt. Box mag die dauerhafte Collaboration-Kopie sein, doch die Anwendung benötigt weiterhin genügend Identitäts- und Audit-Status, um zu erklären, wie das Dokument entstanden ist und ob es aktuell ist.
Die Rollen von Quelle und PDF klar halten
Ein normalisiertes PDF kann die Collaboration-Kopie sein, während die editierbare Office-Datei die maßgebliche Quelle bleibt. Alternativ kann ein Aktenverwaltungsprozess das geprüfte PDF als fixierte Fassung festlegen. Dokumentieren Sie diese Entscheidung in der Anwendung, statt zuzulassen, dass zufällig die jeweils in Box vorhandene Datei maßgeblich wird.
Wird eine Quelle ersetzt, erstellen Sie eine neue Anwendungsversion und Zielidentität, oder wenden Sie einen bewusst festgelegten Überschreibvertrag an. Gehen Sie niemals davon aus, dass ein gleichnamiger Upload dasselbe Geschäftsdokument darstellt, und löschen Sie die vorherige Quelle erst, wenn die Anforderungen an Aufbewahrung und Rollback erfüllt sind.
Wissenswerte technische Details
- /document/convert kann unterstützte Office- und Textformate in PDF konvertieren. PDF wird nicht als Eingabe unterstützt, leiten Sie bestehende PDFs daher um diesen Konvertierungs-Step herum.
- /box/store akzeptiert einen Pfad mit Assembly Variables und verwendet standardmäßig einen Pfad mit eindeutigem Präfix, wenn kein Pfad angegeben wird.
- Die Box-Exportoption create_sharing_link ist standardmäßig auf false gesetzt. Wird sie aktiviert, ersetzt sie die url-Eigenschaft der Ergebnisdatei durch die Freigabe-URL.
- Box-Template-Zugangsdaten verwenden Server Authentication mit JWT. Anwendungsadministratoren müssen diese App-Autorisierung und das zugehörige Schlüsselmaterial gültig halten.
- Template-Zugangsdaten halten den Box-Zugriff aus dem Template-JSON und dem Browser-Bundle heraus, während die Anwendung den Zielordner weiterhin autorisieren muss.
- Das exportierte PDF ist ein neues Derivat. Ob der ursprüngliche Upload behalten oder gelöscht wird, ist eine separate produkt- und aktenverwaltungsbezogene Entscheidung.
Ein praxisnaher Ansatz
- 1
Legen Sie unterstützte Office-Formate, maximale Größe, Richtlinie für den Zielordner und Aufbewahrungsfrist fest.
- 2
Erstellen Sie eingeschränkte Box-Template-Zugangsdaten und speichern Sie das gesperrte Template mit drei Steps.
- 3
Laden Sie repräsentative Dokumente hoch und überprüfen Sie Seitenlayout, Schriftarten, Dateinamen und die Ablage in Box.
- 4
Testen Sie nicht unterstützte PDFs, doppelte Namen, widerrufene Box-App-Autorisierung und teilweise fehlgeschlagene Exporte.
Wann Transloadit hilfreich ist
Verwenden Sie diesen Workflow für die nutzerbezogene, interaktive Aufnahme in einen Box-Collaboration-Ordner. Nutzen Sie /upload/handle für die Nutzeraufnahme, /document/convert für die unterstützte Office-zu-PDF-Konvertierung und /box/store für den dauerhaften Export. Bewahren Sie den Box-Zugriff in Template-Zugangsdaten auf, verwenden Sie einen von der Anwendung freigegebenen Ordnerpfad, und lassen Sie die Erstellung von Freigabelinks deaktiviert, sofern das Produkt sie nicht ausdrücklich benötigt.
Architekturgrenze
Transloadit konvertiert und exportiert das hochgeladene Dokument. Die Anwendung bleibt verantwortlich für Nutzerberechtigungen, Fall- oder Projektidentität, Aufbewahrung, rechtliche Einstufung, die Box-Kollaborationseinstellungen und die Frage, ob ein resultierendes Dokument geteilt werden darf.
Häufig gestellte Fragen
Kann dieses Template PDFs als Eingabe akzeptieren?
/document/convert akzeptiert keine PDF-Eingaben. Leiten Sie vorhandene PDFs an der Konvertierung vorbei oder verwenden Sie einen separaten, für die benötigte PDF-Operation passenden Workflow.
Sollte /box/store einen Freigabelink erstellen?
In der Regel nicht während der Aufnahme. Lassen Sie create_sharing_link auf false und machen Sie das Teilen zu einer späteren autorisierten Aktion mit einer expliziten Zielgruppe und einer Widerrufsrichtlinie.
Bleiben bei der Konvertierung alle Funktionen des Office-Dokuments erhalten?
Nein. Überprüfen Sie repräsentative Schriftarten, das Layout, Formeln, Links und komplexe anwendungsspezifische Funktionen, bevor Sie sich auf das PDF als maßgebliche Wiedergabe verlassen.
Kann der Browser den Box-Ordner auswählen?
Der Browser darf einen begrenzten Anwendungsbezeichner übermitteln, aber ein vertrauenswürdiger Server sollte ihn autorisieren, und das gesperrte Template sollte den tatsächlichen Zielpfad steuern.
Was sollte in der Anwendungsdatenbank gespeichert werden?
Bewahren Sie die Identität des Quelldokuments und der Version, die Workflow-Version, die Assembly-ID, die Box-Dateiidentität, den Zielpfad und den finalen Workflow-Zustand auf.