Syntax: POST /rest/v1/record/<ormType>[?validateOnly=true]
Dieser Aufruf erstellt einen neuen Datensatz des angegebenen Typs.
Parameter
Name | Pflicht | Beschreibung |
---|---|---|
ormType | Ja | Guid oder technischer Name einer Datentabelle (vgl. Benamung von CSV-Importdateien). Beispiele für denselben Typen: OrmUserProfile oder 4B00F31C-E05D-42EF-9172-64608316C4C3 |
Mögliche Rückgabestatus
Status | Beschreibung |
---|---|
200 OK | Der Datensatz wurde erfolgreich validiert (betrifft nur Anfragen mit “validateOnly=true”). |
201 Created | Der Datensatz wurde wie gewünscht erstellt. Eine URI zum Abrufen des Datensatzes findet sich im Location -Header der Antwort. |
400 Bad request |
|
403 Forbidden | Der aktuelle Benutzer hat keine Berechtigung Datensätze des angegebenen Typs zu erstellen. |
500 Internal server error | Bei der Verarbeitung kam es zu einem unvorhergesehenen Fehler. |
Rückgabe
Nach erfolgreicher Erstellung des Datensatzes liefert die Anfrage ein JSON-Objekt zurück, welches in den Eigenschaften Oid
die Oid des neuen Datensatzes und in OrmType
den Datentypen beinhaltet. Sollten nach erfolgter Erstellung des Datensatzes nachgelagert Fehler aufgetreten sein, enthält die Eigenschaft Errors
eine Liste mit entsprechenden Standardfehlerdatensätzen. In diesem Fall sollten Oid
und OrmType
nicht verwendet werden, da sie ungülte Werte enthalten könnten.
Beispiel bei erfolgreicher Erstellung:
{
"Oid": "066b3156-8a49-4439-8850-10f038dcf75b",
"OrmType": "fe7eb8ae-71be-4220-8da5-dc04078e6b3c",
"Errors": []
}
Diese Methode kann ausßerdem dazu verwendet werden, um zu prüfen, ob anhand der gegebenen Daten ein neuer Datensatz erstellt werden könnte. Um diesen Mechanismus zu aktivieren, muss der Parameter validateOnly=true
zum Query-Teil der URL hinzugefügt werden. Die Methode durchläuft dann alle Phasen der Erstellung inklusive der Validierung, speichert den Datensatz am Ende aber nicht.
Beispiel bei erfolgreicher Validierung:
{
"Validation": "PASS",
"OrmType": "fe7eb8ae-71be-4220-8da5-dc04078e6b3c",
"Errors": []
}
Besonderheiten bezüglich des Anfrageinhalts
Standardfelder (Text, Zahlen, Boolean)
Diese Felder werden als einfache Zuordnung des entsprechenden Werts übergeben. Für Felder des Typs Boolean
können entweder true
oder false
oder aber auch 0 oder 1 verwendet werden.
Beispiele:
"searchnames": "Meine Firma"
"CreditBlocking": true
oder "CreditBlocking": 1
Datumswerte
Datumswerte müssen in JavaScript-konformem Format (ISO 8601) übergeben werden.
Beispiel:
"EndDate": "2022-08-02T09:44:30.5715234+02:00"
Wenn das Dautmsfeld Wiederholungen erlaubt, ist es möglich (aber nicht zwingend notwendig) diese Wiederholungsinformationen in einem JSON-Objekt zusammen mit dem zu setzenden Datumswert zu übergeben. Der Datumswert muss dann in der Eigenschaft Value
und die Wiederholungsinformation in der Eigenschaft RecurrenceInfo
stehen. Der von der GET-Methode zurückgegebene zusätzliche Wert RecurrenceType
kann nicht gesetzt werden; er wird automatisch auf 0
oder@1@ gesetzt, je nachdem ob Wiederholungsinformationen vorhanden sind oder nicht.
Beispiel:
"RepeatDate": {
"Value": "2022-08-02T09:44:30.5715234+02:00",
"RecurrenceInfo": "(gültiges XML)"
}
Quellrelationsdefinitionen
Diese Daten können als Einzelwert oder als Liste von Oids oder MigrationIds verknüpfter Datensätze übergeben werden. Es sind die möglichen Datenquellen aus typeinfo
zu beachten!
Beispiel:
"RelatedCustom_ParentCompany": "596063d0-c741-4d32-820a-72c6f63ed94f"
Dateianhangsfelder
Die Inline-erstellung von Dateianhängen wird unterstützt aber aufgrund der Komplexität nicht empfohlen. Beim Setzen von Dateianhängen müssen die Eigenschaften FileName
als Dateiname und Data
angegeben werden, die Eigenschaften IsInline
, Subject
und ContentID
sind optional (ist IsInline
true
so ist ContentID
Plicht). Die Daten müssen derweil als BASE64 codierter String in der Data
-Eigenschaft übergeben werden.
Die Inline-Erstellung hat den Vorteil, dass sie die gleichzeitige Erstellung mehrer Dateianhänge unterstützt.
Beispiel:
"DefaultAttachments": [
{
"FileName": "Konzept.docx",
"Subject": "Das ist ein Konzept!",
"Data" : "..."
}
]
HTML-Felder
Es gibt verschiedene Arten, auf die HTML-Felder und zugehörige Bilddateien im System abgelegt werden können. Ein Bild gehört hierbei immer zu einem bestimmten HTML-Feld und kann nicht zwischen verschiedenen Feldern geteilt werden.
1. HTML-Daten ohne Bild
Enthalt das HTML keine eingebetteten Bilder, so kann das Feld wie ein ganz normales Textfeld beschrieben werden.
2. HTML-Daten mit eingebettetem BASE64-Bild
Eingebettete Bilder mit inline-base64-Daten im src-Tag werden beim Speichern in das systemübliche Format mit Nutzung einer Content-ID und Ablage eines richtigen inline-Image-Dateianhangs umgewandelt.
3. Temporäre Dateianhänge
Bilder können transaktionslos als temporäre Dateianhänge hochgeladen und bei einer anderen Anfrage an die REST-Schnittstelle in dem entsprechenden HTML-Feld verwendet werden. Dieses Vorgehen entspricht dem Erstellen eines Dateianhangs. Hierbei ist zu beachten, dass der verwendete Feldname bei der Erstelliung des Dateianhangs der Name des HTML-Feldes sein muss und dass die Content-ID in diesem Fall obligatorisch ist. Ob zuerst der Anhang hochgeladen wird und anschließend der Inhalt des HTML-Feldes geändert wird oder umgekehrt, ist egal; die Zuordnung zwischen Bild und HTML erfolgt beim Speichern des Datensatzes automatisch. Aufgrund der durchbrochenen Transaktion in diesem Fall, wird dieses Vorgehen nicht empfohlen.
4. Objektstruktur
Das HTML-Feld kann mit einer ähnlichen Struktur beschrieben werden wie die, mit der es abgerufen wird. Hierbei müssen die Daten der Bilddatei als BASE64-Text übergeben werden.
Beispiel:
"Description": {
"Value": "My <b>content</b> with inline. <img src=cid:inline_content_id@local>",
"InlineImages": [
{
"FileName": "Irrelevant_Inline_Filename.png",
"ContentId": "inline_content_id@local",
"Data": "xxBASE64xx=="
}
]
}
Auswahlistenwerte
Auswahllistenwerte können sowohl anhand ihrer Guid als auch anhand einer vollständigen Übersetzung identifiziert und ebenfalls auf verschiedene Arten übergeben werden. Sowohl Guids als auch Übersetzungen können sowohl als einzelner String-Wert kommagetrennt als auch als Liste einzelner Werte übergeben werden. Des Weiteren können bei Auswahllisten, welche dies unterstützen, auch neue Werte erstellt werden. In diesem Fall wird entweder, bei Angabe eines einzelnen Strings, der übergebene Text als Übersetzung aller konfigurierter Sprachen verwendet, es ist aber auch möglich, alle Übersetzungen in einem Objekt anzugeben. BItte beachten Sie, dass Sie bei Verwendung der zuletzt genannten Methodik alle Übersetzungen angeben müssen, um den Auswahllistenwert zu erstellen. Wenn Sie möchten, dass eine ganz bestimmte Guid für den neuen Auswahllistenwert verwendet wird, so können Sie diese in der Oid
-Eigenschaft angeben, es wird dann geprüft, ob diese Guid verwendet werden kann. Es ist bei der Übergabe als Objekt ebenfalls möglich, zusätzliche Eigenschaften von Auswahllistenwerten bei deren Erstellung zu belegen.
Beispiele:
Hier wird ein neuer Kommunikationsstatus erzeugt, der in allen Übersetzungen den Text “Ich will das nicht.” eingetragen bekommt.
"CommunicationStatus" : "Ich will das nicht."
Der existierende Kommunikationsstatus wird anhand seiner Übersetzung erkannt und verwendet, es wird kein neuer Eintag erstellt.
"CommunicationStatus" : "Keine Werbung"
Sollte ein Kommunikationstatus mit dieser Guid existieren, so wird er verwendet, wenn nicht, wird er ignoriert (es wird aktuell nicht unterstützt neue Auswhallistenwerte mit einer Guid als Übersetzung zu erstellen!).
"CommunicationStatus" : "596063d0-c741-4d32-820a-72c6f63ed94f"
Es ist möglich, mehrere Auswahllistenwerte durch Komma getrennt in einer Zeile anzugeben, die Suche nach einer Übersetzung ignoriert übrigens Groß-/Kleinschreibung.
"CommunicationStatus" : "596063d0-c741-4d32-820a-72c6f63ed94f,Keine werBUNG"
Das vorige Beispiel kann auch als Liste übergeben werden.
"CommunicationStatus" : [ "596063d0-c741-4d32-820a-72c6f63ed94f", "Keine werBUNG" ]
Das folgende ist eins der komplizierteren Beispiele:
Für ein Feld namens “Country” mit der potenziell verknüpften Auswahlliste EnumCountries
wird ein neuer Auswahllistenwert erstellt. Der Auswahllistenwert hat eine Wunsch-Oid, kann diese nicht gesetzt werden, wird ein entsprechender Fehler zurückgegeben. Die Oid
-Eigenschaft ist kein Pflichtfeld. Im System sind die Sprachen Deutsch und Englisch konfiguriert, für alle Sprachen muss eine eindeutige Übersetzung angegeben werden; es ist nicht möglich, einen neuen Auswahllistenwert mit in dieser Auswahlliste bereits verwendeten Übersetzungen zu erstellen! Weiterhin werden zwei zusätzliche Eigenschaften des Auswahllistenwertes belegt.
"Country" : {
"Oid" : "596063d0-c741-4d32-820a-72c6f63ed94f",
"Language_de" : "Mein Land",
"Language_en" : "My country",
"ISOCode" : "MCO",
"FormatLetterClosing" : "Wiedersehen!"
}
Teildatentabellen
Teildatensätze werden als Liste mit Objekten mit den entsprechenden Eigenschaften der Teildatentabelle erstellt.
Beispiel:
"Addresses": [
{
"Address": "Chemnitzer Straße 98",
"AddressType": "Hauptanschrift",
"City": "Dortmund",
"Country": "bac53e30-797b-4ba0-802b-b4bc7700d590",
"PostalCode": "44139"
}
]