Callbacks

Callbackskript erstellen

Um ein Callbackskript zu erstellen, kann die Vorlage ou.tmpl.IF.settings.callback.example kopiert werden.

1. Portalskript ou.tmpl.IF.settings.callback.example öffnen und Inhalt kopieren
2. Neues Portalskript anlegen mit dem Prefix ou.cust.IF.settings.callback.
3. Code aus ou.tmpl.IF.settings.callback.example einfügen und speichern
4. Die gewünschte Importregel öffnen und Callbackskript auswählen.

Reihenfolge der Import Callbacks

1. Nach dem Import, Datei verschieben
   1. beforeMoveFile
   2. SP Logik (Datei wird verschoben)
   3. onFileMoved

beforeMoveFile boolean?

Callback bevor die Datei verschoben wird. Die Standard-Logik kann über return false übersprungen werden.

beforeMoveFile: (importFile: importFile, sourceFile: string, targetFile: string, rule: importFileRule) =>
    false | undefined;

onFileMoved void

Callback nachdem die Zielmappe erstellt und ein sync() ausgeführt wurde.

onFileMoved: (targetFilePath: string) => void;

onFileMoved: (targetFilePath) => {
    util.out(targetFilePath);
};

Reihenfolge der Transform Callbacks

1. Start

   1. startTransformFile
   2. SP Logik (Zurücksetzen der Mappenfelder)

2. Duplikatsprüfung

   1. generateDocKeySid3 (nur bei Dateityp 'SID3')
   2. beforeDuplicateCheck
   3. SP Logik
   4. onDuplicateChecked

3. Mapping laden

   1. SP Logik (Statisches Feldmapping aus Regel)
   2. mapping bzw. mappingArchiveImport oder mappingSid3

4. Mappentyp erstellen

   1. beforeFileCreate
   2. SP Logik
   3. onFileCreated

5. Mappenfelder belegen

   1. beforeMapping
   2. SP Logik
   3. onFieldsMapped

6. Datei anhängen

   1. overwriteAttachmentsPathSid3 (nur bei Dateityp 'SID3')
   2. beforeAttachDocument
   3. mappingTargetRegisterArchiveImport bzw. mappingTargetRegisterSid3 (nur bei Dateityp 'Easy Archive XML Export' / 'SID3')
   4. SP Logik
   5. onDocumentAttached

7. Workflow starten

   1. determineWorkflowNameSid3 (nur bei Dateityp 'SID3')
   2. beforeStartWorkflow
   3. SP Logik
   4. onWorkflowStarted

8. Importmappe löschen

   1. beforeDeleteImportFile
   2. SP Logik
   3. onImportFileDeleted

9. Dateianhänge löschen (nur bei Dateityp 'EASY Archiv XML Export' und 'SID3')

   1. determineAttachmentsDestinationSubDirectorySid3 (nur bei Dateityp 'SID3')
   2. SP Logik

10. Abschluss

    1. onTransformFileFinished

vorsicht

Ab Punkt 5, erfolgt im Fehlerfall ein Rollback und die neu erstellte Mappe wird gelöscht.

startTransformFile boolean?

Callback bevor die Transformation gestartet wird. Die Transformation kann über return false übersprungen werden.

startTransformFile: (importFile: importFile, rule: importFileRule) => boolean;

Transformation für Mappe überspringen

beforeDuplicateCheck: (importFile, rule) => {
    if (importFile.fileName === "skip.pdf") {
        return false;
    }
};

generateDocKeySid3 string?

Callback für den Dateityp 'SID3' zum Generieren eines eindeutigen Dokumentenschlüssels des Ursprungsdokuments (MUSS implementiert werden). Ist dieser Callback nicht implementiert bzw. gibt er keinen Wert zurück, wird ein Fehler geworfen. Der Dokumentenschlüssel wird für den Dublettencheck verwendet.

generateDocKeySid3: (targetFileType: string, mapping: {field: string; value: any}[]) => string | null;

Dokumentenschlüssel zur Verfügung stellen

generateDocKeySid3: (targetFileType, mapping) => {
    const docKey = mapping.find((fieldInfo) => fieldInfo.field === "barcode").value;
    return docKey;
};

beforeDuplicateCheck boolean?

Callback bevor der Duplikatscheck ausgeführt wird. Wird ein boolischer Wert zurückgegeben, so wird Duplikatsprüfung übersprungen.

beforeDuplicateCheck: (importFile: importFile) => boolean | null;

Duplikatsprüfung überspringen

beforeDuplicateCheck: (importFile) => {
    // Kein Duplikat
    return false;
};

Duplikat gefunden

beforeDuplicateCheck: (importFile) => {
    // Duplikat
    return true;
};

onDuplicateChecked boolean?

Callback nach dem der Duplikatscheck ausgeführt wurde. Wird ein boolischer Wert zurückgegeben, so wird Duplikatsprüfung übersprungen.

onDuplicateChecked: (importFile: importFile, duplicateFileIds?: string[]) => boolean;

Duplikatsprüfung überspringen

onDuplicateChecked: (importFile, duplicateFileIds) => {
    // Kein Duplikat
    return false;
};

Duplikat gefunden

onDuplicateChecked: (importFile, duplicateFileIds) => {
    // Duplikat
    return true;
};

beforeFileCreate DocFile?

Callback bevor die Zielmappe erstellt wird. Über diesen Callback ist es möglich, eine eigene Mappe zu erstellen und zurückzugeben.

beforeFileCreate: (importFile: importFile, targetFileType: string) => DocFile | null;

Eigene Mappeninstanz erstellen

beforeFileCreate: (importFile, targetFileType) => {
    return context.createFile("myCustomFileType");
};

onFileCreated void

Callback nachdem die Zielmappe erstellt und ein sync() ausgeführt wurde.

onFileCreated: (newFile: DocFile) => void;

onFileCreated: (newFile) => {
    util.out(newFile.recipient);
};

mapping FieldMapping[]

Callback für Mappenfelder-Mapping für den Dateityp 'Einzeldatei'. Neben dem statischen Mapping der Regel, ist es hier möglich dynamisch Werte zu belegen.

mapping: (options: {
    importFile: importFile;
    rule: importFileRule;
    fileFragements: string[];
}) => FieldMapping[];

Dynamisch Mappenfelder belegen

mapping: (options) => {
    const fileName = options.fileFragements[options.fileFragements.length - 1];
    const directoryName = options.fileFragements[options.fileFragements.length - 2];
    const originalPath = options.importFile.filePath;

    /** @type {{field: string, value: string}[]} */
    const customMapping = [];

    customMapping.push({
        field: "recipient",
        value: directoryName,
    });

    return customMapping;
};

mappingArchiveImport FieldMapping[]

Callback für Mappenfelder-Mapping für den Dateityp 'Easy Archive XML Export'. Neben dem statischen Mapping der Regel, ist es hier möglich dynamisch Werte zu belegen. Wird ein Mapping zurückgegeben, so werden die Felder der Zielmappe entsprechend befüllt. Felder, die bereits über das statische Mapping der Regel gesetzt wurden, werden hierbei überschrieben. Wird null zurückgegeben bzw. der Callback nicht implementiert, so wird versucht, die Feldwerte der Ursprungsmappe gleichnamigen Feldern in der Zielmappe zuzuweisen. Existiert kein gleichnamiges Feld, wird ein Fehler geworfen. Bereits über das statische Mapping der Regel gesetzte Werte werden nicht überschrieben.

mapping: (options: {
    importFile: importFile;
    rule: importFileRule;
    fileFragements: string[];
    oldDocId: string;
    oldFieldMapping: FieldMapping[];
}) => FieldMapping[];

Dynamisch Mappenfelder belegen

mapping: (options) => {
    const fileName = options.fileFragements[options.fileFragements.length - 1];
    const directoryName = options.fileFragements[options.fileFragements.length - 2];
    const originalPath = options.importFile.filePath;
    const oldDocId = options.oldDocId;
    const mapping = {
        oldField1: "newField1",
        oldField2: "newField2",
    };

    /** @type {{field: string, value: any}[]} */
    const newFieldMapping = [];
    options.oldFieldMapping.forEach((oldMapping) => {
        const newField = mapping[oldMapping.field];
        if (newField) {
            newFieldMapping.push({
                field: newField,
                value: oldMapping.value
            });
        }
    });
    return newFieldMapping;
};

mappingSid3 Object

Callback für Mappenfelder-Mapping für den Dateityp 'SID3' sowie Definition des Zielmappentyps (MUSS implementiert werden). Wird ein Objekt zurückgegeben, in welchem sowohl 'fileType' als auch 'fieldMapping' gesetzt sind, so wird eine neue Mappe des angegebenen Mappentyps erstellt und die Felder entsprechend befüllt. Wird null zurückgegeben, der Callback nicht implementiert oder fehlt im Rückgabeobjekt die Dateitypangabe, so wird ein Fehler geworfen. Wird ein Objekt zurückgegeben, in welchem 'fieldMapping' null ist, so wird versucht, die Feldwerte der Ursprungsmappe gleichnamigen Feldern in der Zielmappe zuzuweisen. Existiert kein gleichnamiges Feld, wird ein Fehler geworfen.

