Erstellen einer JSON Datei

Inhaltstypen werden mithilfe einer JSON-Datei definiert. Dieser Leitfaden zeigt Ihnen, wie Sie einen Inhaltstyp mithilfe eines JSON-Dokuments definieren.

Vorbereitungen

• Um einen Inhaltstypen erstellen zu können, benötigen Sie einen Texteditor - idealerweise mit Strukturierungsfunktionen für das .json-Format wie VS Code, Sublime Text oder Notepad++
• Um den Inhaltstyp in eine Arbeitsmappe zu integrieren, benötigen Sie den iCL Designer.
• Um den Inhaltstyp auf die iCL Portal Website hochzuladen, benötigen Sie ein Konto mit Administratorrechten.

JSON-Grundlagen

Sie können eine leere Textdatei beginnen und ihren Datentyp als .json speichern oder eine bestehende Datei bearbeiten und als neue .json-Datei speichern.

Das JSON-Format wird verwendet, um die Felder und Funktionen zu definieren, die ein Inhaltstyp hat. Jedes Mal, wenn Sie ein neues Element dieses Inhaltstyps hinzufügen, wird es als eine Zeile in einer Datentabelle gespeichert, wobei jedes Feld eine Spalte dieser Tabelle ist.

Eine JSON-Datei für Inhaltstypen definiert mehrere Eigenschaften, von denen einige optional sind, je nach Verwendungszweck oder Komplexität. In den folgenden Abschnitten werden die Struktur und die Optionen der Reihe nach erläutert.

JSON-Struktur

Jeder Inhaltstyp erfordert zumindest einige grundlegende Parameter.

Einige von ihnen sind optional und werden nach dem Hochladen in das iCL Portal automatisch mit einem Standardwert hinzugefügt, wie z.B. "icon", "version", "builtinTypeId" und "formTemplate".

Hier sehen Sie ein einfaches Beispiel für einen einfachen Inhaltstyp mit zwei Text- und einem Zahlenfeld.

{
    "$type": "contentType",
    "name": "ct_objects",
    "displayName": "Content Type Name",
    "titleFieldName": "obj_nr",
    "titleFieldExpression": "<%obj_nr%> - <%obj_address%>"
    "id": "73ee4c51-d99a-4596-9533-2bea4e0c65c5",
    "builtinTypeId": 0,
    "icon": "",
    "version": 1,
    "fields": [
        {
            "$type": "contentType",
            "name": "obj_nr",
            "displayName": "Object Number",
            "isRequired": true
        },      
        {
            "$type": "contentType",
            "name": "obj_address",
            "displayName": "Object Address",
        },      
        {
            "$type": "contentType",
            "type": "Number",
            "name": "obj_floors",
            "displayName": "Object Floors",
        }
    ],
    "relationships": [],
    "formTemplate": {}
}

JSON-Abschnitte

Es gibt verschiedene Abschnitte innerhalb des Inhaltstyps, einige davon sind optional oder werden automatisch generiert.

In der Klammer Felder werden alle vorhandenen Felder des Inhaltstyps definiert. (z.B. Name, Adresse, Preis, Seriennummer oder was immer Sie als speicherbaren Wert benötigen)

Manchmal ist ein Inhaltstyp mit einem anderen verwandt. Zum Beispiel könnte ein Inhaltstyp Aufzug zu einem Gebäude gehören. Diese Beziehungen werden in den Klammern Relations definiert.

Das formTemplate definiert das Formular, das dem Benutzer angezeigt wird, wenn er Elemente dieses Typs hinzufügt oder bearbeitet. Wenn Sie es weglassen, wird beim Hochladen des Inhaltstyps in das iCL Portal automatisch eine Grundvorlage generiert. Manchmal werden Sie die Vorlage jedoch ändern wollen. Wenn zum Beispiel für ein bestimmtes Feld eine Dropdown-Auswahl erforderlich ist, können Sie diese hier definieren.

Hinweis

Wenn Sie das formTemplate anpassen, müssen Sie nicht alle Felder definieren. Definieren Sie nur das eine Feld, das Sie ändern möchten. Wenn Sie die json-Datei mit dem unvollständigen formTemplate in das iCL Portal hochladen, wird es das bemerken und die fehlenden Felder für Sie ergänzen.

