Nuxic Discovery

A Nuxeo addon that exposes document types and Studio-defined attributes via REST API endpoints, allowing users to discover and explore the content model.

Access to bulk action API.

Overview

Nuxic Discovery provides REST API endpoints that enable users to retrieve information about registered document types and schemas in a Nuxeo instance, including:

• Complete list of document types
• Complete list of schemas with detailed field definitions
• Schema information for each document type
• Detailed attribute definitions:
  • Type (string, integer, decimal, boolean, date, vocabulary, user, complex, etc.)
  • Cardinality (single vs. multi-valued)
  • Schema and schema prefix
  • Required vs. optional status
  • Read-only status (configurable per field)
  • Default values
  • Vocabulary references
  • Complex type hierarchies with nested attributes
• Bulk command monitoring and management

Installation

Prerequisites

• Nuxeo Platform 2023
• Java 17
• Maven 3.6+

Building

bash git clone https://github.com/nuxeo/nuxic-discovery.git cd nuxic-discovery mvn clean install

Deployment

Copy the built JAR from the target directory to your Nuxeo server's nxserver/bundles directory and restart Nuxeo.

Alternatively, you can use Nuxeo's package management system:

bash nuxeoctl mp-install /path/to/nuxic-discovery-{version}.zip

Usage

Document Type Discovery

The addon provides two ways to access document type information:

Automation Operation

Operation ID: Discovery.GetDocumentTypes

Parameters: - docTypes (optional): Comma-separated list of document types to include. If empty, all types will be returned. - excludeSystemTypes (optional, default: true): Whether to exclude system document types from the results. - groupBySchema (optional, default: false): Whether to group properties by schema. - locale (optional): Locale name for label resolution. - reportMissingLabels (optional, default: false): Whether to include a list of unresolved label keys in the response.

Example:

Basic Example: bash curl -X POST -u Administrator:Administrator \ -H "Content-Type: application/json" \ -d '{"params":{"docTypes":"File,Folder","excludeSystemTypes":true}}' \ http://localhost:8080/nuxeo/api/v1/automation/Discovery.GetDocumentTypes

Example with missing labels report: bash curl -X POST -u Administrator:Administrator \ -H "Content-Type: application/json" \ -d '{"params":{"docTypes":"File","reportMissingLabels":true}}' \ http://localhost:8080/nuxeo/api/v1/automation/Discovery.GetDocumentTypes

REST API Endpoint

The document type information is also available through a dedicated REST API endpoint:

GET {{host}}/site/discovery/content/types?docTypes=File,Folder,Document

Optional query parameters: - docTypes: Comma-separated list of document types to include - excludeSystemTypes: Set to false to include system types - groupBySchema: Set to true to group properties by schema - locale: Locale for label resolution (e.g., "en", "fr") - reportMissingLabels: Set to true to include unresolved label keys in the response

Label Resolution and Missing Labels

The addon attempts to resolve human-readable labels for document types, schemas, and field names using Nuxeo's i18n mechanism. Labels are looked up from Studio's resources/i18n/messages.json file using specific key patterns:

• Document type labels: label.ui.type.TypeName
• Schema labels: label.ui.schema.schemaName
• Field labels: label.ui.schema.prefix.fieldName

When labels cannot be found, the raw key is displayed instead. To identify which labels are missing, use the reportMissingLabels=true parameter:

Example with missing labels: bash curl "http://localhost:8080/nuxeo/site/discovery/content/types?docTypes=File&reportMissingLabels=true"

Response: json { "docTypes": { "File": { "name": "File", "label": "label.ui.type.File", "schemas": { "file": { "name": "file", "label": "label.ui.schema.file", "fields": { "content": { "name": "content", "label": "label.ui.schema.file.content" } } } } } }, "unresolvedMessages": { "label.ui.type.File": "label.ui.type.File", "label.ui.schema.file": "label.ui.schema.file", "label.ui.schema.file.content": "label.ui.schema.file.content" } }

You can then add these missing labels to your Studio project's resources/i18n/messages.json:

