Cloning portlet

From VYRE

Jump to: navigation, search
Picture 1: Example data model addressing the cloning portlet

This portlet is a part of default Unify installation, from version 4.4]

Contents

Usage

The Cloning portlet is made to clone connected items. The word connected implies items are connected via item links or item lists. Connections form a chain (see domain model) which is cloned according to default and specified rules; items that are not connected to the chain are out of the scope and cannot be cloned. Cloned items can belong to the same or different stores.

Let's look at the picture. Collection schema items there are shown as parallelograms while item links are ellipses. You can see that items A0, B0, C0, D0 and E0 belong to the cloneable chain while F isn't. The dependency to the chain is not determined by the links only but by configuration and links. In other words, the portlet administrator must define collection schemas items of which it wants to clone, but schemas having no interconnections (item link definitions or list definitions in between) cannot be selected.

Item cloning is relatively straightforward: items which belong to cloneable space, are duplicated, with all the content and metadata attributes. That said, item A0 would be cloned into A1, B0 into B1 and so on. Item F does not belong to the chain therefore is not cloned. The greatest complexity here comes from item link and list handling.

Rules for links, connecting cloneable items

Picture 2: Retainable (sticky) link behaviour on different conditions

The default policy (1) is that item links and lists which connect chain nodes, are cloned to connect corresponding cloned items, unless stated otherwise. For the given image, this rule would apply to link2_A0-B0, link_B0-C0, link_C0-D0 and link1_D0-E0 - those links were cloned to link2_A1-B1, link_B1-C1, link_C1-D1 and link1_D1-E1, correspondingly. By cloning, new link connects two newly created items.

Alternatively, it is also possible to clone/retain the link (make it sticky). In this case, a new link is created but one end of the link is attached to the original item and another end to the cloned item. In the given picture, this would be the case for link1_A0-B0 which is cloned/retained into link1_A0-B1. It is possible to select which end is retained (B0 or A0, in our case it is the latter).

Let's look at the Picture 2. There are different variations how this can happen. The picture in the left shows the case when the item A is the link parent and B - child while the picture in the right shows the inverse. Items A and B are cloned:

  • by not retaining links (non-sticky), as shown into A1 and B1.
  • by retaining links - making them sticky to link parent, into A2 and B2;
  • by retaining links - making them sticky to link child, into A3 and B3.

Finally, it is possible to forbid cloning by specifying this in the configuration. In our example (shown in Picture 1) this would be link2_D0-E0 a clone of which is not present in the cloned space.

Rules for links, connecting cloneable items with external items

The default policy (2) here is to create new retainable (non-sticky) links, unless stated otherwise. In our example, link1_C0-F is cloned/retained into link1_C1-F. All links to external items are by default cloned and retain connections to those external items.

It is also possible to specify that links to external items should not be cloned. link2_C0-F would be an example of this capability.

Other link rules

  • User links do not play any role in cloning; they never form any links of cloning chain.
  • If a link definition is defined for schema of cloned item, but actual link itself isn't, then the new link for cloned item will not be created, regardless of link type.

Rules for item lists

Picture 3: Retainable (sticky) list behaviour on different conditions
  • Chain connection can only follow if the item is the descriptor item. If an item is included in the list, but is not a descriptor item, the list and its items are not cloned, unless the same list has a descriptor item elsewhere in the clonable chain.
  • If list addresses multiple items within same store, all items will be cloned/created.
  • If the same item is added to the list twice, both relationships will be cloned (and so on).
  • Similar to item links, same cloning/creating, cloning/retention and non-cloning policies and configuration rules apply as with regards to inner or outer cloning space.

See Picture 3 for an example how sticky lists would work in the cloning process.

Configuration

When configuring this portlet, the following settings must be defined:

  1. schema - ordered list of schemas which form the cloning chain. If you want to override any of attribute values, specify them there as shown in the example. Don't forget to specify the isContent flag - it must be true if the attribute belongs to content, or false for metadata.
  2. linkDef2Retain and listDef2Retain - list of link and/or list definitions which interconnect chain nodes and would be retaining ("sticking") one connection end of the cloned link to to one of the original items. The list can only consist of link definitions or list definitions, having all collection schemas members of the chain. Specify whether you want to stick this to link parent or child.
  3. linkDef2Drop and listDefToDrop - list of link and/or list definitions which need not to be cloned. Every list item should have a reference to schema participating in the chain.
  4. sendReport - a flag which if set to true, will triger a simple e-mail being sent to the user running the cloning process. Set it to false if you don't want it.
  5. redirectPath - string, containing HTTP URL to redirect the user to, after the process is done.
  6. sync - a flag which if set to false, will run entire cloning process in the background and redirect the user to the next page immediately. A report will be sent when cloning is done. Otherwise, the user will have to wait for result page to load after pressing submit button. For the latter case, the result page would only load when the cloning process is complete.

