Start your customization from the default schemas of the CIHUB module. Test, upload and activate your custom schemas. |
To validate and test your custom schemas you must enable the Service Accounts and Authorization settings in the cihub client settings in Keycloak. Make sure to disable these settings in production. For more information, see Setup CI HÙB integration in censhare. |
The CIHUB module provides a REST interface for the CI HUB Server to retrieve the asset data that are then shown in the CI HUB panel. The REST interface delivers entity types that are configured in the schemas (image, video, audio, 3D model). Each schema definition for an entity type contains a mapping of properties that are retrieved from the asset. The REST interface delivers a serialized JSON format.
For the customization, there are three basic principles:
When you start with your customization, you must first identify the schema that you want to adapt. The following schemas are delivered with the CIHUB module:
The assigned asset types can be changed. It is also possible to change assigned properties. If you want to change or add properties for a certain schema, you must edit that schema. If you want to change or add properties that apply to all entities, you must edit the media schema.
Before you start, it is important that you understand the general structure of the schemas. Exspecially, the definition of properties for
This article and the following articles give you an overview about the various of parts of the provided schemas. For each part, there are examples for a better understanding.
There are some restrictions of what you can do if you adapt the provided schema. To help you with this, there is an own section at the end this articles series with guidelines on that. For more information, see the Guidelines for schema adaption section below.
To start with customization, download the default schemas from the CI HUB module on the censhare Server.
Run the following command to download all schemas in the ../schemas/ directory on your computer.
scp -r root@CENSHARE_SERVER: /opt/corpus/censhare/censhare-Custom/censhare-Server/app/modules/cihub/schemas/* |
CENSHARE_SERVER is the domain name of your censhare Server. The path is the default path on the censhare Server.
HTTP method: PUT Authorization: OAuth 2.0 Path: CENSHARE_SERVER/cihub/schema/SCHEMA_NAME Body: Schema in JSON format Data encoding: raw |
CENSHARE_SERVER is domain name of the censhare Server. SPECIFIC_SCHEMA_NAME is the name of your schema. Use the naming pattern: NAME-schema.json.
curl -X PUT http: //CENSHARE_SERVER/cihub/schema/user -d @001-media-schema.json --header "Content-Type: application/json" -H "Authorization: Bearer ACCESS_TOKEN" |
You can use Postman to request the ACCESS_TOKEN. For more information, see the last section.
To upload a changed or new schema, run the following command:
scp 050-picture-schema.json root@CENSHARE_SERVER: /opt/corpus/censhare/censhare-Custom/censhare-Server/app/modules/cihub/schemas |
CENSHARE_SERVER is the domain name of your censhare Server. The URL points to the default schema directory of the CIHUB module on the censhare Server.
After the schema update, you must reload the CIHUB module. To do so, click Update server configuration in the censhare Admin Client. If necessary, also Synchronize remote servers.
It is not necessary to change the configuration in the CIHUB module. The Update server configuration reloads all schemas from the schema directory of the module. |
Test if the REST API is delivering the data as you have defined it for the or changed entity type. Send a HTTPS request to REST API to receive data the entity type in question. You can use the following parameters in your test tool, for example Postman. For more information see the Configure Postman to test the schemas section at the end of this article.
HTTP method: GET Authorization: OAuth 2.0 Path: CENSHARE_SERVER/cihub/entity/ENTITY_NAME/ Body: None |
This delivers all asset data for the mapped entity type and attributes in JSON format.
The name of the schema is defined in the URL endpoint. For example:
/hcms/v2.0/schema/picture |
The structure of an entity schema contains the following elements:
Basic definitions are related to JSON format, for example, the data type of the entity. The root level element must always be of the type: object. Use the following entry:
"type": "object" |
A set of properties. Each property is mapped to a data structure in censhare. In the simplest case, it assigns an asset feature to the attribute. For properties that are related to censhare specific semantics use the cs: prefix:
"cs:asset.type": "group." |
The generic schema defines an asset type and maps two attributes. The asset type is mapped as a constant:
{ assign asset type "type": "object", "properties": { property 1, property 2, type of the entity } } } |
The following example is based on the above definition:
{ "cs:asset.type": "person.user.", "type": "object", "properties": { "name": { "type": "string" "cs:feature.key": "censhare:asset.name", }, "id": { "type": "integer", "cs:feature.key": "censhare:asset.id" } "type": { "cs:$const": true, "const": "person", "type": "string" }, } } |
It maps the person entity type to the person.user. asset type. There are two properties: name and id that are mapped to asset features (asset id and asset name.
The response payload from the above example schema is as follows:
{ "result": [ { "name": "Test-Person", "id": 11354, "type": "person" } ], ... # some data related to the query } } |
The assignment of the asset type to an entity type is a 1:n relations. This means that there can be several asset types assigned to an entity type. Do not assign the same asset type to different schemas. It might not be deterministic which schema is then used!
The "cs:asset.type" property also allows you to assign more than one asset type to a schema. For this case, you can assign an array of asset type, for example:
"cs:asset.type": { "types": [ "ad.", "document." ], "default": "document." } |
The default attribute defines the asset type that is used when a new entity with this type is created. You must add this if there is more than one asset type assigned.
If you have an existing schema, you can change (add, change, remove) the assignment of asset type. Asset types also include sub-types, for example:
"cs:asset.type": { "types": [ "document.", "document.training.", "ad." ], "default": "document.", "mimetype-of": [ "master" ] } |
The mimetype-of attribute defines that the asset type is set according to MIME type of the master file of an asset. The default property is required. If the MIME type does match any of the types from the list above, the default asset type is used.
Only use the mimetype-of property for asset types that are created by uploading a master file!
Each schema contains a properties section. You can map any asset property to the entity.
{ ... "properties": { "PROPERTY-1": { attribute 1, attribute 2 }, "PROPERTY-2": { attribute 1, attribute 3 }, ... "PROPERTY-3": { attribute 2, attribute 3 } } } |
Properties define any values that you want to retrieve from an asset. The following can be retrieved:
Attributes are added within the attributes section of a schema. For a basic definition, the cs:feature.key is required. You can look up feature keys in the censhare Admin Client in Master data/Features.
"wf_step": { "cs:feature.key": "censhare:asset.wf_step", "type": "string" }, |
The type defines the data type as part of the JSON schema. Ensure that the type matches the value type of the asset feature. |
A link to the mapped asset can be defined as follows:
"link": { "cs:entity.link": true, "type": "string" } |
This generates an URL endpoint that links to the asset. The property is defined at the top level of the schema. In the response, links are give back as absolute URLs: "link": "<HOST>/hcms/v2.0/history/image/51782/1".
To enable full-text faceted search, add the following line to the schema definition:
"cs:fulltext.$faceted": true |
In censhare, these are the so-called alternate results of a search for a feature. Add this line at the root level. This also makes it valid for all feature definitions.
To integrate the censhare Server into the CI HUB Server, a Resource Adapter censhare has been built as an API by CI HUB. The API has been built upon the provided basic schemas of the CIHUB module of the censhare Server. As of that, changes of the provided schemas are limited not to break the API of Resource Adapter censhare.
Here is a list of changes that you at least can do:
Be careful if you do the following:
Here is a list of what you should not do. It will probably not break the CI HUB Server API but no useful data might be displayed:
Here is list of change that you at least must NOT do:
censhare Server with censhare WP uses KeyCloak for authentication that is based on OAuth 2.0. This also means that every request to the REST API of the CIHUB module must be authenticated. This is done by adding an access token to the request. You can use Postman to query KeyCloak and receive access token.
Here are the parameters that you must configure:
CENSHARE_SERVER is the URL of your censhare Server. The CLIENT_SECRET is the secret in KeyCloak for the censhare5 client. You find the client in Configure/Clients. Select censhare5, open the entry and go to the Credentials tab and copy the entry in Secret.
Use the Get New Access Token button in Poastman, to start the request. KeyCloak then opens a login page where you enter the credentials of a user in KeyCloak. After succesfull authentication, KeyCloak returns among others access token and refresh token.
|