Nuxeo Server

Collections

Updated: December 5, 2017 Page Information Edit on GitHub

Functional Overview

Collections are a folder-like document in which you can classify existing documents. Documents are not actually copied or moved into the collection, which only holds a link to the document in its original location.

It enables you to create your own organization of the content without duplicating content and having the size of the content growing uncontrollably.

Depending on your user interface you can access collections by different means.

Web UI

The list of collections available to you is available from the side menu, in the Collections tab.

Click on the collection title to go on the collection and see the list of the documents that are classified in it.

Click on a document to consult it. The main view shows the document. The unfolded side panel shows the content of the collection. You can click on the icon  to see the collections list.

JSF UI

The list of collections available to you is available from your Home, in the Collections tab.

Click on the collection title to go on the collection and see the list of the documents that are classified in it.

Click on a document to consult it. You are moved out of the collection to be displayed the document inside its original location.

Collecting Documents

You can classify any type of document in a collection. You just need to have Read access to the document to be able to collect it. Collecting a document doesn't give you more permissions on the document: your permissions are the one defined on the original parent of the document.

Collecting documents in Web UI

Documents can be collected:

  • Individually by clicking on the icon  of the document
  • By batch by selecting documents from a list of documents and clicking on the icon  in the selection header.

In both cases you can select the collection by:

  • Browsing the collections in the list
  • Starting to type the collection name and select it
  • Typing a new collection name to create it.

The list of collections the document is available from is displayed on its View tab.

Collecting documents in JSF UI

Documents can be collected:

  • Individually by clicking on the icon of the document
  • By batch by selecting documents from their parent and clicking on the Add to collection button
  • From the collection itself by clicking the icon and searching the documents to collect

In the first two cases you can select the collection by:

  • Browsing the collections in the list
  • Starting to type the collection name and select it
  • Typing a new collection name to create it.

The Collection list shows all the collection you have access to, even collection in which you cannot collect documents. Collections you only have read access to are grayed.

The list of collections the document is available from is displayed on its Summary tab.

Creating Collections

Creating collections in Web UI

There are two ways to create a collection:

  • Like any other document, using the button : Just fill in the creation form and the collection is created in the current workspace / folder.
  • Directly from the Add to collection popup: collections about to be created are displayed with the icon , while existing collections are displayed in the drop down list. The collection is created in your personal workspaces, in a My Collections folder.

Creating collections in JSF UI

There are two ways to create a collection:

  • Like any other document, using the New button: Just fill in the creation form and the collection is created in the current workspace / folder.
  • Directly from the "Add to collection" popup: collections about to be created are displayed with the icon , while existing collections have the icon . The collection is created in your personal workspaces, in a My Collections folder.

Sharing a Collection

Sharing a collection means giving permissions to users on the collection. Collections created in the default domain in a shared workspace or folder are automatically shared to all the workspace or folder's users, following the rights inheritance principle.

Collections created in your personal workspace are private by default. You must grant the needed permissions on the collection if you want to share it. Granting permissions to a collection makes the collection available to users from their Home. The list of documents displayed inside the collection depends on the permissions of the user on each of the documents.

Beside the generic permissions, collection have a specific right, called "can collect". When you share a collection, you can choose to:

  • Give read access: By giving them Read permission, you enable users to see the collection in their Home and the documents inside it depending on their permissions on each document;
  • Enable users to add documents to the collection: By giving the permission "Can collect", you enable users to add documents to the collection and remove them;
  • Give edit access: By giving the Edit permission, you enable users to add documents to the collection, remove them and to edit the collection (i.e. title, description, etc.);
  • Make them manager for the collection: By giving them Manage everything permission, you enable users to manage the content of the collection and who can access it.

Removing Documents from a Collection

Web UI

To remove a document from a collection click on the icon of the collection from the document view.

To remove several documents from a collection:

  1. Go to the Collections tab in your side menu.
  2. Click on the collection name that you want to manage.
  3. Select the documents to remove using the checkboxes.
  4. In the selection header, click on the Remove from collection icon .

In both ways documents are immediately removed from the collection.

JSF UI

To remove a document from a collection, either click on the icon of the collection from the Summary tab of the document, or select the document in the collection the checkboxes and click on the Remove from collection button.

In both ways the document is immediately removed from the collection.

Favorites

Favorites is a particular collection that enables you to bookmark documents.

On Web UI

The list of documents bookmarked as favorites is available:

  • On the dashboard in the Favorite Item widget
  • On the Favorites Tab in the side menu

Bookmarking documents in your favorites can be done like when you add documents to a collection and selecting the Favorites collection, or using the Favorites icon from the document itself.

Once the document is added to your favorites, it will be available in the dashboard and in the Favorites tab.

On JSF UI

