Mesh ContentRepository

This feature allows publishing into an instance of Gentics Mesh

1 Configuration

If you want to use this feature, you first have to enable it globally in your node.conf


$FEATURE['mesh_contentrepository']=true;

1.1 General settings

The following settings can be changed in the configuration:

Name Description Default
pageSize Number of objects, which are loaded from Mesh when checking for obsolete objects during every publish run. Higher numbers increase performance but also memory consumption of the CMS Server. 10000

$MESH["pageSize"] = 10000;

1.2 Client Timeouts

The publish process uses an HTTP Client for accessing Gentics Mesh. In cases, where requests may take longer than the default timeout of 1 minute (e.g. for uploading files), the following timeouts can be configured:


// Timeout for connecting in seconds
$MESH["client"]["connectTimeout"] = 60;

// Write timeout in seconds
$MESH["client"]["writeTimeout"] = 60;

// Read timeout in seconds
$MESH["client"]["readTimeout"] = 60;

// Timeout for completing a call in seconds. This includes resolving DNS, connecting, writing the request body, server processing, and reading the response body.
$MESH["client"]["callTimeout"] = 60;

2 Create ContentRepository

When the feature is activated, the field ContentRepository Type in the creation dialog has the new option Mesh ContentRepository.

2.1 Connection Url

The field Url must contain a valid connection Url to an instance of Gentics Mesh. The Url must be in the format [protocol]://[hostname]:[port]/[cr_identifier].

Name Description Mandatory
protocol Connection protocol (http or https) false (Default http)
hostname Hostname true
port Connection port false (Default 80 for http, 443 for https)
cr_identifier Identifier, which is used as schema prefix and project name, if Project per Node is not selected true

Examples of valid Connection Urls:

  • my.mesh.cr/project
  • my.mesh.cr:8080/project
  • http://my.mesh.cr/project
  • http://my.mesh.cr:8080/project
  • https://my.mesh.cr/project
  • https://my.mesh.cr:8080/project

2.2 Authentication with Username/Password

It is recommended to use authentication with ApiToken instead, to prevent session timeouts in long publish runs.

Gentics CMS will authenticate against Gentics Mesh with username/password filled into the fields Username and Password.

If the field Username is left empty, the field Password must contain a valid API Token. Consult the documentation of Gentics Mesh about how an API Token can be generated.

2.4 Permissions

The user (identified either by username/password or be API Token) must have sufficient privileges to publish into the Mesh ContentRepository:

  • Create new Projects
  • Read/Update/Delete/Publish on all nodes of the project
  • Assign and Revoke permissions on nodes of the project
  • Create new Schemas
  • Read/Update/Delete on all created schemas

2.5 Roles Objectproperty

By setting the field Roles Objectproperty to an object property (e.g. object.meshroles) it is possible to assign the readPublished permission on published objects to selected roles in Gentics Mesh.

The object property must at least have one part of type Select (multiple) or Select (single) using an initially empty datasource. The datasource will automatically be filled with the roles in Gentics Mesh with the Repair action on the ContentRepository.

It is necessary to perform the Repair action on the ContentRepository, after the roles in Gentics Mesh have changed to synchronize them into the datasource.

2.6 Project per Node

With this option, the mapping between Nodes published into this ContentRepository and projects in Mesh can be configured:

2.6.1 Single project

When the option “Project per Node” is not selected, all Nodes that are published into the ContentRepository will be published into a single Mesh project. The name of the project is the [cr_identifier] from the connection Url.

The contents of every Node in GCMS will be published into a separate folder in Mesh (having the same name as the Node).

2.6.2 Multiple projects

When the option “Project per Node” is selected, every Node will be published into a separate Mesh project (having the same name as the Node).

In this case, there will be no “root” folders in the Mesh projects, representing the Nodes, but all immediate children of the Nodes in the GCMS will be directly put into the roots of their respective Mesh projects.

In order to publish a master node with its channels into the same Mesh ContentRepository, this option must be selected. See Multichannelling for details.

2.7 Implementation version

By setting an implementation version, it is possible to let the publish process publish objects into separate Mesh branches. For details see Mesh ContentRepository Implementation Branches.

2.8 Tagmap

The CMS publishes folders, pages, images and files into Gentics Mesh. The nodes in Gentics Mesh will use three schemas in Gentics Mesh:

  • [cr_identifier]_folder for folders
  • [cr_identifier]_content for pages
  • [cr_identifier]_binary_content for images/files

The fields in the schemas are defined by the tagmap entries of the Mesh ContentRepository in the CMS.

Tagmap Attributetype Schema field type
Text string
Node node
Integer number
Binary binary
Date date
Boolean boolean
Micronode micronode

When a new Mesh ContentRepository is created, it will have some default tagmap entries. Some of them are Reserved and cannot be modified or removed, because they are absolutely necessary.

2.8.1 Segmentfield

For each object type, exactly one tagmap entry is marked as Segmentfield. The segmentfield is used to construct the URLs to objects in Gentics Mesh and must be unique among objects with the same parent folder.

For folders, the default segmentfield is pub_dir, but for this to work as expected, the feature Publish Directory Segment must be activated for the node.

2.8.2 Displayfield

For each object type, exactly one tagmap entry is used as Displayfield. The displayfield is used to represent the object in the Administration UI of Gentics Mesh and must be unique among objects with the same parent folder.