json { "label.ui.type.File": "File Document", "label.ui.schema.file": "File Schema", "label.ui.schema.file.content": "File Content" }

Schema Discovery

The addon provides comprehensive schema discovery capabilities:

Automation Operation

Operation ID: Discovery.GetSchemas

Parameters: - schemas (optional): Comma-separated list of schemas to include. If empty, all schemas will be returned. - excludeSystemSchemas (optional, default: true): Whether to exclude system schemas from the results. - locale (optional): Locale name for label resolution. - reportMissingLabels (optional, default: false): Whether to include a list of unresolved label keys in the response.

Example:

bash curl -X POST -u Administrator:Administrator \ -H "Content-Type: application/json" \ -d '{"params":{"schemas":"dublincore,file","excludeSystemSchemas":false}}' \ http://localhost:8080/nuxeo/api/v1/automation/Discovery.GetSchemas

REST API Endpoint

The schema information is also available through a dedicated REST API endpoint:

GET {{host}}/site/discovery/content/schemas?schemas=dublincore,file

Optional query parameters: - schemas: Comma-separated list of schemas to include - excludeSystemSchemas: Set to false to include system schemas - locale: Locale for label resolution (e.g., "en", "fr") - reportMissingLabels: Set to true to include unresolved label keys in the response

Read-Only Fields Configuration

The discovery operations support marking fields as read-only through configuration. This allows administrators to control which properties can be edited by end users.

Configuration in Nuxeo Studio:

1. Navigate to UI → Translations
2. Select or create the messages-nx.json file (technical locale nx)
3. Add read-only field configurations:

json { "readOnly.uid.uid": "true", "readOnly.dc.created": "true", "readOnly.dc.modified": "true", "readOnly.dc.creator": "true", "readOnly.dc.lastContributor": "true" }

Format: "readOnly.{schemaPrefix}.{fieldName}": "true"

API Response: Fields marked as read-only will include "readOnly": true in the response:

json { "name": "created", "schema": "dublincore", "fullName": "dc:created", "type": "date", "required": false, "readOnly": true }

Note: The readOnly attribute is only included when true. If a field is editable (the default), the attribute is omitted.

Quick Setup Guide: See STUDIO_SETUP.md for step-by-step Studio instructions

Detailed Documentation: See READONLYFIELDS.md for complete technical documentation

Bulk Command Discovery

The addon provides tools for discovering and managing Nuxeo bulk commands:

Automation Operation

Operation ID: Discovery.BulkActionDiscovery

Parameters: - commandId (optional): ID or name of a specific bulk command to retrieve. If empty, all commands will be returned. - repository (optional, default: "default"): Repository name to filter commands. - terminate (optional, default: false): Whether to terminate the specified command. - state (optional): Filter commands to only include those in the specified state (e.g., "RUNNING", "COMPLETED", etc.). - exclusive (optional): Filter commands by their exclusive flag (true/false). - startTime (optional): Filter commands by start time (ISO 8601 format). - endTime (optional): Filter commands by end time (ISO 8601 format).

Example:

curl -X POST -u Administrator:Administrator \ -H "Content-Type: application/json" \ -d '{"params":{"commandId":"index","repository":"default","state":"RUNNING","exclusive":true}}' \ http://localhost:8080/nuxeo/api/v1/automation/Discovery.BulkActionDiscovery

REST API Endpoints

The bulk command discovery functionality is available through dedicated REST API endpoints:

List all bulk commands: GET {{host}}/site/discovery/bulk

List bulk commands with filters: GET {{host}}/site/discovery/bulk?state=RUNNING&exclusive=true

Get a specific bulk command by ID: GET {{host}}/site/discovery/bulk?commandId={commandId} or GET {{host}}/site/discovery/bulk?id={commandId}

Terminate a bulk command: GET {{host}}/site/discovery/bulk?commandId={commandId}&terminate=true or POST {{host}}/site/discovery/bulk?commandId={commandId}&terminate=true

Response Format

Document Types Response

The document types response is a JSON document containing:

