...

The media download functionality allows users to download a selection of assets from a portal as a ZIP file. The process involves creating a download request and then retrieving the file through a download link.

The zip will not be created on the server but directly sent to the request flow.

Registering the download request

...

1. The download service lets users retrieve the ZIP file from a portaldownload instance.

2. The download link uses the UUID of the portaldownload instance created during the register step.

3. API Example: GET api/packaged/portals/zip/download/{portalDownloadUUID}

4. Optional parameter :

   • filename: Custom name for the ZIP file

Registered Services

Below is a list of services used within the plugin PACKAGED_Portals for the portals feature.

Triggers

Portal

The service com.wedia.packaged.portals.extensions.PortalsTrigger contains the logic for managing triggers related to the "portal" object. It ensures that the appropriate actions are performed whenever certain events (here insertion or update) occur on the portal object.

• Visibility

The visibility property of the portal object controls the visibility state of an instance. Three values are possible for that property: public, private, and internal. If an unknown value is set inside that property, it will be replaced by a value that will be inferred from the current instance properties.

The properties controlled by the visibility property are status and private.

• Synchronization between page and sections

With the help of the service trigger on the portal object, some properties are automatically propagated from the parent portal to its sections.

Those properties are team, viewers, private, status and activated.

On the other hand, if a section has one of these properties set to a value different from its parent portal, it will be rolled back to the portal’s value for that property.

• Send notification to viewers/team

The trigger on portal is also used to send notifications when one of the properties team or viewers is updated with a new user.

Assets

The plugin PACKAGED_Portals provides a trigger on assets related to portals (objects that have the tag damobject and a field portals that points to the portal object). That trigger is executed whenever an asset is inserted or updated.

It handles essentially the correct assignment/removal to/from portal’s sections when inserting or updating assets, through the portals property, ensuring that the management of the property portal.newestitems is correctly updated with the uuids of the newly added/removed asset.

The trigger also makes sure that instances assigned to portals property are updatable by surfer. If it’s not the case, an error will be thrown during save.

1. Portal Object Trigger Service

• Service Class: com.wedia.packaged.portals.extensions.PortalsTrigger

• Interface: com.noheto.extensions.interfaces.services.IObjectTriggerBusinessService

• Description:
  This service contains the logic for managing object triggers related to the "portal" object. It ensures that the appropriate actions are performed whenever certain events (here insertion or update) occur on the portal object.

2. Assets Object Trigger Service

• Service Class: com.wedia.packaged.portals.extensions.AssetsTrigger

• Interface: com.noheto.extensions.interfaces.services.IObjectTriggerBusinessService

• Description:
  This service manages the triggers associated with DAM Objects that have a property named portals and that points to the portal object. It handles the management of assignments/removal of portal’s sections when inserting or updating assets, through the portals property.

3. Plugin Lifecycle Management Service

• Service Class: com.wedia.packaged.portals.extensions.PluginLifecycle

• Interface: com.noheto.extensions.interfaces.services.IPluginLifeCycleBusinessService

• Description:
  This service handles the lifecycle of the plugin, initializing various singletons and thread pools when the plugin PACKAGED_Portals starts or stops.

4. Portals API Service

• Service Class: com.wedia.packaged.portals.extensions.PortalsAPIService

• Interface: com.noheto.extensions.interfaces.services.AbstractPluginApiService

• Description:
  This service acts as the entry point for the public APIs related to portals. It exposes functionality that allows the front or external systems/users to interact with the portals and perform operations such as assignments/removal of assets to/from sections, media downloads, etc.

5. Portals Admin API Service

• Service Class : com.wedia.packaged.portals.extensions.PortalsAdminAPIService

• Interface: com.noheto.extensions.interfaces.services.AbstractPluginApiService

• Description:
  This service serves as the entry point for administrative APIs related to the portals. It allows administrators to configure, manage, and monitor portal-related features and availability.

6. WXM_RESTAPI Extension Service

• Service Identifier: com.noheto.restapi.startup.ApiBusinessServiceStartup

  • Service Class: com.wedia.packaged.portals.extensions.PortalsCustomSection

• Interface: com.noheto.extensions.interfaces.services.InstallableService

• Description:
  This service extends the standard APIs provided by the WXM_RESTAPI plugin. It is mainly used to provide a $custom section when using DAM/DATA services on portal object in order to provide additional pieces of information for the front.

Security

...

Configuration Entry Points

The bulk download functionality on portals uses specific configuration entry points within the cart’s download services to centralize configuration sources.

Profile Settings

When downloading a selection of assets in the portal, the service defaults to the configuration set in the previewsProfiles parameter of the WXMCART_2 plugin. If this parameter is not accessible, the service will fall back to the following variations, in order: original and default.

Zip File Size Limits

