Quick Start

Overview

This guide will walk you through creating your first datalink and linking document properties to database values. We’ll use the included employee datalink example to demonstrate the workflow.

Before starting, ensure you have completed the installation steps and have all three components running.

Prerequisites Checklist

Verify all services are running:

Alfresco Repository

Check that Alfresco is accessible at http://localhost:8080/alfresco/Default credentials: admin / admin

Database Mock Server

Verify the mock database is running on port 3005:

curl http://localhost:3005
# Should return: Venzia employee db mockup

Alfresco Content App

Access ACA at http://localhost:4200 and log in with Alfresco credentials

Your First Datalink

Step 1: Verify Datalink Configuration

The employee datalink is already configured in the system. Let’s verify it’s loaded:

curl http://localhost:8080/alfresco/s/venzia/datalink/v1/datalinks

You should see a JSON response with available datalinks:

[
  {
    "name": "employee",
    "title": "Company Employee",
    "aspectName": "dlnk:employee",
    "order": 10
  },
  {
    "name": "departments",
    "title": "Company Departments",
    "aspectName": "dlnk:departm",
    "order": 20
  }
]

Understanding the Employee Datalink Configuration

The employee datalink is defined in venzia-datalink/src/main/docker/datalink/datalink-employee.json:

{
  "name": "employee",
  "title": "Company Employee",
  "description": "Example to datalink demo",
  "aspectName": "dlnk:employee",
  "aspectPropertyName": "dlnk:employee",
  "order": 10,
  "connectorRest": {
    "url": "http://localhost:3005/api/v1/public/employees/search",
    "authentication": {
      "type": "none"
    },
    "searchParam": "query"
  },
  "columns": [
    {
      "primaryKey": true,
      "name": "emp_no",
      "label": "Id",
      "type": "text",
      "hidden": true
    },
    {
      "name": "first_name",
      "label": "First Name",
      "type": "text"
    },
    {
      "name": "last_name",
      "label": "Last Name",
      "type": "text"
    },
    {
      "name": "hire_date",
      "label": "Hire Date",
      "type": "date",
      "format": "dd/MM/yyyy"
    }
  ]
}

Key Points:

Connects to a public endpoint (no authentication)
Maps to the dlnk:employee aspect
Displays employee name and hire date
Uses emp_no as the primary key (hidden from users)

Step 2: Upload a Test Document

In Alfresco Content App:

Navigate to a Folder

Go to Personal Files or any folder where you have write permissions

Upload a Document

Click the Upload button or drag and drop a fileAny file type works—try a PDF, Word document, or text file

Verify Upload

Confirm the document appears in the file list

Step 3: Link Employee Data to Document

Now let’s link the document to an employee record:

Open Datalink Editor

Right-click on the uploaded document and select Edit Datalink from the context menu

If you don’t see the “Edit Datalink” option, verify that the ACA extension is properly loaded and that you’re using the correct version of ACA.

Select Employee Datalink

In the datalink editor dialog:

Choose Company Employee from the datalink type dropdown
The form will load dynamically based on the datalink configuration

Search for an Employee

Start typing an employee name in the search field:

Try searching for “Adolfo”

The system queries the REST endpoint:

http://localhost:3005/api/v1/public/employees/search?query=Adolfo

Results appear in a searchable list showing:
- First Name
- Last Name
- Hire Date

Select and Save

Click on an employee from the search results
Review the selected employee information
Click Save to apply the datalink to the document

The document now has the dlnk:employee aspect applied with the linked employee data

Step 4: Verify the Linked Data

Confirm that the datalink was applied successfully:

Via ACA UI
Via REST API

Select the document in ACA
Open the Info Drawer (click the info icon)
Expand the Properties section
Look for the Employee aspect properties
You should see the linked employee ID stored in dlnk:employee

Get the document properties via the Alfresco REST API:

# Replace NODE_ID with your document's node ID
curl -u admin:admin \
  "http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/NODE_ID?include=properties"

Look for the dlnk:employee property in the response:

{
  "entry": {
    "properties": {
      "dlnk:employee": "1",
      "cm:name": "my-document.pdf"
    }
  }
}

Try the Department Datalink

Now let’s try the department datalink, which uses basic authentication:

Right-Click the Same Document

Open the datalink editor again by right-clicking on your test document

Select Department Datalink

Choose Company Departments from the dropdown

Search Departments

Search for a department:

Try “Recursos” or “Marketing”
This endpoint uses basic authentication (configured in the datalink JSON)
Credentials: user2019 / g3n3r4l

Apply Department Link

Select a department and saveThe document now has both aspects:

dlnk:employee
dlnk:departm

