Zum Hauptinhalt springen

Inhaltstypen

Mit iCL können Sie schnell leistungsstarke Checklisten erstellen, um Informationen über verschiedene Dinge zu sammeln. In vielen Fällen werden Sie diese "Dinge" als separate Daten verfolgen wollen. Bei Gebäudeinspektionen ist es zum Beispiel ratsam, alle Daten eines Gebäudes in einer separaten Tabelle zu speichern. Dann können Sie bei jeder Inspektion dieses Gebäudes die Daten verwenden, um Teile Ihrer Checklisten vorab auszufüllen.

Gebäude, Feuerlöschgeräte, Aufzugstypen, Kundeninformationen, ... in iCL können diese mit Inhaltstypen modelliert werden. Ein Inhaltstyp definiert

  • die Felder, die er speichert (Name, Adresse, Baujahr des Gebäudes, ...)
  • die Beziehungen zu anderen Inhaltstypen (z.B. ein Aufzug gehört zu einem Gebäude)
  • das Formular zur Bearbeitung seiner Daten
  • erweiterte Regeln für die Synchronisierung der Daten und mehr.
Technischer Leitfaden für Inhaltstypen

Um die Struktur und den Inhalt einer Inhaltstyp-Definition zu verstehen, lesen Sie bitte den Leitfaden zu Inhaltstypen

Mit dieser API können Sie Inhaltstypen erstellen, aktualisieren und löschen.

Jeder Endpunkt erfordert eine Berechtigung, die im jeweiligen Abschnitt angegeben ist. Fehlt sie dem aufrufenden Benutzer, antwortet die API mit 403 Forbidden (401 Unauthorized, wenn die Anfrage gar nicht authentifiziert ist). Ungültige Anfragen und Inhaltstyp-Definitionen werden mit 400 Bad Request und einer Fehlermeldung abgelehnt.

1. Abfrage von Inhaltstypen​

Ruft alle Inhaltstypen ab, die derzeit definiert sind.

Erforderliche Berechtigung: ContentTypes.List

Beispiel:

GET https://dev.iclportal.com/api/contenttypes?$inlinecount=allpages&$top=20 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept-Encoding: gzip, deflate
Authorization: Bearer ..the auth_token...

Die Antwort ist ein JSON-Objekt. result.results enthält die Inhaltstypen, result.__count die Gesamtzahl der Inhaltstypen:

{
    "result": {
        "results": [
            {
                "contentTypeId": "31d1d26b-1475-477e-ab21-13d8fd2dc7ea",
                "name": "building",
                "canBeInspected": false,
                "builtInTypeId": 0,
                "filteredSynchronization": false,
                "syncConflictResolution": 0,
                "creationTime": "2021-06-17T08:27:01.22Z",
                "lastModificationTime": "2021-06-17T13:15:40.58Z"
            },
            ...
        ],
        "__count": 117
    },
    "targetUrl": null,
    "success": true,
    "error": null,
    "unAuthorizedRequest": false,
    "__abp": true
}

Pro Anfrage werden höchstens 50 Inhaltstypen zurückgegeben. Gibt es mehr, enthält result.__next die relative URL (Pfad und Query-String) der nächsten Seite.

2. Abrufen einer Inhaltstypen-Definition​

Ermöglicht das Abrufen der vollständigen Definition eines Inhaltstyps.

Erforderliche Berechtigung: ContentTypes.View

Beispiel: Um die Definition des Typs building zu erhalten, rufen Sie

GET https://dev.iclportal.com/api/contenttypes/building HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept-Encoding: gzip, deflate
Authorization: Bearer ..the auth_token...

Dies gibt die Definition als JSON-Dokument zurück

{
  "name": "building",
  "displayName": "Building",
  "builtinTypeId": 0,
  "canBeInspected": true,
  "titleFieldName": "buildingname",
  "fields": [
    {
      "type": "ShortText",
      "name": "buildingname",
      "displayName": "Objektnummer",
      "isRequired": true,
      "isIndexed": false
    },
    {
      "type": "ShortText",
      "name": "zipcode",
      "displayName": "ZIP",
      "isRequired": false
    },
    ...
  ],
  ...
}

Die syncRules der zurückgegebenen Definition enthalten auch die eingebaute Regel für übergeordnete Elemente, sofern sie für den Inhaltstyp gilt, auch wenn die gespeicherte Definition sie nicht auflistet. Existiert kein Inhaltstyp mit dem angegebenen Namen, antwortet die API mit 404 Not Found.