mappingSid3: (options: {
    importFile: importFile;
    rule: importFileRule;
    fileFragements: string[];
    oldFieldMapping: FieldMapping[];
}) => {fileType:string; fieldMapping: FieldMapping[] | null};

Zielmappentyp und Feldbelegung festlegen

mappingSid3: (options) => {
    const fileName = options.fileFragements[options.fileFragements.length - 1];
    const directoryName = options.fileFragements[options.fileFragements.length - 2];
    const originalPath = options.importFile.filePath;
    const mapping = {
        "oldField1": "newField1",
        "oldField2": "newField2",
    };

    const newFieldMapping = [];
    options.oldFieldMapping.forEach((oldMapping) => {
        const newField = mapping[oldMapping.field];
        if (newField) {
            newFieldMapping.push({
                field: newField,
                value: oldMapping.value
            });
        }
    });
    return {
        fileType: "ptpInvoice",
        fieldMapping: newFieldMapping,
    };
};

beforeMapping boolean

Callback bevor die Mappenfelder befüllt werden. Das Mapping kann über return false übersprungen werden.

beforeMapping: (newFile: DocFile, fieldMappings: { field: string; value: string }[]) => boolean;

Mapping überspringen

beforeMapping: (newFile, fieldMappings) => {
    return false;
};

onFieldsMapped void

Callback nach dem der Mappenfelder befüllt wurden. Nach diesem Callback wird ein sync() ausgeführt, somit ist ein sync() nicht notwendig

onFieldsMapped: (newFile: DocFile) => void;

Mapping überspringen

onFieldsMapped: (newFile) => {
    newFile.ufField = "someValue";
};

overwriteAttachmentsPathSid3 Array

Callback für den Dateityp 'SID3' zum Überschreiben der Anhangspfade. Wird null zurückgegeben bzw. der Callback nicht implementiert, so werden die ursprünglichen Anhangspfade verwendet. Ist ein bestimmter Dokumentenanhang nicht im Rückgabe-Array enthalten, so wird dieser nicht an die erstellte Mappe angehängt.

overwriteAttachmentsPathSid3: (attachments: { fileName: string; filePath: string }[]) => { fileName: string; filePath: string }[] | null;

Anhangspfade überschreiben

overwriteAttachmentsPathSid3: (attachments) => {
    const newAttachments = [];
    attachments.forEach((attachment) => {
        newAttachments.push({
            fileName: attachment.fileName,
            filePath: "D:\\tmp\\newPath\\" + attachment.fileName,
        });
    });
    return newAttachments;
};

beforeAttachDocument boolean

Callback bevor die Datei an die neue Mappe angefügt wird. Das Anfügen der Datei kann über return false übersprungen werden.

beforeAttachDocument: (newFile: DocFile, importFile: importFile, rule: importFileRule) => boolean;

Anfügen der Datei überspringen

beforeAttachDocument: (newFile, importFile, rule) => {
    return false;
};

mappingTargetRegisterArchiveImport Array

Callback für TargetRegister-Mapping für den Dateityp 'Easy Archive XML Export'. Hier kann für jeden Mappenanhang das über die Importregel festgelegte Zielregister überschrieben werden. Wird null zurückgegeben bzw. der Callback nicht implementiert, so wird das über die Importregel festgelegte Zielregister verwendet. Wird im Rückgabe-Array für einen Anhang das Zielregister auf null gesetzt, so wird dieser Anhang nicht an die erstellte Mappe angehängt.

mappingTargetRegisterArchiveImport: (documentFiles: string[]) => {fileName: string; targetRegister: string}[];

Das Zielregister dynamisch festlegen.

mappingTargetRegisterArchiveImport(documentFiles) {
    const mapping = {
        fileABC: "documents",
        fileXYZ: "attachments",
    };

    /** @type {{fileName: string, targetRegister: string}[]} */
    const targetRegisterMapping = [];
    documentFiles.forEach((file) => {
        const register = mapping[file];
        if (register) {
            targetRegisterMapping.push({
                fileName: file,
                targetRegister: register
            });
        }
    });
    return targetRegisterMapping;
};

