Points clés à retenir
- Limitez les téléversements aux types de documents effectivement pris en charge par la méthode de conversion choisie.
- Convertissez le document source accepté en PDF avant de l’exporter vers un chemin Box propre au dossier ou au projet.
- Conservez les informations d’identification permettant l’accès à Box dans les informations d’identification de Template et gardez la sélection du dossier sous le contrôle d’une application de confiance.
La réception de documents commence souvent par un mélange de fichiers DOCX, PPTX, ODT et d’autres formats bureautiques, alors que les réviseurs attendent un PDF stable. Envoyer directement l’original dans un dossier de collaboration laisse subsister des incohérences dans les règles de conversion et de nommage. Un flux de travail enregistré rend le dérivé PDF et sa destination prévisibles sans transformer Box en service de traitement des téléversements.
L’essentiel
- Laissez create_sharing_link à false, sauf si une décision d’autorisation distincte permet un lien de partage.
- Utilisez des chemins de destination uniques pour que les nouvelles tentatives et les téléversements de fichiers portant le même nom n’écrasent pas des enregistrements sans rapport.
- Consignez à la fois l’identité du document source et le résultat PDF exporté dans l’enregistrement durable du document dans l’application.
Choisir un contrat de réception des documents au périmètre restreint
Un dossier rempli de « documents » ne correspond pas à un format technique. Définissez les formats d’entrée, la limite en octets, les attentes concernant les pages et les exigences de fidélité avant d’accepter des téléversements. /document/convert peut créer des PDF à partir des formats bureautiques, texte, HTML et de présentation pris en charge.
Excluez les PDF existants de cette branche de conversion, car /document/convert n’est pas un outil générique permettant de convertir des PDF vers n’importe quel format. Si le produit accepte à la fois les PDF et les fichiers bureautiques convertibles, orientez-les de façon explicite : conservez les PDF acceptés et convertissez uniquement les formats qui nécessitent une normalisation.
Créer le Template de conversion en PDF et d’export vers Box
Ce Template reçoit un seul fichier téléversé sous :original, le convertit en PDF et transmet ce PDF à /box/store. Il n’impose pas de liste de formats bureautiques autorisés : l’application doit valider les formats qu’elle accepte avant de choisir ce flux de travail, ou ajouter un Step /file/filter avec error_on_decline. Les PDF existants nécessitent un flux de travail distinct choisi par l’application, car cet exemple ne prévoit pas de contournement de la conversion pour les PDF. Le chemin de destination comprend un identifiant de dossier ou de projet approuvé par l’application ainsi que des valeurs uniques de l’Assembly, ce qui évite que les fichiers de deux utilisateurs téléversant report.docx s’écrasent mutuellement.
Définissez create_sharing_link sur false. Un lien de partage pour la collaboration relève d’une décision d’autorisation et de conservation, et non d’un effet secondaire de la conversion. Si le produit en a besoin par la suite, créez-le uniquement après que l’application a confirmé la destination Box, le public visé et la politique d’expiration ou de révocation.
{
"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
}
}
}Contrôler les chemins, les informations d’identification et les identités durables
Stockez les informations d’accès à Box dans les informations d’identification de Template et référencez le nom de cet ensemble depuis le Template enregistré. Ne laissez pas un client non fiable choisir un ensemble d’informations d’identification, un dossier arbitraire ou un chemin de remplacement. Le serveur devrait autoriser l’utilisateur en fonction de l’enregistrement du dossier ou du projet et fournir un identifiant au périmètre limité que le Template peut inclure dans son chemin.
Les noms de dossiers relèvent de la présentation, pas de l’identité durable. Conservez ensemble l’identifiant du document dans l’application, la version de la source, l’identifiant d’Assembly, l’identité du résultat dans Box et la version du flux de travail. Ces champs restent valables après un déplacement de dossier et permettent aux opérateurs de distinguer une réexécution d’une nouvelle version du document.
Identité dans l’application
Les identifiants stables du document, du dossier, du locataire et de la version.
Identité du traitement
La version du flux de travail et l’identifiant de l’Assembly qui a produit le PDF.
Identité dans le stockage
L’identité et le chemin du fichier Box renvoyés par l’export réussi.
Vérifier la conversion avant de marquer le document comme prêt
Une Assembly réussie est nécessaire, mais ne suffit pas pour les documents à forts enjeux. Faites inspecter par l’application le type MIME et le nombre de pages du PDF exporté, puis utilisez des données de test représentatives pour inspecter les polices, les tableaux, les sauts de page, les en-têtes, les pieds de page, les liens et le texte non latin. La réussite d’un Job /document/convert ne suffit pas à établir que le résultat correspond à celui de l’application source. Décidez si une divergence bloque le flux de travail ou oriente le fichier vers une vérification manuelle.
Finalisez l’enregistrement dans l’application uniquement après que l’export Box existe et correspond à l’Assembly attendue. Traitez les webhooks de manière idempotente et rapprochez les enregistrements actifs de l’Assembly Status lorsqu’une notification est retardée ou manquée.
Tester les défaillances de stockage et de reprise
Testez les cas suivants : informations d’identification de l’application Box Server Authentication révoquées ou invalides, dossier de destination manquant, droits d’écriture insuffisants, fichiers téléversés portant le même nom, formats sources non pris en charge, échec de conversion et conversion réussie suivie d’un échec d’export. Pour être sûre, une nouvelle tentative devrait réutiliser la source et l’état de l’opération existants plutôt que demander à l’utilisateur un nouveau téléversement, chaque fois que cela est possible.
Définissez séparément les règles de conservation du fichier source téléversé, du PDF dérivé et de l’enregistrement dans l’application. Box peut héberger la copie durable destinée à la collaboration, mais l’application a toujours besoin de suffisamment d’informations d’identité et d’audit pour expliquer comment elle a été produite et si elle est à jour.
Garder explicites les rôles de la source et du PDF
Un PDF normalisé peut servir de copie de collaboration tandis que le fichier bureautique modifiable reste la source de référence. Un processus de gestion des documents peut aussi désigner le PDF vérifié comme la version figée. Documentez ce choix dans l’application au lieu de laisser le fichier qui se trouve dans Box devenir la référence par accident.
Lorsqu’une source est remplacée, créez une nouvelle version dans l’application et une nouvelle identité de destination, ou appliquez un contrat d’écrasement défini explicitement. Ne supposez jamais qu’un fichier téléversé portant le même nom représente le même document métier, et ne supprimez pas la source précédente avant que les exigences de conservation et de retour arrière aient été satisfaites.
Détails techniques à connaître
- /document/convert peut convertir en PDF les formats bureautiques et texte pris en charge. Le PDF n’est pas un format d’entrée pris en charge : faites donc contourner le Step de conversion aux PDF existants.
- /box/store accepte un chemin contenant des Assembly Variables et utilise par défaut un chemin doté d’un préfixe unique lorsqu’aucun chemin n’est fourni.
- L’option d’export Box create_sharing_link vaut false par défaut. Son activation remplace la propriété url du fichier résultat par l’URL de partage.
- Les informations d’identification de Template pour Box utilisent Server Authentication avec JWT. Les administrateurs de l’application doivent maintenir la validité de cette autorisation de l’application et des éléments cryptographiques associés.
- Les informations d’identification de Template gardent les informations d’accès à Box hors du JSON du Template et du bundle du navigateur, tandis que l’application doit toujours autoriser l’accès au dossier cible.
- Le PDF exporté est un nouveau dérivé. La conservation ou la suppression du fichier téléversé d’origine relève d’une décision distincte concernant le produit et la gestion des documents.
Une approche pratique
- 1
Définissez les formats bureautiques pris en charge, la taille maximale, la politique relative aux dossiers de destination et la durée de conservation.
- 2
Créez des informations d’identification de Template pour Box avec des droits limités au périmètre nécessaire, puis enregistrez le Template verrouillé à trois Steps.
- 3
Téléversez des documents représentatifs et vérifiez la mise en page, les polices, les noms de fichiers et leur emplacement dans Box.
- 4
Vérifiez que les PDF en entrée et les autres formats sources non pris en charge sont rejetés, puis testez les noms identiques, la révocation de l’autorisation de l’application Box et les échecs partiels d’export.
Quand Transloadit est utile
Utilisez ce flux de travail pour la réception interactive de documents par utilisateur dans un dossier de collaboration Box. Utilisez /upload/handle pour recevoir les documents des utilisateurs, /document/convert pour convertir les formats bureautiques pris en charge en PDF et /box/store pour l’export durable. Conservez les informations d’identification permettant l’accès à Box dans les informations d’identification de Template, utilisez un chemin de dossier approuvé par l’application et laissez la création de liens de partage désactivée, sauf si le produit en a explicitement besoin.
Périmètre architectural
Transloadit convertit et exporte le document téléversé. L’application reste responsable des autorisations des utilisateurs, de l’identité du dossier ou du projet, de la conservation, de la classification juridique, des paramètres de collaboration Box et de la possibilité de partager le document obtenu.
Questions fréquentes
Ce Template peut-il accepter des PDF en entrée ?
/document/convert n’accepte pas les PDF en entrée. Faites contourner la conversion aux PDF existants ou utilisez un flux de travail distinct adapté à l’opération PDF requise.
/box/store doit-il créer un lien de partage ?
Généralement pas pendant la réception. Gardez create_sharing_link à false et faites du partage une action autorisée ultérieure, avec une audience et une politique de révocation explicites.
La conversion préserve-t-elle toutes les fonctionnalités des documents bureautiques ?
Non. Vérifiez des exemples représentatifs de polices, de mises en page, de formules, de liens et de fonctionnalités complexes propres aux applications avant de vous fier au PDF comme rendu de référence.
Le navigateur peut-il choisir le dossier Box ?
Le navigateur peut soumettre un identifiant applicatif au périmètre limité, mais un serveur de confiance devrait l’autoriser et le Template verrouillé devrait contrôler le chemin de destination réel.
Que faut-il stocker dans la base de données de l’application ?
Conservez l’identité du document source et de sa version, la version du flux de travail, l’identifiant d’Assembly, l’identité du fichier Box, le chemin de destination et l’état final du flux de travail.