The list of documents bookmarked as favorites is available:

  • From your personal workspace in the Favorites collection
  • From your dashboard in a My Favorites widget

Bookmarking documents in your favorites can be done like when you add documents to a collection (see previous sections) and selecting the Favorites collection, or using the icon from the document itself.

Installation & Configuration

The collection module has no specific installation step as it is already included in the default Nuxeo Platform distribution.

Customization

How to Implement a New Type of Collection

If you'd like to implement a new collection (for instance to have new metadata) you can simply add the Collection facet to your specific document type. You'll therefore be able to use it as a regular collection.

  <require>org.nuxeo.ecm.collections.schemas</require>

  <extension target="org.nuxeo.ecm.core.schema.TypeService" point="schema">
    <schema name="yourSchema" src="schemas/xxx.xsd" prefix="xxx" />
  </extension>
  <extension target="org.nuxeo.ecm.core.schema.TypeService" point="doctype">
    <facet name="YourFacet" >
      <schema name="yourSchema" />
    </facet>

    <doctype name="YourDocumentType" extends="Document">
      <facet name="YourFacet" />
      <facet name="Collection" />
    </doctype>

  </extension>

 

NotCollectionMember Facet

All documents can be added to a collection except:

  • Documents with the facet SystemDocument
  • Documents with the facet NotCollectionMember

By default, documents of type Collection, WorkspaceRoot, TemplateRoot, SectionRoot, Domain and Root have the facet NotCollectionMember. Please see collection-core-types-contrib.xml for more details.

Plugging Business Rules to Collection Specific Events

Several events related to collections are available:

  • beforeAddedToCollection
  • addedToCollection
  • beforeRemovedFromCollection
  • removedFromCollection

The collection reference is available in the event context map. For example, within an event listener which starts an automation chain, you can fetch the collection as described below:

- Document.Fetch:
    value: "@{Event.context.getProperty(\"collectionRef\").reference()}"

Synchronizing a Collection with Nuxeo Drive

To do so you need to add the following XML contribution with either Nuxeo Studio or a custom bundle:

<component name="org.nuxeo.drive.actions.collections">
    <require>org.nuxeo.drive.actions</require>
        <extension target="org.nuxeo.ecm.platform.actions.ActionService"
    point="filters">
            <filter id="can_sync_current_doc" append="true">
              <rule grant="true">
                    <type>Collection</type>
              </rule>
            </filter>
          </extension>
</component>

Limitation

With this configuration you won't be able to unsynchronize a collection as usual using the icon as this icon will stay grey: .

Yet you can always unsynchronize the collection from the Nuxeo Drive tab in the user Home.

Notes:

  • Files or folders created in the locally synchronized collection folder will not be added to the collection server-side. For now we have no mechanism to choose their path in the hierarchy.
  • Please be aware that all the limitations applied to online editing with Nuxeo Drive apply to synchronized collections.

Core Implementation

A collection holds the list of references of the documents it contains. Conversely, a document holds the list of references of the collections it belongs to.

Collection operation are offered by the CollectionManager.java service.

Because a collection can potentially contain a large number of documents and, to a lesser extent, a document can belong to many collections, some tasks are performed asynchronously.

For instance, when deleting a collection, an asynchronous work will update the documents it contains to remove the reference of the deleted collection. In the same way, when a document is removed, an asynchronous work will update the collection it belonged to in order to remove the reference of the deleted document.

Finally, when copying a collection, an asynchronous work will also duplicate its content.


5 days ago Manon Lumeau add tags for doc days
5 days ago Manon Lumeau Add tags for doc days
a month ago manonlumeau Added content-review-lts2017 label
2 months ago manonlumeau NXDOC-1346-FT review screenshot
a year ago Anne Jubert 26
2 years ago Manon Lumeau 25
2 years ago Solen Guitter 24
2 years ago Solen Guitter 23
2 years ago Manon Lumeau 22
2 years ago Manon Lumeau 21
2 years ago Solen Guitter 20
2 years ago Solen Guitter 19 | NXDOC-647 : use tabs to show Collections related docs
2 years ago Manon Lumeau 18
2 years ago Solen Guitter 17 | NXDOC-614: Add functional overview
3 years ago Solen Guitter 16 | format
3 years ago Michaël Vachette 15
3 years ago Antoine Taillefer 14
3 years ago Manon Lumeau 13
3 years ago Manon Lumeau 12
3 years ago Solen Guitter 11
3 years ago Solen Guitter 10
3 years ago Solen Guitter 9 | Add links
3 years ago Antoine Taillefer 8
4 years ago Solen Guitter 7
4 years ago Guillaume Renard 6
4 years ago Guillaume Renard 5
4 years ago Guillaume Renard 4
4 years ago Guillaume Renard 3
4 years ago Guillaume Renard 2
4 years ago Guillaume Renard 1
History: Created by Guillaume Renard