mappingTargetRegisterSid3 Array

Callback für TargetRegister-Mapping für den Dateityp 'SID3' (MUSS implementiert werden). Hier muss jedem Mappenanhang das Zielregister zugeordnet werden. Wird null zurückgegeben bzw. der Callback nicht implementiert, so wird ein Fehler geworfen. Wird im Rückgabe-Array für einen Anhang das Zielregister auf null gesetzt, so wird dieser Anhang nicht an die erstellte Mappe angehängt.

mappingTargetRegisterSid3: (documentFiles: string[], newFile: DocFile) => {fileName: string; targetRegister: string}[];

Das Zielregister dynamisch festlegen

mappingTargetRegisterSid3: (documentFiles, newFile) => {
    const mapping = {
        ptpInvoice: {
            fileABC: "documents",
            fileXYZ: "attachments",
        },
        ...
    };

    const targetRegisterMapping = [];
    documentFiles.forEach((file) => {
        const register = mapping[newFile.getAutoText("fileType")][file];
        if (register) {
            targetRegisterMapping.push({
                fileName: file,
                targetRegister: register,
            });
        } else {
            targetRegisterMapping.push({
                fileName: file,
                targetRegister: "documents",
            });
        }
    });
    return targetRegisterMapping;
};

onDocumentAttached void

Callback nach dem die Datei an die neue Mappe angefügt wurde. Nach diesem Callback wird ein sync() ausgeführt, somit ist ein sync() nicht notwendig.

onDocumentAttached: (newFile: DocFile) => void;

onDocumentAttached: (newFile) => {};

determineWorkflowNameSid3 string

Callback für den Dateityp 'SID3' zur Angabe des Workflows, der gestartet werden soll. Wird null zurückgegeben oder der Callback nicht implementiert, so wird für die Mappe kein Workflow gestartet.

determineWorkflowNameSid3: (fileType: string) => string | null;

Workflow festlegen

determineWorkflowNameSid3: (fileType) => {
    const mapping = {
        ptpInvoice: "ptpInvoice_V1-1",
        // ...
    };
    return mapping[fileType] || null;
};

beforeStartWorkflow boolean

Callback bevor der Workflow gestartet wird. Das Starten des Workflows kann über return false übersprungen werden.

beforeStartWorkflow: (newFile: DocFile, workflowName: string) => boolean;

beforeStartWorkflow: (newFile, workflowName) => {
    if (workflowName === "nope") {
        return false;
    }
};

onWorkflowStarted void

Callback nach dem der Workflow gestartet wurde.

onWorkflowStarted: (newFile: DocFile) => void;

onWorkflowStarted: (newFile) => {};

beforeDeleteImportFile boolean

Callback bevor die Importmappe gelöscht wird. Das Löschen kann über return false übersprungen werden.

beforeDeleteImportFile: (importFile: importFile) => boolean;

Mappe nicht löschen

beforeDeleteImportFile: (importFile) => {
    return false;
};

onImportFileDeleted void

Callback nach dem die Importmappe gelöscht wurde.

onImportFileDeleted: () => void;

onImportFileDeleted: () => {};

determineAttachmentsDestinationSubDirectorySid3 Array

Callback für den Dateityp 'SID3' zur Angabe des Unterverzeichnisses in welches die Dokumentanhänge innerhalb des Zielverzeichnisses verschoben werden sollen. Wird nur aufgerufen, wenn an der Importregelmappe ausgewählt wurde, dass Dateien nach dem Import verschoben werden sollen. Wird null zurückgegeben bzw. der Callback nicht implementiert, so werden die Dokumentanhänge direkt in das angegebene Zielverzeichnis verschoben. Anhänge, die im zurückgegebenen Array nicht enthalten sind, werden nicht verschoben.

determineAttachmentsDestinationSubDirectorySid3: (attachments: { fileName: string; filePath: string }[]) => { filePath: string; destinationSubDirectory: string }[] | null;

Angabe des Unterverzeichnisses pro Mappe

determineAttachmentsDestinationSubDirectorySid3: (attachments) => {
    const destinationMapping = [];
    attachments.forEach((attachment) => {
        destinationMapping.push({
            filePath: attachment.filePath,
            destinationSubDirectory: "attachments",
        });
    });
    return destinationMapping;
};

onTransformFileFinished void

Callback nach dem die Transformation abgeschlossen wurde. Dieser Callback wird auch im Fehlerfall getriggert.

onTransformFileFinished: () => void;

onTransformFileFinished: () => {};