A document can have multiple datalink aspects applied simultaneously, allowing you to link different types of data to the same document.

Test the Mock Database

Let’s understand what’s happening behind the scenes:

Employee Endpoint (Public)

# Get all employees
curl http://localhost:3005/api/v1/public/employees/search

# Search for specific employee
curl "http://localhost:3005/api/v1/public/employees/search?query=Ana"

Sample Response

[
  {
    "emp_no": 8,
    "first_name": "Ana",
    "last_name": "Cuesta",
    "hire_date": "2002-03-25T00:00:00.000Z"
  },
  {
    "emp_no": 3,
    "first_name": "Anastasia",
    "last_name": "Lopez",
    "hire_date": "1999-11-04T00:00:00.000Z"
  }
]

Department Endpoint (Authenticated)

# Get all departments (requires auth)
curl -u user2019:g3n3r4l \
  http://localhost:3005/api/v1/private/departments/search

# Search for specific department
curl -u user2019:g3n3r4l \
  "http://localhost:3005/api/v1/private/departments/search?query=Marketing"

Sample Response

[
  {
    "dept_no": 6,
    "dept_name": "Marketing"
  }
]

Create a Custom Datalink

Now let’s create your own datalink configuration:

Create Configuration File

Create a new JSON file in the datalink configuration directory:

cd venzia-datalink/src/main/docker/datalink

Create datalink-project.json:

{
  "name": "project",
  "title": "Project Codes",
  "description": "Link documents to project codes",
  "aspectName": "dlnk:project",
  "aspectPropertyName": "dlnk:project",
  "order": 30,
  "connectorRest": {
    "url": "https://your-api.example.com/api/projects",
    "authentication": {
      "type": "basic",
      "username": "api_user",
      "password": "api_password"
    },
    "searchParam": "search"
  },
  "columns": [
    {
      "primaryKey": true,
      "name": "project_id",
      "label": "Project ID",
      "type": "text",
      "hidden": true
    },
    {
      "primaryKey": false,
      "name": "project_code",
      "label": "Code",
      "type": "text"
    },
    {
      "primaryKey": false,
      "name": "project_name",
      "label": "Project Name",
      "type": "text"
    },
    {
      "primaryKey": false,
      "name": "start_date",
      "label": "Start Date",
      "type": "date",
      "format": "dd/MM/yyyy"
    }
  ]
}

Add Content Model Aspect

Edit the content model to add the new aspect:Open venzia-datalink/src/main/resources/alfresco/module/aqua-datalink/model/datalink-model.xmlAdd the new aspect:

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

Rebuild and Restart

Rebuild the backend module and restart Alfresco:

cd venzia-datalink
./run.sh reload_acs

This will:

Rebuild the ACS module
Recreate the ACS Docker image
Restart the ACS container with the new configuration

Verify New Datalink

Check that the new datalink is available:

curl http://localhost:8080/alfresco/s/venzia/datalink/v1/datalinks

You should see your new “project” datalink in the list.

Configuration Options

Authentication Types

No Authentication
Basic Authentication

"authentication": {
  "type": "none"
}

"authentication": {
  "type": "basic",
  "username": "your_username",
  "password": "your_password"
}

Column Types

Text

{
  "name": "field_name",
  "label": "Display Label",
  "type": "text"
}

Date

{
  "name": "date_field",
  "label": "Date",
  "type": "date",
  "format": "dd/MM/yyyy"
}

Primary Key

{
  "primaryKey": true,
  "name": "id",
  "label": "ID",
  "type": "text",
  "hidden": true
}

Required Response Format

Your REST API endpoint must return an array of objects:

[
  {
    "field_name_1": "value1",
    "field_name_2": "value2",
    "date_field": "2024-01-15"
  },
  {
    "field_name_1": "value3",
    "field_name_2": "value4",
    "date_field": "2024-02-20"
  }
]

The field names in your API response must exactly match the name values in your datalink column definitions.

Common Use Cases

HR Document Management

Scenario: Link employee documents (contracts, evaluations) to HR databaseConfiguration:

{
  "name": "employee",
  "aspectName": "dlnk:employee",
  "connectorRest": {
    "url": "https://hr-system.company.com/api/employees",
    "authentication": {"type": "basic", "username": "...", "password": "..."}
  },
  "columns": [
    {"name": "employee_id", "primaryKey": true, "hidden": true},
    {"name": "full_name", "label": "Employee Name"},
    {"name": "department", "label": "Department"},
    {"name": "position", "label": "Position"}
  ]
}

Customer Documents

Scenario: Link customer documents to CRM systemConfiguration:

