CI HUB - get started with customization

Start your customization from the default schemas of the CIHUB module. Test, upload and activate your custom schemas. 

Introduction

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:

• You can only map existing asset structures at your censhare Server to entities of the REST API of the CIHUB module. Mapping of non-existing elements such as assest features break the REST interface of the CIHUB module. Validation of schema adaptions helps to detect this before upload.
• The basic schemas define a JSON structure with entities and assigned attributes. The interface of the CI HUB Server for censhare is built upon this JSON structure. If this JSON structure is broken through customization, this also breaks the CI HUB Server interface for censhare. As of that, you must be careful with your adaption of schemas.
• For the CI HUB Server interface for censhare it does not matter which asset data are mapped to existing properties. This means that you can the mapping of existing properties but not the property definition itself. For example, there is a property that is mapped to a certain relation type of the censhare Server. If you change the relation type to another one in censhare, the JSON structure of the entity does not change.

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:

• Folder schema
• Media schema
• Audio schema
• Picture schema
• Video schema
• 3D-model schema
• Layout schema

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

• asset features
• storage items
• asset relations
• asset feature references

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.

Download schema definitions

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.

Validate schema definitions

Before you upload a new or changed schema, you must validate the schema. There is a REST endpoint of the CIHUB module for this purpose:

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.

Upload schema definitions

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.

Reload schema definitions

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.

Check for successful update

1. Prepare test data that contain the changes of the schemas that you made. For example:
   • If you have changed the assignment of asset types to an entity, provide an asset with this asset type.
   • If you have added a new asset feature as attribute to an entity, prepare an asset that contains a value of this feature.
   • If you have added a new relation type as attribute to an entity, prepare an asset that has this relation type.
   • If you have added a new asset reference as an attribute to an entity, prepare an asset that has such a reference to another asset.

2. 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.

3. Open the CI HUB connector plug-in in one of your Adobe CC applications. 
4. Navigate to your test assets in CI HUB panel and check if the defined data of that assets display correctly.

General structure of a schema

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
  } 
}

Assign asset type to a schema

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!

General

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:

• asset features
• storage items
• asset relations
• asset references (features)

Simple properties

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"
},

Link to an entity

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".

Fulltext search

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.

Guidelines for schema adaption

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:

• Add new asset types or sub-types to the list of assigned asset type of an entity type.
• For existing feature properties: Change the feature key to map the property to another asset feature. The defined property type must still match with new assigned asset feature. For the CI HUB Server API, it does not make any difference if a link is defined via an relation or asset reference in censhare. In the end, the API requires a URL link to the linked asset.
• For existing relation properties: Change the asset relation type of the relation or define an asset reference feature instead. Note that related asset types must be mapped to asset type that is defined in one of the existing schemas.
• For existing asset feature references: Change the feature key to map the property to another asset reference or define an asset relation instead. Note that the referenced asset type must be mapped to asset type that is defined in one of the existing schemas.
• Add new properties to an existing schema. See for already existing properties in the existing schemas that you can adapt.
• ((NOT VALIDATED)) Add new schemas that are based on existing properties. These properties can also be adapted according the changes mentioned above in this list. For example, you define a person schema that is mapped to the person asset type. If there is an author relation from an image to a person asset, this schema is then used to map and display the defined properties in that schema.
• is used to display author information

Be careful if you do the following:

• Remove properties from a schema because this can break the Resource Adapter censhare API.
  • If you remove the property that defines the link to the master file of an asset in the CIHUB module, this breaks the API, for example.
  • If you remove a property that just maps an asset feature that describes the asset in more detail, you can do that. For example, if you remove the property for the resolution of an image, this is no longer available in the CI HUB panel.

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:

• Do not use another value than link for the ref_type attribute in properties that define relations or asset references. For example, if you define id_extern instead of link, there is no link to the related asset. As of that, no data of the linked asset are available. Only, the id_extern then can be displayed.

Here is list of change that you at least must NOT do:

• Change the name of existing properties.
• Change the type of existing properties. For example, a property has string as type defined. If you change the type to object, you change the JSON representation of the entity defined by the schema. This breaks the CI HUB Server API.

Configure Postman to test the schemas

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:

• Grant type: 'Authorization Code'
• Callback URL: 'CENSHARE_SERVER/hcms/v2.0/entity'
• Auth URL: 'https://CENSHARE_SERVER/auth/realms/censhare/protocol/openid-connect/auth'
• Access Token URL: 'CENSHARE_SERVER/auth/realms/censhare/protocol/openid-connect/token'
• Client ID: 'censhare5'
• Client Secret: CLIENT_SECRET
• Scope: 'openid'
• State: can be empty
• Client Authentication: 'Send as basic authentication header'

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.