Skip to main content

​
Introduction

Venzia Datalinks uses a JSON-based configuration system to define external data sources and their integration with Alfresco Content Services. Each datalink connects a REST API endpoint to an Alfresco content model aspect, enabling documents to be linked with external entities.

​
Configuration Components

A complete Venzia Datalinks implementation consists of three key components:

Datalink JSON Files

Define data source connections, REST endpoints, and column mappings

Content Models

Alfresco XML models that define aspects and properties for linked data

REST Connectors

HTTP client configuration including authentication and API integration

​
File Locations

Datalink definition files are stored in the deployment directory: 
/datalink/
├── datalink-employee.json
├── datalink-department.json
└── [custom-datalink].json
In Docker deployments, these files are typically mounted at /usr/local/tomcat/datalink/ or configured via the datalink.path system property.

​
Content Model XML

Alfresco content models are deployed as AMP module resources: 
alfresco/module/aqua-datalink/model/
└── datalink-model.xml

​
Configuration Workflow

1

Define Content Model

Create Alfresco aspects in your custom content model XML file. Each aspect represents an external entity type (employee, department, etc.).
2

Create Datalink JSON

Define the datalink configuration file that maps the aspect to a REST API endpoint and specifies column definitions.
3

Configure REST Connector

Set up the REST API connection details including URL, authentication, and search parameters.
4

Deploy and Test

Deploy the configuration files and verify the datalink appears in the Alfresco Share document details page.

​
Configuration Validation

Venzia Datalinks validates configuration files on startup:
  • JSON Schema: All datalink JSON files must conform to the expected schema
  • Aspect Reference: The aspectName must exist in the deployed content model
  • Primary Key: At least one column must be marked as primaryKey: true
  • REST Endpoint: The connector URL must be accessible and return valid JSON
Invalid configurations will prevent the datalink from loading. Check the Alfresco logs for detailed error messages.
Here’s how the three components work together for an employee datalink:

​
1. Content Model Aspect

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

{
  "name": "employee",
  "aspectName": "dlnk:employee",
  "aspectPropertyName": "dlnk:employee",
  "connectorRest": {
    "url": "http://localhost:3005/api/v1/public/employees/search"
  }
}

​
3. Document Linkage

When a user applies the dlnk:employee aspect to a document, the Venzia Datalinks widget appears, allowing them to search and link employees from the external REST API.

​
System Properties

Configure Venzia Datalinks behavior using Alfresco global properties:
​
datalink.path
string
default:"/usr/local/tomcat/datalink/"
Directory path containing datalink JSON configuration files
​
datalink.enabled
boolean
default:"true"
Enable or disable the Venzia Datalinks module globally
​
datalink.cache.ttl
integer
default:"300"
Cache time-to-live in seconds for REST API responses

​
Next Steps

Datalink JSON Schema

Complete reference for all JSON configuration options

REST Connector Setup

Configure authentication and API integration

Build docs developers (and LLMs) love

Get started for freeTalk to us