{
  "name": "customer",
  "aspectName": "dlnk:customer",
  "connectorRest": {
    "url": "https://crm.company.com/api/customers/search",
    "authentication": {"type": "basic", "username": "...", "password": "..."}
  },
  "columns": [
    {"name": "customer_id", "primaryKey": true, "hidden": true},
    {"name": "customer_name", "label": "Customer"},
    {"name": "account_number", "label": "Account #"},
    {"name": "contact_email", "label": "Email"}
  ]
}

Product Documentation

Scenario: Link product specs and manuals to product databaseConfiguration:

{
  "name": "product",
  "aspectName": "dlnk:product",
  "connectorRest": {
    "url": "https://products.company.com/api/products",
    "authentication": {"type": "none"}
  },
  "columns": [
    {"name": "sku", "primaryKey": true, "label": "SKU"},
    {"name": "product_name", "label": "Product Name"},
    {"name": "category", "label": "Category"},
    {"name": "release_date", "type": "date", "label": "Release Date"}
  ]
}

Troubleshooting

Datalink Not Appearing in List

Problem: New datalink doesn’t show up in the dropdownSolutions:

Verify JSON syntax is valid
Check the datalink file is in src/main/docker/datalink/
Ensure the aspect exists in the content model
Restart ACS: ./run.sh reload_acs
Check Alfresco logs for errors

Verify via API:

curl http://localhost:8080/alfresco/s/venzia/datalink/v1/datalinks

Can't Connect to REST Endpoint

Problem: Search returns no results or connection errorsSolutions:

Test endpoint directly with curl:

curl "http://your-api.com/endpoint?query=test"

Check authentication credentials
Verify URL is accessible from Docker container
For localhost endpoints, use host networking or host.docker.internal
Check for CORS issues
Review ACS logs for connection errors

Wrong Data Displayed

Problem: Datalink shows incorrect or missing informationSolutions:

Verify API response format matches column definitions
Check that field names are exactly the same
Ensure primaryKey is set on one column

Test API response:

curl "http://localhost:3005/api/v1/public/employees/search" | jq

Verify column types match data types (text, date, etc.)

Authentication Fails

Problem: 401 Unauthorized errorsSolutions:

Verify credentials in datalink JSON

Test authentication manually:

curl -u username:password http://your-api.com/endpoint

Check authentication type is correct (“basic”, “none”)
For the mock database, use user2019 / g3n3r4l
Review API server logs for auth errors

Next Steps

Configuration Reference

Detailed reference for all datalink configuration options

API Reference

Explore the Datalinks REST API and services

Content Models

Learn about custom aspects and content model design

Usage Guide

Learn how to use datalinks in Alfresco Content App

Get Help

If you need assistance:

Getting Started

Configuration

Usage Guide

Components

Development

Overview

Prerequisites Checklist

Your First Datalink

Step 1: Verify Datalink Configuration

Step 2: Upload a Test Document

Step 3: Link Employee Data to Document

Step 4: Verify the Linked Data

Try the Department Datalink

Test the Mock Database

Employee Endpoint (Public)

Department Endpoint (Authenticated)

Create a Custom Datalink

Configuration Options

Authentication Types

Column Types

Text

Date

Primary Key

Required Response Format

Common Use Cases

Troubleshooting

Next Steps

Configuration Reference

API Reference

Content Models

Usage Guide

Get Help

Build docs developers (and LLMs) love

Getting Started

Configuration

Usage Guide

Components

Development

​Overview

​Prerequisites Checklist

​Your First Datalink

​Step 1: Verify Datalink Configuration

​Step 2: Upload a Test Document

​Step 3: Link Employee Data to Document

​Step 4: Verify the Linked Data

​Try the Department Datalink

​Test the Mock Database

​Employee Endpoint (Public)

​Department Endpoint (Authenticated)

​Create a Custom Datalink

​Configuration Options

​Authentication Types

​Column Types

Text

Date

Primary Key

​Required Response Format

​Common Use Cases

​Troubleshooting

​Next Steps

Configuration Reference

API Reference

Content Models

Usage Guide

​Get Help

Build docs developers (and LLMs) love

Overview

Prerequisites Checklist

Your First Datalink

Step 1: Verify Datalink Configuration

Step 2: Upload a Test Document

Step 3: Link Employee Data to Document

Step 4: Verify the Linked Data

Try the Department Datalink

Test the Mock Database

Employee Endpoint (Public)

Department Endpoint (Authenticated)

Create a Custom Datalink

Configuration Options

Authentication Types

Column Types

Required Response Format

Common Use Cases

Troubleshooting

Next Steps

Get Help