| Table of Contents |
|---|
What is content modeling
Systems of ECM class allow work with any content: documents, images, audio and video files, as well as files of any other types. Along with these files, such systems can save certain amount of additional information (metadata, attributes). In general case, an enterprise has its own set of document types (e.g. incoming documents, office memorandums, orders, …), and each type has its set of attributes (registration number, contractor, branch, responsible person, …). That's why an ECM system shall allow addition of new data types and attributes.
Alfresco ECM system allows it by the means of content modeling function. Alfresco administrator sets models (XML files), in which data types and their attributes are defined. The attributes also have some characteristics (mandatory status, default value etc.), which are also set during the modeling.
Who is engaged in content modeling
In EcoS In ECOS system models for a wide range of applications are already available. However, during the implementation of the system at any company it may occur that any types and attributes are lacking in standard models. In this case, implementing engineers shall know how to define new types and attributes and set required characteristic values for them.
Standard modeling options in Alfresco
The following can be defined in Alfresco models:
...
The models are XML files with following structure:
...
| Code Block |
|---|
<model name="letters:lettersModel" xmlns="http://www.alfresco.org/model/dictionary/1.0"> <description>Citeck EcoS letters</description> <author>Citeck</author> <version>1.0</version> <imports> … </imports> <namespaces> … </namespaces> <constraints> … </constraints> <types> … </types> <aspects> … </aspects> </aspect> |
Mandatory elements of a model are name, xmlns and namespaces. Practically, each model also has imported name spaces (imports) and type (types) or aspect (aspects) definitions, for which this model is intended.
Types
The model allows definition of data types (types). For example, ”Incoming document” type can be defined. For the type properties (e.g. reference number) and associations (e.g. contractor), as well as aspects (e.g. classified) can be defined.
...
| Code Block |
|---|
<type name="letters:income"> <title>Incoming</title> <description>Incoming Document</description> <parent>idocs:doc</parent> <properties> ... </properties> <associations> ... </associations> <overrides> ... </overrides> <mandatory-aspects> ... </mandatory-aspects> </type> |
Properties and associations
Properties and associations can be regarded as type attributes. The difference consists in the fact that properties refer to a primitive data type (string, number, date, …), and associations refer to data types defined in the models (incoming, legal entity, user, …).
...
Definitions of the properties are listed in properties section of the model. Mandatory elements of property definition are name and type, other elements can be omitted. Example:
| Code Block |
|---|
<property name="letters:deliveryMethod"> <title>Delivery Method</title> <type>d:text</type> <mandatory>true</mandatory> <multiple>false</multiple> <default>express</default> <constraints> ... </constraints> <index enabled="true"> … </index> </property> |
...
Definitions of the associations are listed in associations section of the model. Mandatory elements of each association are name and target.class. In the field target.class the required type or aspect of the target object shall be specified. Practically, absence of constraints for a source object (mandatory=false, many=true) are also specified.
| Code Block |
|---|
<association name="letters:addressee"> <title>Destinee</title> <source> <mandatory>false</mandatory> <many>true</many> </source> <target> <class>idocs:contractor</class> <mandatory>false</mandatory> <many>false</many> </target> </association> |
Elements source and target in an association definition stand for two linked objects. An association can be represented as an arrow linking two objects, then source is from where the arrow comes and target is where the arrow points. As it is clear from the definition, class shall be assigned for a target object and shall not be assigned for a source object. The reason is the fact that class for source object is type or object, in which this association is defined.
...
- if mandatory = true and many = true, than link arity is: 1…*;
- if mandatory = false and many = true, than link arity is: 0…*;
- if mandatory = false and many = false, than link arity is: 0…1;
- if mandatory = true and many = false, than link arity is: 1...1.
Child associations
Each association sets a link between two objects, and this link can be hierarchical of non-hierarchical. Associations that set a hierarchical link are called child associations, others are called peer associations. In child associations linked objects are parent and child, in peer associations they are just source and target object.
...
In the model, child associations are located in associations section, like common associations, but instead of association child-association is written:
| Code Block |
|---|
<child-association name="cm:contains"> <source> <mandatory>false</mandatory> <many>true</many> </source> <target> <class>sys:base</class> <mandatory>false</mandatory> <many>true</many> </target> <duplicate>false</duplicate> <propagateTimestamps>true</propagateTimestamps> </child-association> |
...
In case of child associations, source object stands for parent, and target object for child. The setting duplicate=false allows activation of name uniqueness control, and the setting propagateTimestamps=true allows activation of change time stamp propagation.
Aspects
Aspects allow adding supplementary properties and associations, as well as other aspects to the objects. In this respect, they are similar to types, but, unlike the types, an object can have multiple various aspects. An aspect can also have parent aspect, but, unlike the types, it is not mandatory. If type names are usually a noun (order, contract), aspect names are adjectives or verbs (classified, has an author).
Definitions of the aspects are listed in aspects section of the model. Each definition looks similar to type definition:
...
| Code Block |
|---|
<aspect name="letters:hasDelivery"> <title>…</title> <description>…</description> <parent>…</parent> <properties> ... </properties> <associations> ... </associations> <overrides> ... </overrides> <mandatory-aspects> ... </mandatory-aspects> </aspect> |
...
The only mandatory element of aspect definition is the name. An aspect can be created, which only has a name; such aspect is called marker aspect. By means of this, objects can be distinguished by presence or absence of such marker aspect. For example, standard model has an aspect cm:personDisabled, which is superposed to the object cm:person (user), if it is not active.
Names and name spaces
Each object determined in the model – including types, aspects, properties and associations, as well as the model itself – shall have a unique name (name). In order to prevent name conflicts, Alfresco uses name spaces (namespace): each name (of type, aspect, …) consists of two parts: name space and local name, and local name shall only be unique within its name space. Each model can define multiple name spaces, and each name within the model shall be contained in these name spaces.
...
If the model uses names from other models (it is an ordinary case), they are imported in the similar manner in imports section:
| Code Block |
|---|
<import uri="http://www.alfresco.org/model/dictionary/1.0" prefix="d" /> <import uri="http://www.alfresco.org/model/content/1.0" prefix="cm" /> |
...
Constraints
Constraints can be specified for property values (constraints). The following constraint types are supported in the models:
...
Example of a constraint set in the model:
...
| Code Block |
|---|
<constraint name="letters:deliveryMethod" type="LIST"> <parameter name="allowedValues"> <list> <value>snailmail</value> <value>courier</value> <value>fax</value> <value>express</value> </list> </parameter> </constraint> |
...
| Code Block |
|---|
<property name="letters:deliveryMethod"> ... <constraints> <constraint ref="letters:deliveryMethod" /> </constraints> </property> |
...
Redefinitions
Redefinitions allow specification of properties in child types or aspects.
...
Example of a redefinition that sets the property as mandatory:
| Code Block |
|---|
<overrides> <property name="letters:deliveryMethod"> <mandatory>true</mandatory> </property> </overrides> |
Localization of models
If model operation in one language is sufficient, attributes title and description can be used; they can be set for all named objects of the model: types, aspects, properties and associations.
| Code Block |
|---|
<type name="letters:income"> <title>Incoming</title> <description>Incoming Document</description> ... |
...
| Code Block |
|---|
listconstraint.letters_deliveryMethod.snailmail=Mail letters_lettersModel.type.letters_income.title=Incoming letters_lettersModel.property.letters_deliveryMethod.title=Delivery Method letters_lettersModel.association.letters_addressee.title=Destinee |
Heritage
It is a frequently appearing task to create the same property (association) in multiple various types. However, the mechanism of the models allows only one definition of each property (association), in any type or aspect. Therefore, in order to solve this problem, we have to involve heritage mechanism.
...
The main difference is that the parent type can be only one, and mandatory aspects can be multiple; that is why aspects are more convenient option for data structuring.
Downloading models
Actual Alfresco models are stored in RAM memory of the repository, so an XML file shall be downloaded in Alfresco in order to begin to work. The system offers two options to do this:
...
- put the model (e.g. file lettersModel.xml) in folder tomcat/shared/classes/alfresco/extension/model;
- put the localization (e.g. files letters*.properties) in folder tomcat/shared/classes/alfresco/extension/messages;
- create file tomcat/shared/classes/alfresco/extension/lettersModel-bootstrap-context.xml with the following content:
| Code Block |
|---|
<?xml version='1.0' encoding='UTF-8'?> <beans xmlns="http://www.springframework.org/schema/beans"> <bean id="letters.dictionaryBootstrap" parent="dictionaryModelBootstrap"> <property name="models"> <list> <value>alfresco/extension/model/lettersModel.xml</value> </list> </property> <property name="labels"> <list> <value>alfresco/extension/messages/letters</value> </list> </property> </bean> </beans> |
...
4. reboot Alfresco repository.
...
Dynamic downloading of a model (during repository operation) can be a little unstable. For example, nothing can be deleted from the model (types, properties etc.), only new ones can be added, and new constraints cannot be imposed (e.g. properties and associations cannot be set as mandatory and the list of mandatory objects cannot be completed). In order to do that, the model shall be unloaded and then deployed again. However, the model cannot be unloaded, if the repository contains objects with types or aspects set in this model; all these objects shall be deleted at first.
Official Alfresco documentation
You can find detailed information on content modeling by the means of Alfresco in official documentation of Alfresco and other resources.
...
In the section below we give some recommendations on modeling based on our experience.
Rules and recommendations
Name spaces
- A model can set multiple name spaces.
...
It is allowed to define a name from an imported name space, but it can lead to conflicts, if an object (e.g. property) with the same name is added in other model.
Naming
- Names should contain only Latin letters.
- Names of type and aspect should differ.
- It is recommended not to duplicate names of type (aspect) and associations.
...
- Conclusions from the above-mentioned information: it’s better to make all names unique. In order to achieve this you can develop some system for names formation.
- It is recommended to avoid creating mandatory constraints (mandatory), especially for associations.
Constraints
In case some mandatory association is programmed in a model, it is impossible to create an object without this association. If this constraint is applied after the creation of object (i.e. model has been updated), one might be totally unable to work with objects without this association.
...
Target-object of an association is usually regarded as an attribute. If constraints on a source-object are applied, it might make it impossible to create objects while some unclear messages about an error would be displayed. Absence of constraints on a source-object means that source.mandatory = false, source.many = true.
Inheritance
- It is mandatory for parent type and should be represented by another type.
...
In order to make a property inherited from aspect mandatory you can use functional of Citeck EcoS Citeck ECOS modeling.
Other
- Please don’t try to add new primitive data-type (data-type).
...
- Sequence order of elements plays an important role in models. For example, elements are placed in a model in the following order: imports, namespaces, constraints, types, aspects. Detailed information about elements order is in XSD-scheme of models, see the file modelSchema.xsd. If the order of elements is violated, you cannot read or download the model.
Modeling resources in
...
Citeck ECOS
What do Alfresco models lack?
Alfresco models make it possible to define new types and attributes but have some drawbacks. Some of the main drawbacks:
- a few attributes’ characteristics (mandatory, multiple, protected, default, title, description, constraints);
- characteristics can be set only as constants (true/false, line, number), expressions are not applicable;
- characteristics in associations are not fully supported (in particular, it’s impossible to set a default value or constraints);
- redefinitions are not fully supported (associations cannot be redifined; properties can be redefined only if its properties inherited from parent type/aspect).
System Citeck EcoS Citeck ECOS includes modeling resources that remedy all these drawbacks:
...
For this purpose functionality of invariants was developed in the Citeck EcoSECOS.
Definition of invariants
Invariant is some kind of affirmation about the attribute’s characteristic that should be true. An example of invariant: “property Number is mandatory if status of the document is not New”. In this example attribute is “Number”, characteristic is “mandatory”, affirmation is “mandatory if …”.
...
Different characteristics have implicit connection. For example, an irrelevant attribute (relevant = false) is always correct (valid = true). Value (value) of a multiple attribute (multiple = true) is an array; value of a single attribute (multiple = false) is a unit value. This rule as well as some other logical rules is encoded in Citeck EcoS Citeck ECOS in order to assist modeling process.
...
Languages JavaScript and FreeMarker are common for Alfresco; the system has quite diverse API for these languages. Criteria language is a search language, it’s added in EcoS ECOS in order to simplify search. It is an alternative for standard Alfresco languages that are used for search such as Lucene and FTS. Explicit language is just explicitly set constant values: true, false, free strings, numbers and values lists.
For example, invariant “property Number is mandatory if status of the document is not New” can be easily described in the language JavaScript:
| Code Block |
|---|
<property name="idocs:registrationNumber"> <invariant on="mandatory" language="javascript"> node.properties['idocs:documentStatus'] != 'new' </invariant> </property> |
...
Properties and methods of access available in invariants allow performing only reading operations, it is quite enough to set arbitrary expressions for invariants.
Files of invariants
Usage of invariants doesn’t mean that you don’t need to download models, vice versa, this option is extended. Invariants are downloaded to Alfresco as separate XML-files that accompany models’ files.
File of invariants has the following structure:
| Code Block |
|---|
<?xml version="1.0" encoding="UTF-8"?> <invariants xmlns="http://www.citeck.ru/ecos/invariants/1.0"> <imports> ... </imports> <!—definitions of invariants --> </invariants> <!—definitions of invariants --> |
...
Scopes can be freely inserted into each other, for example:
...
| Code Block |
|---|
<type name="type1"> <association name="assoc1"> <!—invariant definition for type1.assoc1 --> </association> <property name="prop1"> <!-- invariant definition for type1.prop1 --> </property> <properties type="d:text"> <!-- invariant definition for text properties in type1 --> </properties> </type> <property name="prop2"> <!-- invariant definition for *.prop2 --> <type name="type2"> <!-- invariant definition for type2.prop2 --> </type> <aspect name="aspect2"> <!-- invariant definition for aspect2.prop2 --> </ aspect > </property> |
...
| Code Block |
|---|
<import uri="http://www.alfresco.org/model/dictionary/1.0" prefix="d" /> <import uri="http://www.alfresco.org/model/content/1.0" prefix="cm" /> <import uri="http://www.citeck.ru/model/content/idocs/1.0" prefix="idocs" /> <import uri="http://www.citeck.ru/model/letters/1.0" prefix="letters" /> |
...
In the invariant itself you should specify for what characteristic (on) and in which language (language) this invariant is written. Expression in the specified language is placed as a text inside the element invariant.
...
Objects node, person, companyhome and userhome are the objects of the class Node that’s why these objects represent the same API for access (nodeRef, parent, properties, assocs, …).
Downloading of invariants
You can download invariants right after start of the server with the help of the bootstrap mechanism (similar to the models download method). In order to do so in the file *-context.xml please set the following strings:
...
| Code Block |
|---|
<bean parent="invariantsDeployer"> <property name="location" value="alfresco/extension/invariants/letters-invariants.xml" /> <property name="priority" value="EXTEND" /> </bean> |
...
- COMMON – most common priority, invariants for a wide variety of attributes;
- MODULE – priority of modules EcoS modules ECOS – invariants for attributes of different types of documents;
- EXTEND – extensions priority
- CUSTOM – implementations priority
Developers of EcoS of ECOS use priorities COMMON and MODULE, implementation engineers of EcoS of ECOS – priorities EXTEND and CUSTOM.
...
| Code Block |
|---|
<invariant on="…" language="…" final="true"> ... </invariant> |
Invariants processing
Support of invariants means that in certain parts of the system their values are calculated and taken into consideration in the logic of documents processing.
...
Invariants are also supported in the forms of the system EcoSECOS. Besides, expressions of invariants are calculated when user fulfills the form, thus, user can see at work all rules written in a form of invariants.
...
- first invariants with attribute final, then without it;
- first invariants for certain attributes (property, association), then for arbitrary attributes (properties, associations);
- first invariants with priority CUSTOM, then EXTEND, then MODULE, and finally COMMON;
- first invariants suitable for non-mandatory aspects of the object, then for type of the object, then for mandatory aspects of the type, then for parent type, then for mandatory aspects of the parent type, etc., and finally invariants without class constraints.
Criteria language
Criteria is a search language. It is very easy to specify invariants for characteristics value, default, options in attributes containing references to the repository objects (mainly they are associations) using this language. Expression in the criteria language is a search request that includes search criteria. Each criterion consists of three parts:
...
An example of the invariant defined in the criteria language:
| Code Block |
|---|
<type name="letters:income"> <property name="parent"> <invariant on="default" language="criteria"> <criterion attribute="path" predicate="path-equals" value="/app:company_home/st:sites/cm:letters/cm:documentLibrary/cm:income" /> </invariant> </property> </type> |
...
Insertions in the FreeMarker language can be added to the value, for example, the following invariants are set for the properties Type and Kind:
| Code Block |
|---|
<property name="tk:type">
<invariant on="options" language="criteria">
<criterion attribute="type" predicate="type-equals"
value="cm:category" />
<criterion attribute="parent" predicate="parent-equals"
value="workspace://SpacesStore/category-document-type-root" />
</invariant>
</property>
<property name="tk:kind">
<invariant on="options" language="criteria">
<criterion attribute="type" predicate="type-equals"
value="cm:category" />
<criterion attribute="parent" predicate="parent-equals"
value="${node.properties['tk:type'].nodeRef}" />
</invariant>
<invariant on="relevant" language="javascript">
node.properties["tk:type"] != null
</invariant>
</property> |
In other words the following values, possible for the property Type, are subcategories of the special category “category-document-root-type”; possible values for the property Kind are subcategories of the specified Type. In case a type isn’t specified, the property Kind isn’t relevant.