Publication add-ons for Content.

h1. Extended Publication Plugin {anchor:id=CONTref.Extensions.AuthoringExtension.ExtendedPublicationPlugin}
This section covers the following topics:
* [States|#CONTref.Extensions.AuthoringExtension.ExtendedPublicationPlugin.States]
* [Start/End publication dates|#CONTref.Extensions.AuthoringExtension.ExtendedPublicationPlugin.StarEndPublicationDates]
* [New Publication Mixin|#CONTref.Extensions.AuthoringExtension.ExtendedPublicationPlugin.NewPublicationMixin]

h2. States {anchor:id=CONTref.Extensions.AuthoringExtension.ExtendedPublicationPlugin.States}

This extended publication has new states and new profiles that are enabled in Content.

* Profiles
** Author: This profile can edit a content and mark this content as redacted.
** Approver: This profile approves a pending content (marked by the Author).
** Publisher: This profile publishes contents or marks them as "Ready for publication" in multi-server mode.
** Archiver: An administrative profile which moves contents to an archive storage.
* States
** enrolled: It is a pure technical state, generally used for content creation.
** draft (Author): Content is in editing phase.
** pending (Author): The author validates the content.
** approved (Approver): A content is approved by the manager.
** inreview (Manager): This state can be used when a second approval state is needed (for i18 translation for example).
** staged (Publisher): A content is ready for publication (multi-server mode).
** published (Publisher or Automatic): A content is published and visible in the *Live* mode.
** unpublished (Publisher or Automatic): A content is not visible in the *Live* mode.
** obsolete: A content can still be published but it is not in an editing lifecycle anymore.
** archived (Automatic): A content is archived and ready to be moved in the archive workspace if enabled.

h2. Start/End publication dates {anchor:id=CONTref.Extensions.AuthoringExtension.ExtendedPublicationPlugin.StarEndPublicationDates}

In most cases, you do not want to publish a content directly, but at a defined date and you can also want  the content to be unpublished automatically after that.
New properties are added to the new publication plugin, that allows you to manage this:
* _publication:startPublishedDate_
* _publication:endPublishedDate_

The Content rendering engine does not know anything about publication dates, so another service needs to manage that.
When the publisher sets start/end publication dates, he can "stage" the content. The content will go automatically to the "published" state when the start date arrives and to the "unpublished" state after end date.
A cron job checks every hour (or less) all contents which need to be published (the start date in the past and the "staged" state) or unpublished (the end date in the past and the "published" state).

Thus, the publication dates are not mandatory and a content can go to:
* Staged: in multi-server mode, the publisher can only put the content to the "staged" state and wait for auto-publication.
* Published: in single-server mode, the publisher can directly publish a content (with or without publication dates).

h2. New Publication Mixin {anchor:id=CONTref.Extensions.AuthoringExtension.ExtendedPublicationPlugin.NewPublicationMixin}

{code:xml}
<nodeType name="publication:authoringPublication" isMixin="true" hasOrderableChildNodes="false" primaryItemName="">
  <supertypes>
    <supertype>publication:stateAndVersionBasedPublication</supertype>
  </supertypes>
  <propertyDefinitions>
    <propertyDefinition name="publication:startPublishedDate" requiredType="Date" autoCreated="false"
      mandatory="true" onParentVersion="IGNORE" protected="false" multiple="false">
      <valueConstraints />
    </propertyDefinition>
    <propertyDefinition name="publication:endPublishedDate" requiredType="Date" autoCreated="false" mandatory="true"
      onParentVersion="IGNORE" protected="false" multiple="false">
      <valueConstraints />
    </propertyDefinition>
  </propertyDefinitions>
</nodeType>
{code}

*Publication plugin UI*: {anchor:id=CONTref.Extensions.AuthoringExtension.ExtendedPublicationPlugin.PublicationPluginUI}

Note that some labels containing special or non-ASCII characters could not be well displayed in the publication UI.
You can extend the width of the current UI State button by adding:

{code:css}
.UIPublicationPanel .StatusTable .ActiveStatus {
  width: 75px !important;
}
{code}

Also, for the publication date inputs, _UIPublicationPanel_ should not initialize the dates to any default value.
The publishing and unpublish CRON jobs will do this:
* A staged document with null publication start date is published instantly.
* A document with null publication end date is published forever.

See the export section for more information about the CRON jobs.

h1. Publication Manager {anchor:id=CONTref.Extensions.AuthoringExtension.PublicationManager}

The Publication Manager manages lifecycles and contexts in the Content platform. It allows to manages different lifecycles based on different publication plugin in the platform.

{code:java}
public interface PublicationManager {

	public List<Lifecycle> getLifecycles();

	public List<Context> getContexts();

	public Context getContext(String name);

	public Lifecycle getLifecycle(String name);

	public List<Lifecycle> getLifecyclesFromUser(String remoteUser, String state);
}
{code}

In which:

* _getLifecycles_: returns a list of lifecycles (see below), with lifecycle name, publication plugin involved and possible states.
* _getContexts_: returns a list of context, with name, related Lifecycle and other properties (see below).
* _getContext_: returns a context by its name.
* _getLifecycle_: returns a lifecycle by its name.
* _getLifecycleFromUser_: returns a list of lifecycles in which the user has rights (based on membership property).

h2. Lifecycle {anchor:id=CONTref.Extensions.AuthoringExtension.PublicationManager.Lifecycle}

A lifecycle is defined by a simple vertical workflow with steps (states) and profiles (membership). Each lifecycle is related to a *Publication* plugin (compliant with the JBPM or Bonita business processes).

For example: _Two lifecycles with/without states_

{code:xml}
<external-component-plugins>
    <target-component>org.exoplatform.services.wcm.publication.PublicationManager</target-component>
    <component-plugin>
        <name>AddLifecycle</name>
        <set-method>addLifecycle</set-method>
        <type>org.exoplatform.services.wcm.publication.lifecycles.StatesLifecyclePlugin</type>
        <init-params>
            <object-param>
                <name>lifecyles</name>
                <object type="org.exoplatform.services.wcm.publication.lifecycles.impl.LifecyclesConfig">
                    <field name="lifecycles">
                        <collection type="java.util.ArrayList">
                            <value>
                                <object type="org.exoplatform.services.wcm.publication.lifecycles.impl.LifecyclesConfig$Lifecycle">
                                    <field name="name">
                                        <string>lifecycle1</string>
                                    </field>
                                    <field name="publicationPlugin">
                                        <string>States and versions based publication</string>
                                    </field>
                                </object>
                            </value>
                            <value>
                                <object type="org.exoplatform.services.wcm.publication.lifecycles.impl.LifecyclesConfig$Lifecycle">
                                    <field name="name">
                                        <string>lifecycle2</string>
                                    </field>
                                    <field name="publicationPlugin">
                                        <string>Authoring publication</string>
                                    </field>
                                    <field name="states">
                                        <collection type="java.util.ArrayList">
                                            <value>
                                                <object type="org.exoplatform.services.wcm.publication.lifecycles.impl.LifecyclesConfig$State">
                                                    <field name="state">
                                                        <string>draft</string>
                                                    </field>
                                                    <field name="memberships">
                                                        <collection type="java.util.ArrayList">
                                                            <value>
                                                                <string>author:/CA/communicationDG</string>
                                                            </value>
                                                            <value>
                                                                <string>author:/CA/alerteSanitaire</string>
                                                            </value>
                                                            <value>
                                                                <string>author:/CA/alerteInformatique</string>
                                                            </value>
                                                            <value>
                                                                <string>author:/CA/informations</string>
                                                            </value>
                                                        </collection>
                                                    </field>
                                                </object>
                                            </value>
                                            <value>
                                                <object type="org.exoplatform.services.wcm.publication.lifecycles.impl.LifecyclesConfig$State">
                                                    <field name="state">
                                                        <string>pending</string>
                                                    </field>
                                                    <field name="membership">
                                                        <string>author:/platform/web-contributors</string>
                                                    </field>
                                                </object>
                                            </value>
                                            <value>
                                                <object type="org.exoplatform.services.wcm.publication.lifecycles.impl.LifecyclesConfig$State">
                                                    <field name="state">
                                                        <string>approved</string>
                                                    </field>
                                                    <field name="membership">
                                                        <string>manager:/platform/web-contributors</string>
                                                    </field>
                                                </object>
                                            </value>
                                            <value>
                                                <object type="org.exoplatform.services.wcm.publication.lifecycles.impl.LifecyclesConfig$State">
                                                    <field name="state">
                                                        <string>staged</string>
                                                    </field>
                                                    <field name="membership">
                                                        <string>publisher:/platform/web-contributors</string>
                                                    </field>
                                                </object>
                                            </value>
                                            <value>
                                                <object type="org.exoplatform.services.wcm.publication.lifecycles.impl.LifecyclesConfig$State">
                                                    <field name="state">
                                                        <string>published</string>
                                                    </field>
                                                    <field name="membership">
                                                        <string>automatic</string>
                                                    </field>
                                                </object>
                                            </value>
                                        </collection>
                                    </field>
                                </object>
                            </value>
                            <value>
                                <object type="org.exoplatform.services.wcm.publication.lifecycles.impl.LifecyclesConfig$Lifecycle">
                                    <field name="name">
                                        <string>lifecycle3</string>
                                    </field>
                                    <field name="publicationPlugin">
                                        <string>Authoring publication</string>
                                    </field>
                                    <field name="states">
                                        <collection type="java.util.ArrayList">
                                            <value>
                                                <object type="org.exoplatform.services.wcm.publication.lifecycles.impl.LifecyclesConfig$State">
                                                    <field name="state">
                                                        <string>draft</string>
                                                    </field>
                                                    <field name="membership">
                                                        <string>author:/platform/web-contributors</string>
                                                    </field>
                                                </object>
                                            </value>
                                            <value>
                                                <object type="org.exoplatform.services.wcm.publication.lifecycles.impl.LifecyclesConfig$State">
                                                    <field name="state">
                                                        <string>published</string>
                                                    </field>
                                                    <field name="memberships">
                                                        <collection type="java.util.ArrayList">
                                                            <value>
                                                                <string>publisher:/CA/communicationDG</string>
                                                            </value>
                                                            <value>
                                                                <string>publisher:/CA/alerteSanitaire</string>
                                                            </value>
                                                            <value>
                                                                <string>publisher:/CA/alerteInformatique</string>
                                                            </value>
                                                            <value>
                                                                <string>publisher:/CA/informations</string>
                                                            </value>
                                                        </collection>
                                                    </field>
                                                </object>
                                            </value>
                                        </collection>
                                    </field>
                                </object>
                            </value>
                        </collection>
                    </field>
                </object>
            </object-param>
        </init-params>
    </component-plugin>
</external-component-plugins>
{code}

In the last example, there are three lifecycles:

* Lifecycle 1: Based on _[StatesAndVersionsPublicationPlugin|#CONTref.Configuration.Plugins.StageAndVersionPublicationPlugin]_.
** This allows to be backward compliant with older Content releases. If all your site contents are using an existing plugin, you can create a lifecycle for it and it will work.
** For new instances, you should use the new plugin with dynamic states capabilities.

* Lifecycle 2: Based on _[AuthoringPublicationPlugin|#CONTref.Configuration.Plugins.AuthoringPublicationPlugin]_.
** Visibility: Define only the "visible" steps. In this example, there is no step for "enrolled". Even if this step exists, it will not be displayed in the UI.
** Automatic: Set a step as "automatic". In this mode, the step will be visible in the UI but it will be managed by the system (e.g. a cron job).
* Lifecycle 3: Simulates the _StatesAndVersionsPublicationPlugin_ plugin. Note that this simple lifecycle will work in a single server configuration.

h3. Listen to a lifecycle {anchor:id=CONTref.Extensions.AuthoringExtension.PublicationManager.ListenToLifecycle}

When a state is changed, you can broadcast an event to add features.
The event could look like this:

{code:java}
listenerService.broadcast(AuthoringPlugin.POST_UPDATE_STATE_EVENT, null, node);
{code}
Listener declaration could look like this:

{code:xml}
<external-component-plugins>
  <target-component>org.exoplatform.services.listener.ListenerService</target-component>
  <component-plugin>
    <name>PublicationService.event.postUpdateState</name>
    <set-method>addListener</set-method>
    <type>org.exoplatform.services.wcm.publication.listener.post.PostUpdateStateEventListener</type>
    <description>this listener will be called every time a content changes its current state</description>
  </component-plugin>
</external-component-plugins>
{code}

h3. Perform tasks when a content's state is updated {anchor:id=CONTref.Extensions.AuthoringExtension.PublicationManager.PeroformTasksWhenContentUpdated}

To perform some tasks when a content's state is updated, you need to create a listener that handles the task and configure it. Following is the general configuration:

{code:xml}
<external-component-plugins>
<target-component>org.exoplatform.services.listener.ListenerService</target-component>
<component-plugin>
<name>PublicationService.event.postUpdateState</name>
<set-method>addListener</set-method>
<type>my.package.MyListener</type>
<description>Your listener description</description>
</component-plugin>
</external-component-plugins>
{code}

With this configuration, your listener _my.package.MyListener_ will be executed each time a content's state is changed.

For example, eXo provides a listener which automatically sends email notifications about the new state to all users of defined groups: _org.exoplatform.wcm.authoring.listener.PostUpdateStateEventListener_. So, the configuration will be:

{code:xml}
<external-component-plugins>
<target-component>org.exoplatform.services.listener.ListenerService</target-component>
<component-plugin>
<name>PublicationService.event.postUpdateState</name>
<set-method>addListener</set-method>
<type>org.exoplatform.wcm.authoring.listener.PostUpdateStateEventListener</type>
<description>This listener will send a mail when there are changes in a content's state</description>
</component-plugin>
</external-component-plugins>
{code}

h2. Context {anchor:id=CONTref.Extensions.AuthoringExtension.PublicationManager.Context}

A context is defined by simple rules. In Content, you can select to enroll the content in a specific lifecycle (for example, publication plugin) based on context parameters.
There are three parameters used to define contexts:
* Remote User: The current user who can create/edit the content.
* Current site name: The site from where the content is created (not the storage but the navigation).
* Node: The node which you want to enroll.

From these parameters, you can easily connect and define contexts based on:
* Membership: Does the current user have this membership?
* Site: On this particular site, you want to enroll contents in a specific lifecycle.
* Path: You can enroll contents in the lifecycles based on their path (from the Node).
* Type of content: You can enroll contents in the lifecycles based on their nodetype (from the Node).

Because each site has a content storage (categories + physical storage), you can select the right lifecycle for the right storage/site.
To avoid conflicts on contexts, you can set a priority (the less is the best).

For example, *Different Contexts*:

{code:xml}
<external-component-plugins>
    <target-component>org.exoplatform.services.wcm.publication.PublicationManager</target-component>
    <component-plugin>
        <name>AddContext</name>
        <set-method>addContext</set-method>
        <type>org.exoplatform.services.wcm.publication.context.ContextPlugin</type>
        <init-params>
            <object-param>
                <name>contexts</name>
                <object type="org.exoplatform.services.wcm.publication.context.impl.ContextConfig">
                    <field name="contexts">
                        <collection type="java.util.ArrayList">
                            <value>
                                <object type="org.exoplatform.services.wcm.publication.context.impl.ContextConfig$Context">
                                    <field name="name">
                                        <string>contextdefault</string>
                                    </field>
                                    <field name="priority">
                                        <string>200</string>
                                    </field>
                                    <field name="lifecycle">
                                        <string>lifecycle1</string>
                                    </field>
                                </object>
                                <object type="org.exoplatform.services.wcm.publication.context.impl.ContextConfig$Context">
                                    <field name="name">
                                        <string>context1</string>
                                    </field>
                                    <field name="priority">
                                        <string>100</string>
                                    </field>
                                    <field name="lifecycle">
                                        <string>lifecycle1</string>
                                    </field>
                                    <field name="membership">
                                        <string>*:/platform/web-contributors</string>
                                    </field>
                                    <field name="site">
                                        <string>acme</string>
                                    </field>
                                    <field name="path">
                                        <string>repository:collaboration:/sites content/live/acme/categories</string>
                                    </field>
                                </object>
                                <object type="org.exoplatform.services.wcm.publication.context.impl.ContextConfig$Context">
                                    <field name="name">
                                        <string>context2</string>
                                    </field>
                                    <field name="priority">
                                        <string>100</string>
                                    </field>
                                    <field name="lifecycle">
                                        <string>lifecycle1</string>
                                    </field>
                                    <field name="site">
                                        <string>classic</string>
                                    </field>
                                </object>
                                <object type="org.exoplatform.services.wcm.publication.context.impl.ContextConfig$Context">
                                    <field name="name">
                                        <string>context3</string>
                                    </field>
                                    <field name="priority">
                                        <string>80</string>
                                    </field>
                                    <field name="lifecycle">
                                        <string>lifecycle3</string>
                                    </field>
                                    <field name="membership">
                                        <string>manager:/company/finances</string>
                                    </field>
                                    <field name="path">
                                        <string>repository:collaboration:/documents/company/finances</string>
                                    </field>
                                </object>
                                <object type="org.exoplatform.services.wcm.publication.context.impl.ContextConfig$Context">
                                    <field name="name">
                                        <string>context4</string>
                                    </field>
                                    <field name="priority">
                                        <string>50</string>
                                    </field>
                                    <field name="lifecycle">
                                        <string>lifecycle4</string>
                                    </field>
                                    <field name="memberships">
                                        <collection type="java.util.ArrayList">
                                            <value>
                                                <string>manager:/CA/communicationDG</string>
                                            </value>
                                            <value>
                                                <string>manager:/CA/alerteSanitaire</string>
                                            </value>
                                            <value>
                                                <string>manager:/CA/alerteInformatique</string>
                                            </value>
                                            <value>
                                                <string>manager:/CA/informations</string>
                                            </value>
                                        </collection>
                                    </field>
                                    <field name="path">
                                        <string>repository:collaboration:/documents/company/finances</string>
                                    </field>
                                    <field name="nodetype">
                                        <string>exo:article</string>
                                    </field>
                                </object>
                            </value>
                        </collection>
                    </field>
                </object>
            </object-param>
        </init-params>
    </component-plugin>
</external-component-plugins>
{code}

The logic is very simple. When creating a content, it should be attached a lifecycle with the lifecyle priority:
* _context4_ is the most important (priority=50): you will enroll the content in the lifecycle "lifecycle4" if:
** The content creator has the _manager\:/company/finances_ membership.
** The content is stored in _repository\:collaboration\:/documents/company/finances_ or any subfolders.
** The content is a '{{exo\:article}}'.
* If not, you will continue with _context3_.

The logic is very simple. When you create a content, go lifecycle by lifecycle starting with the better priority:
* _context4_ is the most important (priority=50): you will enroll the content in the lifecycle "lifecycle4" if:
** The content creator has the _manager\:/company/finances_ membership.
** The content is stored in '_repository\:collaboration\:/documents/company/finances_ or any subfolders.
** The content is a _exo\:article_.
* If not, you will continue with _context3_.

{note}
The contexts will be used only when the content is created and when you want to enroll it in a lifecycle for the first time.
Once you have the corresponding lifecycle, you will set the lifecycle inside the content (see [New Authoring Mixin|#CONTref.Extensions.AuthoringExtension.PublicationManager.NewAuthoringMixin]) and the context service will not be called again for this content.
{note}

h2. New Authoring Mixin {anchor:id=CONTref.Extensions.AuthoringExtension.PublicationManager.NewAuthoringMixin}

{code:xml}
<nodeType name="publication:authoring" isMixin="true" hasOrderableChildNodes="false" primaryItemName="">
  <propertyDefinitions>
    <propertyDefinition name="publication:lastUser" requiredType="String" autoCreated="false" mandatory="false"
      onParentVersion="IGNORE" protected="false" multiple="false">
      <valueConstraints />
    </propertyDefinition>
    <propertyDefinition name="publication:lifecycle" requiredType="String" autoCreated="false" mandatory="false"
      onParentVersion="IGNORE" protected="false" multiple="false">
      <valueConstraints />
    </propertyDefinition>
  </propertyDefinitions>
</nodeType>
{code}
When adding the content in a lifecycle, set the _publication:lifecycle_ property with the corresponding lifecycle.

{note}
A content can be in one lifecycle only.
{note}
Each time you change from one state to another, set the user who changed the state in _publication\:lastUser_.

*Querying based on publication status*: {anchor:id=CONTref.Extensions.AuthoringExtension.PublicationManager.QueryBaseOnPublicationStatus}

By adding this mixin to contents, you can access contents by simple queries based on the current user profile.
For example:
* All your draft contents:
** query: select \* from _nt\:base_ where {{publication:currentState}}"draft" and {{publication:lastUser}}="benjamin".
* All the contents you have to approve.
** call: _PublicationManager.getLifecycles('benjamin','approved')_ => returns lifecycles where you can go to the 'approved' state.
** query: select \* from _nt\:base_ where _publication\:currentState="pending"_ and _publication\:lifecycle="lifecycle1"_ or _publication\:lifecycle="lifecycle3"_.
* All the content that will be published tomorrow.
** query: select \* from _nt\:base_ where _publication\:currentState="staged"_ and _publication\:startPublishedDate_="xxxx".