REST Connector Configuration - Venzia Datalinks

Overview

The REST connector is the bridge between Venzia Datalinks and external data sources. Each datalink uses a REST connector to query external APIs and retrieve entity data for linking to Alfresco documents.

Connector Configuration

The REST connector is defined within the connectorRest object in your datalink JSON file:

{
  "connectorRest": {
    "url": "http://localhost:3005/api/v1/public/employees/search",
    "authentication": {
      "type": "none",
      "username": "user2019",
      "password": "g3n3r4l"
    },
    "searchParam": "query"
  }
}

Configuration Properties

URL Configuration

url

string

required

Full HTTP(S) URL of the REST API endpoint that handles search requests.The endpoint must:

Accept GET requests with a query parameter
Return a JSON array of entity objects
Be accessible from the Alfresco server

Examples:

http://localhost:3005/api/v1/public/employees/search
https://api.example.com/v2/departments/search
http://internal-api:8080/entities/find

The URL should point to a search endpoint, not a direct entity retrieval endpoint. Users will enter search terms in the Alfresco Share UI, and the connector will append them as query parameters.

Search Parameter

searchParam

string

default:"query"

The query parameter name used to send the user’s search input to the API.Default: "query"Example: With searchParam: "query", user search for “John” becomes:

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

With searchParam: "search", the same search becomes:

GET http://localhost:3005/api/v1/public/employees/search?search=John

Authentication Configuration

The authentication object defines how the connector authenticates with the external API.

authentication.type

string

required

Authentication method used for API requests.Supported values:

"none" - No authentication (public API)
"basic" - HTTP Basic Authentication

Example: "basic"

No Authentication

For public APIs that don’t require authentication:

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

Even when type is "none", the username and password fields may be present in configuration files but are ignored by the connector.

Basic Authentication

For APIs requiring HTTP Basic Authentication:

{
  "authentication": {
    "type": "basic",
    "username": "user2019",
    "password": "g3n3r4l"
  }
}

authentication.username

string

Username for Basic Authentication. Required when type: "basic".Example: "user2019"

authentication.password

string

Password for Basic Authentication. Required when type: "basic".Example: "g3n3r4l"

Basic Authentication credentials are stored in plain text in the JSON configuration file. Ensure proper file system permissions are set to protect sensitive credentials.

API Response Format

Expected Response Structure

The REST API must return a JSON array of objects. Each object represents one searchable entity:

[
  {
    "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"
  }
]

Response Requirements

JSON Array

Response must be a JSON array, even for single results

Matching Fields

Object properties must match column names in datalink configuration

Primary Key

Each object must include the primary key field defined in columns

Consistent Structure

All objects should have the same property structure

Complete Examples

Employee Datalink with Public API

{
  "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"
    }
  ]
}

Department Datalink with Basic Authentication

{
  "name": "departments",
  "title": "Company Departments",
  "description": "Example to datalink demo",
  "aspectName": "dlnk:departm",
  "aspectPropertyName": "dlnk:departm",
  "order": 20,
  "connectorRest": {
    "url": "http://localhost:3005/api/v1/private/departments/search",
    "authentication": {
      "type": "basic",
      "username": "user2019",
      "password": "g3n3r4l"
    },
    "searchParam": "query"
  },
  "columns": [
    {
      "primaryKey": true,
      "name": "dept_no",
      "label": "Id",
      "type": "text",
      "hidden": true
    },
    {
      "primaryKey": false,
      "name": "dept_name",
      "label": "Name",
      "type": "text"
    }
  ]
}

Request Flow

Here’s how a search request flows through the connector:

User Enters Search

User types search text (e.g., “John”) in the Venzia Datalinks widget in Alfresco Share

Connector Builds Request

Venzia Datalinks constructs the HTTP request:

Method: GET
URL: Configured url + ? + searchParam + = + user input
Headers: Authentication headers if configured

API Returns Results

External API processes the search and returns JSON array of matching entities

Display Results

Venzia Datalinks parses the response and displays matching entities according to column configuration

User Links Entity

User selects an entity, and its primary key is stored in the document’s aspect property

Security Best Practices

Use HTTPS

Always use HTTPS URLs for production APIs to encrypt credentials in transit

Restrict File Access

Set proper file permissions on JSON configuration files (chmod 600)

Network Security

Use firewall rules to restrict API access to Alfresco server IPs only

Credential Rotation

Regularly rotate API credentials and update configuration files

Security Considerations:

Credentials are stored in plain text in configuration files
Ensure JSON files are not accessible via web server
Use service accounts with minimal required permissions
Consider using API keys or tokens instead of user credentials