Technischer Leitfaden zu Inhaltstypen

Um die Struktur und den Inhalt einer Inhaltstyp-Definition zu verstehen, lesen Sie bitte den Leitfaden zu Inhaltstypen

3. Herunterladen einer Inhaltstyp-Definition​

Dieser Endpunkt gibt im Wesentlichen die gleichen Informationen zurück wie Abrufen einer Inhaltstyp-Definition Allerdings gibt er diese als Antwort in Form einer Download-Datei zurück:

Erforderliche Berechtigung: ContentTypes.View

GET https://dev.iclportal.com/api/contenttypes/building/download  HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept-Encoding: gzip, deflate
Authorization: Bearer ..the auth_token...

Dadurch wird die Definition als json-Dokument zurückgegeben, aber die folgenden Antwort-Header angehängt, sodass die Browser die Antwort als Dateidownload interpretieren. Die Datei ist nach dem Inhaltstyp benannt (<name>.json):

  "cache-control": "no-store, must-revalidate, no-cache, max-age=0",
  "content-disposition": "attachment; filename=building.json",
  "content-encoding": "gzip",
  "content-length": "871",
  "content-type": "application/json",
  "date": "Fri, 03 Feb 2023 09:17:20 GMT",
  "server": "Microsoft-IIS/10.0",
  "x-aspnet-version": "4.0.30319",
  "x-powered-by": "ASP.NET"

Existiert kein Inhaltstyp mit dem angegebenen Namen, antwortet die API mit 404 Not Found.

4. Einen Inhaltstyp erstellen​

Ermöglicht die Erstellung eines neuen Inhaltstyps.

Erforderliche Berechtigung: ContentTypes.Create

Inhaltstypen mit eindeutigen IDs

Ein Inhaltstyp muss immer eine eindeutige ID haben. Die Namen von Inhaltstypen müssen zwar eindeutig sein, aber diese Anforderung soll sicherstellen, dass es nicht zu Namensüberschneidungen kommt, ohne dass es jemand merkt. Wenn z.B. zwei Benutzer einen Inhaltstyp mit dem Namen "Gebäude" erstellen, der aber völlig unterschiedliche Felder und Konfigurationen hat. Im schlimmsten Fall könnte dies zu Datenverlusten führen. Um eine eindeutige ID für Ihren Inhaltstyp zu erhalten holen Sie sich eine GUID von hier

Der Name des Inhaltstyps in der URL muss mit dem name im Anfragetext übereinstimmen (Groß-/Kleinschreibung wird nicht beachtet). Namen werden in Kleinbuchstaben gespeichert: Das Portal wandelt den Namen des Inhaltstyps, seinen titleFieldName, die Namen seiner Felder und die Fremdschlüsselfelder seiner Beziehungen in Kleinbuchstaben um.

Beispiel

POST https://dev.iclportal.com/api/contenttypes/elevator  HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept-Encoding: gzip, deflate
Authorization: Bearer ..the auth_token...

{
  "id": "fee7bb0d-7f53-4a86-8696-c9cf683680a9",
  "name": "elevator",
  "displayName": "Elevator",
  "builtinTypeId": 0,
  "canBeInspected": true,
  "titleFieldName": "elevator_name",
  "fields": [
    {
      "type": "ShortText",
      "name": "elevator_name",
      "displayName": "Aufzugsname",
      "isRequired": true,
      "isIndexed": false
    },
    {
      "type": "ShortText",
      "name": "zipcode",
      "displayName": "ZIP",
      "isRequired": false
    }
  ]
}

Bei Erfolg antwortet die API mit 200 OK und einem leeren Antworttext. Sie antwortet mit 400 Bad Request, wenn

  • der Anfragetext leer ist oder keine id enthält
  • der Name in der URL und der name im Anfragetext nicht übereinstimmen
  • bereits ein Inhaltstyp mit derselben id existiert (verwenden Sie stattdessen den Endpunkt zum Aktualisieren)
  • bereits ein anderer Inhaltstyp mit demselben Namen existiert
  • die Definition ungültig ist (z.B. ungültige Felder, Beziehungen oder Sync-Regeln)

5. Aktualisieren eines Inhaltstyps​

