Home > Developer Documentation Center > Additional Services > Publisher
Additional Services

Publisher

Updated: July 17, 2023

Functional Overview

Working with Sections

When a document is finished and ready for distribution, you must publish it in a section. Sections are spaces dedicated to the distribution of documents to a wider audience.

Sections are spaces that are managed like workspaces, there is no section that is automatically created by default, except for the sections root. You are free to organize your section the way it fits your needs or your project the best. The section tree is completely independent from workspaces. Their structure is not linked. Still, you can guide users as to where they should publish documents from a specific workspace using the publication targets.

As in workspaces, the access to sections is determined by permissions.

The main difference with workspaces is the fact that documents can't be edited in sections. The only actions available on published documents are:

Publishing Documents

Publishing a document means publishing the version of the document as it is at the time of publication. If you modify the document in the workspace once published, it is not modified in the section. If you want to modify a published document, you must modify it in the workspace and then publish the modified version of the document. The workspace document can be deleted without the published document to be affected: section readers will still be able to consult the published document, comment it, etc.

When you want to publish a document, you need to submit it to publishing. When the document is submitted to publication, the section's managers can approve the publication submission, that is to say publish the document, or reject it. In that last case, the document is not available in the section. However, it is still available in the workspace. You can modify it and submit it again.

When you publish a document, the following elements are kept from the workspace document:

  • The metadata
  • All attachments
  • The document history (Event log tab only)
  • The tags (if this is a first publication — in case of a republication, tags from the workspace are merged with existing tags on the published document)

The following elements are not available on the published document:

Submitting a Document to Publishing

To submit a document to publication, you need the following permissions:

  • at least "Edit" on the workspace from which you want to publish
  • at least "Read" and "Can ask for publishing" on the section into which you want to publish the document (Read permission is usually inherited from the user’s group permissions).

You can submit a document in several sections. The publishing workflows in the different sections are independent. The document can be published in a section and rejected in another one. The list of the sections in which you can publish a document is defined by your permissions.

To submit a document to publishing, from the Publish tab of the document in the workspace, select:

  • the domain you want to publish the document in
  • the rendition that should be published, typically no rendition (same document format as in the workspace) or a PDF version of the document.

Unfold the sections tree and click on the Publish here link corresponding to the section you want to publish the document in.

The version number of the submitted document is indicated in the publication form.

Alternatively you can drag the icon of the document to publish onto the target section in the navigation tree until the section is highlighted, and drop the document icon.

The document submitted to publication in the section:

  • Users with Read permission in the section don't see it yet, since its publication has to be approved.

  • Users with Edit or Manage everything permission can see it in the section and in their dashboard as a pending document. They need to approve its publication.

    If you have edit or management permissions in the selected section, the document is automatically published and visible to all section users. It doesn't need to be approved.

    In the workspace, the document's minor version is automatically incremented if the published version doesn't correspond to the latest archived version (version number is suffixed with +, 0.1+ for instance).

Approving Document Publishing

Users with edit and management permissions in the section can approve the publishing of a document.

When a document is submitted to publication in a section in which you have management permissions, it is displayed in your dashboard. You must then approve or reject the document.

To publish a document, click on the Home main tab (the Dashboard tab is automatically selected. The pending documents are displayed in your tasks). Click on the pending document and go to the Publishing part at the bottom of the tab, with has a Reject and a Publish buttons.

Only users with edit or management permissions can see the pending document in the section. You can type a comment or click on Publish directly. The document is now available to all the users who can access the section.

Rejecting Document Publishing

Only users with edit and management permissions in the section can reject the publishing of a document.

When a document is submitted to publication in your section, you must decide if it can be published in it. If you think that the document is not ready for publication or that it shouldn't be published in this section, you must reject it.

Only users with edit and management permissions can see the pending document in the section.

To reject a document click on the Home main tab and then on the pending document. The document opens in the section on its Summary tab. It has a Publishing part at the bottom of the tab, with a Publishing part that has a Reject and a Publish buttons. Type a comment explaining why you reject the document publication. This comment is mandatory to reject the document publishing.

Once it is done, click on the Reject button. The document is not published and is deleted from section content. You are redirected on the Content tab of the section. In the workspace, the fact that publishing was rejected is logged in the History of the document.

Republishing Documents

Since version 5.7.1, users with Edit permissions can easily publish a new version of a document that has already been published. Republishing is available after the published document has been edited, with or without version increment.

To republish a document, in the workspace, open the document to republish and click on the Publish tab. The list of sections in which the document is published is displayed and a Republish button is displayed next to the Unpublish button. Click on the Republish button corresponding to the section in which you want to publish a new version of the document. The latest version of the document is immediately available from the section. It replaced the previously published version in the section.

