Der SDK-Helper

Der SDK-Helper ist die zentrale Schnittstelle zwischen C#-Skripten und der Syncler-Anwendung.
Er ermöglicht den Datenaustausch (Quell-/Ziel-/Kontextdaten), steuert Sync-Parameter, liefert Hilfsfunktionen (z. B. Logging, HTTP-Aufrufe, Parameterverwaltung) und stellt Modelle (z. B. Datensatz-Abbildungen) bereit.

Geltungsbereich: Alle Eigenschaften und Methoden des Helpers beziehen sich immer auf den aktuellen Account/Mandanten.

Syncler stellt zusätzlich ausgewählte .NET-APIs und Newtonsoft.Json (z. B. JObject, JArray, JToken) bereit, um JSON-Daten komfortabel zu lesen und zu erzeugen.

Lebenszyklus & Einsatz

1. Skriptstart: Der Helper wird dem Skript beim Start als Objekt Helper übergeben.
2. Kontextzugriff: Skripte lesen/setzen Sync-Parameter (z. B. Filter, Konflikt-/Fehlerverhalten) und greifen auf Quell-/Zieldaten zu.
3. Operationen: Daten lesen/schreiben, Mappings abfragen/aktualisieren, Protokolle schreiben, HTTP/Service-Aufrufe durchführen, Warteschlangen-Einträge anlegen u. v. m.
4. Rückgabe: Modifizierte Daten/Ergebnisse werden an den Workflow (Transformation, Sync, SDK-Konnektor) zurückgegeben.

Eigenschaften

Einige Eigenschaften wirken steuernd auf SDK-Syncs (werden vom Sync ausgewertet).
JSON-Typen: JObject, JArray (Newtonsoft.Json).

Methoden

Ausführung steuern

• Helper.Cancel()
  Fordert den Abbruch der aktuellen Ausführung an (SDK-Syncs werten dies aus).
• Helper.SkipLoad()
  Überspringt den Lese-Schritt (Quelle) in SDK-Syncs.

Parameter lesen/schreiben

• Helper.GetParam(string name) : string
  Liefert den Parameterwert (oder "" wenn nicht vorhanden).
• Helper.GetParam<T>(string name, T defaultValue = default) : T
  Liefert typisiert; bei Nichtvorhandensein defaultValue.
• Helper.GetParamOrNull<T>(string name) : T
  Liefert typisiert oder null (für explizit nullable, z. B. DateTime?).
• Helper.SetParam<T>(string name, T value)
  Legt/aktualisiert einen Parameter.

Feldnotation & Parsing

• Helper.FieldStringToColumnObject(string fieldString) : JObject
  Wandelt eine Feldnotation (z. B. aus Filtern) in ein JObject mit adressierbaren Eigenschaften um.

Datensatz-Abbildungen (Mappings)

• Helper.GetDataMappingBySourceId(int processId, string sourceId) : SisDataMapping
• Helper.GetDataMappingByTargetId(int processId, string targetId) : SisDataMapping
• Helper.GetDataMappingComplementaryBySourceId(int processId, string sourceId, string targetObject = null) : List<SisDataMapping>

  Komplementäre Mappings entgegengesetzter Syncs (für Konfliktmanagement/Zielerkennung).

• Helper.GetDataMappingParallelByTargetId(int processId, string targetId) : List<SisDataMapping>

  Parallele Mappings gleicher Richtung (Ziel-Änderungsinformation muss häufig mitgezogen werden).

• Helper.SaveDataMapping(SisDataMapping mapping) : SisDataMapping
  Legt eine neue oder aktualisiert eine bestehende Datensatz-Abbildung.
• Helper.IncreaseOwnDataMapping(SisDataMapping mapping, object newUpdatedInfoA, object newUpdatedInfoB, bool onlyA = false, bool onlyB = false)
  Aktualisiert Änderungsinformationen (Quelle/Ziel) für das eigene Mapping (Konfliktauflösung).
• Helper.IncreaseComplementaryMappings(string currentSourceId, string currentTargetId, object newUpdatedInfoA, object newUpdatedInfoB, bool onlyA = false, bool onlyB = false)
  Sucht/aktualisiert komplementäre Mappings (teilweise Aktualisierung möglich).
• Helper.IncreaseParallelMappings(string currentSourceId, string currentTargetId, object newUpdatedInfoA, object newUpdatedInfoB, bool onlyA = false, bool onlyB = false)
  Sucht/aktualisiert parallele Mappings (Konfliktpfade entschärfen).

Sync-Informationen

• Helper.GetProcessInfoList(int? sourceConnectionId = null, int? targetConnectionId = null) : List<SisProcessInfo>
  Liefert Infos zu Syncs des Accounts (optional gefiltert nach Systemen).
• Helper.GetProcessInfoComplementary(int processId) : List<SisProcessInfo>
  Komplementäre Syncs des angegebenen Syncs.