Die Aktualisierungsmethode ändert die Titel eines Inhaltstyps und fügt neue Spalten hinzu - also im Grunde dasselbe, was ein normaler Drag&Drop-Upload im Portal bewirkt. Es sind nur nicht-zerstörende Änderungen erlaubt:

  • Hinzufügen eines neuen Feldes zu einem Inhaltstyp
  • Ändern des Anzeigenamens eines Feldes oder Inhaltstyps
  • Ändern eines Feldes, sodass es erforderlich ist
  • usw.

Erforderliche Berechtigung: ContentTypes.Edit

Existiert noch kein Inhaltstyp mit der angegebenen id, wird er angelegt. Mit diesem Endpunkt können Sie einen Inhaltstyp also auch in einem Schritt erstellen oder aktualisieren. Wie beim Erstellen eines Inhaltstyps muss der Name in der URL mit dem name im Anfragetext übereinstimmen. Der Name eines bestehenden Inhaltstyps kann nicht geändert werden.

Im folgenden Beispiel ändern wir den displayName des Feldes elevator_name auf Englisch, was eine nicht-zerstörende Änderung ist:

Beispiel

PUT https://dev.iclportal.com/api/contenttypes/elevator  HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept-Encoding: gzip, deflate
Authorization: Bearer ..the auth_token...

{
  "id": "fee7bb0d-7f53-4a86-8696-c9cf683680a9",
  "name": "elevator",
  "displayName": "Elevator",
  "builtinTypeId": 0,
  "canBeInspected": true,
  "titleFieldName": "elevator_name",
  "fields": [
    {
      "type": "ShortText",
      "name": "elevator_name",
      "displayName": "Elevator name",
      "isRequired": true,
      "isIndexed": false
    },
    {
      "type": "ShortText",
      "name": "zipcode",
      "displayName": "ZIP",
      "isRequired": false
    }
  ]
}

Bei Erfolg antwortet die API mit 200 OK und einem leeren Antworttext. Nicht-rückwärtskompatible Änderungen und ungültige Definitionen werden mit 400 Bad Request abgelehnt.

Aktualisierungen

Bei der Aktualisierung eines Inhaltstyps werden die Elemente dieses Typs überhaupt nicht geändert. Vielmehr wird die neue Definition des Inhaltstyps vom System verwendet, um zu wissen, wie ein vorhandenes Inhaltselement geladen und gespeichert werden soll. Davon abgesehen: Wenn Sie einem Inhaltstyp ein Feld hinzufügen, wird dieses Feld nicht automatisch zu jedem Artikel hinzugefügt. Vielmehr wird dieses Feld beim nächsten Speichern des Artikels mitgespeichert. Dieser Ansatz beruht auf einer Designentscheidung, um Synchronisierungskonflikte zu vermeiden. Würden alle Artikel sofort geändert, würden alle Änderungen, die von nicht verbundenen Anwendungen vorgenommen werden, einen Zusammenführungskonflikt verursachen.

Lesen Sie den Leitfaden zu Zusammenführungskonflikten für weitere Informationen

6. Aktualisierung eines Inhaltstyps mit nicht-rückwärtskompatiblen Änderungen​

Eine erzwungene Aktualisierung kann die bestehende Struktur der Inhaltstypen überschreiben, indem Titel, Feldnamen, Datentypen geändert und sogar ganze Felder entfernt werden.

Diese Aktion ermöglicht nicht-rückwärtskompatible Änderungen und kann zu Datenverlusten führen.

Erforderliche Berechtigung: ContentTypes.Edit

Solche nicht-rückwärtskompatiblen Änderungen umfassen:

  • das Ändern des Namens eines Inhaltstypen-Feldes
  • Ändern des Typs eines Inhaltstypfelds
  • Entfernen eines Feldes aus einem Inhaltstyp
Hinweis

Der Name eines Inhaltstyps kann nicht geändert werden, auch nicht mit einer erzwungenen Aktualisierung. Eine solche Anfrage wird mit 400 Bad Request abgelehnt. Sync-Regeln werden in jedem Fall geprüft: Eine erzwungene Aktualisierung mit ungültigen Sync-Regeln wird ebenfalls abgelehnt.

nicht-rückwärtskompatible Änderungen

Da nicht-rückwärtskompatible Änderungen zu schwerwiegenden Problemen führen können, raten wir Ihnen dringend davon ab, sie jemals in Ihrem Produktionssystem einzuführen. Wenn Sie allerdings noch in einer Entwicklungs- oder Testumgebung arbeiten, in der Sie sicher sind, dass Sie Dinge kaputt machen können, können Sie den folgenden Ansatz verwenden, um einen Inhaltstyp zu aktualisieren

