HOWTO: Manage Relations on a Document

Updated: March 18, 2024

Nuxeo REST API provides 3 methods to query, create and delete relationships between documents, the description of each of these operations can be found in Nuxeo Platform Explorer.

On this page, we are going to create an element to retrieve relations on a document and to add/delete them.


Create an Automation Scripting

The Document.GetLinkedDocuments operation provides the relationships of a document based on the address and type of relationship. However, we need to recover all the relationships in the document in order to show them.

That's why we're going to create an Automation Scripting called getAllRelations from the Configuration > Automation > Automation Scripting menu in Studio Modeler.

Get the relations for the input document. The ‘outgoing’ parameter can be used to specify whether outgoing or incoming relations should be returned. Returns a document list.

  1. On Modeler, go to Automation Scripting.
  2. Click on New and name it getAllRelations.
  3. Copy the content from our Nuxeo cookbook.
  4. Save your changes.

Create Element to Retrieve Relation

Let's create an element nuxeo-se-document-relations that uses the javascript.getAllRelations operation that we created above to retrieve all the document's relationships.

This element refers to two auxiliary elements that are responsible for the creation and deletion of new relationships, we will create them right after.

  1. On Designer, go to Resources.
  2. Create a new folder under UI and name it Relations.
  3. In it, create a new element and name it nuxeo-se-document-relations.
  4. Choose the type Sample layout template.
  5. Copy the content from our cookbook.
  6. Save your changes.

Add Relation

The web element nuxeo-se-add-relation-dialog shows a popup to add a new relationship specifying the direction and the type of relation. To create the relationship use the operation Document.AddRelation. At the end of the creation of the relationship, we will launch a custom event called relation-added to notify that the relationship has been created.

The Document.AddRelation operation uses negative logic in the outgoing parameter, which makes it more difficult to follow the logic.

  1. In your Relations folder, create a new element.
  2. Name it nuxeo-se-add-relation-dialog.
  3. Choose the type Sample layout template.
  4. Copy the content from our cookbook.
  5. Save your changes.

Delete Relation

Finally, we need to create a web element in charge of deleting relationships, nuxeo-se-remove-relation-button. For the deletion, we will use the operation Relations.DeleteRelation. At the end of the relationship deletion, we will launch a custom event called relation-removed to notify that the relationship has been removed.

  1. In your Relations folder, create a new element.
  2. Name it nuxeo-se-remove-relation-button.
  3. Choose the type Sample layout template.
  4. Copy the content from our cookbook.
  5. Save your changes.

Use the Element

Now that you have your element you need to add it to a document type. You can add it to a custom document type or override an existing one. Here we'll add it to the File document type.

The types of relationships are defined in the predicate and inverse_predicates vocabularies. The definition of both vocabularies can be consulted in the Web UI Administration > Vocabularies menu.

Here is our File document type view layout final result:

<link rel="import" href="../../relations/nuxeo-se-add-relation-dialog.html">
<link rel="import" href="../../relations/nuxeo-se-document-relations.html">
<link rel="import" href="../../relations/nuxeo-se-remove-relation-button.html">
(C) Copyright Nuxeo Corp. (

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
See the License for the specific language governing permissions and
limitations under the License.

@group Nuxeo UI
@element nuxeo-file-view-layout
<dom-module id="nuxeo-file-view-layout">

      nuxeo-document-viewer {
        @apply --paper-card;
    <nuxeo-document-viewer role="widget" document="[[document]]"></nuxeo-document-viewer>
    <nuxeo-se-document-relations document="[[document]]"></nuxeo-se-document-relations>

    is: 'nuxeo-file-view-layout',
    behaviors: [Nuxeo.LayoutBehavior],
    properties: {
         * @doctype File
      document: Object


The result is a list with the related documents, which include the direction of the relationship (incoming/outgoing) and the type of relationship (Based on, Reference ...). We can eliminate existing relationships or add a new one. It should look like this:


To add a new relation, click on the relations-add-relation-icon.png icon, a popup window appears to let you define your relation:


To remove a relation, click on the relations-remove-relation-icon.png icon on the relation that you want to delete.