From a functional point of view, portals are filling the gap between the DAM and Boards. A portal allows to group together different assets and to feature this group within the DAM.

From a DAM perspective, portals is just a tree metadata to index assets. The main relationship for linking an asset to a portal is by checking the asset portals metadata.

In order for portals to have their own landing page, they require some additional properties for storing content.

The portal object

portal is a PONO (Plain Old Noheto Object) defined to meet within a single object, all the needs of a portal to be displayed :

• it is a tree so it can manage sections, with sorting capabilities (portal, position)

• it is i18n and can handle indexed description OR HTML description

• it can be shared with a team like collaborativespace

• it can be private like a board

• it can have viewers

• it can provide a list of assets per entry position

• its visibility can be easily managed through visibility

• it allows the front end to store any view option

Open

Portals fields

The portal object regarding assets

Open

Additional structures and changes to the model

Home widgets

Overview

Faces

Faces of vueapphomewidget have been updated to have BO forms with better behaviour.
Only faces for rowX2, rowX3, rowX4 elements have been updated. Faces for carousel and waffle are still the same. Here you will find a plantuml graph explaining the behaviour.

Download assets of a portal

Overview

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

To initiate a media download, a download request must be registered. This is done by requesting the service api/packaged/portals/zip/register/{portalUUID}, which creates an instance of the portaldownload object. This object contains all the necessary information to prepare the ZIP file.

The service will generate a portaldownload object, which holds details like:

1. name: The name of the ZIP file (without the extension).

2. portal: The unique identifier (UUID) of the portals/section from which assets are downloaded.

3. uuids: The UUIDs of the selected media files for download.

4. data: Additional metadata about the request such as download options, file transformation profiles, etc.

5. expires: The expiration date for the download link.
   Once it reaches its expiration date, the instance will be automatically deleted. The expiration date is obtained by adding to the date of the request creation, the value of the parameter portal_download_expiration of the plugin PACKAGED_Portals (the Default value is 7 days).

6. query: If provided, this specifies a query to select assets for dynamic download. If filled, the value set in the uuids property is ignored.

    

Downloading the media

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

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:

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.

Portals filters managment

Since 2024.5 users can edit filters of portals. Each portal can have it's own filters configuration.
The selected filter configuration will also be applied to all it's sections.

By default all portals are presenting filters from: src/wedia-portal-apps-configs/starter-kit/dam/explore/filters/default-cursor-config/default-resource-config.json
=> default filters configuration

(Actually it's very important for your project that this file exists and it's value is not just null. It may cause problems in the entire app)

We are allowing users to modify the configuration for a each portal. Filters configuration can be modified if user has the rights to edit the portal.
To update the filters config, user can choose from default filters configuration and from other named filters.
The updated config which will be stored on the portal instance, will be written on portal.state through an array called filters

In the content below we will see filters of different "types" / "names"

• named filters

  • Lets say our default configuration is :

    •  

    • What is really important here is filters array. We can see that we have only "named filters", named filters are filters called by a simple string (filter’s name). This string represents a file under dam/named-filters/ or under common/named-filters which is containing the details of filter’s configuration : field, i18n, other props...
      Named filters are also created and stored unded dam/named-filters when a filter is created from wedia-config.
      All filters created from wedia-config can be used on the portal’s filters edition feature !

• raw filters

  • Lets say our default configuration has been edited for a project :

    • Now we have a new filter config added to the default config (Project developper action).
      This filter is called a raw filter, because it's configuration is directly on the filters configuration.
      I've used a simple example with only a field value, but it's also working for grouped filters with i18n props and config props inside as array etc...

• named additional filters

  • Same as named filter but the detailed configuration contains additional: true

• raw addiftional filters

  • Same as raw filter config but the configuration contains additional: true

For each named filter, we are computing a display label from it's field or from a prop in filters configuration.
For each raw filter we are also computing a label the same way, but we've added a "custom " prefix to differentiate the named filters from the custom/project added ones.
Also custom filters are by default selected and can not be removed. The checkbox is disabled.

Foreach named additional filter we are computing a display label from it's field or from a prop in filters configuration, checkbox is not disabled.
A specific prefix is added to differentiate it from standard named filters.

Foreach raw additional filter we are computing a display label from it's field or from a prop in filters configuration, checkbox is disabled and by default selected.
An other word is added to the label differentiate it from standard raw filters and named additional filters.

We also have named filters under common folder. These named-filters are not available for selection. If a Project developper adds a common/named-filter filter to the default configuration it will not be displayed on the filter edition modal. However, the filter will still be available for use on the portal.

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.

Role types default permissions

insert rules

Administrators and Contributors types are allowed to create portals

objectdata/insert/$anycreation

Other users can’t create portals

update rules

Administrators are allowed to update any portal

objectdata/insert/$anystatus/$anyowner

Other roles are allowed to update their portals and portals they are team members of :

objectdata/update/$anystatus/$selfowner

objectdata/update/$anystatus/$teammember

View rules

Administrators are allowed to view any portal

objectdata/insert/$anystatus/$anyowner

Other roles are allowed to view their portals, portals they are team members of, portal they are members of viewers, internal portals and public portal :

objectdata/view/$online/$anyowner

objectdata/view/$public/$anyowner

objectdata/view/$anystatus/$selfowner

objectdata/view/$anystatus/$teammember

objectdata/view/$anystatus/$viewer

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 : Portals installation guide | 4.3/ Segmentation of portals