2.8.3 URL-field

Tagmap entries can be marked as URL-field. By filling URL-fields, it is possible to specify additional URLs (besides the URL, which is constructed from the segment fields) for accessing objects, that are published into the Mesh ContentRepository.

This is especially useful in combination with the feature Nice URLs:

2.8.4 Micronode Fields

Tagmap entries of type “Micronode” will publish the editable data contained in tags into micronodes. It is possible to publish single tags (e.g. by using the tagname page.tags.content to publish the tag content) into a single value field of type Micronode. When using e.g. page.tags, the field must be multivalue and will contain all tags of the page as list of micronodes.

2.8.4.1 Transformation of tagtypes

When a Mesh ContentRepository contains at least one tagmap entry of type “Micronode”, all constructs that meet all of the following requirements will be transformed into microschemas:

  1. The construct must be assigned to at least one Node that publishes into the Mesh ContentRepository
  2. The construct must contain at least one editable Part with a non-empty keyword – other than Tag (global), File (localpath), Table ext, Velocity, Breadcrumb, Navigation
  3. The construct matches at least one of the micronode filters
2.8.4.2 Part Types with special mapping

The following list contains all Part Types that have a special mapping to fields in the microschema

Part type Schema field Description
URL (page) [keyword]_internal Node reference to linked page
[keyword]_external External URL (as string)
Tag (page) [keyword]_page Node reference to linked page
[keyword]_tag Name of the referenced tag
Overview [keyword]_listType Type of listed objects
[keyword]_selectType Selection type
[keyword]_orderDir Order Direction
[keyword]_orderBy Ordering type
[keyword]_items Node references to listed items
[keyword]_nodeIds List of internal node IDs from which items were selected
[keyword]_source Overview template
[keyword]_recursive Flag for recursive selection
[keyword]_maxItems Maximum number of items to be shown in the overview
List [keyword] List of entries
[keyword]_ordered Boolean flag ordered/unordered
Tag (template) [keyword]_template Internal ID of the referenced template
[keyword]_tag Name of the referenced tag

If the field names of a microschema to be generated are not unique, creation of the microschema (and therefore the publish process) will fail. It is for instance not possible to create a microschema from a construct having a part of type URL (page) with keyword url when there is another part with keyword url_internal.

All other part types will be mapped to a single field.

2.8.4.3 Micronode filter

For tagmap entries of type “Micronode”, it is possible to define a filter for the published micronodes. Only tags matching the filter will be published into the field.

The filter can contain a list of construct keywords (separated by comma, whitespace or newline), and can be a whitelist (keywords are not prefixed) or a blacklist (keywords are prefixed with -).

2.9 Searchindex Configuration

Objects that are written into Gentics Mesh will automatically be put into a search index. To implement specific search features (like autocompletion, did-you-mean, …) it is necessary to extend the default configuration. This can be done by adding index specific configuration to the ContentRepository and to tagmap entries.

2.9.1 ContentRepository Searchindex Configuration

The ContentRepository Searchindex Configuration can be set in the ContentRepository properties dialog in JSON format. The root-object can have attributes page, folder and file which contain the searchindex configuration for pages, folders and files.

Example configuration:


{
  "page" : {
    "settings": {
      "number_of_shards" :   1,
      "number_of_replicas" : 0
    },
    "analysis" : {
      "analyzer" : {
        "suggest" : {
          "tokenizer" : "mesh_default_ngram_tokenizer",
          "char_filter" : [ "html_strip" ],
          "filter" : [ "lowercase" ]
        }
      }
    }
  }
}
2.9.2 Tagmap Entry Searchindex Configuration

Every tagmap entry can have a specific searchindex configuration set in its properties dialog in JSON format.

Example configuration:


{
  "suggest": {
    "analyzer": "suggest",
    "type": "string"
  }
}

3 Multichannelling

For publishing a node and all its channels into the same Mesh ContentRepository, the option Project per Node must be activated for the ContentRepository.

The master node and its channels will be published into the same Mesh project, but every node/channel into its own Mesh Branch.

The names of the Branches are the names of the node/channel (with spaces replaced by underscores).

If an Implementation version is set, the branch names will be composed of the node/channel name and the implementation version.

4 Check/Repair

With the action Check the validity of the Mesh ContentRepository will be checked:

  • Accessing the instance of Gentics Mesh
  • Existence and correctness of the schemas
  • Existence of the project
  • Schemas assigned to the project
  • Roles Objectproperty filled with roles from Gentics Mesh

The action Repair is used to repair incorrect data in Gentics Mesh:

  • Missing schemas will be created
  • Incorrect schemas will be updated
  • Missing project will be created
  • Schemas will be assigned to the project
  • Datasource used in the Roles Objectproperty is filled with roles from Gentics Mesh

The publish process will also try to repair incorrect data in Gentics Mesh (everything above, but the Roles Objectproperty)

5 Mesh Preview URL

The properties dialog of Nodes in the CMS have a field Mesh Preview URL which can contain the URL to an application (portal) that is used to render the objects published into Gentics Mesh.

When the URL is set and a page must be rendered in the CMS (for preview or in edit mode), the CMS will transform the page into a Mesh Node and POST that to the preview URL. The response is then used as template for rendering the page in edit or preview mode.