General

Security

Please note our Statement regarding the Security Improvements here:

Portrait 7.0.0 - Reisalpe | Security Improvements Notice

And make adjustments to Permissions for Forms, Actions 2.0, Sections as needed.

Procedure

1. Please make a backup of your entire configuration this may include the following files. You can download the entire folder directly via <yourInstance.com>/config by rightclick on a folder and select download.

2. Upload the new icon-badge.png

3. Shut down the portrait instance via docker-compose down. (stop is not enough)

4. Update the application-prod.yml - details below

5. Update the .env file to use the latest version:
   Example: (use the latest 7.x that is available) see https://install.portrait.app/ for all versions

   BACKEND_TAG=7.0.0 FRONTEND_TAG=7.0.0 PYTHON_RUNTIME_TAG=7.0.0

6. Startup the instance via docker-compose up -d

7. RECOMMENDED: Elasticsearch Index Space Optimization

   1. Go to the sources config in the admin view and DELETE all ELO indexes.

   2. Restart Portrait to rebuild the indexes completely

If you have a larger YML Config you could also upgrade smaller parts by commenting out some parts and go from there.

Upload new Icon

We extended the icon sets for push notifications. A new icon ‘logo-badge.png’ has been added.
Download this file and add it to the icons folder. As this icon requires specific formats (format, transparency, …) in order to be correctly displayed by multiple devices we recommend to use the default one we provide.

File:

Open

technical details https://notifications.spec.whatwg.org/#badge-resource

The icon will be shown based on the users os and design. Example on android

Open

Example on Samsung Android Lockscreen

Application Config Update (application-prod.yml)

These Guide mainly describes the breaking changes and needed updates in order to migrate old instances. For a full list of new features see our full release notes Portrait 7.0.0 - Reisalpe

Section

Actions:

Reference: Migrate to 7.X - Reisalple | Migration Section Action to new configuration

For Links that were previously build with handlebars in the source. These can now be build with directly in the section. In addition you can specify conditions whenever a link should be displayed for an entry or not.

Details:

Actions

Actions for links:

before

after

Actions for triggering forms:

before

after

Inline Image in HTML

If you previously used the indexing of Files to display Images inline via HTML you have to set a flag to store the files in the public directory.

Enable Public cache folder

publicCache: true

full example:

Disable File download - optional

In addition you may want to disable the download of these files now:

see

Portrait 7.0.0 - Reisalpe | ELO Sources Files Indexing

Example disabledFiles: false (default)

Example disabledFiles: true

Handlebars - Field Processors

ELO GUID’s

With this version we switch to a more classic approach how ELO uses GUID’s. In ELO, the identifier for an Sord now includes the surrounding brackts.

See also: Portrait 7.0.0 - Reisalpe | ELO Sources IDs

Example

A practical example, where this is needed, is the Orgchart view

Additional helper

We added a bunch of new helpers. Check them out and optimize your config as needed:

• Field Processors | In

• Field Processors | Working with numbers

• Field Processors | Working with boolean

• Field Processors | Mathematics Operations

Source

ELO Administration base and Chaosablage

When indexing Elements within the Administration base (“Administration” Folder) and “Chaosablage” results are per default now ignored, this can be changed with

In addition, you can also provide own folder GUIDs that will be excluded.

Details, see: ELO sources

SQL Sources

We increased the security measurements whilst dealing with SQL write operations. This means, the SQL query will be parsed as prepared statement. For safety reasons, we enforce this style now for every SQL query. These changed are valid for all DML Statements. DDL Statements are not supported anymore.

Example

Given this example for the createNewCompany form.

In this given example, the form-data will be inserted into the table DemoOrganigram via the connection organigram.

The FieldProcessors can either be used to format fields or as a fallback in case of an optional field in the form. If not supplied the Query would fail as there would be no valid parameter :Name if not set previously. With the given FieldProcessor the fallback is an empty string.

Details, see: https://portrait.atlassian.net/wiki/x/pQNXPQ

Forms based on existing Entries - Mode and Scope

It is now possible to link forms to existing entries. This allows Portrait administrators to further increase their application security and data consistency. To achieve this goal, we introduced multiple configuration options.

Update-Mode

With the new Mode Update you make the ‘previous’ entry-fields available as variables to be used for Field Processors, SQL queries or further processing in your Python script. In other words, the Create-Mode ignores existing entries - and therefore shouldn’t be used if you need conditions or security.

We recommend that you rework forms which are updating existing entries to increase security by using “update mode” and “scope strict”. This way, input validation will be forced and allows you to get a consistent data store all the time.

Strict-Scope (ELO only)

Furthermore the scope setting was introduced. This was necessary, since it was possible in Portrait 6.x to manipulate unrelated Sord’s in ELO with some “bad-actor-energy”. We won’t go into details here.

However, with Portrait 7.x things changed with the setting the scope to STRICT. This will prevent editing unrelated Sord's which are not indexed in Portrait.

Therefore, it is highly recommended to apply this configuration.

Plausibility check

In addition a check is applied:

• SQL and Python

  • If a form is submitted and no corresponding entry is found in the Portrait index, the operation is cancelled.

• ELO

  • If a form is submitted and no corresponding entry is found in the Portrait index AND the scope is set the STRICT, the operation is cancelled

Summary

Still unsure, what to do? We got your back:

If you have forms, that submit data to ELO, add the mode property to the onSubmit settings and set it accordingly. It will be either: CREATE, UPDATE or DELETE. Also set the scope property to STRICT.

If you have forms, that submit data to SQL or Python, add the mode property to the onSubmit settings and set it accordingly. It will be either: CREATE or UPDATE.

Please read our docs on the given use-case, wholeheartedly:

• Post Processing (onSubmit) - In general, no matter the destination.

• ELO - use the form data in ELO. You will find a separate chapter about the improved security considerations.

• SQL - use the form data in SQL prepared statements.

• Python - use the form data in python scripts.

• BLP 5.1 - start ELO BLP processes.

This examples shall round it up:

Examples

This examples shall round up the previous:

ELO - Update an entry

You have a form in Portrait, that should edit an indexed entry in Portrait and ELO. The config:

ELO - Delete an entry

You have a form in Portrait, that should delete an indexed entry in Portrait and ELO. The config:

Python - Update an entry

You have a form in Portrait, that should edit an indexed entry in Portrait and run a py-script. The config:

SQL - Update an entry

You have a form in Portrait, that should edit an indexed entry in Portrait and SQL. The config:

BLP5.1 - Trigger a process

You have a form in Portrait, that should start a process in BLP5.1. The config: