Portals installation guide

Prerequisites

All the bullet points below have to be respected if you want to use the new feature on your project

Portal & Engine version 2024.4 (or after)
New structures
- portal
- wkfpkgportal
- wkfpkgportalaction
- portaldownload
- homewidgetelttype
Updates on existing structures :
- asset & all your #damobject structures
- vueapphomewidget
Creation or updates of/on instances for :
- wkfpkgportal => CREATION
- wkfpkgportalaction => CREATION
- homewidgetelttype => CREATION
- vueapphomewidgettype => UPDATE
- pkgroletemplate => UPDATE
Plugins :
- PACKAGED_Portals => activated
Portal’s configuration :
- portals config domain added
- named action actions added in common
- features config has a new entry called portals, it should be set to true, if you want to use the creative workflow and it is by default activated

1/ Install on existing projects

Steps to follow for installing portals on existing projects, after fulfilling the prerequisites.

1.1/ Permissions

To have correct permissions on portals we also recommend to update pkgroletemplate instances.
If you can afford to reset your permissions from the nar, don’t forget to call the update (admin) endpoint given by PACKAGED_Security.
A touch on the users may also be needed to ensure that users, roles and roles templates are correctly synchronized.

For the portals to be fully functionnal, and to benefit from the “share” feature fully, the “update” endpoint will add a new instances in pkgsecugroup & pkgsecupermission, to allow users to access public portals and their assets without being logged in (direct access by link).

If you can’t reset your permissions, you must modify them manually, to do this, you will have to check the differences (diffs) in the new role templates, which can be found in the upgrade guide linked here. => https://crossmedia.atlassian.net/wiki/spaces/WD/pages/3181936642/Upgrading+to+2024.4#pkgroletemplate

After this, call the update endpoint to retrieve the new pkgsecugroup and pkgsecupermission instances.

1.2/ Front app

You will also need to upgrade your portal to retrieve all the new components and configs to benefit from the portals

1.3/ Asset Libraries

For all your library structures, which are containing assets that you want to use in portals, you will need to update them by adding a new prop called portals, the same way it’s present on asset structure (tags too).

All asset libraries created from wedia-config will be prepared to work with the portals, and will have a portals prop

1.4/ Front app home widgets

We’ve added the possibility to link portals to a vueapphomewidget instance, and therefore display them on the front’s home page as widgets, the same way boards are displayed.

To benefit from this feature, you have to update your vueapphomewidget structure, retrieve the new structure called homewidgetelttype and it’s instances (from the nar) and update your current vueapphomewidgettype instances. vueapphomewiget received new props and a significant number of faces (facet/ “facettes”). More details here : https://crossmedia.atlassian.net/wiki/spaces/WD/pages/3299180556/Portals+feature+explained#Home-widgets

After updating your structure, we recommend updating any existing instances and selecting the element type "Board" when it's displayed as "None." This update won't affect the front-end rendering, but it will ensure your data remains more consistent.

2/ Install on projects starting on 2024.4

In this case, you will only have to respect the Prerequisites. And the feature is coming by default with the 2024.4.

Don’t forget to call the update (admin) endpoint given by PACKAGED_Security.

If you create asset libraries without using wedia-config, make sure to copy our asset structure if you want to fully benefit from the new feature.

3/ Don’t need the portals

If you are updating your app to the 2024.4 and you don’t want to benefit from or use the new feature, here are the steps to follow :

Disable PACKAGED_Portals
In your front app’s feature config, set portals to false
Deactivate all permissions to portals feature from wedia-config

4/ Configuration possibilites

4.1/ Portals list filters

4.1.1/ Portal list filters configuration

Portals list filters are configured in this file :
starter-kit\portals\explore\filters\default-cursor-config\default-resource-config.json
The configuration is set up and behaves in the same way as it does for the dam domain.

By default, all provided filters are activated. This was achieved while still following the app’s existing principles (same components, filter configurations system combined with named configurations).
We did this by utilizing two core features: constraint filters and cursor query parameter.

Below is portals lists cursor

{
  "i18nQuery": true,
  "orderby": "modified desc",
  "path": "dam/data/portal",
  "security": ["objectdata/update","objectdata/delete"],
  "withAggregates": false,
  "withRights": true,
  "staticQuery": {
    "portal": {
      "empty": true
    }
  },
  // default active constraints
  // for portals list
  "query": {
    "or:portalrole.creator":{
      "owner": { "eq": "${surfer.id}" }
    },
    "or:portalrole.colaborator":{
      "team": { "ct": "${surfer.id}" }
    },
    "or:portalrole.viewer":{
      "viewers": { "ct": "${surfer.id}" }
    },
    "or:portalrole.none":{
      "and": [
        { "owner": { "neq": "${surfer.id}" } },
        { "team": { "nct": "${surfer.id}" } },
        { "viewers": { "nct": "${surfer.id}" } }
      ] 
    },
    // this constraints allows to hide all content when no portalrole constraint is selected
    "or:portalrole.hide": {
      "id": { "eq": 0} 
    },
    "or:portaltype.public":{
      "visibility": { "eq": "public" }
    },
    "or:portaltype.internal":{
      "visibility": { "eq": "internal" }
    },
    "or:portaltype.private":{
      "visibility": { "eq": "private" }
    },
    // this constraints allows to hide all content when no portaltype constraint is selected
    "or:portaltype.hide": {
      "id": { "eq": 0} 
    },
    "or:portalactive.true": {
      "activated": { "eq": true }
    }
  }
}