Due to complexity and portlet nature, the edit mode of the portlet only allows to edit the configuration XML, and there is no GUI mode. However, if the configuration XML is changed, the portlet needs to be redeployed as all other portlets do in order to get the changes affected. Below is an example of such a configuration file:

<CloningPortletPreferences>
  <!-- #1 (schema): A list of schemas forming the chain. If you want to override any of attribute values,
            specify them there as shown in the example. Don't forget to specify the isContent flag - it must be true if
            the attribute belongs to content, or false for metadata -->
  <schema id="123">
    <attributes>
      <attribute defId="1122" newValue="newValue1" isContent="true"/> <!-- isContent flag switches between content or metadata attrs-->
      <attribute defId="2233" newValue="newValue2" isContent="false"/>
    </attributes>
  </schema>
 
  <schema id="456"/>
 
 <!-- #2 (linkDef2Retain and listDef2Retain): List of link and/or list definitions which interconnect chain nodes and
        would be retaining ("sticking") one connection end of the cloned link to to one of the original items. The list
        can only consist of link definitions or list definitions, having all collection schemas members of the chain.
        Specify whether you want to stick this to link parent or child by altering value of stickToParent attribute. -->
  <linkDef2Retain entityId="221" stickToParent="true"/>
 
  <listDef2Retain entityId="223" stickToParent="true"/>
 
  <listDef2Retain entityId="332" stickToParent="false"/>
 
<!-- #3 (linkDef2Drop and listDefToDrop): list of link and/or list definitions which need *NOT* to be cloned. Every
        list item should have a reference to schema participating in the chain. -->
  <linkDef2Drop>11</linkDef2Drop>
 
  <listDef2Drop>22</listDef2Drop>
 
  <listDef2Drop>33</listDef2Drop>
 
<!-- #4 (sendReport): a flag which if set to true, will triger a simple e-mail being sent to the user running the
        cloning process. Set it to false if you don't want it. -->
  <sendReport>true</sendReport>
 
<!-- #5 (redirectPath): string, containing HTTP URL to redirect the user to, after the process is done. -->
  <redirectPath>/some/path</redirectPath>
 
<!-- #6 (sync): a flag which if set to false, will run entire cloning process in the background and redirect the
        user to the next page immediately. A report will be sent when cloning is done (if configured). Otherwise, the 
        user will have to wait for result page to load after pressing submit button. For the latter case, the result
        page would only load when the cloning process is complete. -->
  <sync>false</sync>
 
</CloningPortletPreferences>

Logging and reporting

Either in synchronous, or asynchronous mode the portlet will return to the configured page after the "Clone" button is pressed. There are two ways of getting an idea over what's happened:

  • A brief e-mail will be sent to the current user about success or failure;
  • The system will log statements in the system log providing the log level is set to DEBUG for the following classes:
    • vyre.portlets.cloning.ClonedItemPreferences
    • vyre.portlets.cloning.CloneWorker
    • vyre.portlets.cloning.CloningPortletPreferences
    • vyre.portlets.cloning.EditController
    • vyre.portlets.cloning.ViewController


Few notes on business logic

  • The page containing the portlet must be loaded in Item display mode when viewing.
  • When in view mode, portlet will show input fields for name and description of the cloned item. These will be applied to the "first" item; connected items will retain their existing names and descriptions.
  • The portlet would not clone connected items if they are deleted.

Known limitations

  • The portlet cannot clone secondary items. This means that if original item has secondary items, the relevant copies for cloned item will not be created.
  • The portlet cannot clone file store items but only data store items. This is due to the added complexity of handling the file services, although it should be relatively easy to add this functionality later on if required. Please note that links to those items are cloned. The support for cloning file store items has been added in version 4.6.2.1.
  • The attribute override feature only works for those attributes which are present in the original item. E.g.: if configuration says the cloning process should override attribute X with value "foo", but the clonable item does not have attribute X defined, the resulting (cloned) item will not contain attribute X as well.
  • The portlet is not localized due to lack of relevant backend support features only available in 4.4 release (it was written way before 4.4).
  • The portlet does not run in a transaction. If something unexpectedly fails in the middle of the cloning process, newly cloned items are not deleted (rolled back).

See Also

External Links

N/A

Personal tools