Content Types
iCL allows you to quickly create powerful check lists to gather information on various things. In many cases you will want to track those "things" as separate data. For example, when doing building inspections, it is advisable to store all the data of a building in a separate table. Then, whenever that building is inspected, you can use its data to pre-fill parts of your checklists.
Buildings, fire fighting equipment, elevator types, customer information, ... in iCL these can be modeled with content types. A content type defines
- the fields that it stores (name, address, building year, ...)
- the relationships to other content types (e.g. an elevator belongs to a building)
- the form to edit its data
- advanced rules regarding how it is synchronized and more.
To understand the structure and contents of a content type definition, please read the content types guide
This API can be used to create, update and delete content types.
1. Querying content types
Gets all content types that are currently defined. Example:
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...
The response is a JSON array of content types:
{
"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. Retrieving a content type definition
Allows to retrieve the full definition of a content type.
Example: to get the definition of the building, call
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...
This will return the definition as a json document
{
"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
},
...
],
...
}
To understand the structure and contents of a content type definition, please read the content types guide
3. Downloading a content type definition
This endpoint returns essentially the same information as Retrieving a content type definition However, it returns those as a download file response:
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...
This will return the definition as a json document, but attach the following response headers, so that browsers interpret the response as file download:
"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. Creating a content type
Allows to create a new content type.
A content type must always have a unique id. While content type names must be unique, this requirement is to ensure that no name-clashes happen without anyone noticing. E.g. two users create a content type named "building" but with totally different fields and configuration. In the worst case, this could cause data loss. To get a unique id for your content type get a GUID from here
Example
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. Updating a content type
The update method will alter titles of a content type as well as add new columns - so basically the same, what a normal drag&drop upload on the portal will do. Only non breaking changes are allowed:
- adding a new field to a content type
- changing the display name of some field or content type
- changing some field to be
required - etc.
In the following example, we change the displayName of the field elevator_name which is a non-breaking change:
Example
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", -- changed to english
"isRequired": true,
"isIndexed": false
},
{
"type": "ShortText",
"name": "zipcode",
"displayName": "ZIP",
"isRequired": false
},
...
],
...
}
When updating a content type, any items of that type will not be changed at all. Rather, the new content type definition is used by the system to know how to load and save an existing content item. That said: Whenever you add a field to a content type, this field will not automatically be added to each item. Rather, the next time the item is saved this field will also be stored. This approach is based on a design decision to reduce synchronization conflicts. If all items would be changed instantly, any changes performed by disconnected apps would cause a merge conflict.
6. Update of a content type with breaking changes
A forced update will be able to overwrite the existing content types structure by changing titles, names, datatypes and even by removing entire fields.
This action allows to perform breaking changes and may lead to data loss.
Such breaking changes include:
- changing the name of a content type
- changing the name of a content types field
- changing the type of a content type field
- removing a field from a content type
Because breaking changes can lead to serious issues, we strongly discourage you to ever introduce them in your production system. If you are still working in some development or test environment, though, where you are safe to break things, you can use the following approach to update a content type
In the following example changes the type of the zip-code field from ShortText to Number thereby introducing a breaking change
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", -- changed to english
"isRequired": true,
"isIndexed": false
},
{
"type": "Number",
"name": "zipcode",
"displayName": "ZIP",
"isRequired": false
},
...
],
...
}
When updating a content type, any items of that type will not be changed at all. Rather, the new content type definition is used by the system to know how to load and save an existing content item.
For example, if you change the type of a field from ShortText to Number, all existing items will still keep their field stored as ShortText.
The next time, however, that such an item is loaded, the iCL system tries to automatically convert the stored value to the new type. If it fails to do so, it will clear the field.
But only if the system then stores this loaded content item with the converted field, the old field value will effectively be overwritten.
This means: In case you errornously change the type of a field, the existing data is not instantly lost. So you can still revert your changes (by changing back the field type) and any item that has not been saved using the invalid type definition will still have the original field value.
This approach is based on a design decision to reduce synchronization conflicts. If all items would be changed instantly, any changes performed by disconnected apps would cause a merge conflict.
7. Deleting a content type
To remove a content type with the delete method, it isn't allowed to have any relationships to other content types, and no workbook on the portal may have a reference to it.
Example
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. Deleting a used content type
In case a content type is already
- referenced by some workbook
- having other content types relating to it (relationship) deleting it would introduce a breaking change. If you are sure of what you do and you still need to delete it, use this endpoint
All items of that content type will be deleted
Because breaking changes can lead to serious issues, we strongly discourage you to ever introduce them in your production system. If you are still working in some development or test environment, though, where you are safe to break things, you can use the following approach to update a content type
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. Resetting the sync filters of all content types
When sync rules are evaluated per item, they are valid until midnight of the next day. This is stored in the column ExpirationDate;
This means, that if a sync rule determines that some item "building A" should be synchronized, this remains in effect until the next day.
Only thereafter they will be evaluated again in order to determine, whether some items should actually not be synchronized anymore but deleted from the users devices.
So even if the next incremental evaluation determines that "building A" should not be synchronied anymore, it will remain on the device until the `ExpirationDate´ is reached.
This behavior only delays the removal of items from remote devices. if a new item should be syhcnronized, this will take effect immediately.
This endpoint allows to expire all existing sync filters of all content types and starts the re-evaluation process which usually only runs every night.
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...
Re-calculating sync filters may take some time and can impact the performance of the database. So use this endpoint with caution.