Erforderliche JSON-Attribute

Diese Attribute sind zwingend erforderlich, damit der Inhaltstyp funktioniert.

Eigenschaft	Parameter	Beschreibung
"$type":	"contentType"	Eine Eigenschaft, um den json als Inhaltstyp zu definieren.
"name":	"name_des_ct"	Der eindeutige Name des Inhaltstyps für die Datenbank - nur Kleinbuchstaben, keine Leerzeichen erlaubt (verwenden Sie stattdessen _).
"displayName":	"Content Type Example"	Der angezeigte Name des Inhaltstyps im iCL Portal - Großbuchstaben und Leerzeichen erlaubt.
"id":	"12345678-90ab-cdef-1234-567890abcdef"	Die eindeutige Kennung GUID (ein 32-stelliger Code) für den Inhaltstyp. Er kann im iCL Portal nicht zweimal vorkommen, muss also für jeden verwendeten Inhaltstyp eindeutig sein.
"titleFieldName":	"most_unique_field"	Wenn ein Inhaltstyp alle seine Datensätze (die sogenannten Inhaltselemente) auflistet, definiert der titleFieldName den für den Datensatz angezeigten Titel. Er verwendet den Name eines Feldes, das im Abschnitt "fields": [] definiert ist, und das referenzierte Feld muss auf "erforderlich" gesetzt werden.
"fields":	[]	In den Feldklammern werden alle Felder für den Inhaltstyp definiert. Der Inhaltstyp muss mindestens ein erforderliches Textfeld haben, das mit dem Parameter titleFieldName verbunden ist.

Hinweis

Das Titelfeld ist wichtig: Wann immer Sie ein Dropdown-Feld zur Auswahl eines Inhaltselements verwenden, muss das iCL-System dieses Dropdown-Feld mit einem aussagekräftigen Text füllen, der es dem Benutzer ermöglicht, ein bestimmtes Element zu identifizieren. Hierfür wird der titleFieldName verwendet, der mit einem Textfeld verbunden ist, das required sein muss. Ein weiteres Beispiel ist, wenn ein verwandtes Inhaltselement in einer Datentabelle angezeigt werden soll. Ein Aufzug verweist beispielsweise auf sein Gebäude, so dass die Datentabelle des Aufzugs etwas in der Spalte "Gebäude" anzeigen muss. Dies ist ein weiterer Anwendungsfall für das titleField

Indizierung von Feldern zur Unterstützung von Sortierung und Filterung

Für jedes Feld eines Inhaltstyps wird eine Datenbankspalte erstellt. Standardmäßig ist diese Spalte nicht indiziert. Wenn Sie in der Lage sein wollen, nach einem Feld zu sortieren und zu filtern, müssen Sie die Eigenschaft "isIndexed" auf "true" setzen. Dadurch wird ein Index für diese Spalte in der Datenbank erstellt, der eine schnellere Sortierung und Filterung ermöglicht. Verwenden Sie dies jedoch nur bei Bedarf, da zu viele Indizes dazu führen können, dass die Bearbeitung/Aktualisierung von Elementen sehr langsam wird.

Ohne Index:

Mit Index:

Dieses Verhalten kann mit der folgenden Einstellung deaktiviert werden

Optionale Inhaltstyp-Eigenschaften

Diese Eigenschaften erhalten einen Standardwert, wenn sie nicht verwendet werden, oder werden einfach ignoriert.

