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.

1. Abfrage von Inhaltstypen​

Ruft alle Inhaltstypen ab, die derzeit definiert sind. Beispiel:

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

Die Antwort ist ein JSON-Array mit 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
}

2. Abrufen einer Inhaltstypen-Definition​

Ermöglicht das Abrufen der vollständigen Definition eines Inhaltstyps. Beispiel: Um die Definition des Typs Gebäude zu erhalten, rufen Sie

GET https://dev.iclportal.com/api/contenttype/building HTTP1.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
    },
    ...
  ],
  ...
}
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:

GET https://dev.iclportal.com/api/contenttype/building/download  HTTP1.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:

  "cache-control": "no-store, must-revalidate, no-cache, max-age=0",
  "content-disposition": "attachment; filename=tutorial_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"

4. Einen Inhaltstyp erstellen​

Ermöglicht die Erstellung eines neuen Inhaltstyps.

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

Beispiel

POST https://dev.iclportal.com/api/contenttype/building  HTTP1.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
    },
    ...
  ],
  ...
}

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.

Im folgenden Beispiel ändern wir den Anzeigenamen des Feldes "Aufzugname", was eine nicht-zerstörende Änderung ist:

Beispiel

PUT https://dev.iclportal.com/api/contenttype/building  HTTP1.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", -- geändert in Englisch
      "isRequired": true,
      "isIndexed": false
    },
    {
      "type": "ShortText",
      "name": "zipcode",
      "displayName": "ZIP",
      "isRequired": false
    },
    ...
  ],
  ...
}
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, Namen, Datentypen geändert und sogar ganze Felder entfernt werden.

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

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

  • das Ändern des Namens eines Inhaltstyps
  • das Ändern des Namens eines Inhaltstypen-Feldes
  • Ändern des Typs eines Inhaltstypfelds
  • Entfernen eines Feldes aus einem Inhaltstyp
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 fehlerhafte Änderung eingeführt wird 

PUT https://dev.iclportal.com/api/contenttype/building/force  HTTP1.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", -- geändert in Englisch
      "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 Kurztext in Zahl ändern, wird das Feld in allen vorhandenen Artikeln weiterhin als Kurztext 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​

Um einen Inhaltstyp mit der Löschmethode zu entfernen, darf er keine Beziehungen zu anderen Inhaltstypen haben und keine Arbeitsmappe im Portal darf einen Verweis auf ihn haben.

Beispiel

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

8. Löschen eines verwendeten Inhaltstyps​

Falls ein Inhaltstyp _bereits

  • von einer Arbeitsmappe referenziert
  • mit anderen Inhaltstypen, die sich auf ihn beziehen (Beziehung) 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
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 aktualisieren

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

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 ermöglicht es, alle bestehenden Sync-Filter aller Inhaltstypen ablaufen zu lassen und den Neubewertungsprozess zu starten, der normalerweise nur jede Nacht läuft.

POST https://dev.iclportal.com/api/contenttype/syncfilters/reset  HTTP1.1
Content-Type: application/json;charset=UTF-8
Accept-Encoding: gzip, deflate
Authorization: Bearer ..the auth_token...
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.