Im folgenden Beispiel wird der Typ des Feldes für die Postleitzahl von ShortText in Number geändert, wodurch eine nicht-rückwärtskompatible Änderung eingeführt wird 

PUT https://dev.iclportal.com/api/contenttypes/elevator/force  HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept-Encoding: gzip, deflate
Authorization: Bearer ..the auth_token...

{
  "id": "fee7bb0d-7f53-4a86-8696-c9cf683680a9",
  "name": "elevator",
  "displayName": "Elevator",
  "builtinTypeId": 0,
  "canBeInspected": true,
  "titleFieldName": "elevator_name",
  "fields": [
    {
      "type": "ShortText",
      "name": "elevator_name",
      "displayName": "Elevator name",
      "isRequired": true,
      "isIndexed": false
    },
    {
      "type": "Number",
      "name": "zipcode",
      "displayName": "ZIP",
      "isRequired": false
    }
  ]
}
Ungültige Änderungen rückgängig machen

Wenn Sie einen Inhaltstyp aktualisieren, werden die Elemente dieses Typs überhaupt nicht geändert. Vielmehr wird die neue Definition des Inhaltstyps vom System verwendet, um zu wissen, wie ein vorhandenes Inhaltselement geladen und gespeichert werden soll. Wenn Sie z.B. den Typ eines Feldes von ShortText in Number ändern, wird das Feld in allen vorhandenen Elementen weiterhin als ShortText gespeichert. Wenn jedoch das nächste Mal ein solches Element geladen wird, versucht das iCL-System, den gespeicherten Wert automatisch in den neuen Typ umzuwandeln. Gelingt ihm dies nicht, wird das Feld gelöscht. Aber nur wenn das System dieses geladene Inhaltselement mit dem konvertierten Feld speichert, wird der alte Feldwert tatsächlich überschrieben. Das bedeutet: Wenn Sie irrtümlich den Typ eines Feldes ändern, gehen die vorhandenen Daten nicht sofort verloren. Sie können Ihre Änderungen also immer noch rückgängig machen (indem Sie den Feldtyp wieder ändern) und jedes Element, das nicht unter Verwendung der ungültigen Typdefinition gespeichert wurde, hat weiterhin den ursprünglichen Feldwert.

Dieser Ansatz basiert auf einer Design-Entscheidung, um Synchronisationskonflikte zu vermeiden. Wenn alle Elemente sofort geändert würden, würden alle Änderungen, die von nicht verbundenen Anwendungen durchgeführt werden, einen Zusammenführungskonflikt verursachen.

Lesen Sie den Leitfaden zu Zusammenführungskonflikten für weitere Informationen

7. Löschen eines Inhaltstyps​

Ein Inhaltstyp kann mit diesem Endpunkt nur gelöscht werden, wenn kein anderer Inhaltstyp eine Beziehung zu ihm hat und keine Arbeitsmappe im Portal ihn verwendet. Andernfalls antwortet die API mit 400 Bad Request und listet die verweisenden Inhaltstypen bzw. Arbeitsmappen auf. Beziehungen des zu löschenden Inhaltstyps selbst zu anderen Inhaltstypen verhindern das Löschen nicht.

Erforderliche Berechtigung: ContentTypes.Delete

Hinweis

Alle Elemente dieses Inhaltstyps werden ebenfalls gelöscht.

Beispiel

DELETE https://dev.iclportal.com/api/contenttypes/building HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept-Encoding: gzip, deflate
Authorization: Bearer ..the auth_token...

Bei Erfolg antwortet die API mit 200 OK und einem leeren Antworttext. Existiert kein Inhaltstyp mit dem angegebenen Namen, antwortet sie mit 404 Not Found.

8. Löschen eines verwendeten Inhaltstyps​

Falls ein Inhaltstyp bereits

  • von einer Arbeitsmappe referenziert wird
  • andere Inhaltstypen eine Beziehung zu ihm haben würde das Löschen des Inhaltstyps zu einem Bruch führen. Wenn Sie sich sicher sind, was Sie tun, und Sie ihn trotzdem löschen müssen, verwenden Sie diesen Endpunkt. Er überspringt diese Prüfungen.

