Package com.appiancorp.suiteapi.ix.data.portlet

Class PortletIxHelper

java.lang.Object
com.appiancorp.suiteapi.ix.data.portlet.PortletIxHelper
Direct Known Subclasses:
DefaultPortletIxHelper
public abstract class PortletIxHelper extends Object
This is the base class for all portlet import/export (ix) helper classes. A "portlet ix helper class" is a concrete class that extends this class. A different portlet ix helper class can be specified for each PortletType, using the optional portlet type extension PortletType.EXTENSION_PORTLET_IX_HELPER_CLASS. The ix helper class can be registered along with the portlet type definition in portlet-type-config.xml (see that file for examples of this).

It is not required to implement a custom helper class for every portlet type. If a portlet type does not specify an ix helper class, portlets of that type will still be exported & imported correctly, but the portlet parameters will NOT be exported/imported. Not importing the parameters will result in the portlet being un-configured after it is imported in the target system (unless the portlet has no configuration in the first place or has a fallback configuration, such as the My Tasks portlet).

In order to enable the export & import of portlet parameters, there are 2 options:

  1. If the portlet has parameters, but none of them reference Appian objects, no custom helper class needs to be implemented. Instead, the default helper DefaultPortletIxHelper should be specified as the ix helper for that portlet type; this is all that's needed for the portlet parameters to be exported & imported.
  2. If the portlet has some parameters that reference Appian objects, a custom ix helper must be implemented to enable the import & export of the parameters. The custom helper needs to implement these two methods: replaceIdsWithUuids(java.util.Map<java.lang.String, java.lang.Object>, com.appiancorp.suiteapi.ix.data.portlet.PortletIxHelper.ExportBinder) and replaceUuidsWithIds(java.util.Map<java.lang.String, java.lang.Object>, com.appiancorp.suiteapi.ix.data.portlet.PortletIxHelper.ImportBinder).

Additionally, a custom portlet ix helper class can be implemented in order to export & import custom portlet data (data that is not stored within the portlet parameters map). In that case, the custom helper needs to implement these methods: exportExtraData(java.lang.Long, com.appiancorp.services.ServiceContext)/exportResources(java.lang.Long, com.appiancorp.services.ServiceContext, com.appiancorp.suiteapi.ix.data.portlet.PortletIxHelper.ResourceExporter) and importExtraDataAndResources(java.lang.Long, java.util.Map<java.lang.String, java.lang.String>, com.appiancorp.services.ServiceContext, com.appiancorp.suiteapi.ix.data.portlet.PortletIxHelper.ResourceImporter). This can be used to enable import/export of binary files and [String, String] key-value pairs.

  • Constructor Details

    • PortletIxHelper

      protected PortletIxHelper()

  • Method Details

    • getInstance

      @Deprecated public static PortletIxHelper getInstance(Class<? extends PortletIxHelper> portletIxHelperClass, com.appiancorp.ix.Operation op, Long portletId, String portletUuid, com.appiancorp.ix.diagnostics.Diagnostics d)
      Deprecated.
      use getInstance(Class, Operation, Long, String, Diagnostics, ServiceContext)

    • getInstance

      public static PortletIxHelper getInstance(Class<? extends PortletIxHelper> portletIxHelperClass, com.appiancorp.ix.Operation op, Long portletId, String portletUuid, com.appiancorp.ix.diagnostics.Diagnostics d, ServiceContext sc)

    • getServiceContext

      protected ServiceContext getServiceContext()
      Returns the current service context.

    • getTypedId

      protected com.appiancorp.ix.TypedId<com.appiancorp.ix.data.PortletHaul,Long,String> getTypedId()
      Returns the id of the portlet that this helper is processing.

    • addDiagnosticMessage

      protected void addDiagnosticMessage(com.appiancorp.ix.diagnostics.Diagnostic d)
      Adds a message (such as a warning) that will be displayed to the user after the overall export or import operation is complete.

    • replaceIdsWithUuids

      public abstract void replaceIdsWithUuids(Map<String,Object> portletParamsMap, PortletIxHelper.ExportBinder b) throws AppianException
      Replaces all local ids within the portlet parameters with UUIDs. This method is invoked during the export of a portlet. The UUID bound to each local id should be retrieved using the provided PortletIxHelper.ExportBinder.
      Parameters:
      portletParamsMap - The map of portlet parameters (see Portlet.getParameters()).
      b - API for mapping local ids to uuids.
      Throws:
      AppianException - If the export of this portlet should be failed (the export driver will automatically handle the exception: it will add the portlet to the failed list and proceed with the export of other objects).

    • replaceUuidsWithIds

      public abstract void replaceUuidsWithIds(Map<String,Object> portletParamsMap, PortletIxHelper.ImportBinder b) throws AppianException
      Replaces all UUIDs within the portlet parameters with local ids. This method is invoked during the import of a portlet, and performs the reverse of the conversions made by replaceIdsWithUuids(Map, ExportBinder). The local id corresponding to each UUID should be retrieved using the provided PortletIxHelper.ImportBinder.
      Parameters:
      portletParamsMap - The map of portlet parameters (see Portlet.getParameters()).
      b - API for mapping uuids to local ids.
      Throws:
      AppianException - If the import of this portlet should be failed (the import driver will automatically handle the exception: it will add the portlet to the failed list and proceed with the import of other objects).

    • exportExtraData

      public Map<String,String> exportExtraData(Long portletId, ServiceContext sc) throws AppianException
      Retrieves any custom portlet data to be exported.
      Parameters:
      portletId - The id of the portlet being exported.
      sc - The service context of the user performing the export.
      Returns:
      A map of additional data to be exported. This data will be passed in to #importExtraData during import of the portlet.
      Throws:
      AppianException - If the export of this portlet should be failed (the export driver will automatically handle the exception: it will add the portlet to the failed list and proceed with the export of other objects).

    • exportResources

      public void exportResources(Long portletId, ServiceContext sc, PortletIxHelper.ResourceExporter re) throws AppianException
      Exports portlet resources (such as binary files).
      Parameters:
      portletId - The id of the portlet being exported.
      sc - The service context of the user performing the export.
      re - API for exporting resources.
      Throws:
      AppianException - If the export of this portlet should be failed (the export driver will automatically handle the exception: it will add the portlet to the failed list and proceed with the export of other objects).

    • importExtraDataAndResources

      public void importExtraDataAndResources(Long portletId, Map<String,String> extraData, ServiceContext sc, PortletIxHelper.ResourceImporter ri) throws AppianException
      Stores any custom portlet data exported using exportExtraData(java.lang.Long, com.appiancorp.services.ServiceContext) and exportResources(Long, ServiceContext, ResourceExporter).
      Parameters:
      portletId - The id of the portlet being imported.
      extraData - The map data exported using exportExtraData(java.lang.Long, com.appiancorp.services.ServiceContext).
      sc - The service context of the user performing the import.
      ri - API for importing resources.
      Throws:
      AppianException - If the import of this portlet should be failed (the import driver will automatically handle the exception: it will add the portlet to the failed list and proceed with the import of other objects).