Cinnamon client configuration

Abstract

This documentation applies to Cinnamon Desktop Client plus (CDCplus) configuration which is maintained on the Cinnamon Server and deployed to the client.

How CDCplus configuration works

Concept

Earlier Cinnamon Desktop Client versions maintained client configuration in a file named CinnamonDesktopClient.custom.config.xml that was stored locally with the client.

Since the introduction of CDCplus in 2018, the configuration is no longer maintained on the client, but on the server. All configuration is stored in the metadata of an object named _client_configuration inside the Cinnamon path /system/config/client_configuration.

This object can contain multiple sets of configuration that will be deployed depending on the user's group membership or superuser privileges. It is possible to assign individual configuration to a single user. In any case, there must be a default that is assigned to all users not matching any of the specific configuration sets.

CDCplus itself contains an emergency configuration that is loaded whenever no server-based configuration can be deployed for whatever reason. This can happen when a legacy system is accessed with CDCplus for the first time or when a superuser has somehow misconfigured the server-based configuration. The emergency configuration allows a superuser to fix the configuration and restore a working state for all users.

Assigning configuration to users

The metadata inside the _client_configuration can be accessed with the Edit metadata tab in CDCplus. The exact permissions on this object are subject to ACL configuration and assignment. Generally, only superusers or selected users who are responsible for configuration changes should be allowed to modify the configuration. To use the client, only read access to the object is required.

The metadata has the following, general structure:

<meta>
  <metaset type="client_configuration" id="52146">
    <cinnamon_client>
      <match>
        <default />
      </match>
      ... configuration ...
    </cinnamon_client>
    <cinnamon_client>
      <match>
        <superuser />
      </match>
      ... configuration ...
    </cinnamon_client>
    <cinnamon_client>
      <match>
        <group sysname="test" />
      </match>
      ... configuration ...
    </cinnamon_client>
    ... further group based matches ...
    <cinnamon_client>
      <match>
        <user name="john.doe" />
      </match>
      ... configuration ...
    </cinnamon_client>
    ... further user based matches ...

The following rules apply:

• There must be one default match.
• There may be one superuser match.
• There may be any number of group matches.
• There may be any number of user matches.

Matches are applied in the following order:

• If no configuration object can be retrieved, or if the configuration object is invalid, emergency configuration is returned.
• Next, user matches are tried.
• Next, the superuser match is tried.
• Next, group matches are tried.
• If no match was found, default is tried.
• If no default is found, emergency config is returned.

Structure of the cinnamon_client element

Root structure

The cinnamon_client element has the following structure:

<cinnamon_client>
  <match>
    ... match definition ...
  </match>
  <global_settings>
    ... some basic client settings ...
  </global_settings>
  <classes>
    ... all libraries and classes that are used 
    inside the client, and their configuration ...
  </classes>
  <menu>
    ... context menu structure, referencing classes 
    that were defined inside the classes element ...
  </menu>
</cinnamon_client>

Structure of the global_settings element

The global_settings element has the following structure:

<global_settings>
  <culture_name>en-US</culture_name>
  <log value="false" />
  <branching allow="false" />
</global_settings>

• culture_name defines the client satellite libraries to load. The content of the element must be one of the valid satellite library language codes. The default is en-US (if no culture_name element is provided). Currently, apart from English, only German (de-DE) is fully supported. There is limited language support in French and Dutch, which can be completed, or other languages can be added, if needed. If no culture_name element is present, the user's language setting configured in the user account is used.

• log may have the values true or false in the value element. true causes a log to be written into the temp folder, named Praties_<timestamp>.log

• branching may have the values true or false in the allow element. false disables operations that will cause a branch on client side.

NOTE: This does not disable branching on server level. Also, branching can be enabled or disabled, depending on the configuration deployed to the client, and thus by user role.

Structure of the classes element

The classes element has the following structure:

<classes>
  <default_window assembly="CinnamonEnterpriseClient" type="EnterpriseClientMainWindow">
    <path>/</path>
  </default_window>
  <content_awareness>
    <content id="dita">
      <implementation assembly="ContentAwareness" type="XmlContent" />
      <format_filter>dita</format_filter>
      <format_filter>ditamap</format_filter>
      <custom>
        <children>
          <xPath>//@href</xPath>
          <xPath>//@conref</xPath>
        </children>
      </custom>
    </content>
  </content_awareness>
  <session_extensions>
    <session_extension key="icon_service" assembly="CinnamonEnterpriseClient" type="DefaultIconService" />
    <session_extension key="cec.basichookcontainer" assembly="CinnamonEnterpriseClient" type="BasicHookContainer" />
  </session_extensions>
  <session_window assembly="CinnamonEnterpriseClient" type="EnterpriseClientMainWindow">
    ... session Window configuration ...
  </session_window>  
  <tab_controls>
    ... tab controls configuration ...
  </tab_controls>
  <functions>
    ... context functions configuration ...
  </functions>
</classes>

The default_window element

The default_window element allows the definition of one window to be opened opened whenever a session is created. Different user groups can have different default windows.

NOTE: Future CDCplus versions will allow to define multiple windows. Since opening a window requires several calls to Cinnamon to retrieve the data to display, and thus takes a few seconds, not too many windows should be configured.

The path element's content defines the Cinnamon path to the folder to be shown. Example: /Documentation.

The content_awareness element

The content_awareness element contains configuration of content awareness modules. Content awareness modules are classes that can handle certain data and can be assigned to one or more formats.