Unpublishing Documents

Only users with editing or management permissions can unpublish a document from a section. When a document is obsolete or inaccurate, it shouldn't be available in sections anymore. You have to unpublish it so section readers do not have access to the document.

Unpublishing a document deletes the document from the section, but it does not delete the workspace document.

To unpublish a document from a section, in the Content tab of the section, check the box in front of the document's name and click on the Unpublish button. The document is unpublished and does not appear in the section. The original document in the workspace is not deleted.

Media Publishing

Nuxeo Media Publishing addon enables users to publish video documents stored in the repository to external video hosting websites, without leaving the Nuxeo Platform UI.

Read the page Nuxeo Media Publishing for more information about this addon.

Publication Targets

In order to guide users when they publish documents and make sure documents are published in the correct sections, you can define publication targets for the workspace documents. Publishing targets are sections in which the documents from the workspace will be publishable. Users will then be able to publish documents only in the sections you have defined.

By default, workspaces don't have any targets defined.

To define the publication targets of a workspace click on the Manage > Publication targets, if no section has been defined yet, users can submit documents to publishing in any section (providing they have the permissions to publish). Unfold the sections tree and click on the Add link of the sections to which you want to restrict publishing from this workspace. The selected sections are displayed in a table below the tree. No Add link is available anymore for these sections.

When they click on the Publish tab of documents to publish a document, only the selected sections are available to publish the document. To remove a section from the workspace targets, click on  next to it.

Technical Overview

There are three ways to publish a document:

  • on local sections, i.e. the sections created in your Nuxeo DM instance,
  • on remote sections, i.e. the sections of a remote Nuxeo server,
  • on the file system.

Publication is configured using the PublisherService.

About the PublisherService

When using the PublisherService, you only need to care about three interfaces:

  • PublishedDocument: represents the published document. It can be created from a DocumentModel, a proxy or a file on the file system.
  • PublicationNode: represents a Node where you can publish a DocumentModel. It can be another DocumentModel (mainly Folder / Section) or a directory on the file system.
  • PublicationTree: the tree which is used to publish / unpublish documents, to approve / reject publication, list the already published documents in a PublicationNode, ... See the javadoc of the PublicationTree.

 

The PublisherService mainly works with three concepts:

  • factory: the class which is used to actually create the published document. It also manages the approval / rejection workflow on published documents.
  • tree: a PublicationTree instance associated to a name: for instance, we have a SectionPublicationTree which will publish in Sections, a LocalFSTree to publish on the file system, ...
  • tree instance: an actual publication tree where we define the factory to use, the underlying tree to use, its name / title, and some parameters we will see later.

Configuring Local Sections Publishing

Publishing in local sections was the only way to publish on versions < 5.3GA. From Nuxeo DM 5.3GA, it is the default way to publish documents.

Here is the default contribution you can find in Nuxeo publisher-jbpm-contrib.xml in nuxeo-platform-publisher-jbpm. This contribution overrides the one in publisher-contrib.xml located in the nuxeo-platform-publisher-core project:

<extension target="org.nuxeo.ecm.platform.publisher.impl.service.PublisherServiceImpl"
  point="treeInstance">

  <publicationTreeConfig name="DefaultSectionsTree" tree="RootSectionsCoreTree"
    factory="CoreProxyWithWorkflow" localSectionTree="true"
    title="label.publication.tree.local.sections">
    <parameters>
      <!-- <parameter name="RootPath">/default-domain/sections</parameter> -->
      <parameter name="RelativeRootPath">/sections</parameter>
      <parameter name="enableSnapshot">true</parameter>
      <parameter name="iconExpanded">/icons/folder_open.gif</parameter>
      <parameter name="iconCollapsed">/icons/folder.gif</parameter>
    </parameters>
  </publicationTreeConfig>

</extension>

In this contribution, we define an instance using the RootSectionsCoreTree tree and the CoreProxyWithWorkflow factory. We give it a name, a title and configure it to be a localSectionTree (which means we will publish the documents in the Sections of the Nuxeo application the documents are created in).

The available parameters are:

  • RootPath: it's used when you want to define the root publication node of your PublicationTree. You can't use both RootPath AND RelativeRoothPath parameters.
  • RelativeRootPath: used when you just want to define a relative path (without specifying the domain path). A PublicationTree instance will be created automatically for each domain, appending the RelativeRootPath value to each domain. For instance, let's assume we have two domains, domain-1 and domain-2, and the RelativeRootPath is set to "/sections". Then, two PublicationTree instances will be created: the first one with a RootPath set to "/domain-1/sections", and the second one with a RootPath set to "/domain-2/sections", In the UI, when publishing, you can chose the PublicationTree you want. The list of trees will automatically be updated when creating and deleting domains.
  • iconExpanded and iconCollapsed: specify which icons to use when displaying the PublicationTree on the user interface.