Erforderliche Berechtigung: ContentTypes.Delete

Hinweis

Alle Elemente dieses Inhaltstyps werden gelöscht

nicht-rückwärtskompatible Änderungen

Da nicht-rückwärtskompatible Änderungen zu schwerwiegenden Problemen führen können, raten wir Ihnen dringend davon ab, sie jemals in Ihr Produktionssystem einzuführen. Wenn Sie jedoch noch in einer Entwicklungs- oder Testumgebung arbeiten, in der Sie sicher sind, dass Sie Dinge kaputt machen können, können Sie den folgenden Ansatz verwenden, um einen Inhaltstyp zu löschen

DELETE https://dev.iclportal.com/api/contenttypes/building/force  HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept-Encoding: gzip, deflate
Authorization: Bearer ..the auth_token...

Bei Erfolg antwortet die API mit 200 OK und einem leeren Antworttext. Existiert kein Inhaltstyp mit dem angegebenen Namen, antwortet sie mit 404 Not Found.

9. Zurücksetzen der Sync-Filter aller Inhaltstypen​

Wenn Sync-Regeln pro Artikel ausgewertet werden, sind sie bis Mitternacht des nächsten Tages gültig. Dies wird in der Spalte ExpirationDate gespeichert; Das heißt, wenn eine Synchronisierungsregel festlegt, dass ein Artikel "Gebäude A" synchronisiert werden soll, bleibt dies bis zum nächsten Tag gültig. Erst danach werden sie erneut ausgewertet, um festzustellen, ob einige Elemente tatsächlich nicht mehr synchronisiert, sondern von den Geräten der Benutzer gelöscht werden sollen.

Selbst wenn also die nächste inkrementelle Auswertung ergibt, dass "Gebäude A" nicht mehr synchronisiert werden soll, bleibt es auf dem Gerät, bis das ExpirationDate erreicht ist.

Hinweis

Dieses Verhalten verzögert nur das Entfernen von Objekten von entfernten Geräten. Wenn ein neues Objekt synchronisiert werden soll, wird dies sofort wirksam.

Dieser Endpunkt lässt die Sync-Filter aller Inhaltstypen ablaufen, die von einer aktiven Sync-Regel gesetzt wurden und sonst um die nächste Mitternacht ablaufen würden. Bereits abgelaufene oder später ablaufende Filter bleiben unverändert. Anschließend startet er den Neubewertungsprozess, der normalerweise nur jede Nacht läuft, als Hintergrundjob.

Erforderliche Berechtigung: ContentTypes.Edit

POST https://dev.iclportal.com/api/contenttypes/syncfilters/reset  HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept-Encoding: gzip, deflate
Authorization: Bearer ..the auth_token...

Die Antwort enthält die Anzahl der zurückgesetzten Sync-Filter:

{
  "numberOfResetSyncFilters": 42
}
Auswirkungen auf die Leistung

Die Neuberechnung von Synchronisationsfiltern kann einige Zeit in Anspruch nehmen und die Leistung der Datenbank beeinträchtigen. Verwenden Sie diesen Endpunkt daher mit Vorsicht.

10. Herunterladen einer Excel-Importvorlage​

Gibt eine Excel-Datei (.xlsx) zurück, die ausgefüllt werden kann, um Inhaltselemente eines oder mehrerer Inhaltstypen zu importieren. Sie enthält pro Inhaltstyp ein Arbeitsblatt, das nach dem Inhaltstyp benannt ist. Die erste Zeile jedes Arbeitsblatts enthält die Spaltenüberschriften Id und ExternalId, gefolgt von den Namen der Felder des Inhaltstyps.

Erforderliche Berechtigung: ContentTypes.View

Übergeben Sie die Namen der Inhaltstypen im Query-Parameter contentTypeNames, einmal pro Inhaltstyp. Namen, zu denen kein Inhaltstyp existiert, werden ignoriert.

GET https://dev.iclportal.com/api/contenttypes/download/excel?contentTypeNames=building&contentTypeNames=elevator  HTTP/1.1
Accept-Encoding: gzip, deflate
Authorization: Bearer ..the auth_token...

Die Datei wird als Download (Content-Disposition: attachment) mit dem Namen <tenant id>_ContentTypes_template.xlsx zurückgegeben.

Tipp

Die Vorlage für einen einzelnen Inhaltstyp können Sie auch über die Inhaltselemente-API herunterladen.