You can see on the cursor definition above that the query param’s value is quite large. It is actually containing all the default activated constraints. The key of this implementation is to make sure that the same constraint keys are used on filter’s definition and on cursor’s query param.

Constraint filter’s component(s) have also been updated to allow new UI (selected values on dropdown label, checkbox inline filter)

To improve the user experience, we were tasked with ensuring that if neither of the two default dropdown filters has a selected option, no results are displayed. This was made possible using a small adjustment in the cursor’s query configuration.

These two constraints are always applied to the cursor, allowing us to achieve the desired effect.

    "or:portalrole.hide": {
      "id": { "eq": 0} 
    },
    ...
    "or:portaltype.hide": {
      "id": { "eq": 0} 
    },

The logic works as follows: between constraints like or:portalrole:xxx and or:portalrole:yyy, the system applies an OR operator. However, between constraints such as or:portalrole:xxx and or:portaltype:xxx, the system applies an AND operator. Below, you'll find more details about what happens at the "query" level:

We’ve applied one role constraint and one type constraint. The result at the “query” level is :
- (or:portalrole:xxx OR or:portalrole.hide) AND (or:portaltype:xxx OR or:portaltype.hide)
  - no hidden result, filtered according to chosen constraints
We haven’t applied a role constraint, but we’ve applied a type constraint. The result at the "query" level is:
- (or:portalrole.hide) AND (or:portaltype:xxx OR or:portaltype.hide)
  - hidden result

4.1.2/ Example of configuration

This filters configuration can be edited, to add or remove some filters. The configuration system follows principles that are used on the entire front app. Here you can find an example of a possible customization

starter-kit\portals\explore\filters\default-cursor-config\default-resource-config.json

{
  "hideSide": true,
  "filters": [
    "portalsRoles", 
    "portalsTypes",
    "portalsActive",
    "status"
  ]
}

To activate filters by default when the page loads, follow the approach used for role or type filters. This involves creating a specific filter configuration with constraints and reusing the same constraint keys in the cursor definition within the query parameter

4.2/ Portal default filters

4.2.1/ Portal default filters configuration

By default, portals feature comes with filters on portal’s detail view. These filters are allowing user to filter displayed assets. The filter config used and displayed here, is the same one which is used on new univers creation.

It means that you can modify it, but the next created universe will be created by default with the updated filters config.

file path : starter-kit\dam\explore\filters\default-cursor-config\default-resource-config.json

4.2.2/ Example of configuration

Here we’ve added a prop from asset structure: colorspace

And this is the result

4.3/ Segmentation of portals

You can segment portals by following this documentation https://crossmedia.atlassian.net/wiki/x/EAAnPw

Here are the steps to follow for a possible segmentation by “organization”:

Add a property organization, which is a child of organization, to user structure. This property should have the tag segmenting/tree/readorgs.
Add a property organization, which is a child of organization, to portal structure. This property should have the tag segmented/readorgs.
portal structure should have the tag segmented.
organization structure should have the tag segmented
FYI: "readorgs" is just an alias here. It can be any name you choose, but it must be the same on both properties for the segmentation to work correctly.

After this update, the user will only be able to see portals that share the same organization as their own.

4.4/ Permissions

You can edit portal’s feature permissions from wedia-config under the “Global permissions” menu.
For each role template, you will edit it’s “Global permissions” permissions, here you'll find the settings that are set by default.

For the “Administrator role type” the permissions should be configured this way :
- Create portals => checked ✅
- Administering portals => checked ✅
For the “Contributor role type” the permissions should be configured this way :
- Create portals => checked ✅
- Administering portals => not checked 🟩
For the “Userrole type” the permissions should be configured this way :
- Create portals => not checked 🟩
- Administering portals => not checked 🟩

4.5/ Share privacies configuration

It is possible to configure the different types of visibilities that will be displayed inside the Share Portal modal.

That configuration can be specified via the configuration entry point: starter-kit/portals/share-options[].

For example, to remove the ability to set a portal as Public in the front-end, the visibility entry that has the type “public“ can be deleted from the base configuration array $.portals.shareOptions[].

This selection will control the value of the property visibility and the portal isntance will be updated accordingly (See the https://crossmedia.atlassian.net/wiki/spaces/WD/pages/3299180556/Portals+feature+explained#Visibility for more details).

4.6/ Searching for a Portal through the DAM

When a fulltext search is made, if portals feature is activated and if results are found, a new section will be displayed on the top of the assets results. This section will contain portals based on the performed search

A configuration option for the displayed portals is available. By configuring a cursor dedicated to the portals displayed in the DAM, you can either filter based on a specific property to meet a particular need or deliberately ensure that no portal instances are retrieved, thereby preventing the portals result section from being displayed in the DAM.

Config file : starter-kit\portals\cursors\portals-dam-explore.json
Example of config, to put on the cursor, to hide portals results on the dam

"staticQuery": {
  "id": { 
    "eq": 0
  } 
}