CreateLink / ArchiveLink

Voraussetzungen

Für das Erstellen von ArchiveLink-Verknüpfungen folgende Punkte benötigt:

• EASY for SAP - Archiving (SAP Level 1 / SAPMOD)
• SAP-seitige Konfiguration der Content Repositories und Belegarten, der zu verknüpfenden Dokumente, siehe SAP
• Konfiguration der betroffenen Belegarten in der Datenbank-Tabelle doctypes oder die Verwendung von der Datenbank-Tabelle createIndividualLink, siehe Datenbank

Konfiguration

SAP

Die Konfiguration der Belegarten kann über die Transaktionen "oac3" und "oac2" eingesehen werden. Nur wenn für die benötigte SAP-Belegart hier eine Konfiguration gepflegt ist, kann der CreateLink eingerichtet werden. Die Werte aus den Spalten "Objekttyp", "Dokumentart" und "Content Repository ID" werden im nächsten Step dann auf Datenbank-seite benötigt.

Datenbank

In der Datenbank-Tabelle "doctypes" muss für jede verwendete Belegart eine Archiv-Konfiguration gepflegt sein. Die hierfür relevanten Spalten sind:

Spaltenname	Bedeutung
SAPDocType	Die SAP Belegart des zu verknüpfenden Dokuments / Belegs (z.B. "KR" für Kreditorenrechnung)
SAPObject	Der Name des SAP Objekts zu dem die Verknüpfung hinzugefügt werden soll, z.B. "BKPF"
ArObject	Die SAP-interne "Dokumentart" aus der Transaktion oac3, für unsere Zwecke häufig "FIIINVOICE"
ArDocType	Der SAP-interne "Dokumenttyp" zu der angegebenen "Dokumentart". Dieser Wert kann über die Transaktion "oac2" aufgelöst werden (meist "FAX").
ArchivId	Die Content Repository ID aus der Transaktion "oac3"

Nur wenn es für die Belegart des Dokuments einen entsprechenden Eintrag in der Tabelle "doctypes" gibt (Auflösung über invoiceheader→invoiceheaderdocumenttype = doctypes→WfDocType) und dieser entsprechend der Tabelle vollständig konfiguriert ist, kann die Verknüpfung durchgeführt werden.

Oder es wird die Tabelle createIndividualLink verwendet, für die im Ordner sql ein CREATE TABLE Statement für mssql und mysql zu Verfügung gestellt wird.

Spaltenname	Bedeutung
ID	Die SAP Belegart des zu verknüpfenden Dokuments / Belegs (z.B. "KR" für Kreditorenrechnung)
SAPObjectId	Eindeutige Identifikation des SAP-Geschäftsobjekts, zu dem die Dokumentverknüpfung hergestellt werden soll. Diese ID referenziert das spezifische Objekt (z.B. Belegnummer, Kostenstelle) im SAP-System und wird als OBJECT_ID-Parameter für die ArchiveLink-Verbindung verwendet.
SAPObject	Der Name des SAP Objekts zu dem die Verknüpfung hinzugefügt werden soll, z.B. "BKPF"
ArObject	Die SAP-interne "Dokumentart" aus der Transaktion oac3, für unsere Zwecke häufig "FIIINVOICE"
ArDocType	Der SAP-interne "Dokumenttyp" zu der angegebenen "Dokumentart". Dieser Wert kann über die Transaktion "oac2" aufgelöst werden (meist "FAX").
ArchivId	Die Content Repository ID aus der Transaktion "oac3"
UUID	Die Archive Dokument ID
ArDate	Optional: Das Archivierungsdatum
Filename	Optional: Den Dateinamen
Descr	Optional: Die Beschreibung
Creator	Optional: Den Ersteller

Mapping

Der CreateLink wird ebenso wie alle anderen Kommandos des SAP Connectors über Mappings definiert. Allerdings muss für das Attribut "erpFunction" hier der Wert "createLink" gesetzt werden, damit intern der korrekte Befehl getriggert wird. Die Schnittstelle des Mappings zum SAP-Aufruf ist über die Struktur CONNECTION_DATA wie folgt vorgegeben:

Übergabestruktur CONNECTION_DATA

Feldname	Feldwert
ID	Die eindeutige Id des Documents, die auch für die Rückgabe über die callstate-Tabelle verwendet wird
OBJECT_ID	Optional: OBJECT_ID die exakt so an SAP weitergegeben wird. RECIPIENT, ERP_NUMBER und YEAR bzw DOC_DATE werden ignoriert. Die OBJECT_ID oder ERP_NUMBER ist verpflichtend anzugeben!
ERP_NUMBER	Optional: SAP Belegnummer. Die OBJECT_ID oder ERP_NUMBER ist verpflichtend anzugeben!
RECIPIENT	Optional: Buchungskreis des Belegs
YEAR	Optional: Geschäftsjahr des Belegs (vierstellig), falls nicht gesetzt wird das Jahr aus dem Belegdatum extrahiert
DOC_DATE	Optional: Belegdatum
UUID	Eine eindeutige Id, welche zum Verknüpfen der SAP- mit dem Archiv-Beleg verwendet wird. Im Archiv muss die Bedeutung am entsprechenden Feld gepflegt sein.
SAP_OBJECT	Das zugehörige SAP Object zum Dokument; z.B.: BKPF für FI-Rechnungen oder BUS2081 für MM-Rechnungen
ARCHIV_ID	Die Id des in SAP / SAPMOD gepflegten Archivs
AR_OBJECT	Das SAP Archiv Objekt, für FI-Rechnungen z.B. FIIINVOICE
AR_DOC_TYPE	Die SAP-Belegart des Belegs, z.B.: KR, RE, DN, ...
AR_DATE	Optional: Das Archivierungsdatum das an SAP übergeben wird. Falls nicht gesetzt wird das aktuelle Datum an SAP übergeben.

