Durchsuchbare Dokumentation aufrufen
Zurück zur Dokumentationsübersicht
agorum core sap idoc
Mit agorum core sap idoc lesen Sie die agi-Dateien aus SAP ein und konvertieren diese anschließend in das PDF-Format.
agorum core sap idoc enthält folgende Knoten für den agorum core workflow 3.0:
Voraussetzungen zur Benutzung
- Das Modul SAP muss aktiviert sein.
- Sie benötigen das lizenzierte und konfigurierte Modul „SAP“.
Sobald das Modul SAP aktiviert wird, installiert sich agorum core sap idoc automatisch beim nächsten Neustart des agorum core-Servers. agorum core sap idoc ist deswegen nicht im agorum core plugin manager zu finden.
Nach der Aktivierung und dem Neustart des Servers legt das System automatisch den Ordner agorum.sap.idoc im agorum core explorer an. Sie finden den Ordner unter:
Eigene Dateien/Administration/customers
IDOC-Bibliothek
Die IDOC-Bibliothek ist eine JavaScript-Datei, die Funktionen anbietet, um agi-Dateien zu konvertieren.
Sie finden die IDOC-Bibliothek im agorum core explorer unter:
Eigene Dateien/Administration/customers/agorum.sap.idoc/js/idoc.js
Tipp: Am Ende der IDOC-Bibliothek werden unter module.exports alle relevanten Funktionen aufgeführt.
Verwendung
let idoc = require('/agorum/roi/customers/agorum.sap.idoc/js/idoc');
readIdoc
Diese Funktion liest die XML-Struktur einer agi-Datei ein und wandelt die angegebenen Daten in ein für den Benutzer lesbares JSON-Format um.
Als Resultat wird eine menschenlesbare JSON-Struktur der IDOC-Datei zurückgegeben.
let idoc = require('/agorum/roi/customers/agorum.sap.idoc/js/idoc');
let agi = objects.find(/* AGI-Datei-Objekt oder zugehörige ID */);
let readableIdoc = idoc.readIdoc(agi);
Parameter
| Parameter | Beschreibung | Beispiele |
|---|---|---|
| agi | Entspricht der agi-Datei. |
|
createTemplateData
Diese Funktion erzeugt Daten, die für das Template benötigt werden. Es werden lesbare Daten bereinigt, überflüssige Daten entfernt, Summen nachgerechnet und Daten validiert. Das Ergebnis ist eine bereinigte JSON-Datenstruktur (vgl. unten).
let idoc = require('/agorum/roi/customers/agorum.sap.idoc/js/idoc');
let agi = objects.find(/* AGI-Datei-Objekt oder zugehörige ID */);
let readableIdoc = idoc.readIdoc(agi);
let templateData = idoc.createTemplateData(readableIdoc);
Parameter
| Parameter | Beschreibung |
|---|---|
| readableIdoc | Lesbare IDOC-Datei als Ergebnis der Funktion readIdoc. |
Template-Daten
Im Folgenden werden die einzelnen Sektionen der Template-Daten gezeigt, die als Resultat der Funktion createTemplateData entstehen.
{
"metadata" : {
// Hier finden sich Informationen über das Dokument,
// etwa Dateiname in agorum core, SAP-Status- und control-Record
},
// Im Folgenden werden die Kopfdaten des Dokuments aufgelistet
"currency" : "EUR", // Text, Währungsinformation für das Dokument
"customerNumber" : <Text>, // Kundennummer
"deliveryDate" : <Datum>, // Lieferdatum
"deliveryNoteNumber" : <Text>, // Lieferschein-Nummer
"invoiceDate" : <Datum>, // Rechnungsdatum (allgemeiner: Datum des Dokuments)
"invoiceNumber" : <Text>, // Rechnungsnummer
"orderNumber" : <Text>, // Bestellnummer
"payUntil" : <Datum>, // Zahlbar bis
"sender" : {}, // Anschrift des Dokumentsenders
"receiver" : {}, // Anschrift des Dokumentempfängers
"conditions" : [ ], // Zusätzliche Bedingungen
"deliveryInfo" : {}, // Informationen, die die Lieferung betreffen
"docType" : {}, // Informationen zum Dokumententyp
"paymentInfo" : { // Zahlungsinformationen, zeilenweise
"lines" : [ ]
}
"vatIDs" : {}, // Steuer-IDs
"items" : [ {}, {}, ... ], // Informationen über die Positionen
"total" : {}, // Netto-, Brutto-Summe und Steuern
}
applyModifications
Durch diese Funktion wird das im MetaDB-Schlüssel „PostProcessing“ hinterlegte Skript abgerufen. Diesem Skript wird daraufhin die templateData übergeben. Hierdurch können eigene Anpassungen an der vorgegebenen Datenstruktur durchgeführt werden.
let idoc = require('/agorum/roi/customers/agorum.sap.idoc/js/idoc');
let agi = objects.find(/* AGI-Datei-Objekt oder zugehörige ID */);
let readableIdoc = idoc.readIdoc(agi);
let templateData = idoc.createTemplateData(readableIdoc);
templateData = idoc.applyModifications(templateData);
Parameter
| Parameter | Beschreibung |
|---|---|
| templateData | Template-Daten als Ergebnis der Funktion createTemplateData |
Beispiel eines PostProcessing-Skripts
/* global idoc */
// In der globalen Variable "idoc" wird die Datenstruktur übergeben.
// Das Resultat muss zwingen wieder in diese Variable zurückgeschrieben werden.
if (Array.isArray(idoc.receiver.name)) {
idoc.receiver.name = idoc.receiver.name.join(' ');
}
if (Array.isArray(idoc.sender.name)) {
idoc.sender.name = idoc.sender.name.join(' ');
}
// Variable zurückschreiben
global.idoc = idoc;
handleSourceFile
Diese Funktion verarbeitet die Quelldatei (agi-Datei) nach den angegebenen Konfigurationen, die in der MetaDB hinterlegt sind:
- Wenn der MetaDB-Schlüssel iDocKeepOriginal den Wert true enthält, wird die Quelldatei (agi-Datei) neben dem resultierenden PDF abgelegt. Beide Dokumente werden miteinander verknüpft.
- Wenn der MetaDB-Schlüssel iDocKeepOriginal nicht den Wert true enthält, wird die Quelldatei gelöscht.
let idoc = require('/agorum/roi/customers/agorum.sap.idoc/js/idoc');
let agi = objects.find(/* AGI-Datei-Objekt oder zugehörige ID */);
// Die PDF-Datei wird auch von idoc.generateInvoice(...) zurückgegeben.
let pdf = objects.find(/* PDF-Datei-Objekt oder zugehörige ID */);
idoc.handleSourceFile(agi, pdf);
| Parameter | Beschreibung | Beispiel |
|---|---|---|
| agi | Quelldatei oder zugehörige ID |
|
| PDF-Datei oder zugehörige ID |
applyMetadata
Diese Funktion sorgt dafür, dass die PDF-Datei den Metadaten-Status converted erhält und setzt die in der MetaDB konfigurierten Metadaten auf das PDF.
Sollte die Quelldatei nicht gelöscht worden sein, werden die Metadaten ebenfalls auf die agi-Datei geschrieben.
let idoc = require('/agorum/roi/customers/agorum.sap.idoc/js/idoc');
let agi = objects.find(/* AGI-Datei-Objekt oder zugehörige ID */);
let templateData = idoc.applyModifications(idoc.createTemplateData(idoc.readIdoc(agi)));
// Die PDF-Datei wird auch von idoc.generateInvoice(...) zurückgegeben
let pdf = objects.find(/* PDF-Datei-Objekt oder zugehörige ID */);
idoc.applyMetadata(templateData, agi, pdf);
| Parameter | Beschreibung |
|---|---|
| templateData | Template-Daten als Ergebnis der Funktion createTemplateData |
| agi | Quelldatei oder zugehörige ID |
| PDF-Datei oder zugehörige ID |
runDocumentWorkflow
Diese Funktion ruft einen Workflow auf, den Sie optional über das Property-Entry DocumentWorkflow hinterlegt haben, und führt den dort hinterlegten Workflow aus.
Das System wirft einen Fehler, wenn Sie einen fehlerhaften Workflow-Namen im Property-Entry DocumentWorkflow angegeben haben.
let idoc = require('/agorum/roi/customers/agorum.sap.idoc/js/idoc');
let agi = objects.find(/* AGI-Datei-Objekt oder zugehörige ID */);
let templateData = idoc.applyModifications(idoc.createTemplateData(idoc.readIdoc(agi)));
// Die PDF-Datei wird auch von idoc.generateInvoice(...) zurückgegeben
let pdf = objects.find(/* PDF-Datei-Objekt oder zugehörige ID */);
idoc.runDocumentWorkflow(templateData, agi, pdf);
| Parameter | Beschreibung |
|---|---|
| templateData | Template-Daten als Ergebnis der Funktion createTemplateData |
| agi | Quelldatei oder zugehörige ID |
| PDF-Datei oder zugehörige ID |
generateInvoice
Diese Funktion verhält sich wie der Workflow-Knoten iDoc-Dokumente verarbeiten. Dabei werden jedoch die IDOC-Dateien in separaten Transaktionen abgearbeitet, die im Fehlerfall zurückgerollt werden.
let idoc = require('/agorum/roi/customers/agorum.sap.idoc/js/idoc');
let idocIds = [ 101112, '/agorum/roi/files/Demo/invoice.agi' ];
let templateId = '/agorum/roi/files/Demo/template.odt';
let ouputPath = '/agorum/roi/files/Demo/invoices';
let pdfFiles = idoc.generateInvoice(idocIds, templateId, ouputPath);
Parameter
| Parameter | Beschreibung | Beispiel |
|---|---|---|
| idocIds | Array der Dokument-IDs | [ 101112, '/agorum/roi/files/Demo/invoice.agi' ] |
| templateId (Optional) | ID der Dokumentvorlage | 121110 oder '/agorum/roi/files/Demo/template.odt' |
| ouputPath (Optional) | Ausgabepfad für das PDF | '/agorum/roi/files/Demo/invoices' |
| progress (Optional) | Wenn die Funktion als Hintergrundprozess ausgeführt wird, kann der Hintergrundprozess übergeben werden, damit Status-Updates angezeigt werden. | – |
generateInvoiceInBackground
Diese Funktion führt die Funktion generateInvoice im Hintergrund aus, da das Konvertieren, insbesondere von mehreren Dokumenten, einige Zeit dauern kann, und zeigt dabei ein Statusfenster des Hintergrundprozesses an.
let idoc = require('/agorum/roi/customers/agorum.sap.idoc/js/idoc');
let idocIds = [ 101112, '/agorum/roi/files/Demo/invoice.agi' ];
let templateId = '/agorum/roi/files/Demo/template.odt';
let ouputPath = '/agorum/roi/files/Demo/invoices';
let pdfFiles = idoc.generateInvoiceInBackground(idocIds, templateId, ouputPath);
Parameter
| Parameter | Beschreibung | Beispiel |
|---|---|---|
| idocIds | Array der Dokument-IDs | [ 101112, '/agorum/roi/files/Demo/invoice.agi' ] |
| templateId (Optional) | ID der Dokumentvorlage | 121110 oder '/agorum/roi/files/Demo/template.odt' |
| ouputPath (Optional) | Ausgabepfad für das PDF | '/agorum/roi/files/Demo/invoices' |
MetaDB-Schlüssel anpassen
Einige MetaDB-Schlüssel müssen Sie manuell anpassen, damit Sie SAP IDOC verwenden können.
Property-Bundle „idoc“
Im Property-Bundle idoc stellen Sie die MetaDB-Schlüssel für die IDOC-Funktionen ein.
Sie finden das Property-Bundle folgendermaßen:
- Öffnen Sie links in der Seitenleiste Administration und dann MetaDB.
- Öffnen Sie den Pfad:
MAIN_MODULE_MANAGEMENT/sap/control/idoc
Property-Entry „iDocKeepOriginal“
Bestimmt bei erfolgreicher Konvertierung, ob die ursprüngliche agi-Datei behalten wird.
- Wenn Sie im Feld Wert (String) den Wert true eingeben, bleibt die Ursprungsdatei erhalten und die agi-Datei wird neben der PDF-Datei abgelegt.
- Wenn Sie im Feld Wert (String) den Wert false oder einen anderen Wert als true eingeben, wird die agi-Datei gelöscht.
Property-Entry „PostProcessing“ (optional)
Definiert den Pfad zum JavaScript, das das PostProcessing ausführt und die templateData den Kundenwünschen entsprechend anpasst.
Hinweis: In der Standardeinstellung ist kein Pfad für das PostProcessing angegeben.
Property-Entry „TemplateFile“
Definiert den Pfad zum verwendeten Template, das Sie beliebig anpassen können.
Achtung: Datenverlust durch Änderung des mitgelieferten Templates. Der Inhalt des hier im Standard angegebene Templates invoice-template.odt darf nicht geändert werden, da bei einem Neustart des agorum core-Servers Ihre Änderungen im Template überschrieben werden. Erstellen Sie stattdessen eine neue ODT- oder Word-Datei wie nachfolgend beschrieben und geben Sie den Pfad in den Einstellungen der MetaDB an.
Hinweis: Das verwendete Template muss entweder als ODT-Datei oder als Word-Datei angegeben sein.
So passen Sie das Template an:
- Laden Sie sich das Standardtemplate herunter.
Hinweis: In der Standardeinstellung wird ein Standardtemplate von agorum core verwendet. Das Standardtemplate finden Sie im agorum core explorer unter:
Eigene Dateien/Administration/customers/agorum.sap.idoc/files
- Passen Sie das Template an.
- Laden Sie das Template etwa in den Workspace im agorum core explorer hoch:
workspace/agorum.sap.idoc
- Passen Sie den MetaDB-Schlüssel TemplateFile an, indem Sie im Feld Wert (String) den entsprechenden Pfad angeben:
Beispiel/agorum/roi/customers/agorum.sap.idoc/files/invoice-template.odt
Property-Entry „WorkingFolder“
Definiert den Ausgabepfad.
- In diesem Pfad erzeugt das System die PDF-Dateien.
- Passen Sie den WorkingFolder nach der Installation des Moduls SAP an.
- Sie können einen beliebigen Pfad angeben. Ohne den WorkingFolder können keine PDF-Dateien angelegt werden.
Beispiel eines Ausgabepfads
/agorum/roi/files/SAP/working/idoc
Property-Entry „DocumentWorkflow“ (optional)
Definiert einen Workflow, den das System ausführt, wenn es:
- die agi-Datei in ein PDF umgewandelt hat
- die SAP-Metadaten auf die agi-Datei geschrieben hat
Enthält das Property-Entry keinen Wert oder existiert es nicht, überspringt das System diesen Schritt und führt keinen Workflow aus.
Das System übergibt nach dem Schreiben der Metadaten:
- die ursprüngliche agi-Datei (sofern noch vorhanden)
- die erzeugte PDF-Datei
- die Template-Daten
Auf Grundlage dieser Daten können Sie dann in einem eigenen Workflow weitere Schritte mit den Dateien unternehmen.
- Der Prozess läuft synchron, d. h. die Umwandlung ist so lange pausiert, bis der Subworkflow einen Commit auslöst.
- Ein Commit wird durch die Knoten Verzögerung oder UI ausgelöst oder dadurch, dass der Subworkflow beendet wird.
An den Workflow übergebene Daten
sys_acw_attachments: [ agi ] // UUID of agi file
idoc: {
data: // template data object
pdf: [ <UUID> ] // UUID of resulting pdf
}
Property-Bundle „Recalculate“
Dieses Property-Bundle befindet sich innerhalb des Property-Bundles idoc und enthält Property-Entrys, mit denen Sie die automatische Nachberechnung der Brutto- und Netto-Summe sowie des Steuersatzes aktivieren oder deaktivieren können, sowohl auf Kopfebene als auch auf Positionsebene.
Eine Nachberechnung seitens agorum core findet statt, wenn SAP agi-Dateien an agorum core überträgt, die in agorum core bereits vorhanden sind und deren Werte sich bei der erneuten Übertragung geändert haben (Steuersätze, Preise, Menge).
Automatische Nachberechnung auf Kopfebene aktivieren oder deaktivieren
| Property-Entry | Wert/Beschreibung |
|---|---|
| Total | true (Standard) Aktiviert die automatische Nachberechnung der Brutto- und Netto-Summe auf Kopfebene. false Deaktiviert die automatische Nachberechnung der Brutto- und Netto-Summe auf Kopfebene. |
| Vat | true (Standard) Aktiviert die automatische Nachberechnung des Steuersatzes auf Kopfebene. false Deaktiviert die automatische Nachberechnung des Steuersatzes auf Kopfebene. |
Automatische Nachberechnung auf Positionsebene aktivieren oder deaktivieren
Die Aktivierung oder Deaktivierung der automatischen Nachberechnung auf Positionsebene nehmen Sie im Property-Bundle Item vor, das sich innerhalb des Property-Bundles Recalculate befindet.
| Property-Entry | Wert/Beschreibung |
|---|---|
| Total | true (Standard) Aktiviert die automatische Nachberechnung der Brutto- und Netto-Summe auf Positionsebene. false Deaktiviert die automatische Nachberechnung der Brutto- und Netto-Summe auf Positionsebene. |
| Vat | true (Standard) Aktiviert die automatische Nachberechnung des Steuersatzes auf Positionsebene. false Deaktiviert die automatische Nachberechnung des Steuersatzes auf Positionsebene. |
Property-Bundle „Validate“
Dieses Property-Bundle befindet sich innerhalb des Property-Bundles idoc und enthält Property-Entrys, mit denen Sie die automatische Validierung der Brutto- und Netto-Summe aktivieren oder deaktivieren können, sowohl auf Kopfebene als auch auf Positionsebene.
Eine Validierung seitens agorum core findet statt, wenn SAP agi-Dateien an agorum core übermittelt. agorum core prüft die Daten auf fehlende Werte.
Automatische Validierung auf Kopfebene aktivieren oder deaktivieren
| Property-Entry | Wert/Beschreibung |
|---|---|
| Total | true (Standard) Aktiviert die automatische Validierung der Brutto- und Netto-Summe auf Kopfebene. false Deaktiviert die automatische Validierung der Brutto- und Netto-Summe auf Kopfebene. |
Automatische Validierung auf Positionsebene aktivieren oder deaktivieren
Die Aktivierung oder Deaktivierung der automatischen Validierung auf Positionsebene nehmen Sie im Property-Bundle Item vor, das sich innerhalb des Property-Bundles Validate befindet.
| Property-Entry | Wert/Beschreibung |
|---|---|
| Total | true (Standard) Aktiviert die automatische Validierung der Brutto- und Netto-Summe auf Positionsebene. false Deaktiviert die automatische Validierung der Brutto- und Netto-Summe auf Positionsebene. |
Property-Bundle „Invoice“
In diesem Property-Bundle stellen Sie das Metadata-Mapping für die SAP-Metadaten ein, die auf das Dokument geschrieben werden.
So finden Sie das Property-Bundle:
- Öffnen Sie links in der Seitenleiste Administration und dann MetaDB.
- Öffnen Sie den Pfad:
MAIN_MODULE_MANAGEMENT/sap/control/metadata/invoice
Die MetaDB-Schlüssel für die Invoice-Funktion können Sie nach der Installation des Moduls SAP anpassen. Die Schlüssel sind kundenspezifisch und deswegen nicht voreingestellt. Zudem definieren die MetaDB-Schlüssel die einzufügenden Daten.
Sie können diese jeweils im Feld Wert (String) anpassen.
Hinweis: SAPDocumentTypeInvoice steht im Gegensatz zu den anderen MetaDB-Schlüsseln für einen Wert. Dieser Wert wird als Dokumenttyp (SAPDocumentType) auf das Dokument geschrieben.
CronJob
Im Property-Bundle agorum.sap.idoc.agiConverter stellen Sie die Metadaten für den CronJob ein. Der CronJob sorgt im Hintergrund dafür, dass die agi-Dateien verarbeitet werden.
- Öffnen Sie links in der Seitenleiste Administration und dann MetaDB.
- Öffnen Sie den Pfad:
MAIN_MODULE_MANAGEMENT/cronjob/control/[ SAP ]/agorum.sap.idoc.agiConverter
Property-Entry „CronTime“
Definiert, in welchen Abständen der CronJob Daten ausgibt.
Hinweis: In der Standardeinstellung ist die CronTime auf eine minütliche Ausführung eingestellt. Mehr Angaben zur Einstellung der CronTime finden Sie im Web unter dem Stichwort crontime generator.
Um die CronTime umzustellen, tragen Sie im Feld Wert (String) den gewünschten Wert ein.
SAP IDOC anwenden (agi-Dateien konvertieren)
Hinweise:
-
In der MetaDB muss der WorkingFolder angepasst sein.
-
Das System konvertiert nur agi-Dateien, die nach der Aktivierung des SAP-Moduls angelegt wurden.
So starten Sie das automatische Konvertieren der agi-Dateien:
- Sobald Sie eine agi-Datei in einen beliebigen Ordner im agorum core explorer einfügen, startet das Einlesen automatisch.
- Der CronJob verarbeitet die agi-Datei bei der nächsten Ausführung.
Nachdem die agi-Datei aus dem gewählten Ordner verschwunden ist und verarbeitet wurde, gibt es zwei mögliche Ergebnisse:
Ergebnis 1
Die agi-Datei wurde erfolgreich zu einer PDF-Datei konvertiert.
Ergebnis 2
Die agi-Datei ist fehlerhaft und konnte deswegen nicht konvertiert werden.
Ergebnis 1: Konvertierte PDF-Datei
Hinweis: Die ursprüngliche agi-Datei wird nur zusammen mit der PDF-Datei abgelegt, wenn iDocKeepOriginal aktiviert ist. Wenn iDocKeepOriginal nicht aktiviert ist, wird die ursprüngliche agi-Datei gelöscht.
Die konvertierte PDF-Datei und die ursprüngliche agi-Datei werden in der Standardeinstellung im Ordner idoc abgelegt.
So finden Sie den Ordner:
- Öffnen Sie links in der Seitenleiste Explorer.
- Öffnen Sie den Pfad:
Dateien/SAP/working/idoc
Dass die agi-Datei in eine PDF-Datei konvertiert wurde, erkennen Sie, indem Sie die agi-Datei anklicken und in der Objektinfo das Metadatum Verarbeitungsstatus prüfen. Ist die Datei konvertiert, steht das Metadatum auf converted:
Beispiel
Nachfolgend wird eine PDF-Datei gezeigt, die aus einer agi-Datei konvertiert wurde.
Ergebnis 2: Fehlerhafte agi-Datei
Wenn eine agi-Datei fehlerhaft ist, kann sie nicht konvertiert werden. Dass die agi-Datei fehlerhaft ist, erkennen Sie an den folgenden vier Merkmalen:
- Die agi-Datei wird nicht verschoben, sondern verbleibt im Ablage-Verzeichnis.
- An der agi-Datei hängt eine Notiz, die die Fehler aufzählt.
- Der Verarbeitungsstatus lautet failure anstatt converted.
- Die agi-Datei wird zusätzlich im Ablageordner im Unterordner failures verlinkt.
So finden Sie den Unterordner failures in der Standardeinstellung:
- Öffnen Sie links in der Seitenleiste Explorer.
- Öffnen Sie den Pfad:
Dateien/SAP/working/idoc/failures
Fehler entstehen in der Regel durch fehlende Werte, wodurch die Validierung fehlschlägt. In der Notiz wird angegeben, welche Validierung fehlgeschlagen ist und aus welchem Grund.
Aussehen einer fehlerhaften agi-Datei
In der Objektinfo steht das Metadatum Verarbeitungsstatus auf failure:
Fehler einsehen
- Klicken Sie die agi-Datei mit der linken Maustaste an.
- Prüfen Sie in der Registerkarte Notizen die Notiz, die an die agi-Datei angefügt ist.
Fehler beheben
Eine fehlerhafte agi-Datei weist meistens auf Fehler im Export von SAP hin.
So beheben Sie Fehler:
- Korrigieren Sie die Fehler im Export Ihrer SAP-Software.
Hinweis: Alternativ können Sie den Fehler manuell in der Datei selbst beheben. Laden Sie hierzu die Datei herunter und führen Sie die gewünschten Korrekturen durch.
- Exportieren Sie die agi-Datei erneut.
- Laden Sie die korrigierte agi-Datei neu in agorum core hoch.
Ergebnis: Die Konvertierung der Datei startet.