Testing REST Connectors

Manual Testing with curl

Test your API endpoint before configuring it in Venzia Datalinks:

curl "http://localhost:3005/api/v1/public/employees/search?query=John"

Verifying Response Format

Ensure the API response matches your column configuration:

Example: Validating Employee API Response

Your column configuration:

"columns": [
  {"name": "emp_no", "label": "Id"},
  {"name": "first_name", "label": "First Name"},
  {"name": "last_name", "label": "Last Name"}
]

Expected API response:

[
  {
    "emp_no": "10001",
    "first_name": "John",
    "last_name": "Doe"
  }
]

Validation checklist:

✅ Response is JSON array
✅ Object contains emp_no field
✅ Object contains first_name field
✅ Object contains last_name field
✅ Field names match exactly (case-sensitive)

Troubleshooting

Connection timeout or refused

Possible causes:

API endpoint URL is incorrect
API server is down or unreachable
Network firewall blocking connection
Wrong port number in URL

Solution:

Verify URL is accessible from Alfresco server
Test with curl from the Alfresco server host
Check firewall rules and network connectivity

401 Unauthorized error

Possible causes:

Authentication type is "none" but API requires authentication
Username or password is incorrect
API uses different authentication method (OAuth, API key, etc.)

Solution:

Verify credentials are correct
Confirm API uses Basic Authentication
Test credentials with curl

Search returns empty results

Possible causes:

Search parameter name doesn’t match API expectations
API requires minimum search length
API returns 200 but empty array for no matches

Solution:

Verify searchParam matches API documentation
Test with known entities that exist in the system
Check API documentation for search requirements

Malformed JSON response error

Possible causes:

API returns HTML error page instead of JSON
API returns single object instead of array
Response contains invalid JSON syntax

Solution:

Verify API returns JSON array format
Check API error handling for non-existent searches
Test response with JSON validator

Advanced Configuration

Custom Headers

While not directly configurable in the current version, you can extend the connector to support custom headers by modifying the Java connector implementation.

Timeout Configuration

Connection timeouts are configured at the system level:

# alfresco-global.properties
datalink.rest.timeout=30000
datalink.rest.connectionTimeout=10000

Proxy Configuration

If your Alfresco server requires a proxy to access external APIs:

# alfresco-global.properties
http.proxyHost=proxy.example.com
http.proxyPort=8080
http.proxyUser=proxyuser
http.proxyPassword=proxypass

API Development Guidelines

If you’re developing a custom API for Venzia Datalinks integration:

Return Arrays

Always return JSON arrays, even for single or zero results

Consistent Schema

Use consistent property names across all returned objects

Pagination

Return top 50-100 results by default for performance

Error Handling

Return empty arrays for no matches, not error responses

Recommended API Endpoint Pattern

GET /api/v1/[entity-type]/search?query=[searchterm]

Response: 200 OK
[
  {
    "id": "unique-identifier",
    "displayField1": "value1",
    "displayField2": "value2",
    "dateField": "formatted-date"
  }
]

Getting Started

Configuration

Usage Guide

Components

Development

​Overview

​Connector Configuration

​Configuration Properties

​URL Configuration

​Search Parameter

​Authentication Configuration

​No Authentication

​Basic Authentication

​API Response Format

​Expected Response Structure

​Response Requirements

JSON Array

Matching Fields

Primary Key

Consistent Structure

​Complete Examples

​Employee Datalink with Public API

​Department Datalink with Basic Authentication

​Request Flow

​Security Best Practices

Use HTTPS

Restrict File Access

Network Security

Credential Rotation

​Testing REST Connectors

​Manual Testing with curl

​Verifying Response Format

​Troubleshooting

​Advanced Configuration

​Custom Headers

​Timeout Configuration

​Proxy Configuration

​API Development Guidelines

Return Arrays

Consistent Schema

Pagination

Error Handling

​Recommended API Endpoint Pattern

​Next Steps

Datalink JSON Schema

Content Models

Build docs developers (and LLMs) love

Overview

Connector Configuration

Configuration Properties

URL Configuration

Search Parameter

Authentication Configuration

No Authentication

Basic Authentication

API Response Format

Expected Response Structure

Response Requirements

Complete Examples

Employee Datalink with Public API

Department Datalink with Basic Authentication

Request Flow

Security Best Practices

Testing REST Connectors

Manual Testing with curl

Verifying Response Format

Troubleshooting

Advanced Configuration

Custom Headers

Timeout Configuration

Proxy Configuration

API Development Guidelines

Recommended API Endpoint Pattern

Next Steps