Verschiedene Möglichkeiten createLink zu verwenden

Für die OBJECT_ID die über createLink an SAP übergeben wird gibt es zwei Möglichkeiten.

• Die Angabe der OBJECT_ID in den CONNECTION_DATA: Sorgt dafür das der übergebene Wert exakt so wie angegeben an SAP übergeben wird.
• Eine Kombination aus ERP_NUMBER und RECIPIENT und YEAR bzw DOC_DATE, falls vorhanden, wird automatisch zusammengesetzt.

Falls OBJECT_ID automatisch zusammengesetzt wird, gilt folgendes:

• Wenn SAP_OBJECT = BKPF: ${data.RECIPIENT}${data.ERP_NUMBER}${documentYear}
• Wenn SAP_OBJECT = BUS2081: ${data.ERP_NUMBER}${documentYear}
• Alle anderen Werte von SAP_OBJECT führen zu einem Fehler: Unknown SAP object [${SAP_OBJECT}] passed to Create Link

Das documentYear wiederum ist entweder YEAR, falls vorhanden, oder das Jahr von DOC_DATE welches im Format DD.MM.YYYY oder YYYY-MM-DD angegeben werden muss, falls keines dieser Formate erfüllt wird, führt dies zu folgendem Fehler: Invalid date format [${DOC_DATE}]. Falls das dadurch entstandene documentYear nun kein String oder nicht exakt vier Zeichen hat wird das aktuelle Jahr als documentYear verwendet. Dies gilt im speziellen, wenn YEAR und DOC_DATE nicht angegeben wurden.

Beispiel 1

SAP_OBJECT = BKPF, RECIPIENT = 123, ERP_NUMBER = 123, YEAR = 2023 → OBJECT_ID = 1231232023

Beispiel 2

SAP_OBJECT = BKPF, RECIPIENT = 123, ERP_NUMBER = 123, YEAR = 2023, DOC_DATE = 04.06.2025" → OBJECT_ID = 1231232023

Beispiel 3

SAP_OBJECT = BKPF, ERP_NUMBER = 123, DOC_DATE = 04.06.2025" → OBJECT_ID = 1232025

Beispiel 4

SAP_OBJECT = BUS2081, ERP_NUMBER = 123, YEAR = 2023" → OBJECT_ID = 1232023

Beispiel 5

SAP_OBJECT = BUS2081, RECIPIENT = 123, ERP_NUMBER = 123, DOC_DATE = 04.06.2025" → OBJECT_ID = 1232025

Beispiel 5

OBJECT_ID = objectId, SAP_OBJECT = BUS2081, RECIPIENT = 123, ERP_NUMBER = 123, DOC_DATE = 04.06.2025" → OBJECT_ID = objectId

Mehrer Belagarten auf einem System

Wenn mehrere (unterschiedliche) Belegarten auf einem System verknüpft werden sollen, gibt es zwei Möglichkeiten dies umzusetzen:

• Mehrere createLink-Mappings, die für die jeweilige Belegart speziell konfiguriert sind (z.B. mapping-create-link-invoice.json und mapping-create-link-order.json)
• Eine neue Datenbanktabelle, die nur die für die Verknüpfung relevante Belegdaten enthält und für jede zu erzeugende Verknüpfung einen Eintrag enthält. Damit kann dann mit nur einem Mapping der CreateLink für unterschiedliche Belegarten erzeugt werden. Die Befüllung dieser Tabelle muss dann zwar auch Workflow-seitig zusätzlich umgesetzt werden, bietet aber den Vorteil, dass die Verknüpfung nachvollziehbarer wird.

Verwendung

Direkte Angabe von OBJECT_ID

• Mappingdatei: mapping-create-Individual-link.json
• DB-Tabellen:
  • createIndividualLink

sap-connector.exe "id=123456789" "create-Individual-link"

Ohne direkte Angabe von OBJECT_ID

• Mappingdatei: mapping-create-link.json
• DB-Tabellen:
  • invoiceheader
  • doctypes

sap-connector.exe "invoiceheaderdocumentid=123456789" "create-link"

Ausnahmen

Die generellen Aufrufkonventionen gelten auch hier mit einer kleinen Ausnahme. Es gibt für den häufigsten 'Fehler' beim Aufruf des create link einen besonderen Rückgabewert (-101), dieser bedeutet, dass die Verknüpfung in SAP nicht geschrieben werden konnte und damit sehr wahrscheinlich bereits besteht. Die callstate-Tabelle muss damit auch nicht mehr geprüft werden.

Achtung

Die Mappings sind nicht Update-sicher. Bei Anpassungen bitte ein neues Mapping erstellen.