Configuring Remote Sections Publishing

To make the remote publication work, both the Nuxeo server instance and Nuxeo client instance need to be configured.

Server Configuration

You should create a new configuration file, publisher-server-config.xml for instance, in the nxserver/config folder of your Nuxeo acting as a server (ie the Nuxeo application on which the documents will be published). Best way is to create a custom template with your configurarion, see Configuration Templates.

Here is a sample configuration:

<?xml version="1.0"?>
<component name="org.nuxeo.ecm.platform.publisher.contrib.server">

  <extension target="org.nuxeo.ecm.platform.publisher.impl.service.PublisherServiceImpl"
    point="treeInstance">

    <publicationTreeConfig name="ServerRemoteTree" tree="CoreTreeWithExternalDocs" factory="RemoteDocModel" >
      <parameters>
        <parameter name="RootPath">/default-domain/sections</parameter>
      </parameters>
    </publicationTreeConfig>

  </extension>

</component>

The available parameters are:

  • RootPath: its value must be the path to the document which is the root of your PublicationTree. Here, it will be the document /default-domain/sections, the default Sections root in Nuxeo. This parameter can be modified to suit your needs.

    Don't forget to put the whole path to the document.

Client Configuration

You should create a new configuration file, publisher-client-config.xml for instance, in the nxserver/config folder of your Nuxeo acting as a client (ie the Nuxeo application from which documents are published).  Best way is to create a custom template with your configurarion, see Configuration Templates.

Here is a sample configuration:

<?xml version="1.0"?>
<component name="org.nuxeo.ecm.platform.publisher.contrib.client">

  <extension target="org.nuxeo.ecm.platform.publisher.impl.service.PublisherServiceImpl"
    point="treeInstance">

    <publicationTreeConfig name="ClientRemoteTree" tree="ClientForRemoteTree"
      factory="ClientProxyFactory">
      <parameters>
        <parameter name="title">label.publication.tree.remote.sections</parameter>
        <parameter name="userName">Administrator</parameter>
        <parameter name="password">Administrator</parameter>
        <parameter name="baseURL">
          http://myserver:8080/nuxeo/site/remotepublisher/
        </parameter>
        <parameter name="targetTree">ServerRemoteTree</parameter>
        <parameter name="originalServer">localserver</parameter>
        <parameter name="enableSnapshot">true</parameter>
      </parameters>
    </publicationTreeConfig>

  </extension>

</component>

The available parameters:

  • targetTree: this parameter corresponds to the name of the tree defined on the server Nuxeo application, here ServerRemoteTree.
  • username, password: the user account defined by those parameters will be the one used to connect to the remote Nuxeo and so to create documents in the PublicationTree. This account MUST exist on the server.
  • baseURL: the URL used by the PublisherService on the client side to communicate with the server Nuxeo application.
  • originalServer: identifies the Nuxeo application used as client.

Configuring File System Publishing

To publish on the file system, you just need to define a new TreeInstance using the LocalFSTree and the RootPath of your tree.

Here is a sample configuration:

<extension  target="org.nuxeo.ecm.platform.publisher.impl.service.PublisherServiceImpl"
  point="treeInstance">

  <publicationTreeConfig name="FSTree" tree="LocalFSTree"
    factory="LocalFile" localSectionTree="false"
    title="label.publication.tree.fileSystem">
    <parameters>
      <parameter name="RootPath">/opt/publishing-folder</parameter>
      <parameter name="enableSnapshot">true</parameter>
      <parameter name="iconExpanded">/icons/folder_open.gif</parameter>
      <parameter name="iconCollapsed">/icons/folder.gif</parameter>
    </parameters>
  </publicationTreeConfig>

</extension>

The available parameters are:

  • RootPath: the root folder on the file system to be used as the root of the publication tree.
  • iconExpanded and iconCollapsed: specify which icons to use when displaying the PublicationTree on the user interface.
  • enableSnapshot: defines if a new version of the document is created when the document is published.

Enabling Duplication of Relations upon Publication

By default, the relations on the document in the workspace are not duplicated on the published document. But it is possible to have them duplicated.

To enable this duplication of relations, you need to add the following contribution to the Platform:

<extension target="org.nuxeo.ecm.core.event.EventServiceComponent"
    point="listener">
  <listener name="publishRelationsListener" async="false" postCommit="false"
    class="org.nuxeo.ecm.platform.relations.core.listener.PublishRelationsListener"
    priority="-50">
    <event>documentProxyPublished</event>
  </listener>
</extension>

See the How to Contribute to an Extension page to add the contribution in Nuxeo Studio.