Skip to main content

​
Overview

Datalink JSON files define the connection between Alfresco content model aspects and external REST API data sources. Each JSON file represents a single datalink configuration.

​
File Structure

Datalink JSON files must be valid JSON documents with the following top-level structure: 
{
  "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",
      "username": "user2019",
      "password": "g3n3r4l"
    },
    "searchParam": "query"
  },
  "columns": [
    {
      "primaryKey": true,
      "name": "emp_no",
      "label": "Id",
      "type": "text",
      "hidden": true
    },
    {
      "primaryKey": false,
      "name": "first_name",
      "label": "First Name",
      "type": "text"
    },
    {
      "primaryKey": false,
      "name": "last_name",
      "label": "Last Name",
      "type": "text"
    },
    {
      "primaryKey": false,
      "name": "hire_date",
      "label": "Hire Date",
      "type": "date",
      "format": "dd/MM/yyyy"
    }
  ]
}

​
Schema Reference

​
Root Properties

​
name
string
required
Unique identifier for the datalink. Used internally and must be unique across all datalink configurations.Example: "employee", "departments"
​
title
string
required
Human-readable display name shown in the Alfresco Share UI.Example: "Company Employee", "Company Departments"
​
description
string
Optional description of the datalink’s purpose and usage.Example: "Example to datalink demo"
​
aspectName
string
required
Fully qualified name of the Alfresco content model aspect that this datalink binds to. Must match an aspect defined in your content model XML.Format: prefix:localNameExample: "dlnk:employee", "dlnk:departm"
​
aspectPropertyName
string
required
The property within the aspect where the linked entity’s primary key value will be stored.Example: "dlnk:employee", "dlnk:departm"
​
order
integer
Display order for multiple datalinks on the same document. Lower numbers appear first.Default: 0Example: 10, 20
​
connectorRest
object
required
Configuration object for the REST API connector. See REST Connector Configuration below.
​
columns
array
required
Array of column definitions that map REST API response fields to displayable columns. See Column Configuration below.

​
REST Connector Configuration

The connectorRest object defines how to connect to the external REST API:
​
connectorRest.url
string
required
Full URL of the REST API endpoint for searching entities. This endpoint should accept a search query parameter and return a JSON array of results.Example: "http://localhost:3005/api/v1/public/employees/search"
​
connectorRest.searchParam
string
default:"query"
The URL query parameter name used to send the user’s search text.Default: "query"Example: If searchParam is "query", searches become: ?query=John
​
connectorRest.authentication
object
Authentication configuration for the REST API. See REST Connectors for detailed authentication options.

​
Column Configuration

The columns array defines which fields from the REST API response should be displayed and how:
​
columns[].name
string
required
The field name from the REST API JSON response. Must exactly match the property name in the API response.Example: "emp_no", "first_name", "dept_no"
​
columns[].label
string
required
Human-readable column header displayed in the Alfresco Share UI.Example: "Id", "First Name", "Hire Date"
​
columns[].type
string
required
Data type of the column. Affects formatting and display.Options:
  • "text" - Plain text (default)
  • "date" - Date/time values (requires format property)
  • "number" - Numeric values
  • "boolean" - True/false values
Example: "text", "date"
​
columns[].primaryKey
boolean
required
Indicates whether this column contains the unique identifier for the entity. Exactly one column must have primaryKey: true.Example: true for "emp_no", false for other columns
​
columns[].hidden
boolean
default:"false"
If true, the column value is stored but not displayed in the UI. Typically used for primary key fields.Example: true for ID columns, false for display columns
​
columns[].format
string
Date format pattern for type: "date" columns. Uses Java SimpleDateFormat syntax.Example: "dd/MM/yyyy", "yyyy-MM-dd'T'HH:mm:ss"Common patterns:
  • dd/MM/yyyy - 25/12/2023
  • MM-dd-yyyy - 12-25-2023
  • yyyy-MM-dd - 2023-12-25

​
Validation Rules

Datalink configurations are validated on startup. Invalid configurations will prevent the datalink from loading.

​
Required Fields

The following fields are mandatory:
  • name
  • title
  • aspectName
  • aspectPropertyName
  • connectorRest.url
  • columns (must contain at least one column)

​
Primary Key Requirements

Exactly one column must have primaryKey: true. This column’s value is stored in the aspect property and used to maintain the link between the document and external entity.

​
Aspect Name Validation

The aspectName must:
  • Match an aspect defined in a deployed Alfresco content model
  • Follow the format prefix:localName
  • Use a registered namespace prefix

​
Column Name Restrictions

Column names must:
  • Match exactly with REST API response field names (case-sensitive)
  • Not contain spaces or special characters (except underscore)
  • Be unique within the columns array

​
API Response Format

The REST API endpoint must return a JSON array of objects. Each object should contain properties matching the column names defined in your datalink configuration. 
[
  {
    "emp_no": "10001",
    "first_name": "John",
    "last_name": "Doe",
    "hire_date": "15/01/2020"
  },
  {
    "emp_no": "10002",
    "first_name": "Jane",
    "last_name": "Smith",
    "hire_date": "22/03/2019"
  }
]

​
Complete Configuration Example

Here’s a complete datalink configuration with all available options: 
{
  "name": "employee",
  "title": "Company Employee",
  "description": "Link documents to company employees",
  "aspectName": "dlnk:employee",
  "aspectPropertyName": "dlnk:employee",
  "order": 10,
  "connectorRest": {
    "url": "http://localhost:3005/api/v1/public/employees/search",
    "authentication": {
      "type": "none",
      "username": "user2019",
      "password": "g3n3r4l"
    },
    "searchParam": "query"
  },
  "columns": [
    {
      "primaryKey": true,
      "name": "emp_no",
      "label": "Id",
      "type": "text",
      "hidden": true
    },
    {
      "primaryKey": false,
      "name": "first_name",
      "label": "First Name",
      "type": "text"
    },
    {
      "primaryKey": false,
      "name": "last_name",
      "label": "Last Name",
      "type": "text"
    },
    {
      "primaryKey": false,
      "name": "hire_date",
      "label": "Hire Date",
      "type": "date",
      "format": "dd/MM/yyyy"
    }
  ]
}

​
Best Practices

Use Descriptive Names

Choose clear, meaningful names for datalinks that reflect the business entity type

Hide Primary Keys

Set hidden: true for technical ID columns that users don’t need to see

Set Display Order

Use the order property to control how multiple datalinks appear on documents

Validate JSON

Use a JSON validator before deployment to catch syntax errors early

​
Troubleshooting

Possible causes:
  • REST API endpoint is unreachable
  • Authentication credentials are incorrect
  • Column names don’t match API response fields
  • API returns data in unexpected format
Solution: Test the API endpoint directly and verify the response structure.
Possible causes:
  • Missing format property for date columns
  • Format pattern doesn’t match API date format
Solution: Verify the date format from API and use correct SimpleDateFormat pattern.

​
Next Steps

Content Models

Learn how to define Alfresco aspects for your datalinks

REST Connectors

Configure authentication and advanced REST API options

Build docs developers (and LLMs) love

Get started for freeTalk to us