• Helper.GetProcessInfoParallel(int processId) : List<SisProcessInfo>
  Parallele Syncs des angegebenen Syncs.

Protokoll & Nachrichten

• Helper.InsertLog(SisLog log)
• Helper.InsertLog(string message, int level)
  Speichert Protokolleinträge (in der Account-Datenbank). Level:
  0=Message, 1=Error, 2=Warning, 3=Info/Notice, 4=Feedback, 5=Debug.
• Helper.InsertMessage(string message, int level)
  Schreibt Broadcast-Nachrichten (UI-Ticker, nicht dauerhaft).

HTTP & Service-Aufrufe

• Helper.InvokeUrl(string url, string method, JObject header, string data, bool base64 = false) : string
  Führt einen HTTP-Request aus; Header als JObject (Eigenschaft=Headername).
  Bei base64=true wird der Antwort-Body Base64-kodiert zurückgegeben.
• Helper.ServiceCall(string method, string url, string data) : string
  Ruft die Syncler-API auf (als url nur den Endpunkt übergeben).

Parameterverwaltung (persistente interne Parameter)

• Helper.GetParameterList(string name, string connectionId = null, string processId = null) : List<SisParam>
  Liest Parameterlisten (optional nach System/Sync einschränken).
• Helper.SaveParameter(SisParam parameter, string connectionId = null, string processId = null)
  Speichert/aktualisiert einen Parameter.
• Helper.DeleteParameter(int parameterId)
  Löscht einen Parameter.

Datenzugriff über Konnektoren

• Helper.InvokeGetData(string connectionId, string targetObject, List<SisParam> getParams) : JArray
  Ruft Daten aus einem System ab (Schema = targetObject).
  Übliche Parameter-Namen (abhängig vom System/Konnektor):
  GETDATA_ID, GETDATA_RELATED_ID, GETDATA_RELATED, GETDATA_WHERE, GETDATA_MODIFIED, GETDATA_ORDER, LAST_SYNC_DATE, LAST_SYNC_VERSION.
• Helper.InvokeSetData(string connectionId, string targetObject, JObject jsonObject) : JObject
  Schreibt Daten via System/Konnektor (Schema = targetObject).
  Zusatzoptionen (z. B. DELETE) können im jsonObject["Params"] gesetzt werden.

Warteschlange (Aktionen)

• Helper.InsertAction(int processId, DateTime executeDate, bool isAdhoc, List<SisParam> actionParams)
  Legt einen Warteschlangen-Eintrag für einen Sync an.

Konvertierungen

• Helper.ToDouble(object value) : double
  Kulturunabhängige Zahlkonvertierung nach double.

Datenmodelle

SisParam

• Name : string – Parametername
• Value : object – Wert
• ID : int – interne ID (wird beim Speichern vergeben)

Hilfsmethoden:

• GetValue() : string – Wert als String
• GetValue<T>(T defaultValue) – typisierter Wert oder Default
• GetValueOrNull<T>() : T – typisierter Wert oder null
• HasValue() : bool – Wert vorhanden?

SisDataMapping (Datensatz-Abbildung)

• ID : int – interne DB-ID
• ProcessId : int – zugehöriger Sync
• Description : string – Beschreibung
• SourceRecordId : string – Quell-ID
• TargetRecordId : string – Ziel-ID
• LastSyncDate : DateTime – letztes Sync-Datum
• TargetIsDeleted : bool – Ziel wurde gelöscht
• LastSyncInfo : List<SisParam> – Änderungs-/Zusatzinformationen

SisProcessInfo (Syncbeschreibung)

• ID : int, Name : string, DisplayName : string
• SourceObject : string, TargetObject : string
• SourceConnectionId : int, TargetConnectionId : int
• ClientNumber : int – Mandantennummer
• IsScheduled : bool – Zeitsteuerung aktiv
• SourceType : string, TargetType : string, ProcessType : string

SisLog (Protokoll)

• CreatedDate : DateTime – Erstelldatum
• Level : int – 0..5 (Message/Error/Warning/Info/Feedback/Debug)
• ProcessId : int – zugehöriger Sync
• ActionId : int – zugehöriger Queue-Eintrag
• RecordType : string – Datensatztyp
• RecordId : string – Datensatz-ID
• LogMessage : string – Meldung

Best Practices

• Deterministisch & kompakt: Skripte kurz halten, keine teuren I/O-Operationen; komplexe Flows mit Standard-Transformationen/Syncs lösen.
• Logging sparsam & hilfreich: Klarer Kontext, keine sensitiven Daten protokollieren; Level sinnvoll wählen.
• JSON robust handhaben: Null-Checks, Typprüfungen, ISO-Zeitformate (UTC) verwenden.
• Paging nutzen: Helper.Page für große Datenmengen berücksichtigen (wenn der ausführende Schritt dies unterstützt).