Content Model Configuration

Overview

Venzia Datalinks integrates with Alfresco Content Services through custom content model aspects. Each datalink requires a corresponding aspect in your Alfresco content model to store the reference to the external entity.

Content Model Structure

The Venzia Datalinks content model is defined in XML format following Alfresco’s content model schema:

<?xml version="1.0" encoding="UTF-8"?>

<model name="dlnk:venzia" xmlns="http://www.alfresco.org/model/dictionary/1.0">

   <description>Custom Model of Alfresco DataLink</description>
   <author>Venzia</author>
   <version>1.0</version>

   <imports>
      <import uri="http://www.alfresco.org/model/dictionary/1.0" prefix="d"/>
      <import uri="http://www.alfresco.org/model/content/1.0" prefix="cm"/>
   </imports>

   <namespaces>
      <namespace uri="http://venzia.es/model/datalink/1.0" prefix="dlnk"/>
   </namespaces>

   <aspects>
      <aspect name="dlnk:employee">
         <title>Employee</title>
          <properties>
            <property name="dlnk:employee">
               <type>d:text</type>
                <index enabled="true">
                    <atomic>true</atomic>
                    <stored>false</stored>
                    <tokenised>false</tokenised>
                </index>
            </property>
         </properties>
      </aspect>
      
      <aspect name="dlnk:departm">
         <title>Departm</title>
          <properties>
            <property name="dlnk:departm">
               <type>d:text</type>
                 <index enabled="true">
                    <atomic>true</atomic>
                    <stored>false</stored>
                    <tokenised>false</tokenised>
                </index>
            </property>
         </properties>
      </aspect>
   </aspects>
</model>

Model Elements

Model Declaration

model.name

string

required

Unique identifier for the content model. Convention is prefix:modelname.Example: "dlnk:venzia"

model.description

string

Human-readable description of the model’s purpose.Example: "Custom Model of Alfresco DataLink"

model.author

string

Organization or individual who created the model.Example: "Venzia"

model.version

string

Version number of the content model.Example: "1.0"

Imports

Required Alfresco base models must be imported:

<imports>
   <import uri="http://www.alfresco.org/model/dictionary/1.0" prefix="d"/>
   <import uri="http://www.alfresco.org/model/content/1.0" prefix="cm"/>
</imports>

These imports provide access to Alfresco’s standard data types (d:text, d:int, etc.) and content model structures (cm:content, cm:folder, etc.).

Namespace Declaration

namespace.uri

string

required

Unique URI that identifies your custom namespace. Should be a URL-like format.Example: "http://venzia.es/model/datalink/1.0"

namespace.prefix

string

required

Short prefix used in aspect and property names throughout the system.Example: "dlnk"

<namespaces>
   <namespace uri="http://venzia.es/model/datalink/1.0" prefix="dlnk"/>
</namespaces>

Aspect Definition

Each datalink requires a dedicated aspect in the content model. Aspects define properties that can be applied to documents.

Aspect Structure

<aspect name="dlnk:employee">
   <title>Employee</title>
    <properties>
      <property name="dlnk:employee">
         <type>d:text</type>
          <index enabled="true">
              <atomic>true</atomic>
              <stored>false</stored>
              <tokenised>false</tokenised>
          </index>
      </property>
   </properties>
</aspect>

Aspect Properties

aspect.name

string

required

Fully qualified name of the aspect using the namespace prefix.Format: prefix:localNameExample: "dlnk:employee", "dlnk:departm"

aspect.title

string

required

Human-readable title displayed in the Alfresco UI.Example: "Employee", "Departm"

Property Definition

Each aspect contains one property that stores the linked entity’s primary key value.

Property Elements

property.name

string

required

Fully qualified property name. Must match the aspectPropertyName in your datalink JSON configuration.Example: "dlnk:employee", "dlnk:departm"

property.type

string

required

Alfresco data type for the property. For datalinks, use d:text to store the primary key value.Options:

d:text - Text string (recommended for datalinks)
d:int - Integer number
d:long - Long number
d:boolean - Boolean value
d:date - Date/time value

Example: "d:text"

Index Configuration

The index element configures how Alfresco indexes the property for search:

<index enabled="true">
    <atomic>true</atomic>
    <stored>false</stored>
    <tokenised>false</tokenised>
</index>

index.enabled

boolean

default:"true"

Enable indexing for search functionality.Recommended: true

index.atomic

boolean

default:"true"

Index the entire value as a single unit. For primary keys, this should be true.Recommended: true

index.stored

boolean

default:"false"

Store the value in the search index. For properties stored in the database, this can be false.Recommended: false

index.tokenised

boolean

default:"false"

Break the value into tokens for full-text search. For primary keys, this should be false.Recommended: false

For datalink properties that store primary keys, use:

atomic: true
stored: false
tokenised: false

This ensures exact matching when searching for linked documents.

Deployment

AMP Module Structure

Content model XML files are deployed as part of an Alfresco Module Package (AMP):

venzia-datalink-module/
├── src/main/resources/
│   └── alfresco/
│       └── module/
│           └── aqua-datalink/
│               ├── model/
│               │   └── datalink-model.xml
│               └── module.properties

Module Properties

Ensure your module.properties includes:

module.id=aqua-datalink
module.version=1.0
module.title=Venzia Datalinks
module.description=Content model for Venzia Datalinks integration

Model Deployment Location

Place your content model XML file at:alfresco/module/{module-id}/model/datalink-model.xmlAlfresco automatically loads models from this location on startup.