To ensure manageable downloads, the following parameters from the WXMCART_2 plugin define the zip file size thresholds:

• zip.maxLength (Default: 4096 MB): This parameter sets the maximum allowable size for a zip file generated when downloading assets. If the zip exceeds this size, the download is halted.

...

• zip.warnLength (Default: 300 MB): When the zip file size reaches this threshold, a confirmation modal will appear to let the user decide whether to continue with the download.

Internationalization Bundle

The WXMCART_2 plugin provides the internationalization resources used within the zip files downloaded from portals. This ensures that all text and messages within the zip adhere to the localized settings defined by the plugin.

Registered Services

Below is a list of notable services used within the plugin PACKAGED_Portals for the portals feature.

Triggers

Portal

The service com.wedia.packaged.portals.extensions.PortalsTrigger manages triggers related to the "portal" object. It ensures that appropriate actions are performed whenever certain events, such as insertion or update, occur on the portal object.

Visibility

The visibility property of the portal object controls the visibility state of an instance. There are three possible values for this property: public, private, and internal. If an unknown value is set for this property, it will be replaced with a value inferred from the current instance properties.

The properties controlled by the visibility attribute are status and private:

Synchronization Between Portal and Its Sections

With the help of the service trigger on the portal object, certain properties are automatically propagated from the parent portal to its sections. These properties include team, viewers, private, status, and activated.

If a section has one of these properties set to a value different from its parent portal, it will be reverted to the portal’s value for that property.

Sending Notifications to Viewers/Team

The trigger on the portal is also responsible for sending notifications when the team or viewers property is updated with a new user.

Assets

The PACKAGED_Portals plugin provides a trigger on assets related to portals (objects tagged as damobject with a portals field pointing to the portal object). This trigger is executed whenever an asset is inserted or updated.

Primarily, it ensures the correct assignment or removal of assets to or from the portal’s sections through the portals property, updating the portal.newestitems property with the UUIDs of the newly added or removed assets.

Additionally, the trigger checks if instances assigned to the portals property are updatable by the current surfer. If this is not the case, an error will be thrown during the instance save process.

API for Assigning/Removing Assets to/from Portal’s Sections

A key API service within the portals feature is the one that assigns assets to a portal’s section. The removal process follows the same principle.

• Endpoint: api/packaged/portals/assignToPortal/{uuid_of_section}

It accepts a list of UUIDs as a payload (application/json) representing the assets to be assigned:

{ "assets": ["uuid1", "uuid2", "uuid3"] // List of asset UUIDs to assign to the portal }

Before executing, the service performs several checks:

1. Check if the surfer is connected - returns a 401 status code if this fails.

2. Check if the current surfer is allowed to update the portal instance - returns a 403 status code if this fails.

3. Check if the payload is valid - returns a 400 status code if this fails.

4. Check if the portal specified in the payload exists - returns a 400 status code if this fails.

5. Unhandled errors - return a 500 status code.

If the number of submitted assets exceeds the limit defined by the plugin parameter max_assets_async, the assignment will be processed asynchronously. Otherwise:

• If an asset instance among those provided is lockable for an update, it will be automatically assigned to the portal.

• Otherwise, the assignment will be recorded in a queue to be processed later by a scheduled thread pool execution.

...

Custom Section Service

This service extends the standard APIs provided by the WXM_RESTAPI plugin. It is mainly used to provide a $custom section when using DAM/DATA services on portal object in order to provide additional pieces of information for the front.

Security

From a security perspective, we observe standard security rules. Additionally, we assume that assigning an asset to a portal should be allowed when the user is allowed to update the target portal.

The default starter-kit configuration relies on permissions available / configurable based on the role type.

...

LOWER(objectname) = 'portal'
AND
surfer.connectedisconnected = 1
AND
(
  object.status = 6
  OR
  object.private = 2
  OR
  object.owner = surfer.id
  OR
  NBCOMMONELEMENTS(object.team, surfer.id) > 0
  OR
  NBCOMMONELEMENTS(object.viewers, surfer.id) > 0
)

Extending portals

...

  OR
  NBCOMMONELEMENTS(object.viewers, surfer.id) > 0
)

Extending portals

Adding metadata to the portal object

Portal’s object can be extended. You can add properties for filtering, segmentation, or other specific purposes.

For each added property you can decide to display it on portal’s edition or creation form, you can manage this through portal’s structure facets configuration.
We recommend hiding the added properties in the default facet. Based on your needs, you can make them editable in the page facet (for portal creation) or in the page_update facet (for portal edition).

...

...

You can find another example of property addition for segmentation purposes here : https://crossmedia.atlassian.net/wiki/spaces/WD/pages/3298787349/Portals+installation+guide#4.3%2F-Segmentation-of-portals