json { "docTypes": { "Document": { "name": "Document", "isSystemType": false, "schemaNames": ["common", "dublincore", ...], "schemas": { "common": { "name": "common", "prefix": "common", "fields": { "icon": { "name": "icon", "schema": "common", "fullName": "common:icon", "type": "string" }, "icon-expanded": { "name": "icon-expanded", "schema": "common", "fullName": "common:icon-expanded", "type": "string" } }, "number_of_fields": 2 }, "dublincore": { "name": "dublincore", "prefix": "dc", "fields": { "title": { "name": "title", "schema": "dublincore", "fullName": "dc:title", "type": "string", "required": true }, "description": { "name": "description", "schema": "dublincore", "fullName": "dc:description", "type": "string" } }, "number_of_fields": 2 } }, "fields": { "common:icon": { "name": "icon", "schema": "common", "fullName": "common:icon", "type": "string" }, "dc:title": { "name": "title", "schema": "dublincore", "fullName": "dc:title", "type": "string", "required": true } }, "number_of_fields": 4 }, "Folder": { "name": "Folder", "isSystemType": false, "parent": "Document", "facets": ["Folderish"], "schemaNames": ["common", "dublincore"], "schemas": { ... } } } }

If reportMissingLabels=true is provided and some labels cannot be resolved, the response will include an additional object at the root:

json { "docTypes": { ... }, "unresolvedMessages": { "label.ui.type.SomeType": "label.ui.type.SomeType", "label.ui.schema.dublincore.title": "label.ui.schema.dublincore.title" } }

Bulk Commands Response

The bulk commands response is a JSON document containing:

json { "commands": [ { "commandId": "11865819-7c2c-4db5-af00-cadadc4c5970", "state": "COMPLETED", "processed": 1250, "total": 1250, "submitted": "2023-10-15T14:32:10.123Z", "scrollStartTime": "2023-10-15T14:32:11.456Z", "scrollEndTime": "2023-10-15T14:32:15.789Z", "completed": "2023-10-15T14:33:20.012Z", "exclusive": false, "name": "BulkUpdatePropertiesAction", "repository": "default", "query": "SELECT * FROM Document", "action": "BulkUpdatePropertiesAction", "params": "{\"parameters\":{...}}", "userName": "Administrator", "batchSize": 100, "bucketSize": 50 } ], "count": 1, "repository": "default", "stateFilter": "COMPLETED", "exclusiveFilter": null, "startTime": "2023-10-14T14:32:10.123Z", "endTime": "2023-10-15T14:32:10.123Z", "timeWindow": "24 hours" }

For command termination requests, the response will look like:

json { "status": "success", "message": "Bulk command terminated: 11865819-7c2c-4db5-af00-cadadc4c5970" }

Development

Project Structure

This project follows the standard Nuxeo plugin structure:

nuxic-discovery/ ├── src/ │ └── main/ │ ├── java/ │ │ └── com/ │ │ └── hyland/ │ │ └── nuxic/ │ │ └── discovery/ │ │ ├── operation/ │ │ │ ├── DocumentTypeDiscoveryOperation.java │ │ │ ├── SchemaDiscoveryOperation.java │ │ │ ├── BulkActionDiscoveryOperation.java │ │ │ ├── DiscoveryResponseWriter.java │ │ │ └── StatusInfo.java │ │ ├── webengine/ │ │ │ ├── DiscoveryResource.java │ │ │ └── BulkActionDiscoveryResource.java │ │ └── util/ │ │ └── DocTypeUtils.java │ └── resources/ │ ├── META-INF/ │ │ └── MANIFEST.MF │ └── OSGI-INF/ │ ├── operations-contrib.xml │ └── webengine-contrib.xml ├── pom.xml └── README.md

Running Tests

bash mvn test

License

Copyright © 2025 Hyland Software, Inc. and its affiliates. All rights reserved.

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/my-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin feature/my-feature)
5. Create a new Pull Request

Maintainers

Stan Sokolov stan.sokolov@hyland.com