Linking Aspects to Datalinks

The connection between content model aspects and datalink JSON configurations is established through naming:

Define the Aspect

Create an aspect in your content model XML:

<aspect name="dlnk:employee">
  <title>Employee</title>
  <properties>
    <property name="dlnk:employee">
      <type>d:text</type>
    </property>
  </properties>
</aspect>

Reference in Datalink JSON

Use the same aspect name in your datalink configuration:

{
  "name": "employee",
  "aspectName": "dlnk:employee",
  "aspectPropertyName": "dlnk:employee"
}

Apply to Documents

Users can now apply the dlnk:employee aspect to documents in Alfresco Share, which activates the Venzia Datalinks widget.

Creating Custom Aspects

To create a new datalink aspect:

Step-by-Step: Creating a Customer Datalink

1. Add aspect to content model XML:

<aspect name="dlnk:customer">
   <title>Customer</title>
    <properties>
      <property name="dlnk:customer">
         <type>d:text</type>
          <index enabled="true">
              <atomic>true</atomic>
              <stored>false</stored>
              <tokenised>false</tokenised>
          </index>
      </property>
   </properties>
</aspect>

2. Create corresponding datalink JSON file:

{
  "name": "customer",
  "title": "Customer",
  "aspectName": "dlnk:customer",
  "aspectPropertyName": "dlnk:customer",
  "connectorRest": {
    "url": "http://api.example.com/customers/search"
  },
  "columns": [
    {
      "primaryKey": true,
      "name": "customer_id",
      "label": "ID",
      "type": "text",
      "hidden": true
    },
    {
      "primaryKey": false,
      "name": "company_name",
      "label": "Company",
      "type": "text"
    }
  ]
}

3. Deploy and restart Alfresco

Best Practices

Consistent Naming

Use the same name for aspect and property (e.g., dlnk:employee for both)

Text Data Type

Always use d:text for datalink properties to store primary keys

Disable Tokenization

Set tokenised: false to ensure exact matching of linked IDs

Version Control

Increment model version when making changes to deployed aspects

Advanced Configuration

Multiple Properties per Aspect

While datalinks typically use a single property, you can add additional properties to store metadata:

<aspect name="dlnk:employee">
   <title>Employee</title>
    <properties>
      <property name="dlnk:employee">
         <type>d:text</type>
      </property>
      <property name="dlnk:employeeName">
         <type>d:text</type>
      </property>
      <property name="dlnk:employeeDepartment">
         <type>d:text</type>
      </property>
   </properties>
</aspect>

Only the property specified in aspectPropertyName is managed by Venzia Datalinks. Additional properties can be used for custom business logic or reporting.

Mandatory vs Optional Aspects

You can make aspect properties mandatory:

<property name="dlnk:employee">
   <type>d:text</type>
   <mandatory>true</mandatory>
</property>

Making datalink properties mandatory will prevent users from saving documents without linking an entity. Use with caution.

Troubleshooting

Aspect not available in Alfresco Share

Property value not saved

Possible causes:

Property name mismatch between aspect and datalink JSON
Property type incompatible with data being stored

Solution: Verify aspectPropertyName in JSON matches property name in XML.

Search not returning linked documents

Possible causes:

Index configuration incorrect (tokenised: true or atomic: false)
Solr index not updated

Solution: Check index configuration and trigger Solr reindex if needed.

Next Steps

Datalink JSON Schema

Learn how to configure datalink JSON files

REST Connector Setup

Configure REST API authentication and integration

Getting Started

Configuration

Usage Guide

Components

Development

Overview

Content Model Structure

Model Elements

Model Declaration

Imports

Namespace Declaration

Aspect Definition

Aspect Structure

Aspect Properties

Property Definition

Property Elements

Index Configuration

Deployment

AMP Module Structure

Module Properties

Model Deployment Location

Linking Aspects to Datalinks

Creating Custom Aspects

Best Practices

Consistent Naming

Text Data Type

Disable Tokenization

Version Control

Advanced Configuration

Multiple Properties per Aspect

Mandatory vs Optional Aspects

Troubleshooting

Next Steps

Datalink JSON Schema

REST Connector Setup

Build docs developers (and LLMs) love

Getting Started

Configuration

Usage Guide

Components

Development

​Overview

​Content Model Structure

​Model Elements

​Model Declaration

​Imports

​Namespace Declaration

​Aspect Definition

​Aspect Structure

​Aspect Properties

​Property Definition

​Property Elements

​Index Configuration

​Deployment

​AMP Module Structure

​Module Properties

​Model Deployment Location

​Linking Aspects to Datalinks

​Creating Custom Aspects

​Best Practices

Consistent Naming

Text Data Type

Disable Tokenization

Version Control

​Advanced Configuration

​Multiple Properties per Aspect

​Mandatory vs Optional Aspects

​Troubleshooting

​Next Steps

Datalink JSON Schema

REST Connector Setup

Build docs developers (and LLMs) love

Overview

Content Model Structure

Model Elements

Model Declaration

Imports

Namespace Declaration

Aspect Definition

Aspect Structure

Aspect Properties

Property Definition

Property Elements

Index Configuration

Deployment

AMP Module Structure

Module Properties

Model Deployment Location

Linking Aspects to Datalinks

Creating Custom Aspects

Best Practices

Advanced Configuration

Multiple Properties per Aspect

Mandatory vs Optional Aspects

Troubleshooting

Next Steps