Eigenschaft	Parameter	Beschreibung
"titleFieldExpression":	"ObjNr.: <%Objektnummer%> <%Feldname%>"	Um eine detailliertere Liste von Einträgen zu erhalten, können Sie den Titel des Inhaltselements hier erweitern, indem Sie eine komplexere Kombination aus Text und Feldern erstellen.
"builtinTypeId":	0 oder 6	Diese Eigenschaft legt den Typ des Inhaltstyps fest. 0 ist der Standardwert und verleiht ihm die Eigenschaft "isInspectable". Mit einem Wert von 6 wird er als Defekt-Inhaltstyp definiert, der einen Verweis auf einen übergeordneten Inhaltstyp mit der builtinTypeId 0 benötigt.
"icon":	""	Reserviert für zukünftige Verwendung - bitte leer lassen.
"version":	1	Reserviert für zukünftige Verwendung - bitte leer lassen.
"relationships":	[]	Definieren Sie hier Beziehungen zu anderen Inhaltstypen. Wenn kein Bezug zu einem anderen Inhaltstyp benötigt wird, kann dies weggelassen werden.
"formTemplate":	{}	Wenn kein spezielles Dropdown-Feld für das iCL-Portal benötigt wird, kann dies weggelassen werden.

Felder

Innerhalb der Klammern für die Felder werden alle Felder des Inhaltstyps definiert. Wenn nicht anders angegeben, ist ein Feld ein einfaches Textfeld und kann wie folgt aussehen:

{
    "$type": "contentField",
    "name": "building_address",
    "displayName": "Building Address"
}

Feldeigenschaften

Die folgenden Eigenschaften definieren ein Inhaltsfeld:

Eigenschaft	Parameter	Pflicht	Beschreibung
"$type":	"contentField"	x	Der $type ist immer "contentField".
"name":	"Kleinschreibung_und_Unterstrich"	x	Der Name muss eindeutig sein und aus Kleinbuchstaben bestehen. Verwenden Sie _ anstelle von Leerzeichen.
"displayName":	"Dies ist mein Titel"	x	Der displayName wird als Titel des Eintrags verwendet. Großbuchstaben und Leerzeichen sind erlaubt.
"type":	"Text"	Der Typ (ohne $) definiert den Datentyp des Feldes. Wenn er nicht verwendet wird, wird er standardmäßig als Textfeld festgelegt. Andere Parameter sind die folgenden:
	"Number"		Wandelt das Feld in ein Zahlenfeld um.
	"Date"	Ein Datumsformat zum Speichern von Datumswerten (einschließlich der Uhrzeit.)
	"Time"	Ein Format zum Speichern von Uhrzeiten (Stunden:Minuten)
	"ContentItem"	Das Feld kann eine Referenz auf einen anderen Inhaltstyp speichern.
	"FileEntry"	Felder für Dateieinträge können Bilder speichern.
	"Plan"
"isRequired":	true oder false		Standardmäßig müssen Felder keinen Wert haben - Sie müssen dies also nur einstellen, wenn das Feld obligatorisch sein soll.
"isIndexed":	true oder false	Der Standardwert ist auf false gesetzt. Wenn er auf true gesetzt ist, können Benutzer diese Felder - z.B. in der Datentabelle - filtern und sortieren lassen. Verwenden Sie dies jedoch sparsam, da zu viele Indizes dazu führen können, dass die Bearbeitung/Aktualisierung von Elementen sehr langsam wird.
"builtInField":	"ParentContentItemId"		Ein Inhaltstyp mit der "builtinTypeId": 6" erfordert die Definition eines "übergeordneten" Inhaltstyps. Der übergeordnete Inhaltstyp ist derjenige, zu dem der Defekt gehört. Er wird in einem Inhaltsfeld vom Typ ContentItem gespeichert und muss diese Eigenschaft angeben.
	Ein Feld mit diesem Parameter wird als Referenzfeld betrachtet, in dem jeder Eintrag eindeutig sein muss.
	Das iCL System behandelt defekte Inhaltstypen auf eine besondere Weise: In bestimmten Bildschirmen können Sie sie nach ihrem Status sortieren und filtern. Damit dies funktioniert, müssen Sie jedoch ein Inhaltsfeld vom Typ "Number" - das den Status des Defekts repräsentiert - dem builtInField: "Status" zuordnen.

Beziehungen

Beziehungen sind Verbindungen zu anderen Inhaltstypen. Der übergeordnete Inhaltstyp muss "builtinTypeId" haben: 0.

Jeder Inhaltstyp mit einer "builtinTypeId": 6 benötigt einen Verweis auf seinen 'übergeordneten' Inhaltstyp, der auf zwei Arten hergestellt wird: ein Feld des "type": "contentItem" und ein "relationships": {}, der einen Verweis auf das Feld für den Inhaltstyp erstellt.