Only formats that can contain either references to other objects (like XML or SGML), or that are subject to client-based custom processing on inbound and outbound operations need a content awareness module. Most formats, like pictures and PDF, do not normally need explicit support.

NOTE: The documentation for content awareness will follow. The existing configuration as shown in the example describes referencing in DITA and should not be changed, unless a future DITA release has a different data model, or unless custom behaviour should be achieved.

It is possible (and encouraged) to develop new content awareness modules that support other referencing file formats. For example, Microsoft Office adaptors that support image and hyperlink references are possible.

The session_extensions element

The session_extensions element contains the definitions of session extensions. A session extension is a class that's instantiated when a session is created. The instance is attached to the session and is available anywhere inside the client.

Session extensions can be used to provide functionality that should be globally available to standard and custom functionality.

Two session extensions are defined by default:

• The default icon service which deploys icons inside object lists and elsewhere. Implementing a custom icon service allows displaying individual icons by any available parameters of an object, for example lifecycle state, content format or object type.
• A basic hook container provides methods that are called on the client before and after lifecycle change. Other hooks can be added. The basic hook container has empty methods. To implement custom functionality, a custom hook container must be programmed and linked in the configuration.

Other session extensions can be added as required.

The tab_controls element

The tab_controls element contains the definitions of all tab controls that are available in the upper and lower right portion of the CDCplus main window. In a typical client configuration, there are 20 or more tab controls defined.

Not all tab controls are shown on every selection, since many of the tab controls are bound to specific situations, object types, formats or other parameters. There are, for example, specific tab controls for creating search definitions or managing translation tasks.

As with functions, session extensions, content awareness modules and other entities, tab controls are bound into the client just by configuration. It is therefore possible to program your own tab controls and add them to the client.

A minimal tab_control element looks like this:

<tab_control assembly="Praties" type="PermissionFolderControl" display="list" />

The assembly and type attributes define from which program library the tab control must be loaded and what its name is. The display attribute determines whether the tab control will show:

• in the upper right area (value: tree)
• in the lower right area (value: list)
• in both areas (value: all)

The tab_control element shown above binds the control exposing the permissions on a folder into the client. Whether the tab control is shown or not depends on the return value of a method inside the tab control. That means, the tab control decides itself by the rules the programmer provided, whether to show up or not. In this case, the rule is to show whenever a folder is selected, and to hide when the selection is an object.

The above example is a tab control that has no configurable parameters and therefore, the tab_control element has no configuration inside. Most tab controls are configurable.

Configuration of tab controls

• Relations tab control
• Contents tab controls

The functions element

The functions element contains the definitions of all context functions that are available for objects, folders, lists of objects and / or folders, and the session.

Basically, the configuration works much like the configuration of the tab controls. The functions element contains a list of function elements, where each one configures a context function that's available in the program.

Functions can be triggered by the following:

• The context menu that must be configured in the menu section of the configuration.
• Key events, as configured in the tab controls.
• Buttons in a button bar at the top of the window.
• Drag & drop events, asc configured in the tab controls (drag & drop is not yet functional).

The following example shows two function declarations, one without and one with parameters:

<function assembly="Praties" type="CancelCheckoutObjectFunction" />
<function assembly="Praties" type="CheckinObjectFunction">
  <custom>
    <default_versioning_behaviour checked_out_file="write" other_file="write" />
  </custom>
</function>

Structure of the menu element

Declaring a function in the functions element does not, by itself, add the function to a menu, nor link it with any other type of control. These connections must be made separately.

The menu element describes all context menus available.

The Cinnamon client has four different context domains:

• single objects
• single folders
• the session
• lists of objects and / or folders

All four domains have independent menu definitions. Since some functions provide functionality for more than one domain, it is common to reference the same function in more than one menu.

A menu declaration looks like this:

<menu>
  <object_context_menu>
    <menu_item assembly="Praties" type="CheckoutObjectFunction" />
    <menu_item assembly="Praties" type="CheckinObjectFunction" />
    <menu_item assembly="Praties" type="CancelCheckoutObjectFunction" />
    <separator />
    <menu_item assembly="Praties" type="OpenObjectFunction" />
    <menu_item assembly="Praties" type="CopyNameToClipboardObjectFunction" />
    <menu_item assembly="CinnamonEnterpriseClient" type="CreateNewVersionFunction" />
    <menu_item assembly="Praties" type="AppendContentObjectFunction" />
    <separator />
    <menu_item assembly="Praties" type="ExportObjectFunction" />
    ...
  </object_context_menu>
  <folder_context_menu>
    <menu_item assembly="Praties" type="CreateObjectWithoutContentFolderFunction" />
    ...
  </folder_context_menu>
  <list_context_menu>
    <menu_item assembly="Praties" type="CancelCheckoutListFunction" />
    ...
  </list_context_menu>
  <session_context_menu>
    <menu_item assembly="Praties" type="NewFolderSessionFunction" />
  </session_context_menu>
</menu>

The four domains are defined in the <domain>_context_menu elements. Menu items are declared in the order they should have in the menu. It is possible to add separators as required.

NOTE: The functions that are declared do not necessarily all appear in the menu on every selection. The functions have methods informing the client (based on the current selection) whether they should be displayed or not, and whether they should be active or inactive ("greyed out"). This behaviour is normally not subject to configuration, since functions are made for a specific purpose and context, and refuse to be used outside of their specification. For example, a "cancel checkout" function makes no sense on objects that are not checked out, and is therefore not active.