Referenzfeld

Wenn Sie im Bereich Beziehungen eine Beziehung zu einem anderen Inhaltstyp herstellen, benötigen Sie auch ein Feld mit der "type": "ContentItem", um die Referenz zu speichern.

Tipp

Verwenden Sie einen Namen und einen Titel für dieses Feld, der deutlich macht, dass es sich um eine Referenz handelt. Zum Beispiel "obj_id" als Name für eine gespeicherte Referenz-ID eines Inhaltstyps namens "Objekt". Das Suffix _id hilft bei der Identifizierung solcher Referenzfelder, wenn Sie sich an diesen Standard halten.

Die Felddefinition kann wie folgt aussehen:

{
    "$type": "contentField",
    "type": "ContentItem",
    "name": "obj_id",
    "displayName": "Object ID"
}

Wenn der aktuelle Inhaltstyp ein Defekttyp ("builtinTypeId": 6) ist, benötigen Sie zusätzlich die Eigenschaft "builtinField": "ParentContentItemId" Eigenschaft für dieses Feld:

{
    "$type": "contentField",
    "type": "ContentItem",
    "name": "obj_id",
    "displayName": "Object ID"
    "builtinField": "ParentContentItemId"
}

Sie können diesen Parameter builtinField nur in einem ContentItem-Feld setzen.

Abschnitt "Relationships"

Alle Beziehungen zu anderen Inhaltstypen werden im Abschnitt Beziehungen definiert, der wiefolgt aufgebaut ist:

"relationships": [
    {
        "$type": "contentRelationship",
        "name": "obj_ref",
        "displayName": "Object Ref",
        "foreignKeyField": "obj_id",
        "targetContentType": {
            "$type": "contentTypeRef",
            "id": "21429549-7b35-4cb1-bd6a-ac4f5ea9fbb8",
            "version": 1
        }
    }
]

Ein Verweis muss mit einem Name und DisplayName definiert werden, wie jeder andere Teil der Definition des Inhaltstyps.

Außerdem muss er auf ein Feld des Typs "ContentItem" im Abschnitt ""fields"" verweisenund zusätzlich muss er die eindeutige ID (Guid) des Inhaltstyps kennen, auf den diese Referenz verweist. Sie finden die GUID im Parameter "id": dieser anderen JSON-Datei.

Eigenschaft	Parameter	Beschreibung
$type":``"contentRelationship":	Dies ändert sich nie.
"name"	"obj_ref"	Der Name dieses Beziehungsobjekts. Bewährte Praxis: Verwenden Sie den Namen des Feldes, in dem der Inhaltstyp gespeichert wird, und hängen Sie ein _ref daran.
"displayName"	"Object Ref"	Der Titel dieser Beziehung - da er nirgends angezeigt wird, spielt er keine große Rolle.
"foreinKeyField"	"obj_id"	Der Name des Feldes, in dem die Referenz gespeichert werden soll (es hat die Eigenschaft "type": "ContentItem").
"targetContentType": {}	$type: "contentTypeRef"	Dies ändert sich nie.
	"id:" "12345678-abcd-4321-9876543210ab"	Die GUID des Inhaltstyps, auf den die Referenz zeigt.
	version: 1	Dies ändert sich nie.

Sie können mehr als einen Verweis hinzufügen, indem Sie einen neuen {} Abschnitt innerhalb der ""relationships": [] einen neuen Abschnitt eröffnen, der durch ein Komma getrennt ist:

"relationships": [
    {
        "$type": "contentRelationship",
        "name": "obj_ref",
        "displayName": "Object Ref",
        "foreignKeyField": "obj_id",
        "targetContentType": {
            "$type": "contentTypeRef",
            "id": "12345678-abcd-4321-9876543210ab",
            "version": 1
        }
    },
    {
        "$type": "contentRelationship",
        "name": "items_ref",
        "displayName": "Items Ref",
        "foreignKeyField": "items_id",
        "targetContentType": {
            "$type": "contentTypeRef",
            "id": "87654321-dcba-4321-ba0123456789",
            "version": 1
        }
    }
]